Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Recognise a partially initialised torchvision and fix the studiobench ab_plan row (#11015)

Daniel Han764a0e40001b
diff --git a/tests/studio/studiobench/report/payload.py b/tests/studio/studiobench/report/payload.py
index 4053d0d942e..2742351268e 100644
--- a/tests/studio/studiobench/report/payload.py
+++ b/tests/studio/studiobench/report/payload.py
@@ -39,6 +39,7 @@ import time
from pathlib import Path
from typing import Any, Iterable, Iterator, Mapping, Sequence
+from ..scoring.from_payload import ATTEMPT_ROW_TYPES
from ..scoring.schema import ExcludedCell, Measure, validate_payload
RECORD_KINDS = (
@@ -217,9 +218,10 @@ ROW_TYPE_SECTIONS: Mapping[str, str] = {
"action": "actions",
"sample": "samples",
"failure": "crashes",
- # Bookkeeping about HOW the A/B was run, not a measurement of the app, so it belongs beside the
- # identity fields where a reader can see whether the order was balanced.
- "ab_plan": "header",
+ # Bookkeeping about HOW the A/B was run, not a measurement of the app. Its OWN section: the
+ # `header` section is collapsed to its FIRST row when the payload is assembled, so an ab_plan
+ # row filed there is silently dropped while record_counts still reports two header rows.
+ "ab_plan": "ab_plan",
# The optional surface sweep. Its own section: a surface row is a coverage fact about the UI, not a
# timing, and folding it into `actions` would put it in front of the scorer.
"surface": "surfaces",
@@ -239,6 +241,89 @@ ROW_TYPE_SECTIONS: Mapping[str, str] = {
}
+def executed_balance(order: Sequence[Any], attempted: set[str]) -> bool | None:
+ """`runtime/ab.py` `order_is_balanced`, over the cells that actually ran.
+
+ Same rule: which arm led each `(rung, rep)` pair, every arm equally often, one arm never
+ balanced because nothing cancels. Read off `make_cell_id`'s `r{rung}.{arm}.rep{rep}`,
+ rsplit from the right so a dotted rung parses. None when the ids are another shape, which
+ is cannot-tell, not unbalanced.
+ """
+
+ labels: set[str] = set()
+ first: dict[str, int] = {}
+ seen: set[tuple[str, str]] = set()
+ for cell_id in order:
+ if str(cell_id) not in attempted:
+ continue
+ try:
+ head, arm, rep = str(cell_id).rsplit(".", 2)
+ except ValueError:
+ return None
+ labels.add(arm)
+ if (head, rep) in seen:
+ continue
+ seen.add((head, rep))
+ first[arm] = first.get(arm, 0) + 1
+ if not labels:
+ return None
+ return len(labels) > 1 and len({first.get(label, 0) for label in labels}) == 1
+
+
+def merged_ab_plan(records: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
+ """One plan out of however many sessions wrote one.
+
+ `--resume` emits a fresh `ab_plan` for the work that session was asked to do, so `[0]`
+ drops the cells a later one added while `record_counts` still reports both plans, which is
+ the loss that moved this row out of `header`, one layer down.
+
+ `order` is the union; the refs come from the first plan, and a resume whose refs disagree
+ is refused upstream.
+
+ `balanced` is ANDed over the sessions that still own a cell, taking ownership from
+ `latest_attempt_rows`: `ATTEMPT_ROW_TYPES` rather than `cell` rows alone, keyed on the
+ `session_id` `Recorder.emit` stamps on every row. A second copy of that rule that
+ disagreed would be worse than none.
+
+ Each verdict is recomputed over what that session ATTEMPTED, since the row's own was
+ computed over the whole plan before it ran: a `--reps 2` interrupted after rep 0 planned
+ base, treatment, treatment, base and ran base, treatment, so base led every pair that
+ happened. `order` stays the requested ladder; `balanced` describes the run.
+ """
+
+ plans = [r for r in records if r.get("row_type") == "ab_plan"]
+ if not plans:
+ return {}
+ plan = dict(plans[0])
+ # The merged object is a synthesis of every session's plan, so the first row's own stamps
+ # would assert it was written by one of them at one moment. `sessions` says who contributed
+ # instead, which is the question those fields were being read for.
+ plan["sessions"] = [row.get("session_id") for row in plans]
+ for stamp in ("session_id", "ts_ms"):
+ plan.pop(stamp, None)
+ order: list[Any] = []
+ for row in plans:
+ for cell_id in row.get("order", []):
+ if cell_id not in order:
+ order.append(cell_id)
+ plan["order"] = order
+ owner: dict[str, Any] = {}
+ for record in records:
+ if record.get("row_type") in ATTEMPT_ROW_TYPES and record.get("cell_id") is not None:
+ owner[str(record["cell_id"])] = record.get("session_id")
+ owning = set(owner.values())
+ # No attempt rows at all is not an experiment; the newest request is the best word there is.
+ live = [row for row in plans if row.get("session_id") in owning] or [plans[-1]]
+ verdicts = []
+ for row in live:
+ session = row.get("session_id")
+ attempted = {cell for cell, owned_by in owner.items() if owned_by == session}
+ ran = executed_balance(row.get("order", []), attempted)
+ verdicts.append(bool(row.get("balanced")) if ran is None else ran)
+ plan["balanced"] = all(verdicts)
+ return plan
+
+
def assemble_rows(path: str | Path, *, validate: bool = True) -> dict[str, Any]:
"""Assemble a payload from the HARNESS layer's row stream (`row_type`, not `kind`).
@@ -283,6 +368,7 @@ def assemble_rows(path: str | Path, *, validate: bool = True) -> dict[str, Any]:
"surfaces": sections.get("surfaces", []),
"aborted_cells": sections.get("aborted_cells", []),
"comparability": (sections["comparability"][0] if sections.get("comparability") else {}),
+ "ab_plan": merged_ab_plan(records),
"crashes": sections.get("crashes", []),
"arms": [],
"unknown_rows": unknown,
diff --git a/tests/studio/studiobench/report/selftest/test_studiobench_payload_ab_plan.py b/tests/studio/studiobench/report/selftest/test_studiobench_payload_ab_plan.py
new file mode 100644
index 00000000000..f20f769a359
--- /dev/null
+++ b/tests/studio/studiobench/report/selftest/test_studiobench_payload_ab_plan.py
@@ -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
+
+"""The `ab_plan` row must survive payload assembly (unsloth#9580).
+
+It used to be filed under `header`, which is collapsed to its FIRST row, so the plan was
+dropped without a word while `record_counts` still reported two header rows.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from studiobench.report import payload as payload_module # noqa: E402
+
+
+ROWS = [
+ {"row_type": "run_meta", "run_id": "r1", "base_ref": "aaa", "platform": {"engine": "chromium"}},
+ {
+ "row_type": "ab_plan",
+ "treatment_ref": "bbb",
+ "order": ["base", "treatment"],
+ "balanced": True,
+ },
+ {"row_type": "cell", "completed": True, "cell_id": "c1", "fields": {"instrument_level": 2}},
+]
+
+
+def _assemble(rows):
+ with tempfile.TemporaryDirectory() as tmp:
+ path = Path(tmp) / "rows.jsonl"
+ path.write_text("".join(json.dumps(row) + "\n" for row in rows))
+ return payload_module.assemble_rows(str(path), validate = False)
+
+
+def test_ab_plan_has_its_own_section():
+ assert payload_module.ROW_TYPE_SECTIONS["ab_plan"] == "ab_plan"
+
+
+def test_ab_plan_survives_assembly():
+ built = _assemble(ROWS)
+ assert built["ab_plan"]["treatment_ref"] == "bbb"
+ assert built["ab_plan"]["order"] == ["base", "treatment"]
+ assert built["ab_plan"]["balanced"] is True
+
+
+def test_header_is_still_the_run_meta_row_and_counts_agree():
+ built = _assemble(ROWS)
+ assert built["header"]["row_type"] == "run_meta"
+ assert built["record_counts"]["header"] == 1
+ assert built["record_counts"]["ab_plan"] == 1
+ assert built["unknown_rows"] == []
+
+
+def test_absent_ab_plan_is_an_empty_mapping():
+ built = _assemble([ROWS[0], ROWS[2]])
+ assert built["ab_plan"] == {}
+
+
+# A plan is written BEFORE its session runs, so cell rows decide ownership and the plan's own
+# `balanced` predates the run. Real `make_cell_id` shapes: a placeholder id would silently take
+# `executed_balance`'s cannot-tell path and exercise nothing.
+def _pair(
+ rung,
+ rep,
+ first = "base",
+):
+ second = "treatment" if first == "base" else "base"
+ return [f"r{rung}.{first}.rep{rep}", f"r{rung}.{second}.rep{rep}"]
+
+
+def _plan(
+ session,
+ order,
+ balanced = True,
+):
+ return {
+ "row_type": "ab_plan",
+ "session_id": session,
+ "treatment_ref": "bbb",
+ "order": order,
+ "balanced": balanced,
+ }
+
+
+def _cells(
+ session,
+ *cell_ids,
+ row_type = "cell",
+):
+ # `Recorder.emit` stamps session_id on every row; ownership keys on it as
+ # `latest_attempt_rows` does, over the same ATTEMPT_ROW_TYPES.
+ return [
+ {
+ "row_type": row_type,
+ "session_id": session,
+ "completed": True,
+ "cell_id": c,
+ "fields": {"instrument_level": 2},
+ }
+ for c in cell_ids
+ ]
+
+
+PAIR = _pair("1K", 0)
+LADDER = PAIR + _pair("1K", 1, first = "treatment")
+RUNG_10K = _pair("10K", 0) + _pair("10K", 1, first = "treatment")
+
+RESUMED_ROWS = [
+ ROWS[0],
+ _plan("s1", PAIR, balanced = False),
+ *_cells("s1", *PAIR),
+ _plan("s2", LADDER),
+ *_cells("s2", *LADDER),
+]
+
+
+def test_a_resumed_session_does_not_lose_the_cells_it_added():
+ built = _assemble(RESUMED_ROWS)
+ assert built["record_counts"]["ab_plan"] == 2
+ assert built["ab_plan"]["order"] == LADDER
+ assert built["ab_plan"]["treatment_ref"] == "bbb"
+
+
+def test_a_session_that_re_ran_the_pair_takes_over_the_balance_claim():
+ assert _assemble(RESUMED_ROWS)["ab_plan"]["balanced"] is True
+
+
+def test_a_resume_that_died_before_retrying_leaves_the_old_session_owning_the_pair():
+ rows = [ROWS[0], _plan("s1", PAIR, balanced = False), *_cells("s1", *PAIR), _plan("s2", LADDER)]
+ built = _assemble(rows)
+ assert built["ab_plan"]["balanced"] is False
+ assert built["ab_plan"]["order"] == LADDER
+
+
+def test_an_unbalanced_session_the_resume_did_not_touch_stays_live():
+ rows = [
+ ROWS[0],
+ _plan("s1", PAIR, balanced = False),
+ *_cells("s1", *PAIR),
+ _plan("s2", RUNG_10K),
+ *_cells("s2", *RUNG_10K),
+ ]
+ assert _assemble(rows)["ab_plan"]["balanced"] is False
+
+
+def test_a_retry_that_never_reached_its_cell_row_still_owns_the_cell():
+ """Hard-killed mid-cell: `action` and `window` rows, no terminal `cell` row."""
+ rows = [
+ ROWS[0],
+ _plan("s1", LADDER, balanced = False),
+ *_cells("s1", *LADDER),
+ _plan("s2", LADDER),
+ *_cells("s2", *LADDER, row_type = "window"),
+ ]
+ assert _assemble(rows)["ab_plan"]["balanced"] is True
+
+
+def test_a_plan_balanced_as_written_is_unbalanced_if_only_its_first_half_ran():
+ """A `--reps 2` interrupted after rep 0 planned base, treatment, treatment, base and ran
+ base, treatment, so base led every pair that happened and drift lands on treatment instead
+ of cancelling. That pair is scored, so the plan's `True` describes an order nothing ran."""
+ rows = [ROWS[0], _plan("s1", LADDER, balanced = True), *_cells("s1", *PAIR)]
+ assert _assemble(rows)["ab_plan"]["balanced"] is False
+ whole = [ROWS[0], _plan("s1", LADDER, balanced = True), *_cells("s1", *LADDER)]
+ assert _assemble(whole)["ab_plan"]["balanced"] is True
+
+
+def test_the_derived_verdict_agrees_with_the_producers_on_a_complete_session():
+ for order, planned in ((PAIR, False), (LADDER, True), (RUNG_10K, True)):
+ rows = [ROWS[0], _plan("s1", order, balanced = planned), *_cells("s1", *order)]
+ assert _assemble(rows)["ab_plan"]["balanced"] is planned, order
+
+
+def test_an_id_that_is_not_a_cell_id_keeps_the_plans_own_word():
+ rows = [ROWS[0], _plan("s1", ["alpha", "beta"], balanced = True), *_cells("s1", "alpha")]
+ assert _assemble(rows)["ab_plan"]["balanced"] is True
+
+
+def test_one_arm_running_alone_is_never_balanced():
+ """With one arm every first-count is trivially equal. `order_is_balanced` calls this the
+ one answer it exists to prevent."""
+ base_only = [cell for cell in LADDER if ".base." in cell]
+ rows = [ROWS[0], _plan("s1", LADDER, balanced = True), *_cells("s1", *base_only)]
+ assert _assemble(rows)["ab_plan"]["balanced"] is False
+
+
+def test_the_merged_plan_does_not_claim_one_sessions_identity():
+ built = _assemble(RESUMED_ROWS)["ab_plan"]
+ assert "session_id" not in built, built
+ assert "ts_ms" not in built, built
+ assert built["sessions"] == ["s1", "s2"]
+ assert built["treatment_ref"] == "bbb"
diff --git a/tests/studio/studiobench/scoring/schema.py b/tests/studio/studiobench/scoring/schema.py
index 226a9fc76de..855619b822e 100644
--- a/tests/studio/studiobench/scoring/schema.py
+++ b/tests/studio/studiobench/scoring/schema.py
@@ -128,6 +128,8 @@ EXEMPT_SUBTREE_KEYS = frozenset(
# (`instrument_level`, `stream_tail_chars`, `corpus_dollars`), every one a true statement about
# how the run was configured and legitimately 0. Same rule as `identity` and `config` above.
"comparability",
+ # Run order: bookkeeping, legitimately 0 or False. Same rule as `comparability`.
+ "ab_plan",
"footer",
"record_counts",
"histogram",
diff --git a/tests/test_broken_torchvision_probe.py b/tests/test_broken_torchvision_probe.py
index 9a51a574bce..b37592d3f6a 100644
--- a/tests/test_broken_torchvision_probe.py
+++ b/tests/test_broken_torchvision_probe.py
@@ -24,6 +24,7 @@ breakage was already handled.
import ast
import builtins
+import importlib
import pathlib
import sys
from unittest import mock
@@ -320,3 +321,201 @@ def test_a_conda_torch_is_not_sent_to_pypis_torchvision(tmp_path):
# Without the ledger nothing changes: an absent tag still means PyPI.
assert "pip install" in advice("2.5.1")
+
+
+ "message",
+ [
+ # The reported message (unsloth#1793).
+ "partially initialized module 'torchvision' has no attribute 'extension' "
+ "(most likely due to a circular import)",
+ "partially initialized module 'torchvision.transforms' has no attribute "
+ "'InterpolationMode'",
+ "partially initialized module 'torchvision.io.image' has no attribute 'decode_jpeg'",
+ # 3.13+ names the file in the same message; 3.12 and older do not.
+ "partially initialized module 'torchvision' from "
+ "'/usr/lib/python3/site-packages/torchvision/__init__.py' has no attribute 'extension' "
+ "(most likely due to a circular import)",
+ "partially initialized module 'torchvision.ops' from "
+ "'/opt/venv/lib/torchvision/ops/__init__.py' has no attribute 'nms'",
+ ],
+)
+def test_partially_initialized_torchvision_is_recognised(message):
+ """A torchvision whose extension failed to load can surface as an AttributeError on a
+ half-imported module rather than a loader failure (unsloth#1793)."""
+ assert import_fixes._is_broken_torchvision_error(AttributeError(message))
+
+
+def test_the_lazy_module_wrapper_around_it_is_recognised():
+ """transformers' _LazyModule re-raises as RuntimeError with the original as cause."""
+ inner = AttributeError(
+ "partially initialized module 'torchvision' has no attribute 'extension' "
+ "(most likely due to a circular import)"
+ )
+ outer = RuntimeError(
+ "Failed to import transformers.image_utils because of the following error "
+ "(look up to see its traceback):\n" + str(inner)
+ )
+ outer.__cause__ = inner
+ assert import_fixes._is_broken_torchvision_error(outer)
+
+
+ "message",
+ [
+ # A typo on a HEALTHY torchvision: fully imported, so no "partially initialized".
+ "module 'torchvision' has no attribute 'extension'",
+ "module 'torchvision' has no attribute 'nms'",
+ "module 'torchvision.ops' has no attribute 'nsm'",
+ # Someone else's circular import.
+ "partially initialized module 'numpy' has no attribute 'array'",
+ "partially initialized module 'mypackage.torchvision' has no attribute 'x'",
+ "partially initialized module 'torchvisionfoo' has no attribute 'x'",
+ "partially initialized module 'not_torchvision' has no attribute 'x'",
+ "partially initialized module 'mytorchvision' has no attribute 'extension'",
+ # The `from '...'` clause must not let another module's path carry the match.
+ "partially initialized module 'numpy' from '/x/torchvision/numpy.py' has no attribute 'a'",
+ "module 'os' has no attribute 'extension'",
+ ],
+)
+def test_a_healthy_torchvision_or_another_module_is_not_claimed(message):
+ assert not import_fixes._is_broken_torchvision_error(AttributeError(message))
+
+
+def test_the_probe_names_the_partially_initialized_break():
+ """End to end through the probe, not just the predicate."""
+ error = AttributeError(
+ "partially initialized module 'torchvision' has no attribute 'extension' "
+ "(most likely due to a circular import)"
+ )
+ with pytest.raises(ImportError) as excinfo:
+ _probe_with_import_raising(error)
+ assert "UNSLOTH_SKIP_TORCHVISION_CHECK=1" in str(excinfo.value)
+ assert excinfo.value.__cause__ is error
+
+
+def test_the_probe_stays_silent_on_a_typo_against_a_healthy_torchvision():
+ """`import unsloth` must not be turned into "reinstall torchvision" by an
+ AttributeError that carries no evidence of a half-imported module."""
+ _probe_with_import_raising(AttributeError("module 'torchvision' has no attribute 'extension'"))
+
+
[email protected]("kind", ["module", "package"])
+def test_a_file_shadowing_torchvision_is_named_rather_than_blamed_on_the_binary(
+ tmp_path, monkeypatch, kind
+):
+ """A local torchvision raises the same words while the metadata still reports the
+ installed one. Driven through a real import: the fix turns on which file resolves."""
+ # A shadow exists only relative to an INSTALLED torchvision, so with none this has
+ # nothing to assert and would fail rather than skip.
+ pytest.importorskip("torchvision")
+ body = "import torchvision\ntorchvision.extension\n"
+ if kind == "module":
+ shadow = tmp_path / "torchvision.py"
+ shadow.write_text(body)
+ else:
+ # A directory is a package like the real one, so shape cannot separate them.
+ (tmp_path / "torchvision").mkdir()
+ shadow = tmp_path / "torchvision" / "__init__.py"
+ shadow.write_text(body)
+ with mock.patch.dict(sys.modules):
+ for name in [n for n in sys.modules if n.startswith("torchvision")]:
+ sys.modules.pop(name, None)
+ monkeypatch.syspath_prepend(str(tmp_path))
+ assert import_fixes._shadowing_torchvision_path() == str(shadow)
+ with pytest.raises(ImportError) as excinfo:
+ import_fixes._probe_torchvision_binary("2.11.0", "0.26.0", (0, 26))
+ text = str(excinfo.value)
+
+ assert str(shadow) in text, text
+ assert "reinstalling torchvision will not change which one wins" in text, text
+ assert "force-reinstall" not in text, text # the binary branch's advice, wrong here
+ assert isinstance(excinfo.value.__cause__, AttributeError)
+
+
+def test_the_real_torchvision_is_not_mistaken_for_a_shadow():
+ pytest.importorskip("torchvision")
+ assert import_fixes._shadowing_torchvision_path() is None
+ assert import_fixes._is_broken_torchvision_error(
+ AttributeError("partially initialized module 'torchvision' has no attribute 'extension'")
+ )
+
+
+def test_the_marker_matches_what_this_interpreter_actually_says(tmp_path, monkeypatch):
+ """3.13.12 adds a `from '<file>'` clause 3.12.3 does not, and a marker matching nothing
+ looks exactly like a healthy box. So provoke it here rather than quoting a bug report."""
+ package = tmp_path / "tvshape"
+ package.mkdir()
+ (package / "__init__.py").write_text("import tvshape\ntvshape.extension\n")
+ monkeypatch.syspath_prepend(str(tmp_path))
+ with mock.patch.dict(sys.modules):
+ sys.modules.pop("tvshape", None)
+ with pytest.raises(AttributeError) as excinfo:
+ importlib.import_module("tvshape")
+
+ produced = str(excinfo.value)
+ assert "partially initialized" in produced, produced
+ assert import_fixes._TORCHVISION_ATTRIBUTE_RE.search(
+ produced.replace("tvshape", "torchvision")
+ ), produced
+ assert not import_fixes._TORCHVISION_ATTRIBUTE_RE.search(produced), produced
+
+
+ "message",
+ [
+ # `from torchvision import X` mid-execution: an ImportError, never "has no attribute".
+ "cannot import name 'extension' from partially initialized module 'torchvision' "
+ "(most likely due to a circular import) (/usr/lib/torchvision/__init__.py)",
+ "cannot import name 'nms' from partially initialized module 'torchvision.ops' "
+ "(most likely due to a circular import)",
+ # A second `import torchvision.ops` after the first failed to initialise.
+ "cannot access submodule 'ops' of module 'torchvision' "
+ "(most likely due to a circular import)",
+ ],
+)
+def test_the_other_two_cpython_wordings_of_the_same_break_are_recognised(message):
+ """Four wordings, one fault. The two above carry no "has no attribute" clause at all,
+ so a marker anchored on that clause reports a healthy box for a torchvision that
+ cannot import."""
+ assert import_fixes._is_broken_torchvision_error(ImportError(message))
+
+
+ "message",
+ [
+ "cannot import name 'x' from partially initialized module 'mytorchvision' "
+ "(most likely due to a circular import)",
+ "cannot access submodule 'torchvision' of module 'mypackage' "
+ "(most likely due to a circular import)",
+ "cannot access submodule 'ops' of module 'torchvisionfoo'",
+ # A fully imported torchvision refusing a name: nothing to reinstall.
+ "cannot import name 'nsm' from 'torchvision.ops' (/usr/lib/torchvision/ops.py)",
+ ],
+)
+def test_the_other_two_wordings_do_not_claim_another_module(message):
+ assert not import_fixes._is_broken_torchvision_error(ImportError(message))
+
+
+def test_the_from_import_wording_is_what_this_interpreter_actually_says():
+ import tempfile
+
+ with tempfile.TemporaryDirectory() as tmp:
+ package = pathlib.Path(tmp) / "tvfrom"
+ package.mkdir()
+ (package / "__init__.py").write_text("from tvfrom import extension\n")
+ sys.path.insert(0, tmp)
+ try:
+ with mock.patch.dict(sys.modules):
+ sys.modules.pop("tvfrom", None)
+ with pytest.raises(ImportError) as excinfo:
+ importlib.import_module("tvfrom")
+ finally:
+ sys.path.remove(tmp)
+
+ produced = str(excinfo.value)
+ assert "partially initialized" in produced, produced
+ assert import_fixes._TORCHVISION_ATTRIBUTE_RE.search(
+ produced.replace("tvfrom", "torchvision")
+ ), produced
+ assert not import_fixes._TORCHVISION_ATTRIBUTE_RE.search(produced), produced
diff --git a/tests/test_import_fixes_drift.py b/tests/test_import_fixes_drift.py
index b59280bcbef..d8cde86537f 100644
--- a/tests/test_import_fixes_drift.py
+++ b/tests/test_import_fixes_drift.py
@@ -232,6 +232,15 @@ def test_peft_transformers_weight_conversion_importable_and_signature():
"""``patch_peft_weight_converter_compatibility``: wraps build_peft_weight_mapping;
silently no-ops if the module is unimportable."""
pytest.importorskip("peft")
+ # transformers_weight_conversion arrived in PEFT 0.19.0 (huggingface/peft 5356277d), but
+ # both pyprojects allow >=0.18.0, where the patch returns early and there is no drift.
+ peft_version = _safe_version(importlib_version("peft"))
+ if peft_version < _PkgVersion("0.19.0"):
+ pytest.skip(
+ f"peft {peft_version} predates peft.utils.transformers_weight_conversion "
+ "(added in 0.19.0); patch_peft_weight_converter_compatibility no-ops by "
+ "design below it, so its absence is the declared floor, not drift."
+ )
try:
from peft.utils import transformers_weight_conversion as twc
except Exception as exc:
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index b5184a6f704..a2880e2645a 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -19,6 +19,7 @@ import importlib.abc
import importlib.machinery
import importlib.util
from pathlib import Path
+from importlib.metadata import distribution as importlib_distribution
from importlib.metadata import version as importlib_version
from importlib.metadata import PackageNotFoundError
from packaging.version import Version as TrueVersion
@@ -1489,6 +1490,59 @@ _TORCHVISION_ABI_MARKERS = (
# unrelated reason must keep importing unsloth, not get "reinstall torchvision".
_LOADER_FAILURE_MARKERS = ("undefined symbol", "cannot open shared object file")
_TORCH_LIBRARY_MARKERS = ("torchvision", "libtorch", "libc10", "_C.so", "c10::")
+# A lazily-imported torchvision with a dead extension surfaces as this, not a loader error.
+# "partially initialized" is load-bearing: without it a typo on a healthy torchvision
+# ("module 'torchvision' has no attribute 'nms'") would be answered with "reinstall". Nothing
+# AFTER the module name is, because CPython words the rest four ways for the one fault:
+# 3.9 - 3.12 partially initialized module 'torchvision' has no attribute 'extension'
+# 3.13, 3.14 partially initialized module 'torchvision' from '<file>' has no attribute
+# from-import cannot import name 'extension' from partially initialized module 'torchvision'
+# submodule cannot access submodule 'ops' of module 'torchvision'
+# The first three share "partially initialized module 'torchvision'"; the fourth names it as
+# the parent instead, so it gets its own alternative.
+_TORCHVISION_ATTRIBUTE_RE = re.compile(
+ r"partially initialized module 'torchvision(?:\.[\w.]+)?'"
+ r"|cannot access submodule '[\w.]+' of module 'torchvision(?:\.[\w.]+)?'"
+)
+
+
+def _shadowing_torchvision_path():
+ """What is standing in for torchvision, if something is, else None.
+
+ A local `torchvision` earlier on sys.path raises the same "partially initialized" words
+ while the metadata still describes the installed distribution, so the binary check would
+ answer it with "reinstall", which cannot change which sys.path entry is searched first.
+
+ Identity, not shape: a `torchvision/` directory is a package exactly like the real one, so
+ only asking whether the resolved file is the one the metadata installed separates them.
+
+ find_spec, not sys.modules: the caller is in the `except` of the import that failed, and
+ CPython has already removed the half-built module by then.
+ """
+ try:
+ spec = importlib.util.find_spec("torchvision")
+ except Exception:
+ # A shadow can break find_spec itself. No answer is not evidence of shadowing.
+ return None
+ origin = getattr(spec, "origin", None) if spec is not None else None
+ if not origin:
+ return None
+ try:
+ installed = os.fspath(
+ importlib_distribution("torchvision").locate_file("torchvision/__init__.py")
+ )
+ except Exception:
+ return None
+ if not os.path.exists(installed):
+ # Editable install, usually. Cannot tell, so do not send anyone hunting a file.
+ return None
+ try:
+ if os.path.samefile(origin, installed):
+ return None
+ except OSError:
+ if os.path.realpath(origin) == os.path.realpath(installed):
+ return None
+ return origin
def _is_broken_torchvision_error(error) -> bool:
@@ -1499,6 +1553,8 @@ def _is_broken_torchvision_error(error) -> bool:
message = str(current)
if any(marker in message for marker in _TORCHVISION_ABI_MARKERS):
return True
+ if _TORCHVISION_ATTRIBUTE_RE.search(message) and _shadowing_torchvision_path() is None:
+ return True
if any(m in message for m in _LOADER_FAILURE_MARKERS) and any(
m in message for m in _TORCH_LIBRARY_MARKERS
):
@@ -1614,6 +1670,15 @@ def _probe_torchvision_binary(
import torchvision # noqa: F401
import torchvision.ops # noqa: F401 where the compiled nms lives
except Exception as error:
+ shadow = _shadowing_torchvision_path()
+ if shadow is not None and _TORCHVISION_ATTRIBUTE_RE.search(str(error)):
+ # Named: the metadata says torchvision is installed and it is, so a reinstall
+ # changes nothing. The file is the whole fix.
+ raise ImportError(
+ f"Unsloth: {shadow} is being imported as `torchvision`, ahead of the "
+ f"installed package ({type(error).__name__}: {error}). Rename or move that "
+ f"file; reinstalling torchvision will not change which one wins."
+ ) from error
# Anything else is left for whoever actually needs torchvision.
if not _is_broken_torchvision_error(error):
return