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.

Studio: account hosted quantized components of every image and video family in cache cleanup (#15487)

Daniel Han33ae272d932e
diff --git a/studio/backend/hub/services/models/companion_cleanup.py b/studio/backend/hub/services/models/companion_cleanup.py
index c84ec90d326..c94e5fc6acd 100644
--- a/studio/backend/hub/services/models/companion_cleanup.py
+++ b/studio/backend/hub/services/models/companion_cleanup.py
@@ -201,7 +201,9 @@ def _delete_impact_blocking(
)
# companions become reclaimable only when no runnable checkpoint survives
- removes_last_checkpoint = not any(_repo_holds_denoiser(repo) for repo in surviving)
+ removes_last_checkpoint = not any(
+ companion_assets.repo_is_install(repo, scans) for repo in surviving
+ )
if variant:
for repo_info in repos:
if _remaining_main_gguf_variants(
diff --git a/studio/backend/hub/services/models/deletion.py b/studio/backend/hub/services/models/deletion.py
index 4d519a692bf..7ff522f93a5 100644
--- a/studio/backend/hub/services/models/deletion.py
+++ b/studio/backend/hub/services/models/deletion.py
@@ -1227,9 +1227,8 @@ def _delete_cached_model_blocking(
from hub.utils import companion_assets
try:
- copies = companion_cleanup._repos_by_id(cache_inventory.all_hf_cache_scans()).get(
- repo_id.strip().lower(), []
- )
+ scans = cache_inventory.all_hf_cache_scans()
+ copies = companion_cleanup._repos_by_id(scans).get(repo_id.strip().lower(), [])
# check only this root; a full copy elsewhere must not block deleting this orphan row.
if cache_path:
wanted = Path(cache_path)
@@ -1241,7 +1240,7 @@ def _delete_cached_model_blocking(
if not copies:
# An empty match means the target root is not in this scan, and concluding "orphan" from copies we did not look at is the fail-open this precondition prevents; raising lands in the 503.
raise RuntimeError(f"cache root not present in the scan: {cache_path}")
- still_orphan = not any(companion_assets.repo_holds_denoiser(repo) for repo in copies)
+ still_orphan = not any(companion_assets.repo_is_install(repo, scans) for repo in copies)
except Exception as e:
logger.warning(f"Orphan re-check failed for {repo_id}; refusing delete: {e}")
raise HTTPException(
diff --git a/studio/backend/hub/tests/test_companion_assets.py b/studio/backend/hub/tests/test_companion_assets.py
index ffb10f21e29..3bc8309fc76 100644
--- a/studio/backend/hub/tests/test_companion_assets.py
+++ b/studio/backend/hub/tests/test_companion_assets.py
@@ -6,6 +6,7 @@
from __future__ import annotations
import asyncio
+from pathlib import Path
from types import SimpleNamespace
import pytest
@@ -215,8 +216,8 @@ def test_orphan_listing_reports_the_stranded_companions_once_the_quants_are_gone
result = asyncio.run(companion_cleanup.orphan_companions_response())
assert [c["repo_id"] for c in result["companions"]] == [BASE_REPO]
assert result["total_bytes"] == COMPANION_BYTES
- assert (
- result["companions"][0]["cache_path"] == "/cache/models--black-forest-labs--FLUX.2-klein-4B"
+ assert result["companions"][0]["cache_path"] == str(
+ Path("/cache/models--black-forest-labs--FLUX.2-klein-4B")
)
@@ -296,8 +297,8 @@ def test_orphan_listing_reports_one_row_per_cache(monkeypatch):
_install(monkeypatch, first, second)
result = asyncio.run(companion_cleanup.orphan_companions_response())
assert [c["cache_path"] for c in result["companions"]] == [
- "/cache/models--black-forest-labs--FLUX.2-klein-4B",
- "/other-cache/models--black-forest-labs--FLUX.2-klein-4B",
+ str(Path("/cache/models--black-forest-labs--FLUX.2-klein-4B")),
+ str(Path("/other-cache/models--black-forest-labs--FLUX.2-klein-4B")),
]
assert [c["size_bytes"] for c in result["companions"]] == [COMPANION_BYTES, 900_460]
assert result["total_bytes"] == COMPANION_BYTES + 900_460
@@ -465,7 +466,7 @@ def test_one_full_copy_does_not_hide_an_orphaned_copy_in_another_cache(monkeypat
_install(monkeypatch, full, orphan)
offered = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
assert [c["cache_path"] for c in offered] == [
- "/cache/models--black-forest-labs--FLUX.2-klein-4B"
+ str(Path("/cache/models--black-forest-labs--FLUX.2-klein-4B"))
]
@@ -626,8 +627,8 @@ def test_a_vae_only_prequant_fetch_is_not_a_dependent(monkeypatch):
assert impact["blocked_by"] == [gguf]
-def test_a_prequant_repo_holding_its_checkpoint_still_pins_the_base(monkeypatch):
- """A root prequant checkpoint in the same repo is an installed model and still pins it."""
+def test_a_speed_loaded_base_and_its_hosted_checkpoint_are_one_install(monkeypatch):
+ """The base stays out of Free up space, yet its own delete is not refused by the hosted repo."""
prequant = "unsloth/Qwen-Image-2.1-FP8"
base = "Qwen/Qwen-Image-2.1"
_install(
@@ -641,7 +642,13 @@ def test_a_prequant_repo_holding_its_checkpoint_still_pins_the_base(monkeypatch)
),
_base_repo(base),
)
- assert companion_cleanup.companion_dependents(base) == [prequant]
+ assert companion_cleanup.companion_dependents(base, ignore_repo_ids = [base]) == []
+ assert companion_cleanup.companion_dependents(prequant) == [base]
+ offered = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ assert offered == []
+ impact = asyncio.run(companion_cleanup.delete_impact_response(base))
+ assert impact["blocked_by"] == []
+ assert [row["repo_id"] for row in impact["freeable_companions"]] == [prequant]
def test_a_pre_cast_encoder_fetch_is_not_a_dependent(monkeypatch):
@@ -658,7 +665,7 @@ def test_a_pre_cast_encoder_fetch_is_not_a_dependent(monkeypatch):
assert impact["blocked_by"] == []
-def test_a_prequant_repo_holding_its_checkpoint_and_encoder_still_pins_the_base(monkeypatch):
+def test_a_hosted_checkpoint_and_encoder_are_freed_with_the_last_dependent(monkeypatch):
prequant = "unsloth/Qwen-Image-2.1-FP8"
base = "Qwen/Qwen-Image-2.1"
_install(
@@ -672,7 +679,11 @@ def test_a_prequant_repo_holding_its_checkpoint_and_encoder_still_pins_the_base(
),
_base_repo(base),
)
- assert companion_cleanup.companion_dependents(base) == [prequant]
+ assert companion_cleanup.companion_dependents(prequant) == [base]
+ impact = asyncio.run(companion_cleanup.delete_impact_response(base))
+ assert impact["freeable_companions"] == [
+ {"repo_id": prequant, "size_bytes": 16_520_000_000, "needed_by": []}
+ ]
def test_a_borrowed_chat_repo_is_never_advertised_as_freeable(monkeypatch):
@@ -866,7 +877,9 @@ def test_the_orphan_precondition_is_scoped_to_the_cache_being_deleted(monkeypatc
_repo(dev, [("model_index.json", 460)], cache = "/c2"),
)
rows = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
- assert [r["cache_path"] for r in rows] == ["/c2/models--black-forest-labs--FLUX.2-dev"]
+ assert [r["cache_path"] for r in rows] == [
+ str(Path("/c2/models--black-forest-labs--FLUX.2-dev"))
+ ]
try:
deletion._delete_cached_model_blocking(
dev, None, None, rows[0]["cache_path"], only_if_orphan = True
@@ -1026,3 +1039,501 @@ def test_a_link_to_a_retired_sd_cli_repack_no_longer_pins_it(monkeypatch):
assert required["tongyi-mai/z-image-turbo"] == {gguf}
offered = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
assert retired.lower() in [c["repo_id"].lower() for c in offered]
+
+
+H3_BASE = "unsloth/MiniMax-H3"
+H3_QUANT = "unsloth/MiniMax-H3-FP8"
+H3_ASSETS = [
+ ("MiniMax-H3-INT8-ConvRot.pt", 20_250_000_000),
+ ("text_encoders/official/qwen3vl_32b_minimax_h3_int8_convrot.safetensors", 27_140_000_000),
+]
+
+
+def test_h3_orphan_sidecars_are_offered_with_actual_blob_bytes(monkeypatch):
+ _install(monkeypatch, _repo(H3_QUANT, H3_ASSETS))
+ result = asyncio.run(companion_cleanup.orphan_companions_response())
+ assert result["companions"] == [
+ {
+ "repo_id": H3_QUANT,
+ "size_bytes": 47_390_000_000,
+ "cache_path": str(Path("/cache/models--unsloth--MiniMax-H3-FP8")),
+ }
+ ]
+ assert result["total_bytes"] == 47_390_000_000
+
+
[email protected]("base", [H3_BASE, "MiniMaxAI/MiniMax-H3"])
+def test_h3_speed_loaded_pipeline_protects_hosted_components_without_links(monkeypatch, base):
+ # Speed load: only VAEs land in the pipeline repo; DiT and TE live in the FP8 repo.
+ _install(
+ monkeypatch,
+ _repo(base, [("vae/diffusion_pytorch_model.safetensors", 11_100_000_000)]),
+ _repo(H3_QUANT, H3_ASSETS),
+ )
+ assert companion_cleanup.companion_dependents(H3_QUANT) == [base]
+ assert H3_QUANT not in {
+ row["repo_id"]
+ for row in asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ }
+ with pytest.raises(HTTPException) as excinfo:
+ deletion._delete_cached_model_blocking(H3_QUANT, None, None)
+ assert excinfo.value.status_code == 400
+
+
+def test_h3_delete_preview_shows_sidecars_as_separate_reclaimable_assets(monkeypatch):
+ _install(
+ monkeypatch,
+ _repo(H3_BASE, [("vae/diffusion_pytorch_model.safetensors", 11_100_000_000)]),
+ _repo(H3_QUANT, H3_ASSETS),
+ )
+ result = asyncio.run(companion_cleanup.delete_impact_response(H3_BASE, None))
+ assert result["reclaimed_bytes"] == 11_100_000_000
+ assert result["retained_companions"] == []
+ assert result["freeable_companions"] == [
+ {"repo_id": H3_QUANT, "size_bytes": 47_390_000_000, "needed_by": []}
+ ]
+
+
+def test_h3_delete_preview_retains_sidecars_for_another_cached_checkpoint(monkeypatch):
+ gguf = "unsloth/MiniMax-H3-GGUF"
+ _install(
+ monkeypatch,
+ _repo(H3_BASE, [("vae/diffusion_pytorch_model.safetensors", 11_100)]),
+ _repo(H3_QUANT, H3_ASSETS),
+ _repo(gguf, [("MiniMax-H3-Q4_K_M.gguf", 99_000)]),
+ )
+ result = asyncio.run(companion_cleanup.delete_impact_response(H3_BASE, None))
+ assert result["freeable_companions"] == []
+ assert result["retained_companions"] == [
+ {"repo_id": H3_QUANT, "size_bytes": 47_390_000_000, "needed_by": [gguf]}
+ ]
+
+
+ "name", ["custom-model.safetensors", "transformer/model.safetensors", "custom/model.pt"]
+)
+def test_h3_cleanup_preserves_unknown_weights_alongside_sidecars(monkeypatch, name):
+ _install(monkeypatch, _repo(H3_QUANT, [*H3_ASSETS, (name, 90_000)]))
+ assert asyncio.run(companion_cleanup.orphan_companions_response())["companions"] == []
+ with pytest.raises(HTTPException) as excinfo:
+ deletion._delete_cached_model_blocking(H3_QUANT, None, None, only_if_orphan = True)
+ assert excinfo.value.status_code == 409
+
+
+def test_h3_metadata_only_pipeline_does_not_pin_orphan_sidecars(monkeypatch):
+ _install(monkeypatch, _repo(H3_BASE, [("model_index.json", 400)]), _repo(H3_QUANT, H3_ASSETS))
+ assert companion_cleanup.companion_dependents(H3_QUANT) == []
+ assert H3_QUANT in {
+ row["repo_id"]
+ for row in asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ }
+
+
+def test_h3_legacy_conditioner_copy_is_also_a_companion(monkeypatch):
+ legacy = H3_ASSETS[1][0].replace("/official/", "/")
+ _install(monkeypatch, _repo(H3_QUANT, [(legacy, 27_140_000_000)]))
+ assert (
+ asyncio.run(companion_cleanup.orphan_companions_response())["total_bytes"] == 27_140_000_000
+ )
+
+
+# (hosted repo, its cached files, reading install, its files, a second install sharing a file in the repo)
+_VAE = [("vae/diffusion_pytorch_model.safetensors", 300_000)]
+HOSTED_CASES = {
+ "image-prequant": (
+ "unsloth/Z-Image-Turbo-FP8",
+ [("Z-Image-Turbo-FP8.safetensors", 6_100_000)],
+ "Tongyi-MAI/Z-Image-Turbo",
+ [("model_index.json", 400), *_VAE, ("text_encoder/model.safetensors", 800_000)],
+ ("unsloth/Z-Image-Turbo", [("model_index.json", 400), *_VAE]),
+ ),
+ "hosted-te": (
+ "unsloth/Qwen-Image-FP8",
+ [("Qwen-Image-text_encoder-FP8.safetensors", 9_400_000)],
+ "unsloth/Qwen-Image-GGUF",
+ [("qwen-image-Q4_K_M.gguf", 12_000_000)],
+ ("unsloth/HunyuanImage-2.1-GGUF", [("hunyuanimage2.1-Q4_K_M.gguf", 11_000_000)]),
+ ),
+ "video-nvfp4": (
+ "unsloth/HunyuanVideo-1.5-NVFP4",
+ [("HunyuanVideo-1.5-NVFP4.pt", 4_800_000)],
+ "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
+ [("model_index.json", 400), *_VAE],
+ ("hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v", [*_VAE]),
+ ),
+ "video-mirror-fp8": (
+ "unsloth/Wan2.2-TI2V-5B-FP8",
+ [
+ ("Wan2.2-TI2V-5B-FP8.safetensors", 5_000_000),
+ ("Wan2.2-TI2V-5B-text_encoder-FP8.safetensors", 6_000_000),
+ ],
+ "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
+ [("model_index.json", 400), *_VAE],
+ ("unsloth/Wan2.2-TI2V-5B-GGUF", [("Wan2.2-TI2V-5B-Q4_K_M.gguf", 3_000_000)]),
+ ),
+ "minimax-h3": (
+ H3_QUANT,
+ H3_ASSETS,
+ H3_BASE,
+ [("model_index.json", 400), *_VAE],
+ ("unsloth/MiniMax-H3-GGUF", [("MiniMax-H3-Q4_K_M.gguf", 99_000)]),
+ ),
+}
+_CASE_IDS = list(HOSTED_CASES)
+
+
+def _offered() -> dict:
+ rows = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ return {row["repo_id"]: row["size_bytes"] for row in rows}
+
+
[email protected]("case", _CASE_IDS)
+def test_hosted_component_with_no_dependent_is_offered_with_its_bytes(monkeypatch, case):
+ hosted, files, *_ = HOSTED_CASES[case]
+ _install(monkeypatch, _repo(hosted, files))
+ assert _offered() == {hosted: sum(size for _n, size in files)}
+
+
[email protected]("case", _CASE_IDS)
+def test_hosted_component_stays_protected_while_its_install_remains(monkeypatch, case):
+ hosted, files, dependent, dependent_files, _second = HOSTED_CASES[case]
+ _install(monkeypatch, _repo(hosted, files), _repo(dependent, dependent_files))
+ assert companion_cleanup.companion_dependents(hosted) == [dependent]
+ assert hosted not in _offered()
+ with pytest.raises(HTTPException) as excinfo:
+ deletion._delete_cached_model_blocking(hosted, None, None)
+ assert excinfo.value.status_code == 400
+
+
[email protected]("case", _CASE_IDS)
+def test_deleting_the_last_install_previews_the_hosted_component_as_freeable(monkeypatch, case):
+ hosted, files, dependent, dependent_files, _second = HOSTED_CASES[case]
+ _install(monkeypatch, _repo(hosted, files), _repo(dependent, dependent_files))
+ impact = asyncio.run(companion_cleanup.delete_impact_response(dependent, None))
+ assert impact["reclaimed_bytes"] == sum(size for _n, size in dependent_files)
+ assert impact["blocked_by"] == []
+ assert impact["retained_companions"] == []
+ assert impact["freeable_companions"] == [
+ {"repo_id": hosted, "size_bytes": sum(size for _n, size in files), "needed_by": []}
+ ]
+
+
[email protected]("case", _CASE_IDS)
+def test_a_shared_hosted_component_is_retained_for_the_other_install(monkeypatch, case):
+ hosted, files, dependent, dependent_files, (second, second_files) = HOSTED_CASES[case]
+ _install(
+ monkeypatch,
+ _repo(hosted, files),
+ _repo(dependent, dependent_files),
+ _repo(second, second_files),
+ )
+ assert companion_cleanup.companion_dependents(hosted) == sorted([dependent, second])
+ impact = asyncio.run(companion_cleanup.delete_impact_response(dependent, None))
+ assert impact["freeable_companions"] == []
+ assert impact["retained_companions"] == [
+ {"repo_id": hosted, "size_bytes": sum(size for _n, size in files), "needed_by": [second]}
+ ]
+ assert hosted not in _offered()
+
+
[email protected]("case", _CASE_IDS)
[email protected]("extra", ["custom-model.safetensors", "transformer/model.safetensors"])
+def test_a_hosted_repo_with_an_unknown_weight_is_preserved(monkeypatch, case, extra):
+ hosted, files, *_ = HOSTED_CASES[case]
+ _install(monkeypatch, _repo(hosted, [*files, (extra, 90_000)]))
+ assert hosted not in _offered()
+ with pytest.raises(HTTPException) as excinfo:
+ deletion._delete_cached_model_blocking(hosted, None, None, only_if_orphan = True)
+ assert excinfo.value.status_code == 409
+
+
+def test_a_shared_repo_is_pinned_only_by_the_families_whose_files_are_cached(monkeypatch):
+ """unsloth/Qwen-Image-FP8 serves HunyuanImage-2.1 its encoder, but only Qwen-Image's DiT is cached there."""
+ hosted = "unsloth/Qwen-Image-FP8"
+ gguf = "unsloth/HunyuanImage-2.1-GGUF"
+ dit = [("Qwen-Image-FP8.safetensors", 20_000_000)]
+ _install(monkeypatch, _repo(hosted, dit), _repo(gguf, [("hunyuanimage2.1-Q4_K_M.gguf", 9)]))
+ assert companion_cleanup.companion_dependents(hosted) == []
+ assert _offered() == {hosted: 20_000_000}
+ encoder = [("Qwen-Image-text_encoder-INT8-ConvRot.safetensors", 7_000_000)]
+ _install(
+ monkeypatch,
+ _repo(hosted, [*dit, *encoder]),
+ _repo(gguf, [("hunyuanimage2.1-Q4_K_M.gguf", 9)]),
+ )
+ assert companion_cleanup.companion_dependents(hosted) == [gguf]
+ assert _offered() == {}
+
+
+def test_a_gguf_install_does_not_pin_a_hosted_denoiser(monkeypatch):
+ """A GGUF pick brings its own denoiser; only a speed load beside the base reads the hosted one."""
+ hosted = "unsloth/Z-Image-Turbo-FP8"
+ _install(
+ monkeypatch,
+ _repo(hosted, [("Z-Image-Turbo-FP8.safetensors", 6_100_000)]),
+ _repo("unsloth/Z-Image-Turbo-GGUF", [("z-image-turbo-Q4_K_M.gguf", 3_000_000)]),
+ )
+ assert companion_cleanup.companion_dependents(hosted) == []
+ assert hosted in _offered()
+
+
+def test_a_speed_loaded_image_base_is_never_offered_as_unused(monkeypatch):
+ """The base minus its denoiser plus the hosted DiT is the install: neither half is an unused leftover."""
+ base = "Tongyi-MAI/Z-Image-Turbo"
+ _install(
+ monkeypatch,
+ _repo(base, [("model_index.json", 400), *_VAE]),
+ _repo("unsloth/Z-Image-Turbo-FP8", [("Z-Image-Turbo-FP8.safetensors", 6_100_000)]),
+ )
+ assert _offered() == {}
+ _install(monkeypatch, _repo(base, [("model_index.json", 400), *_VAE]))
+ assert base in _offered()
+
+
+def test_a_scoped_delete_of_one_speed_load_copy_retains_the_hosted_components(monkeypatch):
+ from hub.utils import hf_cache_state
+
+ base, hosted = "Tongyi-MAI/Z-Image-Turbo", "unsloth/Z-Image-Turbo-FP8"
+ copies = [_repo(base, [("model_index.json", 400), *_VAE], cache = c) for c in ("/a", "/b")]
+ monkeypatch.setattr(
+ hf_cache_state, "resolve_delete_target_root", lambda *a: Path(a[2]).parent.resolve()
+ )
+ _install(monkeypatch, *copies, _repo(hosted, [("Z-Image-Turbo-FP8.safetensors", 6_100_000)]))
+ impact = asyncio.run(
+ companion_cleanup.delete_impact_response(base, None, cache_path = copies[0].repo_path)
+ )
+ assert impact["freeable_companions"] == []
+ assert impact["retained_companions"] == [
+ {"repo_id": hosted, "size_bytes": 6_100_000, "needed_by": [base]}
+ ]
+
+
+def test_the_orphan_recheck_refuses_a_base_that_became_a_speed_load(monkeypatch):
+ base = "Tongyi-MAI/Z-Image-Turbo"
+ _install(
+ monkeypatch,
+ _repo(base, [("model_index.json", 400), *_VAE]),
+ _repo("unsloth/Z-Image-Turbo-FP8", [("Z-Image-Turbo-FP8.safetensors", 6_100_000)]),
+ )
+ with pytest.raises(HTTPException) as excinfo:
+ deletion._delete_cached_model_blocking(base, None, None, only_if_orphan = True)
+ assert excinfo.value.status_code == 409
+
+
+_HOSTED_21 = "unsloth/Qwen-Image-2.1-FP8"
+_HOSTED_21_FILES = [
+ ("Qwen-Image-2.1-FP8.safetensors", 7_120_000),
+ ("Qwen-Image-2.1-text_encoder-FP8.safetensors", 9_400_000),
+ ("vae/qwen_image_2.1_vae_bf16.safetensors", 680_000),
+]
+_CONFIG_ONLY_21 = [
+ ("model_index.json", 400),
+ ("transformer/config.json", 300),
+ ("text_encoder/config.json", 300),
+ ("vae/config.json", 300),
+ ("tokenizer/tokenizer.json", 9_000),
+]
+
+
+def test_a_fully_hosted_speed_load_is_an_install(monkeypatch):
+ """Hosted DiT, encoder and VAE: the base keeps only configs and the tokenizer, and still loads."""
+ base = "Qwen/Qwen-Image-2.1"
+ _install(monkeypatch, _repo(base, _CONFIG_ONLY_21), _repo(_HOSTED_21, _HOSTED_21_FILES))
+ assert companion_cleanup.companion_dependents(_HOSTED_21) == [base]
+ assert _offered() == {}
+ impact = asyncio.run(companion_cleanup.delete_impact_response(base, None))
+ assert impact["blocked_by"] == []
+ assert [row["repo_id"] for row in impact["freeable_companions"]] == [_HOSTED_21]
+ for repo_id, refusal in ((base, 409), (_HOSTED_21, 400)):
+ with pytest.raises(HTTPException) as excinfo:
+ deletion._delete_cached_model_blocking(repo_id, None, None, only_if_orphan = True)
+ assert excinfo.value.status_code == refusal
+
+
+def test_a_config_only_base_with_no_hosted_weights_stays_an_orphan(monkeypatch):
+ base = "Qwen/Qwen-Image-2.1"
+ _install(monkeypatch, _repo(base, _CONFIG_ONLY_21))
+ assert base in _offered()
+
+
+def test_a_config_only_base_missing_a_hosted_component_is_kept(monkeypatch):
+ """No hosted VAE cached: the next load refetches the dense vae/, so the speed load is still an install."""
+ base = "Qwen/Qwen-Image-2.1"
+ _install(monkeypatch, _repo(base, _CONFIG_ONLY_21), _repo(_HOSTED_21, _HOSTED_21_FILES[:2]))
+ assert _offered() == {}
+
+
+_HV_TE = (
+ "unsloth/HunyuanVideo-1.5-FP8",
+ [("HunyuanVideo-1.5-text_encoder-FP8.safetensors", 7_000_000)],
+)
+_HV_BASE = "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v"
+
+
+ "pick",
+ ["hunyuanvideo1.5_480p_t2v.safetensors", "split_files/hunyuanvideo1.5_480p_t2v.safetensors"],
+)
+def test_a_video_single_file_checkpoint_pins_its_hosted_encoder(monkeypatch, pick):
+ checkpoint = "some-owner/custom-video"
+ _install(
+ monkeypatch,
+ _repo(checkpoint, [(pick, 16_000_000)]),
+ _repo(*_HV_TE),
+ _repo(_HV_BASE, [("model_index.json", 400), *_VAE]),
+ )
+ assert companion_cleanup.companion_dependents(_HV_TE[0]) == [checkpoint]
+ assert _offered() == {}
+
+
+def _sd_cpp_repos(repo_id: str, gguf: str) -> list:
+ from core.inference.diffusion_families import detect_family_for_pick
+
+ fam = detect_family_for_pick(repo_id, gguf)
+ specs = sorted(companion_assets._sd_cpp_component_specs(fam, repo_id, gguf))
+ by_repo: dict[str, list] = {}
+ for repo, filename in specs:
+ by_repo.setdefault(repo, []).append((filename, 1_000))
+ return [_repo(repo, files) for repo, files in by_repo.items()]
+
+
+def _shape(name):
+ """Every cached repo one install reads, by install shape: nothing here may be offered while it is cached."""
+ base_files = [("model_index.json", 400), *_VAE, ("text_encoder/model.safetensors", 800_000)]
+ klein_te = (
+ "unsloth/FLUX.2-klein-4B-FP8",
+ [("FLUX.2-klein-4B-text_encoder-FP8.safetensors", 9)],
+ )
+ wan_mirror = "unsloth/Wan2.2-TI2V-5B-FP8"
+ wan_base = "Wan-AI/Wan2.2-TI2V-5B-Diffusers"
+ wan_te = (wan_mirror, [("Wan2.2-TI2V-5B-text_encoder-FP8.safetensors", 9)])
+ shapes = {
+ "diffusers-base-image": [
+ _repo(BASE_REPO, [*base_files, ("transformer/model.safetensors", 9)]),
+ _repo(*klein_te),
+ ],
+ "diffusers-base-video": [
+ _repo(wan_base, [("model_index.json", 400), *_VAE, ("transformer/m.safetensors", 9)]),
+ _repo(*wan_te),
+ ],
+ "speed-load-image": [
+ _repo("Tongyi-MAI/Z-Image-Turbo", base_files),
+ _repo(
+ "unsloth/Z-Image-Turbo-FP8",
+ [
+ ("Z-Image-Turbo-FP8.safetensors", 9),
+ ("Z-Image-Turbo-text_encoder-FP8.safetensors", 9),
+ ],
+ ),
+ ],
+ "speed-load-video": [
+ _repo(wan_base, [("model_index.json", 400), *_VAE]),
+ _repo(wan_mirror, [("Wan2.2-TI2V-5B-FP8.safetensors", 9), *wan_te[1]]),
+ ],
+ "fully-hosted-image": [
+ _repo("Qwen/Qwen-Image-2.1", _CONFIG_ONLY_21),
+ _repo(_HOSTED_21, _HOSTED_21_FILES),
+ ],
+ "single-file-image": [
+ _repo("some-owner/custom", [("flux-2-klein-4b.safetensors", 9)]),
+ _repo(BASE_REPO, base_files),
+ _repo(*klein_te),
+ ],
+ "single-file-video": [
+ _repo("some-owner/custom-video", [("hunyuanvideo1.5_480p_t2v.safetensors", 9)]),
+ _repo(_HV_BASE, [("model_index.json", 400), *_VAE]),
+ _repo(*_HV_TE),
+ ],
+ "gguf-image": [
+ _repo(GGUF_REPO, [("flux-2-klein-4b-Q4_K_M.gguf", 9)]),
+ _repo(BASE_REPO, base_files),
+ _repo(*klein_te),
+ ],
+ "gguf-video": [
+ _repo("unsloth/Wan2.2-TI2V-5B-GGUF", [("Wan2.2-TI2V-5B-Q4_K_M.gguf", 9)]),
+ _repo(wan_base, [("model_index.json", 400), *_VAE]),
+ _repo(*wan_te),
+ ],
+ "sd-cpp-image": [
+ _repo("unsloth/Z-Image-Turbo-GGUF", [("z-image-turbo-Q4_K_M.gguf", 9)]),
+ *_sd_cpp_repos("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf"),
+ ],
+ "modular-h3": [
+ _repo(H3_BASE, [("modular_model_index.json", 400), *_VAE]),
+ _repo(H3_QUANT, H3_ASSETS),
+ ],
+ "modular-h3-gguf": [
+ _repo("unsloth/MiniMax-H3-GGUF", [("MiniMax-H3-Q4_K_M.gguf", 9)]),
+ _repo(H3_QUANT, H3_ASSETS[1:]),
+ ],
+ }
+ return shapes[name]
+
+
+INSTALL_SHAPES = [
+ "diffusers-base-image",
+ "diffusers-base-video",
+ "speed-load-image",
+ "speed-load-video",
+ "fully-hosted-image",
+ "single-file-image",
+ "single-file-video",
+ "gguf-image",
+ "gguf-video",
+ "sd-cpp-image",
+ "modular-h3",
+ "modular-h3-gguf",
+]
+
+
[email protected]("shape", INSTALL_SHAPES)
+def test_nothing_an_install_reads_is_offered_while_it_is_cached(monkeypatch, shape):
+ repos = _shape(shape)
+ _install(monkeypatch, *repos)
+ assert _offered() == {}
+ for repo in repos:
+ if repo.repo_id.lower() in companion_assets._hosted_component_table():
+ assert companion_cleanup.companion_dependents(repo.repo_id) != []
+
+
+def test_each_cache_root_contributes_its_own_nested_video_pick(monkeypatch):
+ checkpoint = "some-owner/custom-video"
+ wan_te = ("unsloth/Wan2.2-TI2V-5B-FP8", [("Wan2.2-TI2V-5B-text_encoder-FP8.safetensors", 9)])
+ _install(
+ monkeypatch,
+ _repo(checkpoint, [("split_files/hunyuanvideo1.5_480p_t2v.safetensors", 9)]),
+ _repo(checkpoint, [("split_files/wan2.2-ti2v-5b.safetensors", 9)], cache = "/other-cache"),
+ _repo(*_HV_TE),
+ _repo(*wan_te),
+ )
+ assert companion_cleanup.companion_dependents(_HV_TE[0]) == [checkpoint]
+ assert companion_cleanup.companion_dependents(wan_te[0]) == [checkpoint]
+ assert _offered() == {}
+
+
+def _split_roots(repos: list) -> list:
+ """Each repo's files split across two cache roots (a repo with one file goes whole to the second root)."""
+ out = []
+ for repo in repos:
+ revision = repo.revisions[0]
+ files = [
+ (Path(f.file_path).relative_to(Path(revision.snapshot_path)).as_posix(), f.size_on_disk)
+ for f in revision.files
+ ]
+ first, second = files[: len(files) // 2], files[len(files) // 2 :]
+ if first:
+ out.append(_repo(repo.repo_id, first))
+ out.append(_repo(repo.repo_id, second, cache = "/other-cache"))
+ return out
+
+
[email protected]("shape", INSTALL_SHAPES)
+def test_nothing_an_install_reads_is_offered_across_two_roots(monkeypatch, shape):
+ repos = _split_roots(_shape(shape))
+ _install(monkeypatch, *repos)
+ # A curated base copy with no denoiser in its own root stays a per-root orphan row, as before; hosted files never.
+ hosted = companion_assets._hosted_component_table()
+ assert not {r.lower() for r in _offered()} & set(hosted)
+ for repo in repos:
+ if repo.repo_id.lower() in hosted:
+ assert companion_cleanup.companion_dependents(repo.repo_id) != []
diff --git a/studio/backend/hub/utils/companion_assets.py b/studio/backend/hub/utils/companion_assets.py
index 1bf5ef8adf3..ffdd33b9948 100644
--- a/studio/backend/hub/utils/companion_assets.py
+++ b/studio/backend/hub/utils/companion_assets.py
@@ -160,6 +160,218 @@ _DENOISER_DIRS = ("transformer/", "unet/")
_WEIGHT_SUFFIXES = (".safetensors", ".bin", ".ckpt", ".pt", ".pth", ".gguf")
+_HOSTED_DENOISER = "denoiser"
+
+
+def _hosted_component_table() -> dict[str, dict[str, set[tuple[str, str, str]]]]:
+ """``{repo_id_lower: {filename_lower: {(registry, family, kind)}}}`` for every hosted quantized component the
+ loaders fetch by name, read from the loaders' own tables. Keyed per FILE: one repo can serve several families
+ (``unsloth/Qwen-Image-FP8``). Curated image bases/mirrors are excluded: the image derivation covers them."""
+ table: dict[str, dict[str, set[tuple[str, str, str]]]] = {}
+
+ def add(repo_id, names, owner, kind) -> None:
+ key = _normalise(repo_id)
+ if not key:
+ return
+ files = table.setdefault(key, {})
+ for name in names:
+ if name:
+ files.setdefault(str(name).lower(), set()).add((*owner, kind))
+
+ families = _family_tables()
+ by_name: dict[str, list[tuple[str, str]]] = {}
+ for registry, fam in families:
+ by_name.setdefault(str(fam.name), []).append((registry, str(fam.name)))
+
+ try:
+ from core.inference.diffusion_prequant import derived_prequant_filenames, with_comfy_twins
+ from core.inference.video_denoiser_prequant import denoiser_components
+ for registry, fam in families:
+ owner = (registry, str(fam.name))
+ rows = [*getattr(fam, "prequant_repos", ())]
+ rows += [
+ (scheme, repo) for _b, scheme, repo in getattr(fam, "prequant_variant_repos", ())
+ ]
+ for scheme, repo in rows:
+ names = [
+ n
+ for component in denoiser_components(fam)
+ for n in derived_prequant_filenames(repo, scheme, component = component)
+ ]
+ names += [
+ row[-1] for row in getattr(fam, "prequant_filenames", ()) if row[0] == scheme
+ ]
+ add(repo, with_comfy_twins(names), owner, _HOSTED_DENOISER)
+ except Exception as exc: # noqa: BLE001 -- no table: those repos keep the pre-table handling
+ logger.debug("Hosted denoiser table unavailable: %s", exc)
+
+ try:
+ from core.inference.diffusion_te_prequant import (
+ TE_INT8_CONVROT_FILES,
+ TE_INT8_CONVROT_VARIANT_FILES,
+ te_prequant_repo_filenames,
+ )
+
+ for registry, fam in families:
+ owner = (registry, str(fam.name))
+ rows = [
+ (str(r[2]), str(r[3] if len(r) > 3 else r[1]), str(r[1]))
+ for r in getattr(fam, "te_prequant_repos", ()) or ()
+ if len(r) >= 3
+ ]
+ rows += [
+ (str(r[3]), str(r[2]), str(r[2]))
+ for r in getattr(fam, "te_prequant_variant_repos", ()) or ()
+ if len(r) >= 4
+ ]
+ for repo, component, slot in rows:
+ for scheme in ("fp8", "int8"):
+ add(repo, te_prequant_repo_filenames(repo, component, scheme), owner, slot)
+ for row in getattr(fam, "hosted_bf16_vae", ()) or ():
+ if len(row) == 3:
+ add(row[1], [row[2]], owner, "vae")
+ entries = [
+ (f, c, e) for f, comps in TE_INT8_CONVROT_FILES.items() for c, e in comps.items()
+ ]
+ entries += [
+ (f, c, e)
+ for f, bases in TE_INT8_CONVROT_VARIANT_FILES.items()
+ for comps in bases.values()
+ for c, e in comps.items()
+ ]
+ for fam_name, slot, entry in entries:
+ for owner in by_name.get(str(fam_name), ()):
+ if len(entry) >= 2:
+ add(entry[0], [entry[1]], owner, str(slot))
+ except Exception as exc: # noqa: BLE001
+ logger.debug("Hosted text-encoder table unavailable: %s", exc)
+
+ try:
+ from core.inference.video_minimax_h3_te import H3_TE_QUANT_FILES, H3_TE_QUANT_REPO
+
+ # Old released builds kept the identical conditioner outside official/; both locations are this asset.
+ names = [
+ n
+ for name in H3_TE_QUANT_FILES.values()
+ for n in (name, name.replace("/official/", "/"))
+ ]
+ for owner in by_name.get("minimax-h3", ()):
+ add(H3_TE_QUANT_REPO, names, owner, "text_encoder")
+ except Exception as exc: # noqa: BLE001
+ logger.debug("H3 conditioner table unavailable: %s", exc)
+ try:
+ from core.inference.video_ltx25 import LTX25_TE_HOSTED_FILE, LTX25_TE_HOSTED_REPO
+ for owner in by_name.get("ltx-2.5", ()):
+ add(LTX25_TE_HOSTED_REPO, [LTX25_TE_HOSTED_FILE], owner, "text_encoder")
+ except Exception as exc: # noqa: BLE001
+ logger.debug("LTX-2.5 encoder table unavailable: %s", exc)
+
+ image_bases = {_normalise(b) for b in _with_mirrors(_curated_base_ids())}
+ return {repo: files for repo, files in table.items() if repo not in image_bases}
+
+
+def _hosted_names(table, repo_id: str) -> Optional[set[str]]:
+ files = table.get(_normalise(repo_id))
+ return None if files is None else set(files)
+
+
+def _family_tables() -> list[tuple[str, object]]:
+ """``[(registry, family)]`` for the image and video tables; one missing registry never hides the other."""
+ families: list[tuple[str, object]] = []
+ try:
+ from core.inference.diffusion_families import _FAMILIES as image_families
+ families += [("image", fam) for fam in image_families]
+ except Exception as exc: # noqa: BLE001
+ logger.debug("image family table unavailable: %s", exc)
+ try:
+ from core.inference.video_families import _FAMILIES as video_families
+ families += [("video", fam) for fam in video_families]
+ except Exception as exc: # noqa: BLE001
+ logger.debug("video family table unavailable: %s", exc)
+ return families
+
+
+def _base_families() -> dict[str, set[tuple[str, str]]]:
+ """``{base_id_lower: {(registry, family)}}``: every identity of a curated base a hosted component is loaded
+ beside. Only these ids pin a hosted denoiser; an arbitrary VAE repo never becomes a dependent by filename."""
+ out: dict[str, set[tuple[str, str]]] = {}
+ for registry, fam in _family_tables():
+ bases = {
+ getattr(fam, "base_repo", None),
+ *(getattr(fam, "named_variant_bases", ()) or ()),
+ }
+ bases |= {row[0] for row in getattr(fam, "prequant_variant_repos", ()) or ()}
+ bases |= {row[0] for row in getattr(fam, "te_prequant_variant_repos", ()) or ()}
+ for base in _with_mirrors(b for b in bases if b):
+ out.setdefault(_normalise(base), set()).add((registry, str(fam.name)))
+ return out
+
+
+def _checkpoint_families(repo_id: str, names: Iterable[Optional[str]]) -> set[tuple[str, str]]:
+ """``(registry, family)`` of every family the image or video loader would resolve for this checkpoint."""
+ found: set[tuple[str, str]] = set()
+ try:
+ from core.inference.video_families import detect_video_family
+ except Exception: # noqa: BLE001
+ detect_video_family = None
+ for name in dict.fromkeys([None, *(names or ())]):
+ fam = _detect_family(repo_id, name)
+ if fam is not None:
+ found.add(("image", str(fam.name)))
+ if detect_video_family is not None:
+ for probe in (repo_id, name):
+ try:
+ vfam = detect_video_family(probe) if probe else None
+ except Exception: # noqa: BLE001
+ vfam = None
+ if vfam is not None:
+ found.add(("video", str(vfam.name)))
+ return found
+
+
+def _hosted_repo_owners(table, repo) -> set[tuple[str, str, str]]:
+ """``(registry, family, kind)`` of every curated file actually cached in *repo*."""
+ files = table.get(_normalise(str(getattr(repo, "repo_id", "") or ""))) or {}
+ owners: set[tuple[str, str, str]] = set()
+ for name in _snapshot_relative_names(repo):
+ owners |= files.get(name.lower(), set())
+ return owners
+
+
+def _hosted_holds_unknown(table, repo) -> bool:
+ """Whether a hosted repo holds a weight the table does not name (or, if also a base mirror, any foldered
+ file): that may be a user install, so it is preserved."""
+ key = _normalise(str(getattr(repo, "repo_id", "") or ""))
+ names = _hosted_names(table, key) or set()
+ try:
+ from core.inference.diffusion_families import canonical_base, mirror_repo
+ dual_role = canonical_base(key).lower() != key or mirror_repo(key) is not None
+ except Exception: # noqa: BLE001
+ dual_role = True
+ for name in _snapshot_relative_names(repo):
+ lowered = name.lower()
+ if lowered in names:
+ continue
+ if lowered.endswith(_WEIGHT_SUFFIXES) or (
+ dual_role and ("/" in lowered or lowered in _PIPELINE_INDEXES)
+ ):
+ return True
+ return False
+
+
+_PIPELINE_INDEXES = ("model_index.json", "modular_model_index.json")
+
+
+def _staged_pipeline(repo) -> bool:
+ """A speed-load base copy: a weight, or the pipeline index plus component configs (hosted files replace shards)."""
+ names = [n.lower() for n in _snapshot_relative_names(repo)]
+ if any(n.endswith(_WEIGHT_SUFFIXES) for n in names):
+ return True
+ return any(n in _PIPELINE_INDEXES for n in names) and any(
+ n.count("/") == 1 and n.endswith("/config.json") for n in names
+ )
+
+
def repo_holds_denoiser(repo, *, folders: bool = True) -> bool:
"""Whether *repo* holds a runnable checkpoint, i.e. is a model the user installed. Beyond the name-only test: a single_file pick caches its checkpoint as ONE top-level file, ``sd_xl_base_1.0.safetensors`` for a whole-pipeline family and ``flux2-dev-fp8.safetensors`` for a transformer-only one, with no denoiser folder to recognise. Those repos are curated companion bases whose self-dependency is dropped, so without this the orphan listing called an installed checkpoint an unused leftover and Free up space deleted it. A companion-only fetch never lands a weight at the snapshot root, and the two ways to be wrong are not symmetric: an orphan we decline to offer costs disk, a checkpoint we offer costs the model. The one root weight that is NOT a checkpoint is the curated component repos' own asset, which is why they are excluded by id: a single-file VAE or text encoder is the companion, and reading it as an installed model is what kept an orphaned pair pinned to disk."""
names = list(_snapshot_relative_names(repo))
@@ -167,6 +379,10 @@ def repo_holds_denoiser(repo, *, folders: bool = True) -> bool:
if folders and any(holds_denoiser(name) for name in names):
return True
repo_id = str(getattr(repo, "repo_id", "") or "")
+ hosted = _hosted_component_table()
+ if _normalise(repo_id) in hosted:
+ # Never an install of its own: only files the table cannot name keep it.
+ return _hosted_holds_unknown(hosted, repo)
if _normalise(repo_id) in _component_only_repo_ids():
return False
encoder_casts = _te_prequant_names(repo_id)
@@ -178,7 +394,52 @@ def repo_holds_denoiser(repo, *, folders: bool = True) -> bool:
continue
if _detect_family(repo_id, name) is not None:
return True
- return False
+ return bool(_video_pick_names(repo_id, [n for n in names if n.lower() not in encoder_casts]))
+
+
+# Diffusers / split-release component folders: their weights are companions, never a video pick.
+_VIDEO_COMPONENT_DIRS = frozenset(
+ {
+ "vae",
+ "audio_vae",
+ "vocoder",
+ "connectors",
+ "scheduler",
+ "tokenizer",
+ "tokenizer_2",
+ "text_encoder",
+ "text_encoder_2",
+ "text_encoders",
+ "image_encoder",
+ "feature_extractor",
+ "latent_upsampler",
+ "latent_upscale_models",
+ "transformer",
+ "transformer_2",
+ }
+)
+
+
+def _video_pick_names(repo_id: str, names: Iterable[str]) -> list[str]:
+ """Cached ``.safetensors`` a video ``single_file`` pick can name, as ``video._resolve_load_family_with_source``."""
+ try:
+ from core.inference.video_families import detect_video_family
+ except Exception: # noqa: BLE001
+ return []
+ picks = []
+ for name in names:
+ lowered = name.lower()
+ if (
+ not lowered.endswith(".safetensors")
+ or lowered.split("/", 1)[0] in _VIDEO_COMPONENT_DIRS
+ ):
+ continue
+ try:
+ if detect_video_family(f"{repo_id}/{name}") is not None:
+ picks.append(name)
+ except Exception: # noqa: BLE001
+ continue
+ return picks
def _te_prequant_names(repo_id: str) -> set[str]:
@@ -393,7 +654,7 @@ def _with_mirrors(bases: Iterable[str]) -> set[str]:
def known_companion_base_ids() -> set[str]:
- """Every id (lowercased) that is a curated image-family companion base, or its mirror. Deliberately NOT "anything a link ever named": orphan cleanup offers only repos this set recognises, so a mis-recorded link can never turn an unrelated repo into a delete candidate."""
+ """Every curated image-base id (lowercased, including mirrors) and every hosted quantized component repo id. Deliberately NOT "anything a link ever named": orphan cleanup offers only repos this set recognises, so a mis-recorded link can never turn an unrelated repo into a delete candidate."""
bases = _curated_base_ids()
# The native engine's component-only repos ARE the companions for an sd.cpp pick, and the largest half of the footprint; leaving them out made them link-only strangers. Safe against a chat model borrowed as a text encoder, since the orphan listing skips any repo holding a GGUF.
try:
@@ -401,7 +662,8 @@ def known_companion_base_ids() -> set[str]:
bases |= set(sd_cpp_companion_only_repo_ids())
except Exception as exc: # noqa: BLE001 -- one missing table never hides the rest
logger.debug("sd.cpp companion table unavailable: %s", exc)
- return {_normalise(b) for b in _with_mirrors(bases)}
+ # Own id only: expanding a video -FP8 repo's mirrors would make the upstream base offerable.
+ return {_normalise(b) for b in _with_mirrors(bases)} | set(_hosted_component_table())
def _mirror_pair_ids() -> set[str]:
@@ -473,9 +735,107 @@ def required_companion_bases(
if not base_key or base_key in self_keys or _normalise(_canonical(base)) in self_keys:
continue
required.setdefault(base_key, set()).add(repo_id)
+ _add_hosted_dependents(required, cache_scans, checkpoints, pick_names, ignored)
return required
+def _cached_hosted_owners(table, cache_scans) -> dict[str, set[tuple[str, str, str]]]:
+ cached: dict[str, set[tuple[str, str, str]]] = {}
+ for scan in cache_scans or ():
+ for repo in getattr(scan, "repos", ()) or ():
+ try:
+ key = _normalise(str(getattr(repo, "repo_id", "") or ""))
+ if str(getattr(repo, "repo_type", "")) != "model" or key not in table:
+ continue
+ cached.setdefault(key, set()).update(_hosted_repo_owners(table, repo))
+ except Exception: # noqa: BLE001 -- one unreadable row never hides the rest
+ continue
+ return cached
+
+
+def repo_is_install(repo, cache_scans) -> bool:
+ """:func:`repo_holds_denoiser`, or a curated base whose family's hosted denoiser is cached (a speed load)."""
+ if repo_holds_denoiser(repo):
+ return True
+ try:
+ table = _hosted_component_table()
+ key = _normalise(str(getattr(repo, "repo_id", "") or ""))
+ families = _base_families().get(key) if key not in table else None
+ if not families:
+ return False
+ cached = _cached_hosted_owners(table, cache_scans)
+ if not _staged_pipeline(repo):
+ return False
+ return any(
+ (r, f) in families and k == _HOSTED_DENOISER
+ for owners in cached.values()
+ for r, f, k in owners
+ )
+ except Exception: # noqa: BLE001 -- fail closed: an unreadable cache counts as an install
+ return True
+
+
+def _add_hosted_dependents(required, cache_scans, checkpoints, pick_names, ignored) -> None:
+ """Pin hosted components per cached FILE to installs that read them; only a curated base pins a hosted denoiser."""
+ table = _hosted_component_table()
+ if not table:
+ return
+ cached = _cached_hosted_owners(table, cache_scans)
+ listed = {repo_key: set().union(*files.values()) for repo_key, files in table.items()}
+ in_view = {(r, f) for repo_key in cached for r, f, _k in listed[repo_key]}
+ denoisers = {
+ (r, f) for owners in cached.values() for r, f, k in owners if k == _HOSTED_DENOISER
+ }
+ bases = _base_families()
+ # {key: (display id, families, reads hosted denoisers)}, merged across cache roots.
+ dependents: dict[str, tuple[str, set[tuple[str, str]], bool]] = {}
+
+ def depend(key: str, repo_id: str, families: set, reads_denoisers: bool) -> None:
+ shown, known, reads = dependents.get(key, (repo_id, set(), False))
+ dependents[key] = (shown, known | families, reads or reads_denoisers)
+
+ for scan in cache_scans or ():
+ for repo in getattr(scan, "repos", ()) or ():
+ try:
+ if str(getattr(repo, "repo_type", "")) != "model":
+ continue
+ repo_id = str(getattr(repo, "repo_id", "") or "")
+ key = _normalise(repo_id)
+ if not key or key in ignored:
+ continue
+ families = bases.get(key) if key not in table else None
+ if key in checkpoints:
+ names = [
+ *pick_names.get(key, []),
+ *_video_pick_names(repo_id, _snapshot_relative_names(repo)),
+ ]
+ found = _checkpoint_families(repo_id, names)
+ depend(key, repo_id, found | (families or set()), bool(families))
+ continue
+ # A hosted repo that is also a base mirror is a companion here, never its own speed load.
+ if not families:
+ continue
+ if not _staged_pipeline(repo):
+ continue
+ if families & in_view and not families & denoisers:
+ # This family's hosted repos are cached and none holds its denoiser: a companion-only fetch.
+ continue
+ depend(key, repo_id, families, True)
+ if families & denoisers:
+ required.setdefault(key, set()).add(dependents[key][0])
+ except Exception: # noqa: BLE001
+ continue
+ for own, (repo_id, families, reads_denoisers) in dependents.items():
+ for repo_key, owners in listed.items():
+ if repo_key == own:
+ continue
+ if any(
+ (r, f) in families and (reads_denoisers or k != _HOSTED_DENOISER)
+ for r, f, k in (cached[repo_key] if repo_key in cached else owners)
+ ):
+ required.setdefault(repo_key, set()).add(repo_id)
+
+
def _hosts_artifacts(repo_id: str) -> bool:
"""``mirror_hosts_artifacts``, False when the family tables are unavailable."""
try: