Renderers

Renderers convert chat-style messages into token sequences for training and generation.

Reference

Read these for details:

• tinker_cookbook/renderers/base.py — Renderer base class and API
• tinker_cookbook/renderers/__init__.py — Registry, factory, TrainOnWhat enum
• docs/rendering.mdx — Rendering guide with examples

Getting a renderer

Always use model_info.get_recommended_renderer_name() — never hardcode:

from tinker_cookbook import model_info
from tinker_cookbook.renderers import get_renderer
from tinker_cookbook.tokenizer_utils import get_tokenizer

renderer_name = model_info.get_recommended_renderer_name(model_name)
tokenizer = get_tokenizer(model_name)
renderer = get_renderer(renderer_name, tokenizer)

Available renderers: llama3, qwen3, deepseekv3, kimi_k2, kimi_k25, nemotron3, nemotron3_disable_thinking, role_colon, and more. See tinker_cookbook/renderers/__init__.py for the full registry.

Key renderer methods

# Build generation prompt (for sampling)
model_input = renderer.build_generation_prompt(messages, role="assistant")

# Build supervised example (for training)
model_input, weights = renderer.build_supervised_example(
    messages, train_on_what=TrainOnWhat.ALL_ASSISTANT_MESSAGES
)

# Parse model output back to a message
message, is_complete = renderer.parse_response(token_ids)

# Get stop sequences for sampling
stop = renderer.get_stop_sequences()

# Tool calling support
prefix_messages = renderer.create_conversation_prefix_with_tools(tool_specs)

TrainOnWhat

Controls which tokens receive training signal:

from tinker_cookbook.renderers import TrainOnWhat

# Most common — train on all assistant responses
TrainOnWhat.ALL_ASSISTANT_MESSAGES

# Train only on the final assistant response
TrainOnWhat.LAST_ASSISTANT_MESSAGE

# Train on everything (including user messages)
TrainOnWhat.ALL_TOKENS

# Other options
TrainOnWhat.LAST_ASSISTANT_TURN
TrainOnWhat.ALL_MESSAGES
TrainOnWhat.ALL_USER_AND_SYSTEM_MESSAGES
TrainOnWhat.CUSTOMIZED  # Set trainable=True/False on individual messages

Vision inputs

For VLM models, use ImageChunk in messages:

message = {
    "role": "user",
    "content": [
        {"type": "image", "image_url": "https://..."},  # or local path
        {"type": "text", "text": "What is in this image?"},
    ],
}

See docs/rendering.mdx and tinker_cookbook/recipes/vlm_classifier/train.py for VLM examples.

Custom renderers

Register a custom renderer:

from tinker_cookbook.renderers import register_renderer

def my_renderer_factory(tokenizer, image_processor):
    return MyCustomRenderer(tokenizer)

register_renderer("my_renderer", my_renderer_factory)

Picklability

Renderers must be pickleable for distributed rollout execution. The codebase tests this — see tinker_cookbook/renderers/renderer_pickle_test.py.

Common pitfalls

• Always use model_info.get_recommended_renderer_name() — renderer must match model family
• After loading a checkpoint trained with a specific renderer, use the same renderer name
• build_supervised_example() returns weights as list[float] — wrap with TensorData.from_numpy() if needed
• For tool calling, use create_conversation_prefix_with_tools() to inject tool definitions