Skip to content

vllm.renderers.inkling_encoding

Inkling chat-encoding core.

Pure implementation of Inkling chat rendering, kept deliberately free of vLLM imports: it depends only on the InklingTextTokenizer protocol and speaks OpenAI-style message dicts. If a standalone Inkling input-processing library becomes available, this module is the unit to swap out — the swap point is marked in vllm/renderers/inkling.py.

Multimodal parts follow the contract of vLLM's Inkling multimodal processor (InklingMultiModalProcessor anchors prompt updates on the bare content-kind marker and inserts the per-patch placeholder run itself):

  • image parts emit only <|content_image|> — no seed placeholder id;
  • audio parts emit <|content_audio_input|><|audio_end|> — no seed placeholder id between them.

reasoning_effort (a float in [0, 0.99], sourced from chat_template_kwargs only) renders the Thinking effort level: system control block after the tool declarations and initial system messages.

Classes:

Functions:

InklingTextTokenizer

Bases: Protocol

Structural tokenizer contract required by the renderer.

Source code in vllm/renderers/inkling_encoding.py
class InklingTextTokenizer(Protocol):
    """Structural tokenizer contract required by the renderer."""

    def encode_text(self, text: str) -> list[int]: ...

    def encode_special(self, token: str) -> int: ...

_collect_tools(messages, tools)

Request-level plus per-developer-message tools (Rust renderer semantics), declared in a single leading system block.

Source code in vllm/renderers/inkling_encoding.py
def _collect_tools(
    messages: Sequence[Mapping[str, Any]],
    tools: Sequence[Mapping[str, Any]] | None,
) -> list[Mapping[str, Any]]:
    """Request-level plus per-developer-message tools (Rust renderer
    semantics), declared in a single leading system block."""
    all_tools = list(tools or [])
    for message in messages:
        if message.get("role") == "developer":
            all_tools.extend(message.get("tools") or [])
    return all_tools

_flatten_text_content(content)

Flatten a tool-response content (string or text parts) to text.

Source code in vllm/renderers/inkling_encoding.py
def _flatten_text_content(content: Any) -> str:
    """Flatten a tool-response content (string or text parts) to text."""
    if content is None:
        return ""
    if isinstance(content, str):
        return content
    parts: list[str] = []
    for kind, text in _iter_render_parts(content):
        if kind != "text":
            raise ValueError(
                "Inkling tool response content must be text, "
                f"got a part of kind {kind!r}"
            )
        parts.append(text)
    return "".join(parts)

_iter_render_parts(content)

Yield (kind, text) per content part: kind in {text, image, audio}.

Source code in vllm/renderers/inkling_encoding.py
def _iter_render_parts(content: Any) -> Iterator[tuple[str, str]]:
    """Yield (kind, text) per content part: kind in {text, image, audio}."""
    if content is None:
        return
    if isinstance(content, str):
        if content:
            yield ("text", content)
        return
    if not isinstance(content, Sequence) or isinstance(content, (bytes, bytearray)):
        raise TypeError("message content must be a string or a sequence of parts")
    for part in content:
        if isinstance(part, str):
            yield ("text", part)
            continue
        if not isinstance(part, Mapping):
            raise TypeError(f"content part must be mapping, got {type(part).__name__}")
        ptype = part.get("type")
        if ptype in (None, "text", "input_text"):
            text = part.get("text", "")
            yield ("text", text if isinstance(text, str) else "")
        elif ptype in _IMAGE_PART_TYPES:
            yield ("image", "")
        elif ptype in _AUDIO_PART_TYPES:
            yield ("audio", "")
        else:
            raise ValueError(f"unsupported content part type: {ptype!r}")

_tml_json_dumps(value, *, legacy_floats=True, sort_keys=True)

Compact JSON with the Inkling2 reference float spelling.

Source code in vllm/renderers/inkling_encoding.py
def _tml_json_dumps(
    value: Any, *, legacy_floats: bool = True, sort_keys: bool = True
) -> str:
    """Compact JSON with the Inkling2 reference float spelling."""
    if isinstance(value, Mapping):
        if not all(isinstance(key, str) for key in value):
            raise TypeError("JSON object keys must be strings")
        return (
            "{"
            + ",".join(
                _tml_json_dumps(key)
                + ":"
                + _tml_json_dumps(
                    value[key], legacy_floats=legacy_floats, sort_keys=sort_keys
                )
                for key in (sorted(value) if sort_keys else value)
            )
            + "}"
        )
    if isinstance(value, (list, tuple)):
        items = (
            _tml_json_dumps(item, legacy_floats=legacy_floats, sort_keys=sort_keys)
            for item in value
        )
        return "[" + ",".join(items) + "]"
    if isinstance(value, float):
        if not math.isfinite(value):
            raise ValueError("JSON numbers must be finite")
        result = repr(value)
        if "e" not in result:
            return result
        mantissa, exponent_text = result.split("e")
        exponent = int(exponent_text)
        if -5 <= exponent < 16:
            negative = mantissa.startswith("-")
            digits = mantissa.lstrip("-").replace(".", "")
            decimal = exponent + 1
            if decimal <= 0:
                result = "0." + "0" * -decimal + digits
            elif decimal >= len(digits):
                result = digits + "0" * (decimal - len(digits)) + ".0"
            else:
                result = digits[:decimal] + "." + digits[decimal:]
            return ("-" if negative else "") + result
        sign = "+" if exponent >= 0 and not legacy_floats else ""
        return mantissa + "e" + sign + str(exponent)
    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), allow_nan=False)

