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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Test for the customizable RAG embedding model: a saved override becomes the
effective model and derives its GGUF companion for the llama-server backend."""
from pathlib import Path
import sys
import types as _types
_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
if _BACKEND_DIR not in sys.path:
sys.path.insert(0, _BACKEND_DIR)
_loggers_stub = _types.ModuleType("loggers")
_loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
sys.modules.setdefault("loggers", _loggers_stub)
import pytest
import utils.embedding_model_settings as ems
from core.rag import config as rag_config
@pytest.fixture
def settings_store(monkeypatch):
"""In-memory app_settings store patched under the module's lazy imports."""
import storage.studio_db as studio_db
store: dict = {}
monkeypatch.setattr(
studio_db,
"get_app_settings",
lambda keys: {key: store[key] for key in keys if key in store},
)
monkeypatch.setattr(
studio_db, "upsert_app_settings", lambda settings: store.update(settings) or store
)
def _cas(key, expected, value):
if store.get(key) != expected:
return False
store[key] = value
return True
monkeypatch.setattr(studio_db, "compare_and_set_app_setting", _cas)
# process-wide memo outlives the patched store and would leak into later tests
ems._resolved_gguf_memo.clear()
ems._invalidate_cache()
yield store
ems._resolved_gguf_memo.clear()
ems._invalidate_cache()
def test_custom_model_overrides_default_and_derives_gguf(settings_store, monkeypatch):
"""With nothing stored the default applies; a saved custom model becomes effective and derives
its -GGUF companion that llama-server loads; reset clears it."""
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
assert ems.get_rag_embedding_model() == rag_config.EMBEDDING_MODEL
assert rag_config.effective_gguf_repo() == rag_config.EMBED_GGUF_REPO
assert ems.set_rag_embedding_model(" org/my-embedder ") == "org/my-embedder"
assert rag_config.effective_embedding_model() == "org/my-embedder"
assert rag_config.effective_gguf_repo() == "org/my-embedder-GGUF"
assert ems.reset_rag_embedding_model() == rag_config.EMBEDDING_MODEL
assert ems.get_stored_embedding_model() is None
def test_env_default_derives_its_gguf_companion(monkeypatch):
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
monkeypatch.setattr(rag_config, "EMBEDDING_MODEL", "org/env-default-embedder")
assert rag_config.default_gguf_repo() == "org/env-default-embedder-GGUF"
def test_env_default_keeps_its_resolved_gguf_without_becoming_custom(settings_store, monkeypatch):
"""Selecting the env default must not persist it as a custom override."""
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
monkeypatch.setattr(rag_config, "EMBEDDING_MODEL", "org/env-default-embedder")
ems.set_rag_embedding_model(
"org/env-default-embedder",
gguf_repo = "org/published-conversion",
backend = "llama-server",
)
assert ems.get_stored_embedding_model() is None
assert ems.get_stored_gguf_repo("org/env-default-embedder") == "org/published-conversion"
assert rag_config.effective_gguf_repo() == "org/published-conversion"
def test_resolution_record_keeps_model_repo_and_backend_atomic(settings_store):
ems.set_rag_embedding_model(
"org/embedder",
gguf_repo = "org/embedder-conversion",
backend = "llama-server",
)
assert settings_store[ems.EMBEDDING_RESOLUTION_SETTING_KEY] == {
"model": "org/embedder",
"gguf_repo": "org/embedder-conversion",
"backend": "llama-server",
"download_pending": False,
"gguf_files": None,
}
assert settings_store[ems.EMBEDDING_GGUF_SETTING_KEY] is None
assert settings_store[ems.EMBEDDING_BACKEND_SETTING_KEY] is None
def test_pending_download_is_stored_with_the_same_atomic_resolution(settings_store):
ems.set_rag_embedding_model(
"org/embedder",
gguf_repo = "org/embedder-conversion",
backend = "llama-server",
download_pending = True,
)
assert ems.get_stored_download_pending("org/embedder") is True
assert ems.get_stored_download_pending("org/another") is False
assert settings_store[ems.EMBEDDING_RESOLUTION_SETTING_KEY]["download_pending"] is True
def test_a_completed_transfer_retires_the_pending_marker(settings_store):
"""Nothing else clears it: the picker re-resolves after a download but does not
save again, so a marker left behind pins the model cache-only for good and a
later cache eviction reads as "never downloaded"."""
ems.set_rag_embedding_model(
"org/embedder",
gguf_repo = "org/embedder-conversion",
backend = "llama-server",
download_pending = True,
)
assert ems.clear_stored_download_pending("org/embedder") is True
assert ems.get_stored_download_pending("org/embedder") is False
assert ems.get_stored_gguf_repo("org/embedder") == "org/embedder-conversion"
assert ems.get_stored_backend("org/embedder") == "llama-server"
assert ems.clear_stored_download_pending("org/embedder") is False
assert ems.clear_stored_download_pending("org/another") is False
assert ems.get_stored_gguf_repo("org/embedder") == "org/embedder-conversion"
def test_a_concurrent_save_is_not_reverted_by_a_late_pending_clear(settings_store):
"""A pending clear is conditional on the record read, so a late clear cannot revert a new save."""
ems.set_rag_embedding_model(
"org/a", gguf_repo = "org/a-GGUF", backend = "llama-server", download_pending = True
)
stale = ems._get_stored_state()
assert stale[1] == "org/a" and stale[4] is True
ems.set_rag_embedding_model("org/b", gguf_repo = "org/b-GGUF", backend = "sentence-transformers")
ems._cached[("owner", ems.EMBEDDING_RESOLUTION_SETTING_KEY)] = (
0.0,
stale,
)
assert ems.clear_stored_download_pending("org/a") is False
ems._invalidate_cache()
assert ems.get_stored_gguf_repo("org/b") == "org/b-GGUF"
assert ems.get_stored_backend("org/b") == "sentence-transformers"
assert ems.get_stored_gguf_repo("org/a") is None
def test_a_pinned_jobs_resolved_repo_survives_a_save_for_another_model(settings_store, monkeypatch):
"""A job pinned to A keeps A's repo when B is saved, not the derived A-GGUF mid-run."""
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
ems._resolved_gguf_memo.clear()
from core.rag import config
ems.set_rag_embedding_model(
"org/embedder-a", gguf_repo = "mirror/off-convention-GGUF", backend = "llama-server"
)
assert config.effective_gguf_repo_for_embedding_model("org/embedder-a") == (
"mirror/off-convention-GGUF"
)
ems.set_rag_embedding_model("org/embedder-b", gguf_repo = None, backend = None)
assert ems.get_stored_gguf_repo("org/embedder-a") is None
assert config.effective_gguf_repo_for_embedding_model("org/embedder-a") == (
"mirror/off-convention-GGUF"
)
assert config.effective_gguf_repo_for_embedding_model("org/never-seen") == (
config.gguf_repo_for_embedding_model("org/never-seen")
)
def test_a_reset_keeps_the_repo_a_running_job_still_needs(settings_store, monkeypatch):
"""Reset must keep the memoized GGUF repo, since a job pinned to the old model still needs it."""
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
ems._resolved_gguf_memo.clear()
from core.rag import config
ems.set_rag_embedding_model(
"org/embedder-a", gguf_repo = "mirror/off-convention-GGUF", backend = "llama-server"
)
assert ems.get_stored_gguf_repo("org/embedder-a") == "mirror/off-convention-GGUF"
ems.reset_rag_embedding_model()
assert ems.get_stored_embedding_model() is None
assert ems.remembered_gguf_repo("org/embedder-a") == "mirror/off-convention-GGUF"
assert config.effective_gguf_repo_for_embedding_model("org/embedder-a") == (
"mirror/off-convention-GGUF"
)
assert config.effective_gguf_repo_for_embedding_model("org/never-seen") == (
config.gguf_repo_for_embedding_model("org/never-seen")
)
def test_a_pinned_jobs_backend_and_pending_survive_a_save_for_another_model(
settings_store, monkeypatch
):
"""On an auto CPU install a model with no GGUF resolves to
sentence-transformers; losing that record drops a still-running job onto the
hardware default, and losing the marker re-enables the implicit download."""
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
ems._resolved_gguf_memo.clear()
ems.set_rag_embedding_model(
"org/st-only",
gguf_repo = None,
backend = "sentence-transformers",
download_pending = True,
)
assert ems.get_stored_backend("org/st-only") == "sentence-transformers"
assert ems.get_stored_download_pending("org/st-only") is True
ems.set_rag_embedding_model("org/other", gguf_repo = None, backend = "llama-server")
assert ems.get_stored_backend("org/st-only") == "sentence-transformers"
assert ems.get_stored_download_pending("org/st-only") is True
assert ems.get_stored_backend("org/other") == "llama-server"
assert ems.get_stored_backend("org/never-seen") is None
assert ems.get_stored_download_pending("org/never-seen") is False
def test_retiring_the_pending_marker_retires_it_in_the_memo_too(settings_store, monkeypatch):
"""Otherwise a pinned job keeps seeing pending=True and stays cache-only after download."""
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
ems._resolved_gguf_memo.clear()
ems.set_rag_embedding_model(
"org/embedder",
gguf_repo = None,
backend = "sentence-transformers",
download_pending = True,
)
assert ems.get_stored_download_pending("org/embedder") is True
assert ems.clear_stored_download_pending("org/embedder") is True
ems.set_rag_embedding_model("org/other", gguf_repo = None, backend = None)
assert ems.get_stored_download_pending("org/embedder") is False
assert ems.get_stored_backend("org/embedder") == "sentence-transformers"
def test_a_reset_makes_the_restored_defaults_resolution_durable(settings_store, monkeypatch):
"""Persist the default's resolution, or a restart changes its identity and strands indexed work."""
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
ems._resolved_gguf_memo.clear()
default = ems.default_embedding_model()
ems.set_rag_embedding_model(
default, gguf_repo = "mirror/off-convention-GGUF", backend = "llama-server"
)
assert ems.get_stored_gguf_repo(default) == "mirror/off-convention-GGUF"
ems.set_rag_embedding_model("org/other", gguf_repo = None, backend = None)
assert ems.reset_rag_embedding_model() == default
assert ems.get_stored_embedding_model() is None
ems._resolved_gguf_memo.clear()
assert ems.get_stored_gguf_repo(default) == "mirror/off-convention-GGUF"
assert ems.get_stored_backend(default) == "llama-server"
def test_a_reset_with_nothing_remembered_stays_a_plain_reset(settings_store, monkeypatch):
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
ems._resolved_gguf_memo.clear()
ems.set_rag_embedding_model("org/other", gguf_repo = None, backend = "sentence-transformers")
assert ems.reset_rag_embedding_model() == ems.default_embedding_model()
assert ems.get_stored_embedding_model() is None
assert settings_store[ems.EMBEDDING_RESOLUTION_SETTING_KEY] is None
def test_the_planned_gguf_family_is_stored_and_survives_the_clear(settings_store):
"""The loader needs the family to tell the delivered quant from others in the repo; the clear is
conditional on the record as read, so an extra field must not make it a no-op."""
ems._resolved_gguf_memo.clear()
ems.set_rag_embedding_model(
"org/a",
gguf_repo = "org/a-GGUF",
backend = "llama-server",
download_pending = True,
gguf_files = ["a-Q8_0-00001-of-00002.gguf", "a-Q8_0-00002-of-00002.gguf"],
)
assert ems.get_stored_gguf_files("org/a") == [
"a-Q8_0-00001-of-00002.gguf",
"a-Q8_0-00002-of-00002.gguf",
]
assert ems.clear_stored_download_pending("org/a") is True
assert ems.get_stored_download_pending("org/a") is False
# the family describes the artifact, not the transfer, so it outlives the flag
assert ems.get_stored_gguf_files("org/a") == [
"a-Q8_0-00001-of-00002.gguf",
"a-Q8_0-00002-of-00002.gguf",
]
def test_a_record_written_before_the_family_existed_still_clears(settings_store):
"""An install saved by the previous build has no gguf_files key, so comparing to a rebuilt
record would pin such models cache-only forever."""
from storage.studio_db import upsert_app_settings
ems._resolved_gguf_memo.clear()
upsert_app_settings(
{
ems.EMBEDDING_MODEL_SETTING_KEY: "org/legacy",
ems.EMBEDDING_RESOLUTION_SETTING_KEY: {
"model": "org/legacy",
"gguf_repo": "org/legacy-GGUF",
"backend": "llama-server",
"download_pending": True,
},
}
)
ems._invalidate_cache()
assert ems.get_stored_gguf_files("org/legacy") is None
assert ems.clear_stored_download_pending("org/legacy") is True
assert ems.get_stored_download_pending("org/legacy") is False
def test_a_reset_keeps_a_pending_only_resolution_for_the_default(settings_store):
"""A default saved over a failed resolution keeps only the pending flag, which alone stops the
first index from starting the implicit download."""
ems._resolved_gguf_memo.clear()
default = ems.default_embedding_model()
ems.set_rag_embedding_model(default, download_pending = True)
assert ems.get_stored_download_pending(default) is True
ems.set_rag_embedding_model("org/other", gguf_repo = "org/other-GGUF", backend = "llama-server")
assert ems.reset_rag_embedding_model() == default
# read the store, not the memo: the reset must preserve what a restart will find
ems._resolved_gguf_memo.clear()
ems._invalidate_cache()
assert ems.get_stored_download_pending(default) is True
def test_pinning_a_model_memoizes_what_was_resolved_for_it(settings_store, monkeypatch):
"""Pinning a model must memoize its resolution too, or a save in the gap moves the job mid-run."""
monkeypatch.delenv("RAG_EMBED_GGUF_REPO", raising = False)
from core.rag import config
ems.set_rag_embedding_model(
"org/embedder-a", gguf_repo = "mirror/off-convention-GGUF", backend = "llama-server"
)
ems._resolved_gguf_memo.clear()
assert config.effective_embedding_model() == "org/embedder-a"
ems.set_rag_embedding_model("org/embedder-b", gguf_repo = None, backend = None)
assert config.effective_gguf_repo_for_embedding_model("org/embedder-a") == (
"mirror/off-convention-GGUF"
)
assert ems.get_stored_backend("org/embedder-a") == "llama-server"
def test_a_fresh_read_sees_a_save_from_another_process(settings_store, monkeypatch):
ems.set_rag_embedding_model("org/first")
assert ems.get_rag_embedding_model() == "org/first"
settings_store[ems.EMBEDDING_MODEL_SETTING_KEY] = "org/second" # no invalidation here
assert ems.get_rag_embedding_model() == "org/first"
assert rag_config.effective_embedding_model(fresh = True) == "org/second"
monkeypatch.setattr("storage.studio_db.get_app_settings", lambda keys: 1 / 0)
with pytest.raises(ZeroDivisionError): # an unconfirmed model never passes a fresh check
rag_config.effective_embedding_model(fresh = True)
def test_the_per_identity_cache_is_bounded(settings_store, monkeypatch):
ems._cached.clear()
ems._generation.clear()
for index in range(ems._CACHE_MAX * 2):
monkeypatch.setattr(ems, "current_account_id", lambda index = index: f"account-{index}")
ems._get_stored_state()
assert len(ems._cached) <= ems._CACHE_MAX
assert (
f"account-{ems._CACHE_MAX * 2 - 1}",
ems.EMBEDDING_RESOLUTION_SETTING_KEY,
) in ems._cached
ems._cached.clear()
ems._generation.clear()