renderers 0.1.12.dev16__tar.gz → 0.1.12.dev17__tar.gz

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: renderers
-Version: 0.1.12.dev16
+Version: 0.1.12.dev17
 Summary: Chat template renderers — deterministic message-to-token conversion for LLM training
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -127,7 +127,8 @@ class Renderer(Protocol):
     def bridge_to_next_turn(prev_prompt_ids, prev_completion_ids, new_messages, *, tools=None) -> list[int] | None: ...
 ```
 
-- `RenderedTokens` carries `token_ids` **and** `message_indices` — one entry per token attributing each to its source message (`-1` for structural scaffolding). Lets `build_training_sample` build a per-token loss mask in one render.
+- `RenderedTokens` carries `token_ids` **and** `message_indices` — one entry per token attributing each to its owning message (`-1` for structural scaffolding). Sampled closing markers belong to their assistant, including GLM markers emitted at the next user/tool boundary; user/tool bodies keep their own ownership.
+- `build_training_sample(..., message_loss_mask=[0, 0, 0, 1])` keeps all messages as context but restricts loss to selected messages. Supply one boolean or integer `0`/`1` per message, or `None` for the normal mask. Excluding an assistant also excludes its closing token. Selection never enables targets disabled by the existing role/content settings or changes token IDs.
 - `ParsedResponse` is `(content, reasoning_content, tool_calls)`. It scans token ids for special-token boundaries (e.g. id `151657` for `<tool_call>` on Qwen3) — a literal `"<tool_call>"` in user content tokenizes to ordinary text ids and never matches.
 - Round-trip: rendering `[user, assistant(content, reasoning, tool_calls)]`, slicing the assistant completion, and feeding it through `parse_response` returns an equivalent structured message. Tested per-renderer in `tests/test_roundtrip.py`.
 

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/README.md

@@ -107,7 +107,8 @@ class Renderer(Protocol):
     def bridge_to_next_turn(prev_prompt_ids, prev_completion_ids, new_messages, *, tools=None) -> list[int] | None: ...
 ```
 
-- `RenderedTokens` carries `token_ids` **and** `message_indices` — one entry per token attributing each to its source message (`-1` for structural scaffolding). Lets `build_training_sample` build a per-token loss mask in one render.
+- `RenderedTokens` carries `token_ids` **and** `message_indices` — one entry per token attributing each to its owning message (`-1` for structural scaffolding). Sampled closing markers belong to their assistant, including GLM markers emitted at the next user/tool boundary; user/tool bodies keep their own ownership.
+- `build_training_sample(..., message_loss_mask=[0, 0, 0, 1])` keeps all messages as context but restricts loss to selected messages. Supply one boolean or integer `0`/`1` per message, or `None` for the normal mask. Excluding an assistant also excludes its closing token. Selection never enables targets disabled by the existing role/content settings or changes token IDs.
 - `ParsedResponse` is `(content, reasoning_content, tool_calls)`. It scans token ids for special-token boundaries (e.g. id `151657` for `<tool_call>` on Qwen3) — a literal `"<tool_call>"` in user content tokenizes to ordinary text ids and never matches.
 - Round-trip: rendering `[user, assistant(content, reasoning, tool_calls)]`, slicing the assistant completion, and feeding it through `parse_response` returns an equivalent structured message. Tested per-renderer in `tests/test_roundtrip.py`.
 

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/renderers/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.12.dev16'
-__version_tuple__ = version_tuple = (0, 1, 12, 'dev16')
+__version__ = version = '0.1.12.dev17'
+__version_tuple__ = version_tuple = (0, 1, 12, 'dev17')
 
 __commit_id__ = commit_id = None

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/renderers/base.py

