renderers 0.1.12.dev11__tar.gz → 0.1.12.dev12__tar.gz

{renderers-0.1.12.dev11 → renderers-0.1.12.dev12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: renderers
-Version: 0.1.12.dev11
+Version: 0.1.12.dev12
 Summary: Chat template renderers — deterministic message-to-token conversion for LLM training
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -221,6 +221,42 @@ One shared behaviour flag lives on typed renderer configs: `thinking_retention`,
 
 Generic `thinking_retention` does **not** change full `render()` output: a full re-render always follows the Python chat-template implementation. Only real template knobs can change full-render thinking behaviour. GLM-5 `clear_thinking=False`, Nemotron-3 `truncate_history_thinking=False`, Qwen3.6 `preserve_thinking=True`, and GPT-OSS `auto_drop_analysis=False` all imply bridge policy `"all"`; no-thinking generation knobs also imply `"all"` when `thinking_retention` is unset. Setting a direct keep/drop template knob and a contradictory `thinking_retention` raises at config-load. The full per-renderer mapping lives in [`docs/renderer-config.md`](docs/renderer-config.md).
 
+## Custom renderers
+
+A renderer can live outside this package. Point a `custom` config at the class with `import_path`, as `my_module.Class` or `path/to/file.py:Class`; relative file paths resolve against the working directory. The class sets `config_class` to its own `BaseRendererConfig` subclass, which validates every other field of the config and supplies its `chat_template_kwargs` allowlist. For example, a GLM-5.3 renderer whose generation prompt prefills an empty think block, so the model starts at the answer:
+
+```python
+from typing import Literal
+
+from renderers.configs import GLM53RendererConfig
+from renderers.glm5 import GLM53Renderer
+
+
+class NoThinkingGLM53Config(GLM53RendererConfig):
+    name: Literal["glm-5.3-no-thinking"] = "glm-5.3-no-thinking"
+
+
+class NoThinkingGLM53Renderer(GLM53Renderer):
+    config_class = NoThinkingGLM53Config
+
+    def _emit_generation_prompt(self, emit_special) -> None:
+        emit_special(self._assistant, -1, is_sampled=False, is_content=False)
+        emit_special(self._think, -1, is_sampled=False, is_content=False)
+        emit_special(self._think_end, -1, is_sampled=False, is_content=False)
+```
+
+```python
+from renderers import CustomRendererConfig, create_renderer
+
+config = CustomRendererConfig(
+    import_path="my_renderers.glm53_no_thinking.NoThinkingGLM53Renderer",
+    clear_thinking=True,
+)
+renderer = create_renderer(tokenizer, config)
+```
+
+Downstream TOML configs select it the same way, with `name = "custom"` and an `import_path`.
+
 ## `DefaultRenderer`
 
 Fallback for unsupported text-only models. Wraps `apply_chat_template` and accepts `tool_parser` / `reasoning_parser` (vLLM convention) plus arbitrary Jinja kwargs via `DefaultRendererConfig`'s `extra="allow"`. Explicit `thinking_retention` is rejected: `bridge_to_next_turn` returns `None` because the template's close is unknown, so multi-turn rollouts fall back to full re-render. Implementing a hand-coded renderer is a few hundred lines of Python (`render_ids` + `parse_response` + `bridge_to_next_turn`) and is the only path that closes the failure modes above by construction.

{renderers-0.1.12.dev11 → renderers-0.1.12.dev12}/README.md

@@ -201,6 +201,42 @@ One shared behaviour flag lives on typed renderer configs: `thinking_retention`,
 
 Generic `thinking_retention` does **not** change full `render()` output: a full re-render always follows the Python chat-template implementation. Only real template knobs can change full-render thinking behaviour. GLM-5 `clear_thinking=False`, Nemotron-3 `truncate_history_thinking=False`, Qwen3.6 `preserve_thinking=True`, and GPT-OSS `auto_drop_analysis=False` all imply bridge policy `"all"`; no-thinking generation knobs also imply `"all"` when `thinking_retention` is unset. Setting a direct keep/drop template knob and a contradictory `thinking_retention` raises at config-load. The full per-renderer mapping lives in [`docs/renderer-config.md`](docs/renderer-config.md).
 
+## Custom renderers
+
+A renderer can live outside this package. Point a `custom` config at the class with `import_path`, as `my_module.Class` or `path/to/file.py:Class`; relative file paths resolve against the working directory. The class sets `config_class` to its own `BaseRendererConfig` subclass, which validates every other field of the config and supplies its `chat_template_kwargs` allowlist. For example, a GLM-5.3 renderer whose generation prompt prefills an empty think block, so the model starts at the answer:
+
+```python
+from typing import Literal
+
+from renderers.configs import GLM53RendererConfig
+from renderers.glm5 import GLM53Renderer
+
+
+class NoThinkingGLM53Config(GLM53RendererConfig):
+    name: Literal["glm-5.3-no-thinking"] = "glm-5.3-no-thinking"
+
+
+class NoThinkingGLM53Renderer(GLM53Renderer):
+    config_class = NoThinkingGLM53Config
+
+    def _emit_generation_prompt(self, emit_special) -> None:
+        emit_special(self._assistant, -1, is_sampled=False, is_content=False)
+        emit_special(self._think, -1, is_sampled=False, is_content=False)
+        emit_special(self._think_end, -1, is_sampled=False, is_content=False)
+```
+
+```python
+from renderers import CustomRendererConfig, create_renderer
+
+config = CustomRendererConfig(
+    import_path="my_renderers.glm53_no_thinking.NoThinkingGLM53Renderer",
+    clear_thinking=True,
+)
+renderer = create_renderer(tokenizer, config)
+```
+
+Downstream TOML configs select it the same way, with `name = "custom"` and an `import_path`.
+
 ## `DefaultRenderer`
 
 Fallback for unsupported text-only models. Wraps `apply_chat_template` and accepts `tool_parser` / `reasoning_parser` (vLLM convention) plus arbitrary Jinja kwargs via `DefaultRendererConfig`'s `extra="allow"`. Explicit `thinking_retention` is rejected: `bridge_to_next_turn` returns `None` because the template's close is unknown, so multi-turn rollouts fall back to full re-render. Implementing a hand-coded renderer is a few hundred lines of Python (`render_ids` + `parse_response` + `bridge_to_next_turn`) and is the only path that closes the failure modes above by construction.

{renderers-0.1.12.dev11 → renderers-0.1.12.dev12}/renderers/__init__.py

@@ -37,13 +37,16 @@ from renderers.base import (
     create_renderer,
     extract_message_tool_names,
     is_multimodal,
+    merge_chat_template_kwargs,
     reject_assistant_in_extension,
+    template_field_names,
     trim_to_turn_close,
 )
 from renderers.client import MalformedGenerateResponseError, OverlongPromptError
 from renderers.configs import (
     AutoRendererConfig,
     BaseRendererConfig,
+    CustomRendererConfig,
     DeepSeekR1RendererConfig,
     DeepSeekV3RendererConfig,
     DeepSeekV4RendererConfig,
@@ -76,6 +79,7 @@ from renderers.configs import (
     RendererConfig,
     config_from_name,
 )
+from renderers.custom import custom_renderer_config, load_custom_renderer, load_target
 
 # Concrete renderer classes are lazy-loaded so that consumers needing only the
 # config layer (``RendererConfig`` discriminated union) don't import every
@@ -138,6 +142,7 @@ __all__ = [
     "ChatTemplateTokenizer",
     "Content",
     "ContentPart",
+    "CustomRendererConfig",
     "DeepSeekR1Renderer",
     "DeepSeekR1RendererConfig",
     "DeepSeekV3Renderer",
@@ -226,8 +231,13 @@ __all__ = [
     "build_trajectory_step",
     "config_from_name",
     "create_renderer",
+    "custom_renderer_config",
     "extract_message_tool_names",
     "is_multimodal",
+    "load_custom_renderer",
+    "load_target",
+    "merge_chat_template_kwargs",
     "reject_assistant_in_extension",
+    "template_field_names",
     "trim_to_turn_close",
 ]

{renderers-0.1.12.dev11 → renderers-0.1.12.dev12}/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.dev11'
-__version_tuple__ = version_tuple = (0, 1, 12, 'dev11')
+__version__ = version = '0.1.12.dev12'
+__version_tuple__ = version_tuple = (0, 1, 12, 'dev12')
 
 __commit_id__ = commit_id = None

{renderers-0.1.12.dev11 → renderers-0.1.12.dev12}/renderers/base.py

@@ -1424,6 +1424,12 @@ def create_renderer(
         config,
         chat_template_kwargs=chat_template_kwargs,
     )
+    from renderers.configs import CustomRendererConfig
+    from renderers.custom import custom_renderer_config, load_custom_renderer
+
+    if isinstance(config, CustomRendererConfig):
+        renderer_cls = load_custom_renderer(config.import_path)
+        return renderer_cls(tokenizer, custom_renderer_config(config))
     cls = RENDERER_REGISTRY.get(config.name)
     if cls is None:
         raise ValueError(
@@ -1432,26 +1438,49 @@ def create_renderer(
     return cls(tokenizer, config)
 
 
-def _merge_chat_template_kwargs(
+def template_field_names(config: RendererConfig) -> frozenset[str]:
+    """Chat-template kwargs that ``config``'s renderer accepts, custom renderers included."""
+    from renderers.configs import CustomRendererConfig
+    from renderers.custom import load_custom_renderer
+
+    if isinstance(config, CustomRendererConfig):
+        return load_custom_renderer(
+            config.import_path
+        ).config_class.template_field_names()
+    return type(config).template_field_names()
+
+
+def merge_chat_template_kwargs(
     config: RendererConfig,
     chat_template_kwargs: Mapping[str, Any] | None,
 ) -> RendererConfig:
+    """Return ``config`` with the template kwargs applied, validated against its allowlist."""
     if not chat_template_kwargs:
         return config
     if not isinstance(chat_template_kwargs, Mapping):
         raise TypeError("chat_template_kwargs must be a mapping.")
+    from renderers.configs import CustomRendererConfig
+    from renderers.custom import load_custom_renderer
+
     kwargs = dict(chat_template_kwargs)
     config_cls = type(config)
-    allowed = config_cls.template_field_names()
-    if config_cls._allow_opaque_template_kwargs:
-        reserved = frozenset(config_cls.model_fields) - allowed - {"name"}
+    # A custom config carries its renderer's fields as extras, so the renderer's
+    # own config class decides which kwargs are template controls.
+    fields_cls = (
+        load_custom_renderer(config.import_path).config_class
+        if isinstance(config, CustomRendererConfig)
+        else config_cls
+    )
+    allowed = fields_cls.template_field_names()
+    if fields_cls._allow_opaque_template_kwargs:
+        reserved = frozenset(fields_cls.model_fields) - allowed - {"name"}
         unsupported = frozenset(kwargs) & reserved
     else:
         unsupported = frozenset(kwargs) - allowed
     if unsupported:
         allowed_text = (
             "opaque Jinja kwargs"
-            if config_cls._allow_opaque_template_kwargs
+            if fields_cls._allow_opaque_template_kwargs
             else ", ".join(sorted(allowed)) or "(none)"
         )
         raise ValueError(
@@ -1486,7 +1515,7 @@ def _resolve_renderer_config(
             chat_template_kwargs=chat_template_kwargs,
         )
 
-    return _merge_chat_template_kwargs(config, chat_template_kwargs)
+    return merge_chat_template_kwargs(config, chat_template_kwargs)
 
 
 def _resolve_auto_config(
@@ -1514,7 +1543,7 @@ def _resolve_auto_config(
 
     if renderer_name is not None:
         cfg_cls = _config_class_for(renderer_name)
-        return _merge_chat_template_kwargs(
+        return merge_chat_template_kwargs(
             cfg_cls(**preserve_carry),
             chat_template_kwargs,
         )

{renderers-0.1.12.dev11 → renderers-0.1.12.dev12}/renderers/configs.py

@@ -994,6 +994,40 @@ class DeepSeekV4RendererConfig(BaseRendererConfig):
         return self
 
 
+class CustomRendererConfig(BaseRendererConfig):
+    """Config for a renderer that lives outside this package.
+
+    ``import_path`` names the renderer class as ``my_module.Class`` or
+    ``path/to/file.py:Class``; relative file paths resolve against the
+    working directory. The class sets ``config_class`` to its own
+    :class:`BaseRendererConfig` subclass, and that class validates every other
+    field of this config. A model-specific renderer can therefore ship without
+    a change to this package::
+
+        [renderer]
+        name = "custom"
+        import_path = "my_renderers.glm53_no_thinking.NoThinkingGLM53Renderer"
+        clear_thinking = true
+    """
+
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    name: Literal["custom"] = "custom"
+    import_path: str
+    """Renderer class as ``my_module.Class`` or ``path/to/file.py:Class``."""
+
+    _internal_fields = frozenset({"import_path"})
+
+    @model_validator(mode="after")
+    def _validate_renderer_fields(self):
+        # Fail at config load, not at the first render: the import path must
+        # resolve and the renderer's config must accept the other fields.
+        from renderers.custom import custom_renderer_config
+
+        custom_renderer_config(self)
+        return self
+
+
 RendererConfig = Annotated[
     Union[
         AutoRendererConfig,
@@ -1026,6 +1060,7 @@ RendererConfig = Annotated[
         DeepSeekV3RendererConfig,
         DeepSeekR1RendererConfig,
         DeepSeekV4RendererConfig,
+        CustomRendererConfig,
     ],
     Field(discriminator="name"),
 ]

renderers-0.1.12.dev12/renderers/custom.py

@@ -0,0 +1,99 @@
+"""Load custom renderers from importable modules or local Python files.
+
+An import path is ``my_module.Name`` (dotted, like any ``import``) or
+``path/to/file.py:Name``. File paths are resolved against the working
+directory and imported once per process under a stable module name, so every
+caller gets the same class objects.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import importlib.util
+import sys
+from functools import lru_cache
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from renderers.configs import BaseRendererConfig, CustomRendererConfig
+
+
+def load_target(import_path: str) -> Any:
+    """Return the object that ``import_path`` names."""
+    module_ref, sep, attr = import_path.rpartition(":")
+    if not sep and not _is_file_ref(import_path):
+        module_ref, sep, attr = import_path.rpartition(".")
+    if not sep or not module_ref or not attr:
+        raise ValueError(
+            f"Import path {import_path!r} must look like 'my_module.Name' or 'path/to/file.py:Name'"
+        )
+    module = load_module(module_ref)
+    try:
+        return getattr(module, attr)
+    except AttributeError:
+        raise ValueError(f"Module {module_ref!r} has no attribute {attr!r}") from None
+
+
+def load_module(module_ref: str) -> ModuleType:
+    """Import a module by dotted name or by file path."""
+    if _is_file_ref(module_ref):
+        return _load_file_module(str(Path(module_ref).expanduser().resolve()))
+    return importlib.import_module(module_ref)
+
+
+def _is_file_ref(ref: str) -> bool:
+    return ref.endswith(".py") or "/" in ref
+
+
+@lru_cache(maxsize=None)
+def _load_file_module(path: str) -> ModuleType:
+    file = Path(path)
+    if not file.is_file():
+        raise FileNotFoundError(f"Custom renderer file {path!r} does not exist")
+    # A path-derived name keeps two files with the same name apart.
+    digest = hashlib.sha1(path.encode()).hexdigest()[:8]
+    name = f"renderers_custom_{file.stem}_{digest}"
+    if name in sys.modules:
+        return sys.modules[name]
+    spec = importlib.util.spec_from_file_location(name, file)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot import custom renderer file {path!r}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    try:
+        spec.loader.exec_module(module)
+    except BaseException:
+        sys.modules.pop(name, None)
+        raise
+    return module
+
+
+def load_custom_renderer(import_path: str) -> Any:
+    """Return the renderer class that ``import_path`` names.
+
+    The class must set ``config_class`` to its own
+    :class:`~renderers.configs.BaseRendererConfig` subclass.
+    """
+    from renderers.configs import BaseRendererConfig
+
+    renderer_cls = load_target(import_path)
+    config_cls = getattr(renderer_cls, "config_class", None)
+    if not (
+        isinstance(config_cls, type) and issubclass(config_cls, BaseRendererConfig)
+    ):
+        raise TypeError(
+            f"Custom renderer {import_path!r} must set config_class to a BaseRendererConfig subclass"
+        )
+    return renderer_cls
+
+
+def custom_renderer_config(config: "CustomRendererConfig") -> "BaseRendererConfig":
+    """The renderer's own typed config, built from the fields next to ``import_path``."""
+    config_cls = load_custom_renderer(config.import_path).config_class
+    data = dict(config.model_extra or {})
+    for field_name in config.model_fields_set - {"name", "import_path"}:
+        data[field_name] = getattr(config, field_name)
+    return config_cls.model_validate(data)

{renderers-0.1.12.dev11 → renderers-0.1.12.dev12}/renderers/deepseek_v4.py

@@ -331,6 +331,10 @@ class DeepSeekV4Renderer:
             raise ValueError(f"Expected one token for {token!r}, got {ids}")
         return ids[0]
 
+    def _reasoning_effort_prompt(self) -> str:
+        """Text emitted after BOS in thinking mode; subclasses can replace it."""
+        return _REASONING_EFFORT_PROMPTS[self.config.reasoning_effort]
+
     @staticmethod
     def _render_tools(tools: list[ToolSpec]) -> str:
         schemas = [_json(dict(_tool_function(tool))) for tool in tools]
@@ -573,10 +577,7 @@ class DeepSeekV4Renderer:
         if add_bos:
             emit_special(self._bos, -1)
         if add_effort_prompt and self.config.enable_thinking:
-            emit_text(
-                _REASONING_EFFORT_PROMPTS[self.config.reasoning_effort],
-                -1,
-            )
+            emit_text(self._reasoning_effort_prompt(), -1)
 
         last_query_index = -1
         for index, message in enumerate(logical_messages):

{renderers-0.1.12.dev11 → renderers-0.1.12.dev12}/renderers/glm5.py

@@ -286,11 +286,7 @@ class GLM5Renderer:
         # sampling starts — the model continues from these, never emits
         # them. Always is_sampled=False / is_content=False.
         if add_generation_prompt:
-            emit_special(self._assistant, -1, is_sampled=False, is_content=False)
-            if getattr(self.config, "enable_thinking", True):
-                emit_special(self._think, -1, is_sampled=False, is_content=False)
-            else:
-                emit_special(self._think_end, -1, is_sampled=False, is_content=False)
+            self._emit_generation_prompt(emit_special)
 
         return RenderedTokens(
             token_ids=tokens,
@@ -301,6 +297,16 @@ class GLM5Renderer:
             message_tool_names=extract_message_tool_names(messages),
         )
 
+    def _emit_generation_prompt(self, emit_special) -> None:
+        """Generation prompt: ``<|assistant|><think>`` when thinking is on, or
+        ``<|assistant|></think>`` when ``enable_thinking=False``. A subclass can
+        override this to prefill a different prompt."""
+        emit_special(self._assistant, -1, is_sampled=False, is_content=False)
+        if getattr(self.config, "enable_thinking", True):
+            emit_special(self._think, -1, is_sampled=False, is_content=False)
+        else:
+            emit_special(self._think_end, -1, is_sampled=False, is_content=False)
+
     @staticmethod
     def _ordered_tool_indices(messages: list[Message], block_start: int) -> list[int]:
         """Return one contiguous tool block in its source order."""
@@ -499,11 +505,7 @@ class GLM5Renderer:
                 return None
 
         # Generation prompt — match the gen-prompt branch of ``render()``.
-        emit_special(self._assistant, -1)
-        if getattr(self.config, "enable_thinking", True):
-            emit_special(self._think, -1)
-        else:
-            emit_special(self._think_end, -1)
+        self._emit_generation_prompt(emit_special)
 
         total_len = len(previous_ids) + len(ext)
         return RenderedTokens(

renderers-0.1.12.dev12/tests/test_custom.py

@@ -0,0 +1,194 @@
+"""Custom renderers loaded from local files or importable modules."""
+
+from __future__ import annotations
+
+import pickle
+import textwrap
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from renderers import (
+    CustomRendererConfig,
+    GLM53RendererConfig,
+    RendererConfig,
+    create_renderer,
+    custom_renderer_config,
+    load_custom_renderer,
+    merge_chat_template_kwargs,
+    template_field_names,
+)
+
+TOY_SOURCE = textwrap.dedent(
+    """
+    from typing import Literal
+
+    from renderers.configs import BaseRendererConfig
+
+
+    class ToyRendererConfig(BaseRendererConfig):
+        name: Literal["toy"] = "toy"
+        effort: int = 1
+        cache_size: int = 8
+        _template_fields = frozenset({"effort"})
+        _internal_fields = frozenset({"cache_size"})
+
+
+    class ToyRenderer:
+        config_class = ToyRendererConfig
+
+        def __init__(self, tokenizer, config):
+            self.tokenizer = tokenizer
+            self.config = config
+
+
+    class NoConfigRenderer:
+        pass
+    """
+)
+
+
+@pytest.fixture
+def toy_file(tmp_path):
+    path = tmp_path / "toy_renderer.py"
+    path.write_text(TOY_SOURCE)
+    return path
+
+
+def import_path(path, name="ToyRenderer"):
+    return f"{path}:{name}"
+
+
+def test_custom_fields_validate_through_the_renderer_config(toy_file):
+    config = CustomRendererConfig(import_path=import_path(toy_file), effort=3)
+    assert custom_renderer_config(config).effort == 3
+    assert custom_renderer_config(config).name == "toy"
+    with pytest.raises(ValidationError):
+        CustomRendererConfig(import_path=import_path(toy_file), unknown=1)
+
+
+def test_shared_renderer_fields_reach_the_renderer_config(toy_file):
+    config = CustomRendererConfig(
+        import_path=import_path(toy_file), thinking_retention="all"
+    )
+    assert custom_renderer_config(config).thinking_retention == "all"
+
+
+def test_discriminated_union_parses_renderer_configs(toy_file):
+    config = TypeAdapter(RendererConfig).validate_python(
+        {"name": "custom", "import_path": import_path(toy_file), "effort": 2}
+    )
+    assert isinstance(config, CustomRendererConfig)
+    assert custom_renderer_config(config).effort == 2
+
+
+def test_create_renderer_builds_the_custom_renderer_with_its_own_config(toy_file):
+    tokenizer = object()
+    renderer = create_renderer(
+        tokenizer, CustomRendererConfig(import_path=import_path(toy_file), effort=4)
+    )
+    assert type(renderer).__name__ == "ToyRenderer"
+    assert renderer.tokenizer is tokenizer
+    assert type(renderer.config).__name__ == "ToyRendererConfig"
+    assert renderer.config.effort == 4
+
+
+def test_chat_template_kwargs_use_the_custom_renderer_allowlist(toy_file):
+    config = CustomRendererConfig(import_path=import_path(toy_file))
+    renderer = create_renderer(object(), config, chat_template_kwargs={"effort": 5})
+    assert renderer.config.effort == 5
+    with pytest.raises(ValueError, match="cache_size"):
+        create_renderer(object(), config, chat_template_kwargs={"cache_size": 2})
+
+
+def test_module_import_paths_import_by_name(toy_file, monkeypatch):
+    monkeypatch.syspath_prepend(str(toy_file.parent))
+    config = CustomRendererConfig(import_path="toy_renderer.ToyRenderer", effort=6)
+    assert create_renderer(object(), config).config.effort == 6
+
+
+def test_file_import_paths_load_once_per_process(toy_file):
+    assert load_custom_renderer(import_path(toy_file)) is load_custom_renderer(
+        import_path(toy_file)
+    )
+
+
+def test_invalid_import_paths_fail_clearly(toy_file, tmp_path):
+    with pytest.raises(ValueError, match="must look like"):
+        CustomRendererConfig(import_path=str(toy_file))
+    with pytest.raises(ValueError, match="has no attribute"):
+        CustomRendererConfig(import_path=import_path(toy_file, "Missing"))
+    with pytest.raises(TypeError, match="config_class"):
+        CustomRendererConfig(import_path=import_path(toy_file, "NoConfigRenderer"))
+    with pytest.raises(FileNotFoundError):
+        CustomRendererConfig(import_path=f"{tmp_path / 'missing.py'}:ToyRenderer")
+
+
+def test_renderer_configs_pickle_and_key_caches(toy_file):
+    low = CustomRendererConfig(import_path=import_path(toy_file), effort=1)
+    high = CustomRendererConfig(import_path=import_path(toy_file), effort=9)
+    assert pickle.loads(pickle.dumps(high)) == high
+    cache = {low: "low", high: "high"}
+    assert (
+        cache[CustomRendererConfig(import_path=import_path(toy_file), effort=9)]
+        == "high"
+    )
+    assert low != high
+
+
+def test_public_helpers_resolve_custom_template_fields(toy_file):
+    config = CustomRendererConfig(import_path=import_path(toy_file))
+    assert template_field_names(config) == frozenset({"effort"})
+    merged = merge_chat_template_kwargs(config, {"effort": 7})
+    assert isinstance(merged, CustomRendererConfig)
+    assert custom_renderer_config(merged).effort == 7
+    with pytest.raises(ValueError, match="cache_size"):
+        merge_chat_template_kwargs(config, {"cache_size": 1})
+
+
+GLM53_NO_THINKING_SOURCE = textwrap.dedent(
+    """
+    from typing import Literal
+
+    from renderers.configs import GLM53RendererConfig
+    from renderers.glm5 import GLM53Renderer
+
+
+    class NoThinkingGLM53Config(GLM53RendererConfig):
+        name: Literal["glm-5.3-no-thinking"] = "glm-5.3-no-thinking"
+
+
+    class NoThinkingGLM53Renderer(GLM53Renderer):
+        config_class = NoThinkingGLM53Config
+
+        def _emit_generation_prompt(self, emit_special) -> None:
+            emit_special(self._assistant, -1, is_sampled=False, is_content=False)
+            emit_special(self._think, -1, is_sampled=False, is_content=False)
+            emit_special(self._think_end, -1, is_sampled=False, is_content=False)
+    """
+)
+
+
+def test_readme_example_prefills_the_think_block(tmp_path):
+    from renderers.base import load_tokenizer
+
+    path = tmp_path / "glm53_no_thinking.py"
+    path.write_text(GLM53_NO_THINKING_SOURCE)
+    tokenizer = load_tokenizer("zai-org/GLM-5.3-BF16")
+    messages = [{"role": "user", "content": "What is 2 + 2?"}]
+
+    custom = create_renderer(
+        tokenizer,
+        CustomRendererConfig(
+            import_path=import_path(path, "NoThinkingGLM53Renderer"),
+            clear_thinking=True,
+        ),
+    )
+    builtin = create_renderer(tokenizer, GLM53RendererConfig(clear_thinking=True))
+
+    ids = custom.render_ids(messages, add_generation_prompt=True)
+    builtin_ids = builtin.render_ids(messages, add_generation_prompt=True)
+    assert tokenizer.decode(ids[-3:]) == "<|assistant|><think></think>"
+    assert tokenizer.decode(builtin_ids[-2:]) == "<|assistant|><think>"
+    assert ids[:-1] == builtin_ids
+    assert custom.config.clear_thinking is True