renderers 0.1.8.dev52__tar.gz → 0.1.8.dev54__tar.gz

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: renderers
-Version: 0.1.8.dev52
+Version: 0.1.8.dev54
 Summary: Chat template renderers — deterministic message-to-token conversion for LLM training
 License-Expression: Apache-2.0
 License-File: LICENSE

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/renderers/__init__.py

@@ -19,6 +19,7 @@ from renderers.base import (
     PlaceholderRange,
     RenderedConversation,
     RenderedTokens,
+    RenderedTrainingSample,
     Renderer,
     RendererPool,
     TextPart,
@@ -53,6 +54,7 @@ from renderers.configs import (
     KimiK25RendererConfig,
     KimiK2RendererConfig,
     LagunaXS2RendererConfig,
+    LagunaXS21RendererConfig,
     Llama3RendererConfig,
     MiniMaxM2RendererConfig,
     Nemotron3RendererConfig,
@@ -138,6 +140,7 @@ __all__ = [
     "KimiK2RendererConfig",
     "LagunaXS2Renderer",
     "LagunaXS2RendererConfig",
+    "LagunaXS21RendererConfig",
     "Llama3Renderer",
     "Llama3RendererConfig",
     "MULTIMODAL_MODELS",
@@ -164,6 +167,7 @@ __all__ = [
     "Qwen3VLRendererConfig",
     "RenderedConversation",
     "RenderedTokens",
+    "RenderedTrainingSample",
     "Renderer",
     "RendererConfig",
     "RendererPool",

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/renderers/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.8.dev52'
-__version_tuple__ = version_tuple = (0, 1, 8, 'dev52')
+__version__ = version = '0.1.8.dev54'
+__version_tuple__ = version_tuple = (0, 1, 8, 'dev54')
 
 __commit_id__ = commit_id = None

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/renderers/base.py

@@ -1060,8 +1060,10 @@ MODEL_RENDERER_MAP: dict[str, str] = {
     # construction to pin a different date.
     "meta-llama/Llama-3.2-1B-Instruct": "llama-3",
     "meta-llama/Llama-3.2-3B-Instruct": "llama-3",
-    # Poolside Laguna.
+    # Poolside Laguna. XS-2.1's template is byte-identical to XS.2's minus
+    # the default system message; the config name selects the variant.
     "poolside/Laguna-XS.2": "laguna-xs.2",
+    "poolside/Laguna-XS-2.1": "laguna-xs-2.1",
     # GPT-OSS.
     "openai/gpt-oss-20b": "gpt-oss",
     "openai/gpt-oss-120b": "gpt-oss",
@@ -1327,6 +1329,7 @@ def _populate_registry():
             "kimi-k2": KimiK2Renderer,
             "kimi-k2.5": KimiK25Renderer,
             "laguna-xs.2": LagunaXS2Renderer,
+            "laguna-xs-2.1": LagunaXS2Renderer,
             "llama-3": Llama3Renderer,
             "nemotron-3": Nemotron3Renderer,
             "nemotron-3-ultra": Nemotron3UltraRenderer,
@@ -1534,6 +1537,42 @@ def _resolve_auto_config(
 # ---------------------------------------------------------------------------
 
 
+# Match prime-rl's multimodal token type convention: 0=text, 1=image, 2=video.
+_MM_TYPE_ID: dict[str, int] = {"image": 1, "video": 2}
+
+
+@dataclass(frozen=True)
+class RenderedTrainingSample:
+    """Output of :func:`build_training_sample`.
+
+    ``token_ids`` and ``loss_mask`` are always populated. ``multi_modal_data``
+    and ``mm_token_type_ids`` are populated only when a multimodal renderer
+    actually emitted media (both ``None`` for text-only renderers and for
+    text-only samples through a VLM renderer), so the text path is unchanged.
+    """
+
+    token_ids: list[int]
+    loss_mask: list[bool]
+    multi_modal_data: "MultiModalData | None" = None
+    mm_token_type_ids: list[int] | None = None
+
+
+def _build_mm_token_type_ids(
+    mm_placeholders: dict[str, list[PlaceholderRange]], length: int
+) -> list[int]:
+    """Per-token modality flags (0=text, 1=image, 2=video) from placeholder ranges."""
+    ids = [0] * length
+    for modality, ranges in mm_placeholders.items():
+        type_id = _MM_TYPE_ID.get(modality, 0)
+        if type_id == 0:
+            continue
+        for r in ranges:
+            end = min(r.offset + r.length, length)
+            for i in range(r.offset, end):
+                ids[i] = type_id
+    return ids
+
+
 def build_training_sample(
     renderer: Renderer,
     messages: list[Message],
@@ -1541,8 +1580,12 @@ def build_training_sample(
     role_to_mask: Callable[[Message], bool] | None = None,
     tools: list[ToolSpec] | None = None,
     content_sft_roles: "set[str] | frozenset[str] | None" = None,
-) -> tuple[list[int], list[bool]]:
-    """Build (token_ids, loss_mask) for supervised training.
+) -> RenderedTrainingSample:
+    """Build a :class:`RenderedTrainingSample` for supervised training.
+
+    Returns ``token_ids`` + ``loss_mask`` (always), plus ``multi_modal_data``
+    and ``mm_token_type_ids`` when the renderer emitted media (``None`` for
+    text — the text token_ids/loss_mask are byte-identical to before).
 
     Single render() call + message_indices → per-token mask.
     Replaces build_incremental_token_mask (O(N) renders → O(1)).
@@ -1631,7 +1674,24 @@ def build_training_sample(
             loss_mask.append(True)
         else:
             loss_mask.append(role_to_mask(msg))
-    return rendered.token_ids, loss_mask
+
+    # 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.
+    mm = rendered.multi_modal_data
+    if mm is not None and mm.is_empty():
+        mm = None
+    mm_token_type_ids = (
+        _build_mm_token_type_ids(mm.mm_placeholders, len(rendered.token_ids))
+        if mm is not None and mm.mm_placeholders
+        else None
+    )
+    return RenderedTrainingSample(
+        token_ids=rendered.token_ids,
+        loss_mask=loss_mask,
+        multi_modal_data=mm,
+        mm_token_type_ids=mm_token_type_ids,
+    )
 
 
 def _common_prefix_len(a: list[int], b: list[int]) -> int:

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/renderers/configs.py

@@ -422,6 +422,27 @@ class LagunaXS2RendererConfig(BaseRendererConfig):
     chat template's ``render_assistant_messages_raw`` gate."""
 
 
+class LagunaXS21RendererConfig(BaseRendererConfig):
+    """Laguna XS-2.1 renderer config — distinct discriminator so auto
+    resolution gives XS-2.1 checkpoints the no-default-system-message
+    template variant.
+
+    XS-2.1's chat template is byte-identical to XS.2's except it ships
+    no default system message: when the caller provides none (and no
+    tools), the ``<system>`` block is omitted entirely. Shares
+    :class:`renderers.laguna_xs2.LagunaXS2Renderer`, which selects the
+    variant from ``config.name``.
+    """
+
+    name: Literal["laguna-xs-2.1"] = "laguna-xs-2.1"
+
+    enable_thinking: bool = False
+    """See :class:`LagunaXS2RendererConfig.enable_thinking`."""
+
+    render_assistant_messages_raw: bool = False
+    """See :class:`LagunaXS2RendererConfig.render_assistant_messages_raw`."""
+
+
 class Llama3RendererConfig(BaseRendererConfig):
     """Llama-3.x Instruct renderer config.
 
@@ -576,6 +597,7 @@ RendererConfig = Annotated[
         KimiK2RendererConfig,
         KimiK25RendererConfig,
         LagunaXS2RendererConfig,
+        LagunaXS21RendererConfig,
         Llama3RendererConfig,
         MiniMaxM2RendererConfig,
         Nemotron3RendererConfig,
@@ -613,6 +635,7 @@ _CONFIG_BY_NAME: dict[str, type[BaseRendererConfig]] = {
     "kimi-k2": KimiK2RendererConfig,
     "kimi-k2.5": KimiK25RendererConfig,
     "laguna-xs.2": LagunaXS2RendererConfig,
+    "laguna-xs-2.1": LagunaXS21RendererConfig,
     "llama-3": Llama3RendererConfig,
     "minimax-m2": MiniMaxM2RendererConfig,
     "nemotron-3": Nemotron3RendererConfig,
@@ -659,6 +682,7 @@ __all__ = [
     "KimiK25RendererConfig",
     "KimiK2RendererConfig",
     "LagunaXS2RendererConfig",
+    "LagunaXS21RendererConfig",
     "Llama3RendererConfig",
     "MiniMaxM2RendererConfig",
     "Nemotron3RendererConfig",

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/renderers/laguna_xs2.py

@@ -1,4 +1,4 @@
-"""Laguna-XS.2 Renderer.
+"""Laguna-XS.2 / XS-2.1 Renderer.
 
 Main properties:
 - Prefix is the single token ``〈|EOS|〉`` (also the EOS / stop token).
@@ -12,10 +12,13 @@ Main properties:
 - Tool calls: ``<tool_call>`` / ``</tool_call>`` ARE single tokens, but the
   inner ``<arg_key>`` / ``</arg_key>`` / ``<arg_value>`` / ``</arg_value>``
   markers are plain text — parsed via regex on the decoded inner block.
-- The template bakes in a default system prompt when ``messages[0]`` is not
-  a system message. The system block also contains the tools section (under
-  a ``### Tools`` header with an ``<available_tools>`` listing and prose
-  format instructions that vary on ``enable_thinking``).
+- XS.2's template bakes in a default system prompt when ``messages[0]`` is
+  not a system message; XS-2.1's (otherwise byte-identical) template
+  removed it, so no system message and no tools means no ``<system>``
+  block at all. The config's ``name`` selects the variant. The system
+  block also contains the tools section (under a ``### Tools`` header
+  with an ``<available_tools>`` listing and prose format instructions
+  that vary on ``enable_thinking``).
 - Reasoning is rendered for every assistant message — no last-user-index
   gating. ``thinking_retention`` is accepted for protocol uniformity but
   is effectively a no-op since past reasoning is preserved by default.
@@ -39,7 +42,7 @@ from renderers.base import (
     resolve_thinking_retention,
     should_rerender_for_thinking_retention,
 )
-from renderers.configs import LagunaXS2RendererConfig
+from renderers.configs import LagunaXS2RendererConfig, LagunaXS21RendererConfig
 from renderers.parsing import parse_laguna_xs2
 
 _DEFAULT_SYSTEM_MESSAGE = (
@@ -81,7 +84,7 @@ class LagunaXS2Renderer:
     def __init__(
         self,
         tokenizer: PreTrainedTokenizer,
-        config: LagunaXS2RendererConfig | None = None,
+        config: LagunaXS2RendererConfig | LagunaXS21RendererConfig | None = None,
     ):
         self._tokenizer = tokenizer
         self.config = config or LagunaXS2RendererConfig()
@@ -89,6 +92,11 @@ class LagunaXS2Renderer:
             self.config,
             "all",
         )
+        # XS.2's template bakes in a default system prompt; XS-2.1's
+        # (otherwise byte-identical) template removed it.
+        self._default_system_message = (
+            _DEFAULT_SYSTEM_MESSAGE if self.config.name == "laguna-xs.2" else ""
+        )
 
         self._eos = self._token_id("〈|EOS|〉")
         self._think = self._token_id("<think>")
@@ -184,7 +192,7 @@ class LagunaXS2Renderer:
         emit_special(self._eos, -1, is_sampled=False, is_content=False)
 
         # ── System header (absorbs messages[0] if it's a system message) ──
-        system_content = _DEFAULT_SYSTEM_MESSAGE
+        system_content = self._default_system_message
         system_msg_idx = -1
         caller_has_system = bool(messages and messages[0].get("role") == "system")
         if caller_has_system:
@@ -196,16 +204,12 @@ class LagunaXS2Renderer:
         # gate: when the caller passes an empty system message and no tools,
         # the whole ``<system>...</system>`` block is omitted.
         if has_sys_content or tools:
-            # The template emits ``<system>\n`` then conditionally a second
-            # ``\n``. Bundle those into one emit so BPE merges ``\n\n`` into
-            # its single-token form (rather than two ``\n`` atoms).
-            emit_text(
-                "<system>\n\n" if has_sys_content else "<system>\n",
-                -1,
-                is_sampled=False,
-                is_content=False,
-            )
             if has_sys_content:
+                # The template emits ``<system>\n`` then a second ``\n``
+                # before the system body. Bundle those into one emit so BPE
+                # merges ``\n\n`` into its single-token form (rather than
+                # two ``\n`` atoms).
+                emit_text("<system>\n\n", -1, is_sampled=False, is_content=False)
                 # If the caller provided system content, it's body bytes;
                 # otherwise this is the default system prompt (scaffold).
                 sys_is_content = caller_has_system
@@ -224,6 +228,11 @@ class LagunaXS2Renderer:
                     if self.config.enable_thinking
                     else _TOOLS_FOOTER_NO_THINKING
                 )
+                if not has_sys_content:
+                    # No system body: ``<system>\n`` runs straight into the
+                    # tools header's ``\n\n`` — encode them together so BPE
+                    # merges the ``\n\n\n`` seam as the template does.
+                    tool_text = "<system>\n" + tool_text
                 emit_text(tool_text, -1, is_sampled=False, is_content=False)
             emit_text("\n</system>\n", -1, is_sampled=False, is_content=False)
 

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/tests/conftest.py

@@ -37,6 +37,9 @@ RENDERER_MODELS = [
     # name (auto → MODEL_RENDERER_MAP → nemotron-3-ultra).
     ("nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-BF16", "auto"),
     ("poolside/Laguna-XS.2", "auto"),
+    # XS-2.1 resolves to the `laguna-xs-2.1` config variant (no default
+    # system message) via the model name.
+    ("poolside/Laguna-XS-2.1", "auto"),
     # DeepSeek-V3/R1 are intentionally NOT in this shared barrage: their
     # chat templates can't render the barrage's tool-call fixtures (the
     # templates require ``tool['type']`` and a string-serialized

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/tests/test_build_helpers.py

@@ -4,6 +4,17 @@ Runs against every (model, renderer) pair.
 """
 
 from renderers import build_training_sample, build_trajectory_step
+from renderers.base import PlaceholderRange, _build_mm_token_type_ids
+
+
+def test_build_mm_token_type_ids_marks_ranges():
+    """Image runs → 1, video runs → 2, everything else → 0; clips at length."""
+    placeholders = {
+        "image": [PlaceholderRange(offset=2, length=3)],  # tokens 2,3,4
+        "video": [PlaceholderRange(offset=7, length=2)],  # tokens 7,8
+    }
+    ids = _build_mm_token_type_ids(placeholders, length=10)
+    assert ids == [0, 0, 1, 1, 1, 0, 0, 2, 2, 0]
 
 
 def _expected(tokenizer, messages, **kwargs):
@@ -29,10 +40,14 @@ def test_build_training_sample_ids_match(model_name, tokenizer, renderer):
         {"role": "user", "content": "Hi"},
         {"role": "assistant", "content": "Hello!"},
     ]
-    ids, mask = build_training_sample(
+    sample = build_training_sample(
         renderer, msgs, role_to_mask=lambda m: m["role"] == "assistant"
     )
+    ids = sample.token_ids
     assert ids == _expected(tokenizer, msgs)
+    # text-only sample carries no multimodal payload
+    assert sample.multi_modal_data is None
+    assert sample.mm_token_type_ids is None
 
 
 def test_build_training_sample_has_trainable_tokens(model_name, tokenizer, renderer):
@@ -41,9 +56,10 @@ def test_build_training_sample_has_trainable_tokens(model_name, tokenizer, rende
         {"role": "user", "content": "Hi"},
         {"role": "assistant", "content": "Hello!"},
     ]
-    ids, mask = build_training_sample(
+    sample = build_training_sample(
         renderer, msgs, role_to_mask=lambda m: m["role"] == "assistant"
     )
+    ids, mask = sample.token_ids, sample.loss_mask
     assert sum(mask) > 0
     assert len(mask) == len(ids)
 

{renderers-0.1.8.dev52 → renderers-0.1.8.dev54}/tests/test_is_content.py

@@ -353,12 +353,13 @@ def test_build_training_sample_content_sft_roles_picks_up_tool_body(
         {"role": "tool", "content": "done", "tool_call_id": "call_z"},
         {"role": "assistant", "content": "OK."},
     ]
-    ids, mask = build_training_sample(
+    sample = build_training_sample(
         renderer,
         msgs,
         role_to_mask=lambda m: m["role"] == "assistant",
         content_sft_roles={"tool"},
     )
+    ids, mask = sample.token_ids, sample.loss_mask
     assert len(mask) == len(ids)
 
     # We need at least one trainable tool-body token if the renderer