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.

21.1 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""tool_call arguments must become dicts before rendering, as strict templates call arguments.items()."""

from __future__ import annotations

import json
import sys
from pathlib import Path

import pytest

_BACKEND = Path(__file__).resolve().parent.parent
if str(_BACKEND) not in sys.path:
    sys.path.insert(0, str(_BACKEND))

from core.inference.chat_template_helpers import (  # noqa: E402
    _normalize_tool_call_arguments,
    _split_parallel_tool_calls,
    apply_chat_template_for_generation,
)


def _conv(arguments):
    return [
        {"role": "user", "content": "weather?"},
        {
            "role": "assistant",
            "content": "",
            "tool_calls": [
                {
                    "type": "function",
                    "id": "c1",
                    "function": {"name": "web_search", "arguments": arguments},
                }
            ],
        },
        {"role": "tool", "name": "web_search", "content": "21C sunny"},
    ]


class _StrictTemplateTokenizer:
    """Mimics a strict Qwen tool template: rejects string tool_call arguments."""

    def apply_chat_template(
        self,
        messages,
        *,
        tokenize = False,
        add_generation_prompt = True,
        **kw,
    ):
        for msg in messages:
            for call in msg.get("tool_calls", []) or []:
                args = call.get("function", {}).get("arguments")
                if isinstance(args, str):
                    raise TypeError("Can only get item pairs from a mapping.")
        return "RENDERED"


class _StrictToolOrderTokenizer:
    def __init__(self):
        self.seen_messages = []

    def apply_chat_template(
        self,
        messages,
        *,
        tokenize = False,
        add_generation_prompt = True,
        **kw,
    ):
        self.seen_messages.append(messages)
        for index, message in enumerate(messages):
            if message.get("role") == "tool":
                previous = messages[index - 1] if index else {}
                if previous.get("role") not in ("assistant", "tool"):
                    raise ValueError("A tool message must follow an assistant or tool message.")
        return "RENDERED"


def test_string_arguments_are_parsed_to_dict():
    out = _normalize_tool_call_arguments(_conv('{"query": "sweden"}'))
    args = out[1]["tool_calls"][0]["function"]["arguments"]
    assert args == {"query": "sweden"}


def test_dict_arguments_untouched_and_no_copy():
    conv = _conv({"query": "sweden"})
    assert _normalize_tool_call_arguments(conv) is conv


def test_non_json_string_left_as_is():
    out = _normalize_tool_call_arguments(_conv("not json"))
    assert out[1]["tool_calls"][0]["function"]["arguments"] == "not json"


def test_render_succeeds_on_strict_template_with_string_arguments():
    result = apply_chat_template_for_generation(_StrictTemplateTokenizer(), _conv('{"query": "x"}'))
    assert result == "RENDERED"


def test_render_repairs_orphan_tool_result_after_native_template_failure():
    tok = _StrictToolOrderTokenizer()
    messages = [
        {"role": "user", "content": "weather?"},
        {"role": "tool", "name": "web_search", "content": "21C sunny"},
    ]

    assert apply_chat_template_for_generation(tok, messages) == "RENDERED"
    repaired = tok.seen_messages[-1]
    assert [message["role"] for message in repaired] == ["user", "assistant", "tool"]
    assert repaired[1]["tool_calls"][0]["id"] == "replayed_tool_1"
    assert repaired[2]["tool_call_id"] == "replayed_tool_1"


class _CallLinkedToolTokenizer:
    """gpt-oss rule: each result answers a call of the preceding assistant; no two assistant turns in a row."""

    def __init__(self):
        self.seen_messages = []

    def apply_chat_template(
        self,
        messages,
        *,
        tokenize = False,
        add_generation_prompt = True,
        **kw,
    ):
        self.seen_messages.append(messages)
        call_ids = None
        previous_role = None
        for message in messages:
            role = message.get("role")
            if role == "assistant" and previous_role == "assistant":
                raise ValueError("Conversation roles must alternate")
            if role == "assistant":
                call_ids = {call.get("id") for call in message.get("tool_calls") or ()}
            elif role == "tool":
                if not call_ids or message.get("tool_call_id") not in call_ids:
                    raise ValueError(
                        "Message has tool role, but there was no previous assistant message with a tool call!"
                    )
            else:
                call_ids = None
            previous_role = role
        return "RENDERED"


def test_render_gives_an_assistant_text_turn_the_orphan_call():
    tok = _CallLinkedToolTokenizer()
    messages = [
        {"role": "user", "content": "weather?"},
        {"role": "assistant", "content": "checking"},
        {"role": "tool", "tool_call_id": "c1", "name": "web_search", "content": "21C sunny"},
    ]

    assert apply_chat_template_for_generation(tok, messages) == "RENDERED"
    repaired = tok.seen_messages[-1]
    assert [message["role"] for message in repaired] == ["user", "assistant", "tool"]
    assert repaired[1]["content"] == "checking"
    assert [call["id"] for call in repaired[1]["tool_calls"]] == ["c1"]
    assert "tool_calls" not in messages[1]


class _FirstCallNamesResultsTokenizer(_CallLinkedToolTokenizer):
    def apply_chat_template(self, messages, **kw):
        super().apply_chat_template(messages, **kw)
        lines, last = [], None
        for message in messages:
            if message.get("tool_calls"):
                last = message["tool_calls"][0]["function"]["name"]
            elif message.get("role") == "tool":
                lines.append(f"functions.{last}: {message['content']}")
        return "\n".join(lines)


def test_render_gives_each_orphan_result_its_own_call():
    tok = _FirstCallNamesResultsTokenizer()
    messages = [
        {"role": "user", "content": "weather?"},
        {"role": "tool", "tool_call_id": "c1", "name": "web_search", "content": "21C sunny"},
        {"role": "tool", "name": "web_fetch", "content": "rain later"},
    ]

    rendered = apply_chat_template_for_generation(tok, messages)
    assert rendered == "functions.web_search: 21C sunny\nfunctions.web_fetch: rain later"
    repaired = tok.seen_messages[-1]
    assert [message["role"] for message in repaired] == [
        "user",
        "assistant",
        "tool",
        "assistant",
        "tool",
    ]
    assert [m["tool_calls"][0]["id"] for m in repaired if m.get("tool_calls")] == [
        "c1",
        "replayed_tool_3",
    ]
    assert repaired[4]["tool_call_id"] == "replayed_tool_3"


def test_orphan_repair_is_idempotent_and_leaves_linked_results_alone():
    from core.inference.chat_template_helpers import _repair_orphan_tool_results

    messages = [
        {"role": "user", "content": "weather?"},
        {"role": "tool", "name": "web_search", "content": "21C sunny"},
        {"role": "assistant", "content": "", "tool_calls": [{"id": "c2"}]},
        {"role": "tool", "tool_call_id": "c2", "content": "rain"},
    ]
    snapshot = json.loads(json.dumps(messages))

    repaired = _repair_orphan_tool_results(messages)
    assert [message["role"] for message in repaired] == [
        "user",
        "assistant",
        "tool",
        "assistant",
        "tool",
    ]
    assert repaired[3:] == messages[2:]
    assert _repair_orphan_tool_results(repaired) is repaired
    assert messages == snapshot


def test_render_keeps_valid_tool_result_history_unchanged():
    tok = _StrictToolOrderTokenizer()
    messages = [
        {"role": "assistant", "content": "", "tool_calls": [{"id": "c1"}]},
        {"role": "tool", "tool_call_id": "c1", "content": "21C sunny"},
    ]

    assert apply_chat_template_for_generation(tok, messages) == "RENDERED"
    assert tok.seen_messages == [messages]


class _RecordingTokenizer:
    """Lenient template: renders whatever arguments it is given (string or dict)."""

    def __init__(self):
        self.seen_arguments = None

    def apply_chat_template(
        self,
        messages,
        *,
        tokenize = False,
        add_generation_prompt = True,
        **kw,
    ):
        for msg in messages:
            for call in msg.get("tool_calls", []) or []:
                self.seen_arguments = call.get("function", {}).get("arguments")
        return "RENDERED"


def test_lenient_template_receives_arguments_as_a_mapping():
    tok = _RecordingTokenizer()
    apply_chat_template_for_generation(tok, _conv('{"query": "x"}'))
    assert tok.seen_arguments == {"query": "x"}


_QWEN35_TOOL_CALL_TEMPLATE = """
{%- for message in messages %}
{%- if message.tool_calls %}
{%- for tool_call in message.tool_calls %}
{%- if tool_call.function is defined %}{%- set tool_call = tool_call.function %}{%- endif %}
{{- '<tool_call>\\n<function=' + tool_call.name + '>\\n' }}
{%- if tool_call.arguments is mapping %}
{%- for args_name in tool_call.arguments %}
{%- set args_value = tool_call.arguments[args_name] %}
{{- '<parameter=' + args_name + '>\\n' }}
{%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}
{{- args_value }}
{{- '\\n</parameter>\\n' }}
{%- endfor %}
{%- endif %}
{{- '</function>\\n</tool_call>' }}
{%- endfor %}
{%- endif %}
{%- endfor %}
"""


class _JinjaTokenizer:
    def __init__(self, template):
        self.chat_template = template

    def apply_chat_template(self, messages, **kwargs):
        from transformers.utils.chat_template_utils import _compile_jinja_template
        return _compile_jinja_template(self.chat_template).render(messages = messages)


def test_qwen35_template_sees_the_arguments_of_an_earlier_call():
    prompt = apply_chat_template_for_generation(
        _JinjaTokenizer(_QWEN35_TOOL_CALL_TEMPLATE), _conv('{"query": "gpu prices"}')
    )
    assert "<parameter=query>\ngpu prices\n</parameter>" in prompt


def test_template_that_concatenates_string_arguments_still_renders_them():
    template = (
        "{%- for message in messages %}{%- for tool_call in message.tool_calls or [] %}"
        "{{- tool_call.function.name + ' ' + tool_call.function.arguments }}"
        "{%- endfor %}{%- endfor %}"
    )
    prompt = apply_chat_template_for_generation(_JinjaTokenizer(template), _conv('{"query": "x"}'))
    assert prompt == 'web_search {"query": "x"}'


class _SeparateStringToolTemplateTokenizer:
    def apply_chat_template(
        self,
        messages,
        *,
        tools = None,
        **kwargs,
    ):
        if tools is None:
            return "DEFAULT"
        arguments = messages[1]["tool_calls"][0]["function"]["arguments"]
        return "TOOL " + arguments


def test_string_arguments_retry_before_dropping_the_tools_template():
    prompt = apply_chat_template_for_generation(
        _SeparateStringToolTemplateTokenizer(),
        _conv('{"query": "x"}'),
        tools = [{"type": "function", "function": {"name": "web_search"}}],
    )
    assert prompt == 'TOOL {"query": "x"}'


def test_deeply_nested_arguments_are_left_as_a_string():
    arguments = '{"x":' + "[" * 10000 + "0" + "]" * 10000 + "}"
    conv = _conv(arguments)
    assert _normalize_tool_call_arguments(conv) is conv


def test_messages_without_tool_calls_pass_through_unchanged():
    conv = [{"role": "user", "content": "hi"}]
    assert _normalize_tool_call_arguments(conv) is conv


class _RaiseExceptionTemplateTokenizer:
    """Mimics the bundled gemma-4.jinja: rejects string tool_call arguments via
    ``raise_exception(...)``, which surfaces as a Jinja error, NOT a TypeError."""

    def apply_chat_template(
        self,
        messages,
        *,
        tokenize = False,
        add_generation_prompt = True,
        **kw,
    ):
        for msg in messages:
            for call in msg.get("tool_calls", []) or []:
                args = call.get("function", {}).get("arguments")
                if isinstance(args, str):
                    raise ValueError(
                        "chat_template: tool_calls[].function.arguments must be a "
                        "JSON object (mapping), not a string."
                    )
        return "RENDERED"


def test_render_succeeds_on_raise_exception_template_with_string_arguments():
    result = apply_chat_template_for_generation(
        _RaiseExceptionTemplateTokenizer(), _conv('{"query": "x"}')
    )
    assert result == "RENDERED"


def test_unrelated_template_error_still_propagates_with_dict_args():
    class _AlwaysRaises:
        def apply_chat_template(self, messages, **kw):
            raise ValueError("template is broken")

    with pytest.raises(ValueError, match = "broken"):
        apply_chat_template_for_generation(_AlwaysRaises(), _conv({"query": "x"}))


def _parallel_conv(
    *,
    ids = ("c1", "c2"),
    results_have_ids = True,
    content = "sure",
):
    a, b = ids
    return [
        {"role": "user", "content": "search then render"},
        {
            "role": "assistant",
            "content": content,
            "tool_calls": [
                {
                    "type": "function",
                    "id": a,
                    "function": {"name": "web_search", "arguments": {"query": "x"}},
                },
                {
                    "type": "function",
                    "id": b,
                    "function": {"name": "render_html", "arguments": {"html": "<canvas>"}},
                },
            ],
        },
        {
            "role": "tool",
            "name": "web_search",
            **({"tool_call_id": a} if results_have_ids else {}),
            "content": "no text",
        },
        {
            "role": "tool",
            "name": "render_html",
            **({"tool_call_id": b} if results_have_ids else {}),
            "content": "ok",
        },
    ]


class _SingleToolCallTokenizer:
    """Mimics the Llama 3.x template: rejects >1 call per message."""

    def apply_chat_template(
        self,
        messages,
        *,
        tokenize = False,
        add_generation_prompt = True,
        **kw,
    ):
        for msg in messages:
            if len(msg.get("tool_calls") or ()) > 1:
                raise ValueError("This model only supports single tool-calls at once!")
        return "RENDERED"


def test_parallel_calls_split_into_sequential_single_call_turns():
    out = _split_parallel_tool_calls(_parallel_conv())
    assert [(m["role"], m.get("name")) for m in out] == [
        ("user", None),
        ("assistant", None),
        ("tool", "web_search"),
        ("assistant", None),
        ("tool", "render_html"),
    ]
    assert [len(m["tool_calls"]) for m in out if m.get("tool_calls")] == [1, 1]
    assert out[1]["tool_calls"][0]["function"]["name"] == "web_search"
    assert out[3]["tool_calls"][0]["function"]["name"] == "render_html"


def test_split_pairs_results_by_tool_call_id_not_position():
    conv = _parallel_conv()
    conv[2], conv[3] = conv[3], conv[2]
    out = _split_parallel_tool_calls(conv)
    assert out[1]["tool_calls"][0]["id"] == "c1" and out[2]["tool_call_id"] == "c1"
    assert out[3]["tool_calls"][0]["id"] == "c2" and out[4]["tool_call_id"] == "c2"


def test_split_falls_back_to_order_when_results_have_no_ids():
    out = _split_parallel_tool_calls(_parallel_conv(results_have_ids = False))
    assert [m["role"] for m in out] == ["user", "assistant", "tool", "assistant", "tool"]
    assert out[2]["name"] == "web_search" and out[4]["name"] == "render_html"


def test_split_keeps_content_on_first_piece_only():
    out = _split_parallel_tool_calls(_parallel_conv(content = "sure"))
    assert out[1]["content"] == "sure"
    assert out[3]["content"] == ""


def test_split_keeps_unmatched_results_after_the_split():
    conv = _parallel_conv()
    del conv[3]
    out = _split_parallel_tool_calls(conv)
    assert [m["role"] for m in out] == ["user", "assistant", "tool", "assistant"]


def test_split_leaves_later_turns_intact():
    conv = _parallel_conv() + [
        {"role": "assistant", "content": "done"},
        {"role": "user", "content": "thanks"},
    ]
    out = _split_parallel_tool_calls(conv)
    assert [m["role"] for m in out[-2:]] == ["assistant", "user"]
    assert out[-2]["content"] == "done"


def test_single_call_and_plain_conversations_pass_through_unchanged():
    conv = _conv({"query": "x"})
    assert _split_parallel_tool_calls(conv) is conv
    plain = [{"role": "user", "content": "hi"}]
    assert _split_parallel_tool_calls(plain) is plain


def test_render_succeeds_on_single_call_template_with_parallel_calls():
    result = apply_chat_template_for_generation(_SingleToolCallTokenizer(), _parallel_conv())
    assert result == "RENDERED"


def test_orphan_repair_is_not_built_when_an_earlier_fallback_renders(monkeypatch):
    # Llama 3.x: the split renders parallel calls, so the orphan scan must not run.
    import core.inference.chat_template_helpers as helpers

    def _must_not_run(messages):
        raise AssertionError("orphan repair built although the split rendered")

    monkeypatch.setattr(helpers, "_repair_orphan_tool_results", _must_not_run, raising = False)
    assert (
        apply_chat_template_for_generation(_SingleToolCallTokenizer(), _parallel_conv())
        == "RENDERED"
    )


def test_string_arguments_and_parallel_calls_are_repaired_together():
    conv = _parallel_conv()
    for call in conv[1]["tool_calls"]:
        call["function"]["arguments"] = json.dumps(call["function"]["arguments"])

    class _StrictAndSingleCall(_SingleToolCallTokenizer):
        def apply_chat_template(self, messages, **kw):
            for msg in messages:
                for call in msg.get("tool_calls", []) or []:
                    if isinstance(call.get("function", {}).get("arguments"), str):
                        raise TypeError("Can only get item pairs from a mapping.")
            return super().apply_chat_template(messages, **kw)

    assert apply_chat_template_for_generation(_StrictAndSingleCall(), conv) == "RENDERED"


def test_lenient_template_never_sees_a_split_conversation():
    seen = {}

    class _Lenient:
        def apply_chat_template(self, messages, **kw):
            seen["n"] = len(messages)
            return "RENDERED"

    apply_chat_template_for_generation(_Lenient(), _parallel_conv())
    assert seen["n"] == 4


_MINISTRAL_IMAGE_TEMPLATE = """
{% set ns = namespace(index=0) %}
{% for message in messages %}
{% if message.role == 'user' or (message.role == 'assistant' and not message.tool_calls) %}
{% if (message.role == 'user') != (ns.index % 2 == 0) %}
{{ raise_exception('After the optional system message, conversation roles must alternate user and assistant roles except for tool calls and results.') }}
{% endif %}
{% set ns.index = ns.index + 1 %}
{% endif %}
{% for part in message.content if message.content is not string %}
{% if part.type == 'image' %}[IMG]{% endif %}
{% endfor %}
{% endfor %}
"""


class _MinistralImageTokenizer:
    chat_template = _MINISTRAL_IMAGE_TEMPLATE

    def apply_chat_template(self, messages, **kwargs):
        from transformers.utils.chat_template_utils import _compile_jinja_template
        self.messages = messages
        return _compile_jinja_template(self.chat_template).render(messages = messages)


@pytest.mark.parametrize("processor", [False, True])
def test_tool_image_turn_renders_with_ministral_alternation(processor):
    from core.inference.chat_template_helpers import render_prompt_with_boundary
    from core.inference.mcp_images import placeholder_turn

    conversation = _conv({})
    conversation.append(placeholder_turn(1))
    conversation.append({"role": "assistant", "content": "The image is red."})
    conversation.append({"role": "user", "content": "Another screenshot, please."})
    conversation.extend(_conv({})[1:])
    conversation.append(placeholder_turn(1))
    tokenizer = _MinistralImageTokenizer()
    render = render_prompt_with_boundary if processor else apply_chat_template_for_generation
    assert render(tokenizer, conversation).count("[IMG]") == 2
    assert [m["role"] for m in tokenizer.messages] == [
        "user",
        "assistant",
        "tool",
        "assistant",
        "user",
        "assistant",
        "user",
        "assistant",
        "tool",
        "assistant",
        "user",
    ]
    assert len(conversation) == 9


def test_image_boundary_repair_preserves_markers_and_working_templates():
    from core.inference.mcp_images import placeholder_turn, prepare_image_turn_boundaries

    conversation = _conv({}) + [placeholder_turn(1)]
    assert prepare_image_turn_boundaries(conversation, None) is conversation
    assert prepare_image_turn_boundaries(conversation, "{{ messages }}") is conversation
    fixed = prepare_image_turn_boundaries(conversation, _MINISTRAL_IMAGE_TEMPLATE)
    assert fixed[-1] is conversation[-1]
    assert prepare_image_turn_boundaries(fixed, _MINISTRAL_IMAGE_TEMPLATE) is fixed


def test_image_boundary_repair_does_not_hide_invalid_caller_roles():
    conversation = _conv({}) + [{"role": "user", "content": "A second user turn."}]
    with pytest.raises(Exception, match = "conversation roles must alternate"):
        apply_chat_template_for_generation(_MinistralImageTokenizer(), conversation)