Adds chat_template.jinja, so apply_chat_template renders the same prompts as encoding/encoding.py (asked in #10).

It is the DeepSeek-V4.1-Flash template with the 16 October encoder sync from #74 there, plus four fixes:

• thinking=true/false is accepted like enable_thinking. vLLM only forwards kwargs a template references, so {"thinking": false} was silently ignored.
• OpenAI reasoning_effort values map like deepseek-recipe's Chat Completions adapter: none turns thinking off, minimal/low give 50, medium/high/xhigh give 75, max gives 100. The V4.1-Flash template maps medium to 62 and raises on the others.
• Tool call arguments passed as a JSON string raise instead of rendering a single bogus arguments parameter (huggingface/transformers#45419).
• A tool message with content=None renders like a missing content key, not as None (huggingface/transformers#45422).

Tests

Setup for every snippet (transformers 5.20.1):

import importlib.util, json, random, sys
from huggingface_hub import hf_hub_download
from jinja2 import TemplateError
from transformers import AutoTokenizer

REPO = "deepseek-ai/DeepSeek-V4.1-Flash-1017"
tok = AutoTokenizer.from_pretrained(REPO, revision="refs/pr/11")
spec = importlib.util.spec_from_file_location("encoding", hf_hub_download(REPO, "encoding/encoding.py"))
enc = importlib.util.module_from_spec(spec)
spec.loader.exec_module(enc)

TOOL = {"type": "function", "function": {"name": "lookup", "description": "Look up a value", "parameters": {"type": "object", "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}}}}}
CALL = {"type": "function", "function": {"name": "lookup", "arguments": {"query": "value", "limit": 2}}}


def render(messages, tools=None, **kwargs):
    gen = messages[-1]["role"] != "assistant"
    return tok.apply_chat_template(messages, tools=tools, tokenize=False, add_generation_prompt=gen, **kwargs)


def check(messages, tools=None, thinking_mode="chat", **kwargs):
    ref = [dict(m) for m in messages]
    if tools:  # request tools go on the leading system message, as in deepseek-recipe
        if ref[0]["role"] != "system":
            ref.insert(0, {"role": "system", "content": ""})
        ref[0]["tools"] = tools
    expected = enc.encode_messages(ref, thinking_mode=thinking_mode, **kwargs)
    assert render(messages, tools, thinking_mode=thinking_mode, **kwargs) == expected


def fails(messages, tools=None, **kwargs):
    try:
        render(messages, tools, **kwargs)
    except TemplateError:
        return True
    return False

Golden outputs (encoding/tests)

for i in range(1, 6):
    case = enc.load_cases(hf_hub_download(REPO, f"encoding/tests/test_input_{i}.json"))[0]
    for m in case["messages"]:
        for call in m.get("tool_calls") or []:
            call["function"]["arguments"] = json.loads(call["function"]["arguments"])
    out = render(case["messages"], thinking_mode=case["thinking_mode"] or "chat", reasoning_effort=case["reasoning_effort"])
    assert out == open(hf_hub_download(REPO, f"encoding/tests/test_output_{i}.txt")).read()

inference/examples

for case in json.load(open(hf_hub_download(REPO, "inference/examples/example_harmony.json"))):
    for mode in ["chat", "thinking"]:
        check(case["messages"], case.get("tools"), thinking_mode=mode)

Images

check([{"role": "user", "content": [{"type": "text", "text": "inspect"}, {"type": "image_url", "image_url": {"url": "a.png"}}]}])
for role in ["user", "tool"]:
    assert fails([{"role": role, "content": "hi <｜deepseek_image｜>"}])

Reasoning effort

q = [{"role": "user", "content": "question"}]
for effort in [None, "low", "high", "max", 1, 42, 100]:
    check(q, thinking_mode="thinking", reasoning_effort=effort)
check(q, thinking_mode="chat", reasoning_effort="max")
for effort in [-1, 0, 101, True, False, 1.5]:
    assert fails(q, thinking_mode="thinking", reasoning_effort=effort)

System messages

check([{"role": "system", "content": "sys"}, {"role": "user", "content": "q1"}, {"role": "assistant", "content": "a1", "reasoning_content": "r1"}, {"role": "system", "content": "mid sys"}], thinking_mode="thinking", reasoning_effort=88)
check([{"role": "system", "content": "sys"}, {"role": "latest_reminder", "content": "2026-10-17"}, {"role": "user", "content": "q"}])

Tool calls

messages = [{"role": "user", "content": "question"}, {"role": "assistant", "reasoning_content": "  reason  ", "content": "summary", "tool_calls": [CALL, CALL]}]
for mode in ["chat", "thinking"]:
    check(messages, [TOOL], thinking_mode=mode)
    check(messages, thinking_mode=mode)

Tool namespaces

for ns in ["search", {"name": "search", "description": "Search tools."}]:
    check([{"role": "system", "content": "sys"}], [{**TOOL, "namespace": ns}])
    check([{"role": "system", "content": "sys"}], [{**TOOL, "function": {**TOOL["function"], "namespace": ns}}])
for call in [{**CALL, "namespace": "search"}, {**CALL, "function": {"name": "search::lookup", "arguments": {}}}]:
    check([{"role": "user", "content": "q"}, {"role": "assistant", "content": "", "tool_calls": [call]}], thinking_mode="thinking")
assert fails([{"role": "user", "content": "q"}], [{**TOOL, "namespace": "a::b"}])
assert fails([{"role": "user", "content": "q"}, {"role": "assistant", "content": "", "tool_calls": [{**CALL, "namespace": "files", "function": {"name": "search::lookup", "arguments": {}}}]}])

drop_thinking

messages = [
    {"role": "user", "content": "q1"},
    {"role": "assistant", "content": "a1", "reasoning_content": "r1"},
    {"role": "user", "content": "q2"},
    {"role": "assistant", "reasoning_content": "r2", "tool_calls": [{**CALL, "id": "c1"}]},
    {"role": "tool", "tool_call_id": "c1", "content": "value"},
]
for drop in [True, False]:
    check(messages, thinking_mode="thinking", drop_thinking=drop)
    check(messages + [{"role": "user", "content": "q3"}], thinking_mode="thinking", drop_thinking=drop)
    check(messages, [TOOL], thinking_mode="thinking", drop_thinking=drop)

Tool results in call order

calls = [{**CALL, "id": i} for i in "ab"]
results = [{"role": "tool", "tool_call_id": i, "content": [{"type": "text", "text": f"result {i}"}, {"type": "image_url", "image_url": {"url": f"{i}.png"}}]} for i in "ba"]
check([{"role": "user", "content": "q"}, {"role": "assistant", "content": "", "tool_calls": calls}] + results)

Tasks

check([{"role": "user", "content": "classify me", "task": "query"}])
check([{"role": "user", "content": "q", "task": "action"}, {"role": "assistant", "content": "Search"}])

Random conversations

rng = random.Random(0)
texts = ["Hi", "", "多行\n文本", 'quote " \\ ', "</think>", "{{ x }}"]
values = ["Paris", "", 0, 2.5, True, None, [1, "a"], {"k": [False]}]
for _ in range(5000):
    messages, n = [], 0
    if rng.random() < 0.6:
        messages.append({"role": "system", "content": rng.choice(texts)})
        if rng.random() < 0.2:
            messages.append({"role": "latest_reminder", "content": "2026-10-17"})
    for _ in range(rng.randint(1, 3)):
        content = rng.choice(texts) if rng.random() < 0.8 else [{"type": "text", "text": rng.choice(texts)}, {"type": "image_url", "image_url": {"url": "a.png"}}]
        messages.append({"role": "system" if messages and rng.random() < 0.1 else "user", "content": content})
        for _ in range(rng.randint(0, 2)):
            calls = [{"id": f"c{n + i}", "type": "function", "function": {"name": "lookup", "arguments": {"query": rng.choice(values)}}} for i in range(rng.randint(1, 3))]
            n += len(calls)
            messages.append({"role": "assistant", "content": rng.choice(texts), "reasoning_content": rng.choice(texts), "tool_calls": calls})
            messages += rng.sample([{"role": "tool", "tool_call_id": c["id"], "content": rng.choice(texts)} for c in calls], len(calls))
        messages.append({"role": "assistant", "content": rng.choice(texts), "reasoning_content": rng.choice(texts)})
    messages = messages[: rng.randint(1, len(messages))]
    check(messages, [TOOL] if rng.random() < 0.4 else None, thinking_mode=rng.choice(["chat", "thinking"]), reasoning_effort=rng.choice([None, "low", "max", rng.randint(1, 100)]), drop_thinking=rng.random() < 0.5)

Request kwargs

q = [{"role": "user", "content": "q"}]
assert render(q).endswith("<｜Assistant｜><think>")
for kwargs in [{"thinking": False}, {"enable_thinking": False}, {"thinking_mode": "chat"}, {"reasoning_effort": "none"}]:
    assert render(q, **kwargs).endswith("<｜Assistant｜></think>")
for effort, budget in [("minimal", 50), ("low", 50), ("medium", 75), ("high", 75), ("xhigh", 75), ("max", 100)]:
    assert f"Reasoning Effort: {budget} " in render(q, reasoning_effort=effort)

vLLM forwards thinking (vllm 0.31.0)

from vllm.renderers.hf import resolve_chat_template_kwargs

assert "thinking" in resolve_chat_template_kwargs(tok, tok.chat_template, {"thinking": False})

huggingface/transformers#45419

base = [{"role": "user", "content": "hi"}]
call = {"type": "function", "function": {"name": "f", "arguments": {"a": 1}}}
assert len({render(base + [{"role": "assistant", "tool_calls": [call], **extra}]) for extra in [{}, {"content": None}, {"content": ""}]}) == 1
assert fails(base + [{"role": "assistant", "content": "", "tool_calls": [{"type": "function", "function": {"name": "f", "arguments": '{"a": 1}'}}]}])

huggingface/transformers#45422

prefix = [{"role": "user", "content": "q"}, {"role": "assistant", "content": "", "tool_calls": [{**CALL, "id": "c"}]}]
assert render(prefix + [{"role": "tool", "tool_call_id": "c", "content": None}]) == render(prefix + [{"role": "tool", "tool_call_id": "c"}])
assert render([{"role": "system", "content": None}, {"role": "user", "content": "q"}]) == render([{"role": "system"}, {"role": "user", "content": "q"}])
assert render([{"role": "user", "content": None}]) == render([{"role": "user"}])

Tokenizer

markers = ["<｜begin▁of▁sentence｜>", "<｜end▁of▁sentence｜>", "<｜System｜>", "<｜User｜>", "<｜Assistant｜>", "<｜latest_reminder｜>", "<think>", "</think>", "｜DSML｜", "<｜deepseek_image｜>", "<｜action｜>", "<｜query｜>", "<｜authority｜>", "<｜domain｜>", "<｜title｜>", "<｜read_url｜>"]
assert all(len(tok(m, add_special_tokens=False).input_ids) == 1 for m in markers)
text = render([{"role": "user", "content": "q"}, {"role": "assistant", "reasoning_content": "r", "content": "", "tool_calls": [CALL]}], [TOOL], thinking_mode="thinking")
assert tok.decode(tok(text, add_special_tokens=False).input_ids) == text
assert tok(text).input_ids.count(tok.bos_token_id) == 1

Chat Template Inspector

spec = importlib.util.spec_from_file_location("checks", hf_hub_download("trl-lib/chat-template-inspector", "inspector/checks.py", repo_type="space"))
checks = importlib.util.module_from_spec(spec)
sys.modules["checks"] = checks
spec.loader.exec_module(checks)
ctx = checks.Context(obj=tok, is_processor=False, template_source=tok.chat_template, model_id=REPO)
not_passing = {r.name for r in (fn(ctx) for fn in checks.ALL_CHECKS) if r.status != "pass"}
assert not_passing == {"Assistant masking", "Accepts `arguments` as JSON string"}  # no {% generation %} markers; string arguments raise

TRL (trl 1.16.0)

from trl.chat_template_utils import is_chat_template_prefix_preserving, supports_tool_calling
from trl.data_utils import apply_chat_template

assert supports_tool_calling(tok) and is_chat_template_prefix_preserving(tok)
prompt = [{"role": "user", "content": "Weather?"}]
completion = [{"role": "assistant", "reasoning_content": "r", "content": "", "tool_calls": [CALL]}, {"role": "tool", "content": "sunny"}, {"role": "assistant", "reasoning_content": "r", "content": "Sunny."}]
for kwargs in [{}, {"thinking": False}, {"tools": [TOOL]}]:
    out = apply_chat_template({"prompt": prompt, "completion": completion}, tok, **kwargs)
    assert out["prompt"] == tok.apply_chat_template(prompt, add_generation_prompt=True, tokenize=False, **kwargs)
    prompt_ids = tok(out["prompt"], add_special_tokens=False).input_ids
    assert tok(out["prompt"] + out["completion"], add_special_tokens=False).input_ids[: len(prompt_ids)] == prompt_ids