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
import contextvars
import json
import httpx
import pytest
from fastmcp.exceptions import ToolError
from studio_mcp.caller import bind_caller
from studio_mcp.errors import raise_for_payload, raise_for_route, raise_for_status_field, tool_error
from studio_mcp.forward import ndjson_last
from studio_mcp.profile import CHAT
from .mcp_harness import DEFERRED, make_caller, openai_error
SENTINEL = "/srv/mcp-sentinel/models/secret.gguf"
WIN_SENTINEL = "C:\\mcp-sentinel\\models\\secret.gguf"
BUSY = f"Another account is generating on the resident model {SENTINEL}"
BUSY_OUT = "GPU busy: Another account is generating"
def _response(
status,
body = None,
*,
headers = None,
content = None,
):
content = json.dumps(body).encode() if content is None else content
return httpx.Response(
status, content = content, headers = {"content-type": "application/json", **(headers or {})}
)
def _v1(status, message, **fields):
sent = openai_error(message, status, **fields)
return httpx.Response(status, content = sent.body, headers = sent.raw_headers)
def _route(resp, **kwargs):
# An NDJSON stream's caller passes its last line as the payload.
if resp.content.startswith(b'{"type"'):
kwargs["payload"] = ndjson_last(resp.content)
return raise_for_route(resp, **kwargs)
def _message(resp, **kwargs):
with pytest.raises(ToolError) as caught:
_route(resp, **kwargs)
message = str(caught.value)
assert "mcp-sentinel" not in message
return message
def _ndjson(*lines):
return _response(200, content = "\n".join(json.dumps(line) for line in lines).encode())
# A plain {"detail": str} at each status the routes send.
DETAIL_CASES = [
pytest.param(_response(status, {"detail": f"{text} {path}"}), [text, f"(HTTP {status})"], id = id)
for status, text, path, id in [
(404, "Model not found", SENTINEL, "api-detail"),
(499, "Client cancelled", "", "499"),
(501, "STT runtime missing", WIN_SENTINEL, "501-windows-path"),
(401, "Invalid or expired API key", "", "401"),
(403, "Only the installation owner can do this", "", "403"),
]
]
VALIDATION_422 = {
"detail": [
{"loc": ["body", "max_tokens"], "msg": "Input should be a valid integer", "type": "x"},
{"loc": ["query", "name"], "msg": f"bad {SENTINEL}", "type": "value_error"},
]
}
CASES = DETAIL_CASES + [
pytest.param(
_response(409, {"detail": {"message": f"Busy loading {SENTINEL}", "code": "x"}}),
["Busy loading", "(HTTP 409)"],
id = "api-detail-dict",
),
pytest.param(
_v1(404, f"No model {SENTINEL}", type = "not_found_error", code = "model_not_found"),
["[model_not_found] No model", "(HTTP 404)"],
id = "v1-envelope",
),
pytest.param(
_response(
409,
{"error": "gpu_busy", "message": BUSY, "retry_after": 7},
headers = {"Retry-After": "7"},
),
[BUSY_OUT, "Retry after 7 s."],
id = "gpu-busy-unwrapped",
),
pytest.param(
_v1(409, BUSY, type = "conflict_error", code = "gpu_busy", headers = {"Retry-After": "4"}),
[BUSY_OUT, "Retry after 4 s."],
id = "gpu-busy-v1-envelope",
),
pytest.param(
_response(409, {"detail": {"error": "gpu_busy", "message": BUSY, "retry_after": 9}}),
[BUSY_OUT, "Retry after 9 s."],
id = "gpu-busy-detail-wrapped",
),
pytest.param(
_response(409, {"detail": {"error": "download_busy", "retry_after": 1}}),
[
"[download_busy retry_after=1] Another speech-to-text download is running. Retry after 1 s."
],
id = "download-busy-detail",
),
pytest.param(
_v1(400, "messages: Field required", param = "messages"),
["Invalid arguments: messages: Field required"],
id = "v1-validation-400",
),
pytest.param(
_v1(
400,
"response_format is not supported.",
param = "response_format",
code = "unsupported_parameter",
),
["[unsupported_parameter] Invalid arguments: response_format is not supported."],
id = "v1-validation-400-keeps-its-code",
),
pytest.param(
_response(422, VALIDATION_422),
["Invalid arguments: max_tokens: Input should be a valid integer; query.name: bad"],
id = "api-validation-422",
),
pytest.param(
_response(
503,
{"detail": {"error_type": "model_loading", "message": f"Loading {SENTINEL}"}},
headers = {"Retry-After": "30"},
),
["Loading", "(HTTP 503)", "Retry after 30 s."],
id = "systemone-503-retry-after",
),
pytest.param(
_response(
400,
{"detail": f"Not enough memory for 4096x4096 {SENTINEL}"},
headers = {"X-Unsloth-Refusal": "memory-estimate"},
),
["Not enough memory for 4096x4096", "Pass allow_oversized=true to try anyway."],
id = "image-memory-refusal",
),
pytest.param(
_response(502, content = f"Bad gateway {SENTINEL}".encode()),
["Bad gateway", "(HTTP 502)"],
id = "plain-text",
),
pytest.param(
_ndjson({"type": "progress"}, {"type": "error", "message": f"Decoding failed {SENTINEL}"}),
["Decoding failed"],
id = "ndjson-error-line",
),
*[
pytest.param(
_response(
200,
content = b" " * 64
+ json.dumps(
{"_deferred_error": {**d, "detail": f"{d['detail']} {SENTINEL}"}}
).encode(),
),
[d["detail"], f"(HTTP {d['status_code']})"],
id = f"padded-200-deferred-{d['status_code']}",
)
for d in DEFERRED
],
]
@pytest.mark.parametrize("resp,expected", CASES)
def test_route_errors_become_scrubbed_tool_errors(resp, expected):
message = _message(resp)
for text in expected:
assert text in message
@pytest.mark.parametrize(
"resp,expected",
[
(_response(200, content = b" \n " + b'{"status": "loaded"}'), {"status": "loaded"}),
(
_ndjson({"type": "progress"}, {"type": "result", "text": "hi"}),
{"type": "result", "text": "hi"},
),
(httpx.Response(200, content = b"\x89PNG\r\n"), None),
],
ids = ["padded-200", "ndjson-result", "non-json"],
)
def test_a_successful_body_parses(resp, expected):
assert _route(resp) == expected
assert raise_for_payload(None) is None
def test_train_start_status_error_is_an_error():
payload = {"job_id": "", "status": "error", "message": f"Training is in progress {SENTINEL}"}
assert raise_for_route(_response(200, payload)) == payload
with pytest.raises(ToolError) as caught:
raise_for_status_field(payload)
assert str(caught.value).startswith("Training is in progress")
assert "mcp-sentinel" not in str(caught.value)
assert raise_for_status_field({"job_id": "j", "status": "queued"})["job_id"] == "j"
def test_tool_guidance_survives_the_scrub():
hint = "Load one with load_model(kind='image') first, then retry POST /v1/images/generations."
message = _message(_response(409, {"detail": f"No model at {SENTINEL}"}), hints = {409: hint})
assert message == f"No model at <path> (HTTP 409) {hint}"
assert hint not in _message(_response(500, {"detail": "boom"}), hints = {409: hint})
# gpu_busy keeps its retry hint instead of the tool's guidance.
busy = _response(
409,
{"error": "gpu_busy", "message": "Another account is generating.", "retry_after": 3},
headers = {"Retry-After": "3"},
)
message = _message(busy, hints = {409: "x"})
assert message.startswith("[gpu_busy retry_after=3] ")
assert message.endswith(f"] {BUSY_OUT}. Retry after 3 s.")
def test_a_routes_own_call_this_route_hint_is_dropped():
error = tool_error("No model loaded. Call POST /inference/load first.", "Load a chat model.")
assert str(error) == "No model loaded. Load a chat model."
# A path outside a route hint is scrubbed, not dropped.
assert str(tool_error("Saved to /srv/mcp-sentinel/x.png")) == "Saved to <path>"
# The Keep multiple models loaded refusal, as the owner and a managed account see it.
OWNER_ALWAYS = (
"Loading this model would unload the chat model unsloth/Qwen3-0.6B, and Keep multiple models"
" loaded is set to Always. Unload that model first, or choose When they fit."
)
MANAGED_ALWAYS = (
"Loading this model would unload the chat model unsloth/Qwen3-0.6B, which Unsloth Studio is"
" set to keep loaded. Unload that model first, or ask the Unsloth Studio owner."
)
ALWAYS_TAG = "[multi_model_always kind=chat] "
TOOL_HINT = "Wait for the load to finish, then retry."
def _padded(deferred):
return _response(200, content = b" " * 64 + json.dumps({"_deferred_error": deferred}).encode())
def _assert_always(message, tag = ALWAYS_TAG):
assert message.startswith(tag), message
assert "unload_model(kind='llm')" in message
assert "retrying won't help" in message
assert "Retry after" not in message
assert "force_cancel_active" not in message
assert TOOL_HINT not in message
ALWAYS_HEADERS = {"X-Unsloth-Problem": "multi_model_always kind=chat"} # the route's code
@pytest.mark.parametrize(
"resp",
[
_padded({"status_code": 409, "detail": OWNER_ALWAYS, "headers": ALWAYS_HEADERS}),
_response(
409,
{"detail": OWNER_ALWAYS},
headers = {**ALWAYS_HEADERS, "Retry-After": "5"},
),
_response(409, {"detail": MANAGED_ALWAYS}, headers = ALWAYS_HEADERS),
_v1(409, OWNER_ALWAYS, code = "multi_model_always", headers = ALWAYS_HEADERS),
# A route that copies the headers into the padded body; the copy is not the marker text.
_padded(
{
"status_code": 409,
"detail": "Loading this model would unload the chat model x.",
"headers": {"X-UNSLOTH-PROBLEM": "multi_model_always kind=chat"},
}
),
_response(
409, {"detail": {"code": "multi_model_always", "kind": "chat", "message": "No."}}
),
],
ids = ["padded-deferred", "header", "managed-phrase", "v1-code", "deferred-headers", "code"],
)
def test_a_multi_model_always_refusal_is_tagged_and_names_unload_model(resp):
_assert_always(_message(resp, hints = {409: TOOL_HINT}))
def test_a_multi_model_always_refusal_of_an_unknown_kind_keeps_a_bare_tag():
resp = _response(409, {"detail": "No."}, headers = {"X-Unsloth-Problem": "multi_model_always"})
message = _message(resp, hints = {409: TOOL_HINT})
assert message.startswith("[multi_model_always] ")
assert message.endswith(
"Call unload_model(kind=…) for the model it names to free the GPU; retrying won't help."
)
@pytest.mark.parametrize(
"resp",
[
_response(409, {"detail": OWNER_ALWAYS}),
_response(409, {"detail": MANAGED_ALWAYS}),
_response(400, {"detail": "No model loaded."}),
_v1(503, "No GGUF model loaded. Load a GGUF model first."),
],
)
def test_the_wording_alone_is_not_read_as_a_problem(resp):
message = _message(resp)
assert not message.startswith("[") and "load_model" not in message
def test_always_wording_on_another_status_is_not_a_refusal():
message = _message(_response(500, {"detail": "Keep multiple models loaded is set to Always."}))
assert not message.startswith("[")
assert "unload_model" not in message
@pytest.mark.parametrize(
"resp",
[
_response(409, {"error": "gpu_busy", "message": BUSY, "retry_after": 12}),
_response(409, {"detail": {"error": "gpu_busy", "message": BUSY, "retry_after": 12}}),
_v1(409, BUSY, type = "conflict_error", code = "gpu_busy", headers = {"Retry-After": "12"}),
],
ids = ["top-level", "detail-wrapped", "v1-envelope"],
)
def test_gpu_busy_is_tagged_with_its_retry_after(resp):
message = _message(resp, hints = {409: TOOL_HINT})
assert message.startswith("[gpu_busy retry_after=12] GPU busy: Another account")
assert message.endswith("Retry after 12 s.")
assert TOOL_HINT not in message
def test_gpu_busy_without_a_number_keeps_a_bare_tag():
message = _message(_response(409, {"error": "gpu_busy", "message": "Busy."}))
assert message.startswith("[gpu_busy] GPU busy: Busy.")
def test_a_detail_code_becomes_the_tag():
resp = _response(500, {"detail": {"code": "out_of_memory", "message": f"OOM at {SENTINEL}"}})
message = _message(resp)
assert message.startswith("[out_of_memory] OOM at <path>")
assert message.endswith("(HTTP 500)")
# Not a plain identifier: the message stays, the tag goes.
bad = _message(_response(500, {"detail": {"code": "Bad Code!", "message": "boom"}}))
assert bad.startswith("boom")
def test_a_plain_string_detail_has_no_tag():
message = _message(_response(409, {"detail": "Another model is loading"}))
assert not message.startswith("[")
assert message.startswith("Another model is loading (HTTP 409)")
ACTIVE = {
"error": "active_generations",
"message": (
"Unloading would stop 1 chat that is still generating. Stop them first, or retry with"
" force_cancel_active."
),
"running": 1,
"thread_ids": ["thread-secret"],
}
@pytest.mark.parametrize(
"resp",
[_response(409, {"detail": ACTIVE}), _padded({"status_code": 409, "detail": ACTIVE})],
ids = ["direct", "padded"],
)
def test_running_chats_tell_the_agent_to_wait_or_cancel_its_own(resp):
message = _message(resp, hints = {409: TOOL_HINT})
assert message.startswith("[active_generations running=1] Unloading would stop 1 chat")
assert "Stop them first. (HTTP 409)" in message
assert message.endswith("cancel(kind='chat', id=<its cancel_id>).")
assert "Wait for the running chats to finish" in message
assert "thread" not in message
assert "force_cancel_active" not in message
assert TOOL_HINT not in message
def _at(status, body, path):
return httpx.Response(
status,
content = json.dumps(body).encode(),
headers = {"content-type": "application/json"},
request = httpx.Request("POST", f"http://x{path}"),
)
def _tag(kind):
return {"X-Unsloth-Problem": f"not_loaded kind={kind}"}
@pytest.mark.parametrize(
"resp,kind",
[
(_response(400, {"detail": "No model loaded."}, headers = _tag("audio")), "audio"),
(_response(409, {"detail": "No model"}, headers = _tag("stt")), "stt"),
(_v1(400, "No model loaded.", headers = _tag("llm")), "llm"),
(_padded({"status_code": 400, "detail": "No one.", "headers": _tag("image")}), "image"),
],
)
def test_not_loaded_names_the_kind(resp, kind):
assert _message(resp).startswith(f"[not_loaded kind={kind}] No ")
MUSIC = "audio-cpp/audio.cpp-gguf/Stable-Audio-3-Small-Music-GGUF"
def _message_as(chat, resp, **kwargs):
context = contextvars.copy_context()
if chat:
context.run(bind_caller, make_caller(profile = CHAT, direct_local = False))
return context.run(_message, resp, **kwargs)
def _problem(code, status):
headers = {"X-Unsloth-Problem": f"{code} kind=audio model={MUSIC} page=Audio"}
return _v1(status, "Not here.", code = code, headers = headers)
@pytest.mark.parametrize(
"resp, chat, says",
[
(_problem("not_loaded", 400), False, "with load_model(kind='tts') first."),
(_problem("not_loaded", 400), True, "on the Audio page in Unsloth Studio, then try again."),
# Only the user can: no tool, and no hint repeating the route's message.
(_problem("needs_user_load", 403), False, "kind=audio page=Audio] Not here. (HTTP 403)"),
(_problem("needs_user_load", 403), True, "kind=audio page=Audio] Not here. (HTTP 403)"),
(_problem("needs_download", 404), False, f"download_model(model='{MUSIC}', kind='audio')"),
(_problem("needs_download", 404), True, f"download_model(model='{MUSIC}', kind='audio')"),
(_response(409, {"detail": OWNER_ALWAYS}, headers = ALWAYS_HEADERS), True, ""),
(_response(409, {"detail": ACTIVE}), True, ""),
],
)
def test_a_problem_hint_fits_the_callers_tools(resp, chat, says):
message = _message_as(chat, resp, hints = {400: "Load one."})
assert says in message
if chat or "page=Audio]" in says:
# A chat's tools call loads, unloads and cancels nothing itself.
assert "load_model(kind" not in message and "cancel(" not in message
NOISE = [f"load_tensors: layer {i} assigned to device CUDA0" for i in range(300)]
ERRORS = [
"llama_model_load: error loading model: tensor 'blk.0' has wrong shape",
"llama_init_from_model: failed to load model",
"main: exiting due to model loading error",
]
HEAD = "llama-server failed to start (exit code 1)."
LLAMA_FAILURE = (
f"{HEAD}\n\nllama-server output:\n"
+ "\n".join(NOISE[:150] + ERRORS[:1] + NOISE[150:] + ERRORS[1:])
+ "\n\nFull log: /srv/mcp-sentinel/logs/llama.log"
)
@pytest.mark.parametrize(
"error",
[
lambda: tool_error(LLAMA_FAILURE),
lambda: _caught(_response(500, {"detail": LLAMA_FAILURE})),
],
ids = ["tool-error", "route"],
)
def test_llama_server_output_is_cut_to_its_error_lines(error):
message = str(error())
assert message.startswith(HEAD)
assert message.removesuffix(" (HTTP 500)").endswith(ERRORS[-1])
assert len(message) <= 2000
assert "load_tensors" not in message
assert "Full log" not in message
for line in ERRORS:
assert line in message
assert str(tool_error(message)) == message
def _caught(resp):
with pytest.raises(ToolError) as caught:
raise_for_route(resp)
return caught.value
def test_a_tag_that_is_not_a_plain_code_is_dropped():
assert str(tool_error("boom", tag = "Bad Tag")) == "boom"
assert str(tool_error("boom", "Try again.", tag = "out_of_memory")).startswith(
"[out_of_memory] boom Try again."
)
def test_a_hint_never_names_a_tool_the_owner_turned_off(monkeypatch):
from studio_mcp import problems
from utils import mcp_access
monkeypatch.setattr(mcp_access, "disabled_tools", lambda: frozenset({"download_model"}))
tools = problems.caller_tools()
assert "download_model" not in tools and "load_model" in tools
assert problems.download_hint("image", "org/m", tools).startswith("Ask the user to load")
# Unsloth MCP off: every tool counts as off, so no hint names one.
monkeypatch.setattr(mcp_access, "disabled_tools", lambda: None)
assert problems.caller_tools() == frozenset()