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
"""The generate_image chat tool renders on the loaded image model, as the calling account."""
from __future__ import annotations
import asyncio
import os
import threading
from types import SimpleNamespace
import pytest
from fastapi import HTTPException
from PIL import Image
from auth import policy
from core.inference import (
diffusion_engine_router,
generate_image_tool as tool,
gpu_arbiter,
media_chat_tools,
media_keepwarm,
tools,
)
from core.inference.diffusion_families import DIFFUSION_CANCELLED_MSG
from core.inference.generation_ticket import bind_generation_cancel
from core.inference.tool_loop_controller import (
ToolLoopController,
status_for_tool,
strip_result_for_model,
)
from hub.services.models import account_access as access
from models.inference import DiffusionGenerateRequest, DiffusionGenerateResponse, GalleryImage
from routes import inference
from state import active_generations
from utils.account_context import OWNER, AccountContext, run_as
ALICE = AccountContext("a" * 32, "alice")
STATUS = {"loaded": True, "repo_id": "org/public-model", "family": "z-image", "base_repo": None}
class FakeEngine:
def __init__(self, status = None):
self.status_dict = dict(STATUS if status is None else status)
self.calls: list[dict] = []
self.release = threading.Event()
self.started = threading.Event()
self.block = False
self.active = False
self.cancels: list[str] = []
def status(self):
return dict(self.status_dict)
def generate_progress(self):
return {"active": self.active}
def cancel_generate(self, expected_account = None):
self.release.set()
return True
def generate(self, **kwargs):
# Like the real engines: the per-generation event goes to the caller's ticket.
cancel = threading.Event()
bind_generation_cancel(cancel)
self.calls.append(kwargs)
self.started.set()
if self.block:
cancel.wait(20)
raise RuntimeError(DIFFUSION_CANCELLED_MSG)
size = (kwargs.get("width") or 1024, kwargs.get("height") or 1024)
return {
"images": [Image.new("RGB", size, "blue")],
"seed": 7,
"repo_id": "org/public-model",
}
@pytest.fixture(autouse = True)
def isolated(monkeypatch, tmp_path):
monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "home"))
monkeypatch.setattr(policy, "installation_is_multi_user", lambda: True)
monkeypatch.setattr(access, "_resident_accounts", {})
monkeypatch.setattr(access, "_generation_accounts", {})
monkeypatch.setattr(access, "repo_is_public", lambda *a, **k: True)
monkeypatch.setattr(gpu_arbiter, "_owner", None)
monkeypatch.setattr(gpu_arbiter, "_owner_account", None)
monkeypatch.setattr(tool, "_STOP_WAIT_S", 5.0)
monkeypatch.setattr(inference, "_enabled_agent_skills", lambda: [])
monkeypatch.setattr(inference, "_thread_has_conversation_archive", lambda _: False)
active_generations.reset_for_tests()
yield
active_generations.reset_for_tests()
@pytest.fixture
def engine(monkeypatch):
fake = FakeEngine()
monkeypatch.setitem(media_keepwarm._ENGINES, gpu_arbiter.DIFFUSION, lambda: fake)
monkeypatch.setitem(media_keepwarm._ENGINES, gpu_arbiter.VIDEO, lambda: None)
monkeypatch.setattr(diffusion_engine_router, "get_active_diffusion_engine", lambda: fake)
return fake
@pytest.fixture
def server_loop(monkeypatch):
loop = asyncio.new_event_loop()
thread = threading.Thread(target = loop.run_forever, daemon = True)
thread.start()
monkeypatch.setattr(media_chat_tools, "_server_loop", loop)
yield loop
loop.call_soon_threadsafe(loop.stop)
thread.join(5)
loop.close()
@pytest.fixture
def keepwarm(monkeypatch):
counts = {"begin": 0, "end": 0}
async def begin(owner):
assert owner == gpu_arbiter.DIFFUSION
counts["begin"] += 1
def end(owner, *, counted = True):
counts["end"] += 1
monkeypatch.setattr(media_keepwarm, "begin_request", begin)
monkeypatch.setattr(media_keepwarm, "end_request", end)
return counts
def _alice_loaded(monkeypatch):
monkeypatch.setattr(gpu_arbiter, "_owner", gpu_arbiter.DIFFUSION)
monkeypatch.setattr(gpu_arbiter, "_owner_account", ALICE.account_id)
def _in_thread(account, fn, *args, **kwargs):
"""Run like the chat tool loop does: on a worker thread bound to the caller's account."""
out = {}
thread = threading.Thread(target = lambda: out.update(r = run_as(account, fn, *args, **kwargs)))
thread.start()
thread.join(60)
return out["r"]
def _select(enabled, *, tools_on = True):
payload = SimpleNamespace(enabled_tools = enabled, rag_scope = None, bypass_permissions = False)
async def go():
selected = await inference._select_request_tools(
payload, tools_on = tools_on, mcp_allowed = False, supports_vision = True
)
return selected, asyncio.get_running_loop()
selected, loop = asyncio.run(go())
return {t["function"]["name"]: t for t in selected}, loop
def test_offered_only_while_a_usable_text_to_image_model_is_loaded(engine, monkeypatch):
media_chat_tools._server_loop = None
names, loop = _select(["generate_image"])
assert "generate_image" in names and media_chat_tools._server_loop is loop
assert "generate_image" not in _select(["web_search"])[0]
assert "generate_image" not in _select(None)[0]
assert "generate_image" not in _select(["generate_image"], tools_on = False)[0]
# A video model isn't loaded, so its tool isn't offered alongside.
assert "generate_video" not in _select(["generate_image", "generate_video"])[0]
engine.status_dict["workflows"] = ["edit"]
assert "generate_image" not in _select(["generate_image"])[0]
engine.status_dict["workflows"] = ["txt2img", "edit"]
assert "generate_image" in _select(["generate_image"])[0]
engine.status_dict["loaded"] = False
assert "generate_image" not in _select(["generate_image"])[0]
engine.status_dict["loaded"] = True
monkeypatch.setattr(access, "resident_hidden", lambda *a, **k: True)
assert "generate_image" not in _select(["generate_image"])[0]
def test_a_managed_account_refused_the_model_is_not_offered_it(engine, monkeypatch):
def refuse(status, modality):
raise HTTPException(status_code = 403, detail = "not allowed")
_alice_loaded(monkeypatch)
assert "generate_image" in run_as(ALICE, _select, ["generate_image"])[0]
monkeypatch.setattr(access, "require_media_generation_access", refuse)
assert "generate_image" in _select(["generate_image"])[0] # the owner is never refused
assert "generate_image" not in run_as(ALICE, _select, ["generate_image"])[0]
def test_unselected_loop_is_not_remembered(engine):
media_chat_tools._server_loop = None
_select(["web_search"])
assert media_chat_tools._server_loop is None
@pytest.mark.parametrize("supports", [True, False])
def test_negative_prompt_follows_the_model_family(supports):
status = {**STATUS, "supports_negative_prompt": supports, "prompt_hint": "Use tags."}
schema = tool.generate_image_schema(status)["function"]
assert ("negative_prompt" in schema["parameters"]["properties"]) is supports
assert schema["parameters"]["required"] == ["prompt"]
assert schema["description"].endswith(" Use tags.")
assert "Unsloth Studio" in schema["description"]
def test_managed_account_run_lands_in_its_own_gallery(
engine, server_loop, keepwarm, monkeypatch, tmp_path
):
_alice_loaded(monkeypatch)
checked = []
real_check = access.require_media_generation_access
monkeypatch.setattr(
access,
"require_media_generation_access",
lambda status, modality: (checked.append(modality), real_check(status, modality))[1],
)
workdir = tmp_path / "work"
monkeypatch.setattr(tools, "_get_workdir", lambda session_id = None: str(workdir))
result = _in_thread(
ALICE,
tools.execute_tool,
"generate_image",
{"prompt": "a sloth\n on a branch", "width": 512, "height": 512},
session_id = "s",
)
assert result.startswith("Generated a 512x512 image (seed 7)"), result
assert "Prompt used: a sloth on a branch" in result
assert checked and set(checked) == {"diffusion"}
from core.inference import image_gallery
alice_ids = run_as(ALICE, lambda: [p.stem for p in image_gallery.gallery_dir().glob("*.png")])
owner_dir = run_as(OWNER, image_gallery.gallery_dir)
assert len(alice_ids) == 1 and not list(owner_dir.glob("*.png"))
saved = workdir / f"generated-image-{alice_ids[0][:8]}.png"
assert saved.is_file() and Image.open(saved).size == (512, 512)
assert keepwarm == {"begin": 1, "end": 1}
@pytest.mark.parametrize(
"status, expected",
[
({"generation_defaults": {"steps": 28, "guidance": 3.5}}, (28, 3.5)),
# sd.cpp and MLX report no recipe; the family table decides from the base repo.
({"repo_id": "/models/my-flux", "base_repo": "black-forest-labs/FLUX.1-dev"}, (20, 3.5)),
],
)
def test_omitted_steps_and_guidance_follow_the_loaded_model(
engine, server_loop, keepwarm, monkeypatch, tmp_path, status, expected
):
engine.status_dict.update(status)
monkeypatch.setattr(tools, "_get_workdir", lambda session_id = None: str(tmp_path / "w"))
result = _in_thread(
OWNER, tools.execute_tool, "generate_image", {"prompt": "p"}, session_id = "s"
)
assert result.startswith("Generated a 1024x1024 image"), result
assert (engine.calls[0]["steps"], engine.calls[0]["guidance"]) == expected
def test_the_core_runs_under_the_account_bound_in_the_coroutine(
engine, server_loop, keepwarm, monkeypatch, tmp_path
):
import utils.account_context as account_context
bound = []
real = account_context.arun_as
def spy(account, awaitable):
bound.append(account)
return real(account, awaitable)
monkeypatch.setattr(account_context, "arun_as", spy)
_alice_loaded(monkeypatch)
result = _in_thread(
ALICE, tool.run_generate_image, {"prompt": "x"}, workdir = str(tmp_path), timeout = 30
)
assert result.startswith("Generated"), result
assert bound == [ALICE]
def _fake_core(monkeypatch, behaviour):
seen = []
async def core(request):
seen.append(request)
return await behaviour(request)
monkeypatch.setattr(inference, "_generate_diffusion_image_core", core)
return seen
def _response(tmp_path, monkeypatch):
from core.inference import image_gallery
png = tmp_path / "abcdef0123456789.png"
Image.new("RGB", (1024, 768)).save(png)
monkeypatch.setattr(image_gallery, "image_path", lambda image_id: png)
record = {
"id": "abcdef0123456789",
"url": "/x",
"prompt": "p",
"width": 1024,
"height": 768,
"steps": 9,
"guidance": 0.0,
"seed": 3,
"created_at": 0.0,
}
return DiffusionGenerateResponse(images = [GalleryImage(**record)])
def test_omitted_settings_are_not_sent_and_sizes_snap(engine, server_loop, monkeypatch, tmp_path):
response = _response(tmp_path, monkeypatch)
async def ok(request):
return response
seen = _fake_core(monkeypatch, ok)
work = tmp_path / "w"
tool.run_generate_image({"prompt": "x", "width": 1030, "height": 100}, workdir = str(work))
tool.run_generate_image({"prompt": "x", "negative_prompt": "blur"}, workdir = str(work))
first, second = seen
assert "steps" not in first.model_fields_set and "guidance" not in first.model_fields_set
assert (first.width, first.height) == (1024, 256)
assert first.model_fields_set == {"prompt", "width", "height"}
assert second.negative_prompt is None # the family has no negative prompt
engine.status_dict["supports_negative_prompt"] = True
tool.run_generate_image({"prompt": "x", "negative_prompt": "blur"}, workdir = str(work))
assert seen[-1].negative_prompt == "blur"
def test_sentinels_stay_out_of_the_model_text(engine, server_loop, monkeypatch, tmp_path):
response = _response(tmp_path, monkeypatch)
async def ok(request):
return response
_fake_core(monkeypatch, ok)
result = tool.run_generate_image({"prompt": "x"}, workdir = str(tmp_path / "w"))
assert '\n__FILES__:[{"name": "generated-image-abcdef01.png"' in result
assert result.endswith('\n__IMAGES__:["generated-image-abcdef01.png"]')
assert (tmp_path / "w" / "generated-image-abcdef01.png").is_file()
stripped = strip_result_for_model(result, "generate_image")
assert "__FILES__" not in stripped and "__IMAGES__" not in stripped
assert stripped.startswith("Generated a 1024x768 image (seed 3)")
@pytest.mark.parametrize(
"error, expected",
[
(gpu_arbiter.GpuBusyForAnotherAccountError("chat", 1), tool.ERR_OTHER_ACCOUNT),
(
HTTPException(409, detail = {"error": "gpu_busy", "message": "busy"}),
tool.ERR_OTHER_ACCOUNT,
),
(HTTPException(400, detail = "Width too large for this model."), "Error: Width too large"),
(HTTPException(409, detail = "Model was replaced."), "Error: Model was replaced."),
(HTTPException(500, detail = "Image generation failed: OOM"), "Error: Image generation"),
(HTTPException(404, detail = {"error": {"message": "Model not found"}}), "Error: Model not"),
(HTTPException(409, detail = DIFFUSION_CANCELLED_MSG), tool.ERR_STOPPED),
(RuntimeError("boom"), "Error: image generation failed: boom"),
],
)
def test_failures_become_error_strings(engine, server_loop, monkeypatch, tmp_path, error, expected):
async def fail(request):
raise error
_fake_core(monkeypatch, fail)
assert tool.run_generate_image({"prompt": "x"}, workdir = str(tmp_path)).startswith(expected)
def test_refusals_before_any_render(engine, server_loop, monkeypatch, tmp_path):
run = lambda args: tool.run_generate_image(args, workdir = str(tmp_path)) # noqa: E731
assert run({"prompt": " "}) == tool.ERR_NO_PROMPT
assert run("not a dict") == tool.ERR_NO_PROMPT
engine.active = True
assert run({"prompt": "x"}) == tool.ERR_BUSY
engine.active = False
engine.status_dict["workflows"] = ["edit"]
assert run({"prompt": "x"}) == tool.ERR_EDIT_ONLY
engine.status_dict["loaded"] = False
assert run({"prompt": "x"}) == tool.ERR_NOT_LOADED
monkeypatch.setattr(media_chat_tools, "_server_loop", None)
assert run({"prompt": "x"}) == tool.ERR_NO_LOOP
assert not engine.calls
@pytest.mark.parametrize("how", ["cancel", "timeout"])
def test_stop_and_timeout_stop_the_engine_too(
engine, server_loop, keepwarm, monkeypatch, tmp_path, how
):
_alice_loaded(monkeypatch)
engine.block = True
cancel = threading.Event()
if how == "cancel":
threading.Thread(target = lambda: engine.started.wait(20) and cancel.set()).start()
result = _in_thread(
ALICE,
tool.run_generate_image,
{"prompt": "x"},
workdir = str(tmp_path),
cancel_event = cancel,
timeout = 2 if how == "timeout" else 60,
)
assert result == (tool.ERR_STOPPED if how == "cancel" else tool.ERR_TIMEOUT)
# The run unwound before the tool returned: the keep-warm count is already closed.
assert keepwarm == {"begin": 1, "end": 1}
assert not os.listdir(tmp_path)
def test_a_render_that_finishes_inside_the_stop_window_is_still_returned(
engine, server_loop, keepwarm, monkeypatch, tmp_path
):
# The timeout lands at the last step: the engine finishes the image instead of cancelling.
_alice_loaded(monkeypatch)
finish = engine.generate
def generate(**kwargs):
cancel = threading.Event()
bind_generation_cancel(cancel)
engine.started.set()
cancel.wait(20)
return finish(**kwargs)
monkeypatch.setattr(engine, "generate", generate)
result = _in_thread(
ALICE, tool.run_generate_image, {"prompt": "x"}, workdir = str(tmp_path), timeout = 1
)
assert result.startswith("Generated a 1024x1024 image"), result
assert [n for n in os.listdir(tmp_path) if n.startswith("generated-image-")]
def test_keepwarm_counts_once_per_tool_call_and_never_in_the_core(
engine, server_loop, keepwarm, tmp_path
):
assert media_keepwarm.owner_for_path("/api/inference/images/generate") == gpu_arbiter.DIFFUSION
asyncio.run(inference._generate_diffusion_image_core(DiffusionGenerateRequest(prompt = "x")))
assert keepwarm == {"begin": 0, "end": 0}
for _ in range(2):
tool.run_generate_image({"prompt": "x"}, workdir = str(tmp_path))
assert keepwarm == {"begin": 2, "end": 2}
def test_registries_treat_both_media_tools_alike():
from core.inference.tool_loop_controller import (
_FILE_SENTINEL_TOOLS,
_IMAGE_SENTINEL_TOOLS,
REPEATABLE_TOOL_NAMES,
)
for name in ("generate_image", "generate_video"):
assert not tools.is_potentially_unsafe_tool_call(name, {"prompt": "x"})
assert name in _FILE_SENTINEL_TOOLS and name in REPEATABLE_TOOL_NAMES
assert name in inference._ANTHROPIC_UNPROMPTED_SAFE_TOOLS
assert "generate_image" in _IMAGE_SENTINEL_TOOLS
assert "generate_video" not in _IMAGE_SENTINEL_TOOLS
assert (
status_for_tool("generate_image", {"prompt": "p" * 99}) == "Generating image: " + "p" * 60
)
assert status_for_tool("generate_video", {"prompt": "dog"}) == "Generating video: dog"
def test_anthropic_never_selects_media_tools(engine):
picked = inference._select_anthropic_server_tools(
tools.ALL_TOOLS, {"generate_image", "generate_video"}, ["generate_image", "web_search"]
)
assert [t["function"]["name"] for t in picked] == ["web_search"]
assert not {t["function"]["name"] for t in tools.ALL_TOOLS} & media_chat_tools.MEDIA_CHAT_TOOLS
def test_the_same_prompt_twice_is_two_renders():
controller = ToolLoopController(tools = [tool.generate_image_schema(STATUS)])
call = {"id": "g", "function": {"name": "generate_image", "arguments": '{"prompt":"x"}'}}
first = controller.prepare_call(call)
controller.record_result(first, "Generated a 1024x1024 image.")
assert controller.prepare_call(call).action == "execute"
def test_stopping_a_queued_call_never_cancels_the_render_ahead_of_it(
engine, server_loop, keepwarm, monkeypatch, tmp_path
):
# A render holds the engine first, so stopping the chat must cancel only its own queued run.
_alice_loaded(monkeypatch)
lock = threading.Lock()
other_cancel = threading.Event()
other_done = threading.Event()
account_wide = []
ran = []
def cancel_generate(expected_account = None):
account_wide.append(expected_account)
other_cancel.set()
return True
def generate(**kwargs):
cancel = threading.Event()
bind_generation_cancel(cancel)
engine.started.set()
while not lock.acquire(timeout = 0.05):
if cancel.is_set():
raise RuntimeError(DIFFUSION_CANCELLED_MSG)
try:
ran.append(kwargs)
raise RuntimeError(DIFFUSION_CANCELLED_MSG)
finally:
lock.release()
holding = threading.Event()
def other_render():
with lock:
holding.set()
other_cancel.wait(3)
other_done.set()
monkeypatch.setattr(engine, "cancel_generate", cancel_generate)
monkeypatch.setattr(engine, "generate", generate)
# What the router does for a real engine: cancel whatever render the account has active.
monkeypatch.setattr(
diffusion_engine_router,
"cancel_generation_for_account",
lambda account_id: engine.cancel_generate(expected_account = account_id),
)
holder = threading.Thread(target = other_render)
holder.start()
assert holding.wait(10)
stop = threading.Event()
threading.Thread(target = lambda: engine.started.wait(20) and stop.set()).start()
result = _in_thread(
ALICE,
tool.run_generate_image,
{"prompt": "x"},
workdir = str(tmp_path),
cancel_event = stop,
timeout = 60,
)
holder.join(10)
assert result == tool.ERR_STOPPED
assert not other_cancel.is_set() and not account_wide
assert other_done.is_set() and not ran
def test_sizes_follow_the_loaded_family_grid_and_bounds(engine, server_loop, monkeypatch, tmp_path):
response = _response(tmp_path, monkeypatch)
async def ok(request):
return response
seen = _fake_core(monkeypatch, ok)
engine.status_dict["conditioning"] = {
"dimension_multiple": 32,
"max_output_side": 2752,
"max_output_pixels": 2400 * 1792,
}
schema = tool.generate_image_schema(engine.status_dict)
width_doc = schema["function"]["parameters"]["properties"]["width"]["description"]
assert "multiple of 32" in width_doc and "2752" in width_doc
work = str(tmp_path / "w")
tool.run_generate_image({"prompt": "x", "width": 1280, "height": 720}, workdir = work)
tool.run_generate_image({"prompt": "x", "width": 2752, "height": 2752}, workdir = work)
engine.status_dict["conditioning"] = {
"dimension_multiple": 16,
"max_output_side": 2048,
"max_output_pixels": 2048 * 2048,
}
tool.run_generate_image({"prompt": "x", "width": 2752}, workdir = work)
from core.inference.diffusion_conditioning import check_output_size
fams = [
SimpleNamespace(dimension_multiple = 32, max_output_side = 2752, max_output_pixels = 2400 * 1792),
] * 2 + [
SimpleNamespace(dimension_multiple = 16, max_output_side = 2048, max_output_pixels = 2048 * 2048)
]
for fam, request in zip(fams, seen):
check_output_size(fam, request.width, request.height) # the route's own check accepts it
assert (seen[0].width, seen[0].height) == (1280, 704)
assert (seen[2].width, seen[2].height) == (2048, 1024)