_tml_json_loads(text)

Parse JSON as the Inkling2 reference does (64-bit ints, finite floats).

Source code in vllm/renderers/inkling_encoding.py
def _tml_json_loads(text: str) -> Any:
    """Parse JSON as the Inkling2 reference does (64-bit ints, finite floats)."""

    def invalid_constant(value: str) -> Any:
        raise ValueError(f"Invalid JSON constant: {value}")

    def finite_float(value: str) -> float:
        number = float(value)
        if not math.isfinite(number):
            raise ValueError("JSON number out of range")
        return number

    def bounded_int(value: str) -> int | float:
        number = int(value)
        if value == "-0" or not -(1 << 63) <= number < 1 << 64:
            return finite_float(value)
        return number

    return json.loads(
        text,
        parse_constant=invalid_constant,
        parse_float=finite_float,
        parse_int=bounded_int,
    )

continuation_prefix(message)

Return the text an Inkling2 continue_final_message request extends.

Only a plain-string assistant message with no tool calls or reasoning is continued; None means the message renders as a closed turn.

Source code in vllm/renderers/inkling_encoding.py
def continuation_prefix(message: Mapping[str, Any]) -> str | None:
    """Return the text an Inkling2 `continue_final_message` request extends.

    Only a plain-string assistant message with no tool calls or reasoning is
    continued; `None` means the message renders as a closed turn.
    """
    content = message.get("content")
    if (
        message.get("role") != "assistant"
        or not isinstance(content, str)
        or message.get("tool_calls")
        or _assistant_reasoning(message)
    ):
        return None
    return content

render_inkling2_messages(messages, tokenizer, *, tools=None, tool_choice=None, parallel_tool_calls=True, reasoning_effort=DEFAULT_REASONING_EFFORT, continue_final_message=False)

Render chat messages to Inkling2 input ids.

With continue_final_message, a final assistant message holding only a text string is left open so generation continues its text.

Source code in vllm/renderers/inkling_encoding.py
def render_inkling2_messages(
    messages: Sequence[Mapping[str, Any]],
    tokenizer: InklingTextTokenizer,
    *,
    tools: Sequence[Mapping[str, Any]] | None = None,
    tool_choice: Any = None,
    parallel_tool_calls: bool = True,
    reasoning_effort: float = DEFAULT_REASONING_EFFORT,
    continue_final_message: bool = False,
) -> list[int]:
    """Render chat messages to Inkling2 input ids.

    With `continue_final_message`, a final assistant message holding only
    a text string is left open so generation continues its text.
    """
    messages = list(messages)
    assistant_prefix = None
    if continue_final_message and messages:
        assistant_prefix = continuation_prefix(messages[-1])
        if assistant_prefix is not None:
            messages.pop()

    input_ids: list[int] = []
    choice = _inkling2_tool_choice(tool_choice)
    declared_tools = _collect_tools(messages, None if choice == "none" else tools)
    if isinstance(choice, _NamedToolChoice):
        declared_tools = [
            tool
            for tool in declared_tools
            if _as_mapping(_as_mapping(tool).get("function", {})).get("name")
            == choice.name
        ]
    if declared_tools:
        _append_message(
            input_ids,
            tokenizer,
            "system",
            "xml",
            _inkling2_tool_declare_json(declared_tools),
            author_name="tool_declare",
        )

    effort_text: str | None = _inkling2_effort_text(reasoning_effort)
    instruction = (
        _inkling2_tool_choice_instruction(choice, parallel_tool_calls)
        if declared_tools
        else None
    )
    if instruction is not None:
        if messages and messages[0].get("role") in {"system", "developer"}:
            messages[0] = _with_appended_text(messages[0], instruction)
        else:
            effort_text = f"{effort_text}\n\n{instruction}"

    tool_call_id_to_name: dict[str, str] = {}
    for message in messages:
        role = _expect_role(message)
        if effort_text is not None and role not in {"system", "developer"}:
            _append_message(input_ids, tokenizer, "system", "text", effort_text)
            effort_text = None

        author_name = None
        if role == "tool":
            name = message.get("name")
            author_name = (
                str(name)
                if name
                else tool_call_id_to_name.get(str(message.get("tool_call_id") or ""))
            )
        blocks = _inkling2_blocks(message, role, tool_call_id_to_name)
        for kind, text, block_author in blocks:
            _append_message(
                input_ids,
                tokenizer,
                role,
                kind,
                text,
                author_name=block_author or author_name,
            )
        if role == "assistant" and blocks:
            input_ids.append(tokenizer.encode_special(CONTENT_MODEL_END_SAMPLING))

    if effort_text is not None:
        _append_message(input_ids, tokenizer, "system", "text", effort_text)

    if assistant_prefix is not None:
        input_ids.append(tokenizer.encode_special(MESSAGE_MODEL))
        input_ids.append(tokenizer.encode_special(CONTENT_TEXT))
        input_ids.extend(tokenizer.encode_text(assistant_prefix))
    return input_ids

render_inkling_messages(messages, tokenizer, *, add_generation_prompt=True, tools=None, reasoning_effort=None)

Render chat messages to Inkling input ids.

PURE renderer: emits Inkling framing plus bare media markers; media encoding and placeholder expansion happen later in the MM processor. add_generation_prompt appends the assistant turn opener so the model continues into the response.

Source code in vllm/renderers/inkling_encoding.py
def render_inkling_messages(
    messages: Sequence[Mapping[str, Any]],
    tokenizer: InklingTextTokenizer,
    *,
    add_generation_prompt: bool = True,
    tools: Sequence[Mapping[str, Any]] | None = None,
    reasoning_effort: float | None = None,
) -> list[int]:
    """Render chat messages to Inkling input ids.

    PURE renderer: emits Inkling framing plus bare media markers; media
    encoding and placeholder expansion happen later in the MM processor.
    `add_generation_prompt` appends the assistant turn opener so the
    model continues into the response.
    """
    input_ids: list[int] = []
    tool_call_id_to_name: dict[str, str] = {}

    all_tools = _collect_tools(messages, tools)
    if all_tools:
        _append_message(
            input_ids,
            tokenizer,
            "system",
            "xml",
            _tool_declare_json(all_tools),
            author_name="tool_declare",
        )

    for message in messages:
        role = _expect_role(message)
        if role not in {"system", "developer"} and reasoning_effort is not None:
            _append_reasoning_effort(input_ids, tokenizer, reasoning_effort)
            reasoning_effort = None

        if role == "tool":
            tool_name = str(
                message.get("name")
                or tool_call_id_to_name.get(str(message.get("tool_call_id") or ""), "")
            )
            # Tool responses may carry media parts (e.g. screenshots). Emit one
            # marker per media item for the MM processor, but coalesce adjacent
            # text parts so text-only results keep the same framing as before.
            tool_parts = list(_iter_render_parts(message.get("content")))
            if not tool_parts:
                # Keep an empty block so the tool call it answers is not left
                # dangling.
                tool_parts = [("text", "")]
            text_parts: list[str] = []
            for kind, text in tool_parts:
                if kind == "thinking":
                    raise ValueError("Inkling thinking parts require role='assistant'")
                if kind == "text":
                    text_parts.append(text)
                    continue
                if text_parts:
                    _append_message(
                        input_ids,
                        tokenizer,
                        "tool",
                        "text",
                        "".join(text_parts),
                        author_name=tool_name,
                    )
                    text_parts.clear()
                _append_message(
                    input_ids,
                    tokenizer,
                    "tool",
                    kind,
                    text,
                    author_name=tool_name,
                )
            if text_parts:
                _append_message(
                    input_ids,
                    tokenizer,
                    "tool",
                    "text",
                    "".join(text_parts),
                    author_name=tool_name,
                )
            continue

        if role == "assistant":
            reasoning_content = message.get("reasoning")
            if reasoning_content is None:
                reasoning_content = message.get("reasoning_content")
            if reasoning_content:
                if not isinstance(reasoning_content, str):
                    raise TypeError(
                        "assistant reasoning_content must be a string for "
                        "Inkling rendering"
                    )
                _append_message(
                    input_ids,
                    tokenizer,
                    "assistant",
                    "thinking",
                    reasoning_content,
                )

        for kind, text in _iter_render_parts(message.get("content")):
            _append_message(input_ids, tokenizer, role, kind, text)

        if role == "assistant":
            for tool_call in message.get("tool_calls") or []:
                name, args = _tool_call_name_and_args(tool_call)
                tool_call_id = _as_mapping(tool_call).get("id")
                if tool_call_id:
                    tool_call_id_to_name[str(tool_call_id)] = name
                _append_message(
                    input_ids,
                    tokenizer,
                    "assistant",
                    "invoke_tool_json",
                    _tool_call_json(name, args),
                    author_name=name,
                )

            input_ids.append(tokenizer.encode_special(CONTENT_MODEL_END_SAMPLING))

    if reasoning_effort is not None:
        _append_reasoning_effort(input_ids, tokenizer, reasoning_effort)

    if add_generation_prompt:
        input_ids.append(tokenizer.encode_special(MESSAGE_MODEL))
    return input_ids