@@ -224,8 +224,11 @@ class MultiModalData:
 class RenderedTokens:
     """Result of rendering messages to tokens.
 
-    Each token carries an index into the original message list so callers can
-    build per-token loss masks without re-rendering. Tokens from structural
+    Each token carries its owning message's index into the original message
+    list so callers can build per-token loss masks without re-rendering.
+    Sampled closing tokens belong to the assistant that generated them, even
+    when emitted while rendering the next message's role marker. User/tool
+    bodies retain their own message indices. Tokens from structural
     scaffolding the renderer adds outside any single message (e.g. the
     trailing generation prompt) carry index ``-1``.
 
@@ -383,7 +386,10 @@ class RenderedTokens:
         is not represented.
 
         Hand-coded renderers emit each message's tokens contiguously,
-        so the span is well-defined. The implementation tolerates
+        so the span is well-defined. Spans follow input-message indices,
+        not necessarily token order: templates can reorder tool results.
+        Empty messages whose role marker closes the preceding assistant
+        may have no tokens of their own. The implementation tolerates
         non-contiguous attribution by returning the outer span
         ``(first_k, last_k + 1)``; if you suspect interleaving, slice
         ``message_indices`` yourself to verify.
@@ -1640,6 +1646,7 @@ def build_training_sample(
     tools: list[ToolSpec] | None = None,
     content_sft_roles: "set[str] | frozenset[str] | None" = None,
     ensure_final_stop: bool = False,
+    message_loss_mask: list[bool | int] | None = None,
 ) -> RenderedTrainingSample:
     """Build a :class:`RenderedTrainingSample` for supervised training.
 
