Template API Reference

Template defines how messages are formatted, what system messages are used, and how tools or multimodal content are inserted.

Minimal Example

from chat_bricks.templates import Template

template = Template(
    name="custom",
    system_template="<|im_start|>system\n{system_message}<|im_end|>\n",
    system_message="You are a helpful assistant.",
    user_template="<|im_start|>user\n{content}<|im_end|>\n",
    assistant_template="<|im_start|>assistant\n{content}<|im_end|>\n",
    stop_words=["<|im_end|>"],
)

chat_bricks.templates.Template dataclass

Class that holds all the components of a chat template. Convert messages to string prompts, tokenize messages to token ids, and generate jinja-based chat templates.

Parameters:

• name (str) –

  The name of this template

• system_template (str, default: '{system_message}' ) –

  The system template — may include {tools} and {skills} placeholders which are filled with the rendered section blocks.

• system_message (str, default: '' ) –

  The default system message

• stop_words (Union[str, List[str]], default: None ) –

  The stop words where the model stops generating (usually EOS token)

• observations_template (str, default: None ) –

  Wraps the whole tool-response message (renamed from the old tool_template).

• single_observation_template (str, default: '{observation}' ) –

  Wraps one observation inside a parallel response (renamed from the old tool_observation_template).

• tools_template / single_tool_template –

  Catalogue section + per-tool wrapper. Filled into system_template's {tools} placeholder.

• skills_template / single_skill_template –

  Skill catalogue section + per-skill wrapper. Filled into system_template's {skills} placeholder.

• user_template (str, default: None ) –

  The user template component

• user_template_with_tools (str, default: None ) –

  The user template with tool usage component

• assistant_template (str, default: None ) –

  The assistant template component

• global_policy (GlobalPolicy, default: None ) –

  The global policy, controls the behavior of the template

• system_policy (SystemPolicy, default: None ) –

  The system message policy, controls the behavior of forming the system message

• tool_policy (ToolPolicy, default: None ) –

  The tool policy for the template, controls the behavior of forming tools.

• skill_policy (SkillPolicy, default: None ) –

  The skill policy for the template, controls how skill entries are rendered.

__post_init__()

Post-initialization to automatically register vision processor if vision tokens are defined

encode(messages, tokenizer, return_tensors=None, tools=None, skills=None, add_generation_prompt=False, processor=None, train_on_last_turn_only=False, **kwargs)

Encode the messages to token ids.

Parameters:

• messages (List[Dict]) –

  The list of messages

• tokenizer (PreTrainedTokenizer) –

  The tokenizer

• return_tensors (str, default: None ) –

  The return tensors

• tools –

  The list of tools

• skills –

  Optional list of skill objects to render into the system prompt.

• add_generation_prompt –

  Whether to add the generation prefix

• processor –

  The processor for vision templates

Returns:

• inputs ( str ) –

  The dictionary of input ids, attention mask, labels, and action mask

jinja_template()

Get the Jinja template string for the template. The jinja template is compitable with Hugging Face's tokenizer.apply_chat_template method.

Example:

tokenizer.chat_template = template.jinja_template()
tokenizer.apply_chat_template(messages, tokenize=False, tools=tools, add_generation_prompt=add_generation_prompt, **kwargs)

Returns: The Jinja template for the template.

render(messages, tools=None, skills=None, add_generation_prompt=False, train_on_last_turn_only=False)

Render the messages to a string prompt by applying the chat template. The render logic is implemented in the Renderer class.

Parameters:

• messages (List[Dict]) –

  The list of messages

• tools –

  The list of tools

• skills –

  Optional list of skill objects/dicts to advertise in the system prompt's {skills} placeholder. Each entry needs at least name and description (either as dict keys or attributes). The template's skills_template and single_skill_template (or skill_policy) control the rendered form.

• add_generation_prompt (bool, default: False ) –

  Whether to add the generation prompt

Returns:

• prompt ( str ) –

  The final prompt string

• elements ( List[str] ) –

  The list of string elements that compose the prompt

• mask_flags ( List[bool] ) –

  The list of mask flags for the elements

set_system_message(system_message)

Set the system message.

supports_vision()

Check if this template supports vision processing

chat_bricks.templates.Renderer

render(messages, tools=None, skills=None, add_generation_prompt=False)

Render the template.

The heavy lifting is delegated to small, single-purpose helpers so the high-level flow is immediately apparent:

1. _insert_tools              – decide where the tool catalogue lives
2. _format_skills             – format the optional skill catalogue
3. _encode_turns              – encode every conversation turn
4. _maybe_add_generation_prompt – append the generation prefix if requested

Parameters:

• messages (List[Dict]) –

  The list of messages

• tools –

  The list of tools

• skills –

  Optional list of skill objects/dicts. Each entry needs name and description (either as dict keys or attributes). The template's skills_template + single_skill_template (or skill_policy) control the rendered form. When skills_template is not set, this argument is silently ignored.

• add_generation_prompt (bool, default: False ) –

  Whether to add the generation prefix

Returns:

• prompt ( str ) –

  The final prompt string

• elements ( str ) –

  The list of string elements that compose the prompt

• mask_flags ( str ) –

  The list of mask flags for the elements. True if the element is a non-assistant message, False if the element is an assistant message.

chat_bricks.templates.JinjaGenerator

generate_jinja_template()

Return a Hugging-Face style chat-template (Jinja-mini dialect).

The implementation mirrors the structure of the render method in the renderer.py file. render() for easier maintenance:

1.  _jinja_header_constants      – immutable `set` statements
2.  _jinja_system_block          – first turn / system handling
3.  _jinja_loop_messages         – remaining turns & per-role logic
4.  _jinja_generation_block      – optional generation prefix

Returns:

• str –

  The Jinja template string.