@@ -1656,11 +1663,8 @@ def build_training_sample(
     it's attributed to. This is the recommended default for renderer
     callers — the renderer owns the per-token "is this model output"
     signal, so role-level filtering becomes a downstream constraint
-    rather than a precondition. (Some role markers — e.g. GLM
-    ``<|user|>`` / ``<|observation|>`` after a tool-calling assistant
-    turn — *are* sampled by the model at inference and live inside the
-    next message's span; ``sampled_mask`` captures that, but a
-    naive role filter would mask them out.)
+    rather than a precondition. Sampled closing markers, including GLM's
+    ``<|user|>`` / ``<|observation|>``, are attributed to their assistant.
 
     When ``role_to_mask`` is provided, ``loss_mask`` is the AND of the
     role-based attribution and the sampled signal: only tokens the
@@ -1706,7 +1710,27 @@ def build_training_sample(
     fires, the output intentionally diverges from ``apply_chat_template``.
     Ignored for renderers without ``sampled_mask`` (``DefaultRenderer``) —
     the close of an opaque template can't be located reliably.
+
+    ``message_loss_mask`` optionally selects messages for supervision with
+    one boolean or integer 0/1 per message. It only restricts the existing
+    mask: selecting a message never enables targets disabled by the role,
+    sampled, or content settings. Unselected messages remain context,
+    including prefilled assistant turns at arbitrary positions. Sampled
+    closing tokens follow their owning assistant, even when a template
+    emits them at the next message boundary. A synthesized final stop
+    follows the final message's selection. Token ids are unaffected.
+    ``None`` preserves the existing mask.
     """
+    if message_loss_mask is not None:
+        if len(message_loss_mask) != len(messages):
+            raise ValueError("message_loss_mask must have one entry per message")
+        if any(
+            not isinstance(value, (bool, int)) or value not in (0, 1)
+            for value in message_loss_mask
+        ):
+            raise ValueError(
+                "message_loss_mask entries must be booleans or integers 0/1"
+            )
     rendered = renderer.render(messages, tools=tools)
     has_sampled_info = len(rendered.sampled_mask) == len(rendered.token_ids)
     has_content_info = len(rendered.is_content) == len(rendered.token_ids)
@@ -1765,6 +1789,19 @@ def build_training_sample(
             # stop is a training target, like any sampled token.
             loss_mask.append(True)
 
+    if message_loss_mask is not None:
+        for k in range(len(loss_mask)):
+            # Any synthesized stop after the rendered sequence belongs to
+            # the final assistant, just like an in-message closing token.
+            msg_idx = (
+                rendered.message_indices[k]
+                if k < len(rendered.message_indices)
+                else len(messages) - 1
+            )
+            loss_mask[k] = (
+                loss_mask[k] and msg_idx >= 0 and bool(message_loss_mask[msg_idx])
+            )
+
     # Surface the multimodal payload for VLM renderers. ``None`` for text
     # renderers and for text-only samples (empty media) so downstream
     # ``multi_modal_data is not None`` is a reliable "has media" check.

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/renderers/glm45.py

@@ -192,20 +192,8 @@ class GLM45Renderer:
             role = msg["role"]
             content = self._visible_text(msg.get("content"))
 
-            # When the previous message is an assistant, this message's
-            # role-opening token (``<|user|>`` / ``<|observation|>``) is
-            # the inference-time stop signal that closes the assistant's
-            # turn (see ``get_stop_token_ids``). Mark it
-            # ``is_sampled=True`` so the loss-mask pipeline trains the
-            # model to emit it after ``</tool_call>`` (instead of
-            # continuing with another ``<tool_call>`` block). The token
-            # stays attributed to this message (msg_idx=i) and remains
-            # ``is_content=False`` — it's a role-marker / scaffold, not
-            # body bytes, so ``content_mask_for_roles({"tool"})`` and
-            # ``content_token_spans_by_role()`` correctly exclude it
-            # from "tool body" views. Byte stream is unchanged.
-            # ``system`` only appears at the start of a GLM conversation,
-            # so its opener is never the closer of an assistant turn.
+            # A user/tool role marker that closes generation belongs to
+            # the preceding assistant's sampled output, not the next body.
             closes_assistant_turn = i > 0 and messages[i - 1]["role"] == "assistant"
 
             if role == "system":
@@ -219,9 +207,9 @@ class GLM45Renderer:
             elif role == "user":
                 emit_special(
                     self._user,
-                    i,
+                    i - 1 if closes_assistant_turn else i,
                     is_sampled=closes_assistant_turn,
-                    is_content=False,
+                    is_content=closes_assistant_turn,
                 )
                 # ``\n`` is scaffold; ``content`` is body; the optional
                 # ``/nothink`` suffix is scaffold the renderer injects
@@ -508,15 +496,9 @@ class GLM45Renderer:
         # (think block + content + tool calls) is the model-sampled
         # portion.
         #
-        # GLM-4.5 does NOT emit an explicit per-turn close token inside
-        # the assistant message; the next message's role marker
-        # (``<|user|>`` / ``<|observation|>`` / ``<|endoftext|>``) acts
-        # as the stop signal at inference, and those tokens are
-        # attributed to the *next* message (or are absent on the final
-        # turn). So no sampled stop-signal token lives inside this
-        # assistant span — content / think / tool_calls carry the
-        # is_sampled=True signal.
-        #
+        # The next user/tool role marker closes this assistant turn and
+        # is attributed here when that later message is rendered.
+
         # Invariant on assistant tokens: ``is_content == sampled_mask``.
         # Every scaffold token here gets ``is_sampled=False/is_content=False``;
         # every model-sampled emit gets both True.
@@ -598,23 +580,17 @@ class GLM45Renderer:
         emit_text,
         emit_text_segments,
     ) -> None:
-        # Tool body bytes get ``is_content=True``; the wraps are
-        # scaffold. The ``<|observation|>`` role tag is scaffold too
-        # (``is_content=False`` so ``content_mask_for_roles({"tool"})``
-        # excludes it). When the previous message is an assistant it
-        # doubles as the inference stop signal for that assistant's
-        # turn — mark it ``is_sampled=True`` so SFT trains the model to
-        # emit it after ``</tool_call>``. The token stays attributed to
-        # this tool message; byte stream is unchanged.
+        # Tool bodies keep their own attribution; a sampled observation
+        # marker belongs to the assistant that generated it.
         prev_role = messages[msg_idx - 1]["role"] if msg_idx > 0 else None
         closes_assistant_turn = prev_role == "assistant"
 
         if prev_role != "tool":
             emit_special(
                 self._observation,
-                msg_idx,
+                msg_idx - 1 if closes_assistant_turn else msg_idx,
                 is_sampled=closes_assistant_turn,
-                is_content=False,
+                is_content=closes_assistant_turn,
             )
 
         emit_text_segments(

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/renderers/glm5.py

@@ -225,20 +225,8 @@ class GLM5Renderer:
             role = msg["role"]
             content = self._visible_text(msg.get("content"))
 
-            # When the previous message is an assistant, this message's
-            # role-opening token (``<|user|>`` / ``<|observation|>``) is
-            # the inference-time stop signal that closes the assistant's
-            # turn (see ``get_stop_token_ids``). Mark it
-            # ``is_sampled=True`` so the loss-mask pipeline trains the
-            # model to emit it after ``</tool_call>`` (instead of
-            # continuing with another ``<tool_call>`` block). The token
-            # stays attributed to this message (msg_idx=i) and remains
-            # ``is_content=False`` — it's a role-marker / scaffold, not
-            # body bytes, so ``content_mask_for_roles({"tool"})`` and
-            # ``content_token_spans_by_role()`` correctly exclude it
-            # from "tool body" views. Byte stream is unchanged.
-            # ``system`` only appears at the start of a GLM conversation,
-            # so its opener is never the closer of an assistant turn.
+            # A user/tool role marker that closes generation belongs to
+            # the preceding assistant's sampled output, not the next body.
             closes_assistant_turn = i > 0 and messages[i - 1]["role"] == "assistant"
 
             if role == "system":
@@ -248,9 +236,9 @@ class GLM5Renderer:
             elif role == "user":
                 emit_special(
                     self._user,
-                    i,
+                    i - 1 if closes_assistant_turn else i,
                     is_sampled=closes_assistant_turn,
-                    is_content=False,
+                    is_content=closes_assistant_turn,
                 )
                 emit_text(content, i, is_sampled=False, is_content=True)
 
@@ -272,13 +260,17 @@ class GLM5Renderer:
                     ):
                         tool_message = messages[tool_idx]
                         self._render_tool(
-                            messages,
                             tool_idx,
                             self._visible_text(tool_message.get("content")),
                             emit_special=emit_special,
                             emit_text=emit_text,
                             emit_text_segments=emit_text_segments,
                             starts_block=position == 0,
+                            closing_assistant_index=(
+                                i - 1
+                                if position == 0 and closes_assistant_turn
+                                else None
+                            ),
                         )
 
         # ── Generation prompt ───────────────────────────────────────
@@ -649,7 +641,6 @@ class GLM5Renderer:
 
     def _render_tool(
         self,
-        messages: list[Message],
         msg_idx: int,
         content: str,
         *,
@@ -657,24 +648,22 @@ class GLM5Renderer:
         emit_text,
         emit_text_segments,
         starts_block: bool = False,
+        closing_assistant_index: int | None = None,
     ) -> None:
-        # Tool body bytes get ``is_content=True``; the wraps are
-        # scaffold. The ``<|observation|>`` role tag is scaffold too
-        # (``is_content=False`` so ``content_mask_for_roles({"tool"})``
-        # excludes it). When the previous message is an assistant it
-        # doubles as the inference stop signal for that assistant's
-        # turn — mark it ``is_sampled=True`` so SFT trains the model to
-        # emit it after ``</tool_call>``. The token stays attributed to
-        # this tool message; byte stream is unchanged.
-        prev_role = messages[msg_idx - 1]["role"] if msg_idx > 0 else None
-        closes_assistant_turn = prev_role == "assistant"
-
-        if starts_block or prev_role != "tool":
+        # Tool bodies keep their own attribution; a sampled observation
+        # marker belongs to the assistant that generated it.
+        # The caller supplies the block's assistant because results may
+        # be reordered relative to their input-message indices.
+        closes_assistant_turn = closing_assistant_index is not None
+
+        if starts_block:
             emit_special(
                 self._observation,
-                msg_idx,
+                closing_assistant_index
+                if closing_assistant_index is not None
+                else msg_idx,
                 is_sampled=closes_assistant_turn,
-                is_content=False,
+                is_content=closes_assistant_turn,
             )
 
         emit_special(

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/tests/test_build_helpers.py

@@ -95,6 +95,110 @@ def test_build_training_sample_ensures_final_stop(model_name, tokenizer, rendere
         assert sample.token_ids == baseline.token_ids
 
 
+@pytest.mark.parametrize(
+    "selection",
+    [[0] * 6, [1] * 6, [0, 1, 0, 0, 1, 0], [False, False, True, True, False, True]],
+)
+@pytest.mark.parametrize("ensure_final_stop", [False, True])
+@pytest.mark.parametrize("body_roles", [None, {"user", "tool"}])
+@pytest.mark.parametrize("tool_turn", [False, True])
+def test_build_training_sample_message_loss_mask(
+    model_name, tokenizer, renderer, selection, ensure_final_stop, body_roles, tool_turn
+):
+    """Select arbitrary messages without changing tokens or enabling new targets."""
+    messages = [
+        {"role": "user", "content": "Hi"},
+        {"role": "assistant", "content": "Earlier answer."},
+        {"role": "user", "content": "Next question"},
+        {"role": "assistant", "content": "New answer."},
+        {"role": "user", "content": "One more question"},
+        {"role": "assistant", "content": "Final answer."},
+    ]
+    if tool_turn:
+        messages[1]["tool_calls"] = [
+            {
+                "id": "call_1",
+                "type": "function",
+                "function": {"name": "lookup", "arguments": '{"q":"x"}'},
+            }
+        ]
+        messages[2] = {
+            "role": "tool",
+            "content": "Lookup result",
+            "tool_call_id": "call_1",
+            "name": "lookup",
+        }
+    rendered = renderer.render(messages)
+    kwargs = {
+        "ensure_final_stop": ensure_final_stop,
+        "content_sft_roles": body_roles,
+    }
+    if not rendered.sampled_mask:
+        kwargs["role_to_mask"] = lambda m: m["role"] == "assistant"
+    baseline = build_training_sample(renderer, messages, **kwargs)
+    sample = build_training_sample(
+        renderer, messages, message_loss_mask=selection, **kwargs
+    )
+    assert sample.token_ids == baseline.token_ids
+    assert len(sample.loss_mask) == len(sample.token_ids)
+    for k, index in enumerate(rendered.message_indices):
+        if index < 0 or not selection[index]:
+            assert not sample.loss_mask[k]
+        else:
+            assert sample.loss_mask[k] == baseline.loss_mask[k]
+    # A synthesized stop is controlled by the final assistant's flag.
+    assert sample.loss_mask[len(rendered.token_ids) :] == [
+        keep and bool(selection[-1])
+        for keep in baseline.loss_mask[len(rendered.token_ids) :]
+    ]
+    disabled = build_training_sample(
+        renderer,
+        messages,
+        message_loss_mask=selection,
+        role_to_mask=lambda _: False,
+        ensure_final_stop=ensure_final_stop,
+    )
+    assert not any(disabled.loss_mask)
+    trained = tokenizer.decode(
+        [t for t, keep in zip(sample.token_ids[1:], sample.loss_mask[1:]) if keep]
+    )
+    for index, text in [
+        (1, "Earlier answer."),
+        (3, "New answer."),
+        (5, "Final answer."),
+    ]:
+        assert (text in trained) == bool(selection[index])
+    # Closing tokens are assistant output, including markers emitted while
+    # rendering the next user/tool message. Its body keeps its own owner.
+    for index, sampled in zip(rendered.message_indices, rendered.sampled_mask):
+        if sampled:
+            assert index >= 0 and messages[index]["role"] == "assistant"
+
+
+@pytest.mark.parametrize(
+    "selection",
+    [
+        [],
+        [1],
+        [1] * 5,
+        [1, 0, 2, 1],
+        [1, -1, 0, 1],
+        [1, "0", 0, 1],
+        [1, 1.0, 0, 1],
+        [1, None, 0, 1],
+    ],
+)
+def test_build_training_sample_rejects_invalid_message_loss_mask(selection):
+    messages = [
+        {"role": "user", "content": "Hi"},
+        {"role": "assistant", "content": "Answer"},
+        {"role": "tool", "content": "Result"},
+        {"role": "assistant", "content": "Final"},
+    ]
+    with pytest.raises(ValueError, match="message_loss_mask"):
+        build_training_sample(None, messages, message_loss_mask=selection)
+
+
 def test_build_trajectory_step_reconstructs_full(model_name, tokenizer, renderer):
     """prompt_ids + completion_ids must equal the full rendered sequence."""
     prompt = [

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/tests/test_message_indices.py

@@ -40,6 +40,69 @@ Tests in this file:
 
 from __future__ import annotations
 
+import pytest
+
+from renderers import build_training_sample
+from renderers.glm45 import GLM45Renderer
+from renderers.glm5 import GLM5Renderer
+from tests.reference_rendering import render_reference
+
+
+def test_glm_tool_stop_ownership(model_name, tokenizer, renderer):
+    """The first emitted observation closes the assistant, even after reordering."""
+    if not isinstance(renderer, (GLM5Renderer, GLM45Renderer)):
+        pytest.skip("GLM turn-closing role markers")
+    messages = [
+        {"role": "user", "content": "Look up both"},
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": f"c{i}",
+                    "type": "function",
+                    "function": {"name": f"f{i}", "arguments": {}},
+                }
+                for i in (1, 2)
+            ],
+        },
+        {
+            "role": "tool",
+            "content": "Second result",
+            "tool_call_id": "c2",
+            "name": "f2",
+        },
+        {"role": "tool", "content": "First result", "tool_call_id": "c1", "name": "f1"},
+        {"role": "assistant", "content": "Done"},
+    ]
+    rendered = renderer.render(messages)
+    assert rendered.token_ids == render_reference(tokenizer, messages)
+    observation = tokenizer.encode("<|observation|>", add_special_tokens=False)[0]
+    positions = [
+        k for k, token in enumerate(rendered.token_ids) if token == observation
+    ]
+    first, *rest = positions
+    assert rendered.message_indices[first] == 1
+    assert rendered.sampled_mask[first] and rendered.is_content[first]
+    assert not any(rendered.sampled_mask[k] for k in rest)
+    assert not rendered.content_mask_for_roles({"tool"})[first]
+    span = rendered.message_token_spans()[1]
+    assert span is not None
+    assert all(index == 1 for index in rendered.message_indices[span[0] : span[1]])
+    for selected in (False, True):
+        sample = build_training_sample(
+            renderer,
+            messages,
+            message_loss_mask=[0, selected, not selected, not selected, 0],
+            content_sft_roles={"tool"},
+            ensure_final_stop=True,
+        )
+        assert sample.loss_mask[first] == selected
+        for k, is_tool_body in enumerate(rendered.content_mask_for_roles({"tool"})):
+            if is_tool_body:
+                assert sample.loss_mask[k] == (not selected)
+        assert not sample.loss_mask[-1]
+
 
 def test_message_indices_in_range(model_name, renderer):
     """Every emitted token's ``message_indices`` must be in

{renderers-0.1.12.dev16 → renderers-0.1.12.dev17}/tests/test_sampled_mask.py

@@ -41,6 +41,8 @@ def test_sampled_mask_excludes_user_and_system(model_name, renderer):
         {"role": "system", "content": "You are helpful."},
         {"role": "user", "content": "Hi"},
         {"role": "assistant", "content": "Hello!"},
+        {"role": "user", "content": "Another question"},
+        {"role": "assistant", "content": "Another answer"},
     ]
     rendered = renderer.render(msgs)
     if not rendered.sampled_mask: