clams-python 1.7.1__tar.gz → 1.7.2__tar.gz

{clams_python-1.7.1 → clams_python-1.7.2}/CHANGELOG.md

@@ -1,4 +1,9 @@
 
+## releasing 1.7.1 (2026-06-19)
+### Overview
+Updates the `mmif-python` SDK dependency to 1.5.1 to incorporate a bugfix in VDH, with some other minor documentation generation improvements.
+
+
 ## releasing 1.7.0 (2026-05-29)
 ### Overview
 This release introduces a specialized base class `ClamsPromptableApp` and its HuggingFace specialization `ClamsHFPromptableApp` for CLAMS apps that wrap LLM / VLM / ALM / LMM-based analyzers, along with other HF-related helper code in various places. Additionally, it adds `appTags` field for app categorization in app metadata, and new timeframe related local utility recipe for `clams develop --recipe utl-tf` scaffold.

{clams_python-1.7.1/clams_python.egg-info → clams_python-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clams-python
-Version: 1.7.1
+Version: 1.7.2
 Summary: A collection of APIs to develop CLAMS app for python
 License-Expression: Apache-2.0
 Project-URL: homepage, https://clams.ai

{clams_python-1.7.1 → clams_python-1.7.2}/clams/app/__init__.py

@@ -1005,8 +1005,10 @@ class ClamsPromptableApp(ClamsApp):
         """
         Persist a single LLM text response into a view. Writes one
         ``TextDocument`` (containing the response) plus possible
-        grounding via an ``Alignment`` annotation and ``origins`` / 
-        ``origination`` properties on the TD.
+        grounding via an ``Alignment`` annotation and ``origins`` /
+        ``origination`` properties on the TD. The TD also inherits the
+        ``document`` of its ``source`` annotation, so it records which
+        medium the response describes.
 
         The two grounding link kinds are semantically distinct:
 
@@ -1028,7 +1030,12 @@ class ClamsPromptableApp(ClamsApp):
             ``Alignment`` first if needed.
         :param source: ``id`` of the annotation to record as the
             cross-modal anchor of the response (see above).
-        :param response: the text generated by the model.
+        :param response: the text to store as the TextDocument's
+            value. Typically the model's generated answer, but the
+            caller MAY pass a post-processed form (e.g. with a
+            reasoning block stripped, whitespace trimmed, or otherwise
+            reformatted); this method stores whatever it is given,
+            verbatim, as the ``text``.
         :param origins: optional list of ``id``\\s of annotations the
             response was *derived* from. Must be paired with
             ``origination``.
@@ -1039,15 +1046,24 @@ class ClamsPromptableApp(ClamsApp):
             ``origins``.
         :param reasoning_trace: optional model-side reasoning trace
             (a chain-of-thought / scratchpad string, NOT a Python
-            traceback). NOT YET SUPPORTED -- passing a non-``None``
-            value raises :py:class:`NotImplementedError`. Storage
-            convention is still being decided at
-            clamsproject/clams-python#263.
+            traceback). When non-``None``, it is stored on the
+            returned TextDocument as the ``modelReasoningTrace``
+            property, kept OUT of the ``text`` (which holds whatever
+            ``response`` the caller passed). The point is separation,
+            not any claim about the ``text`` being verbatim: storing a
+            trace adds no annotation and no new type, so the type-level
+            output shape is identical whether or not a trace is stored.
+            Pass ``None`` (the default) to store no trace. The property
+            name is provisional pending the
+            vocabulary convention (clamsproject/clams-vocabulary#11).
         :return: ``(TextDocument, Alignment)`` tuple of the new
             annotations.
         :raises ValueError: if exactly one of ``origins`` /
-            ``origination`` is set; they must be supplied together
-            or both omitted.
+            ``origination`` is set (they must be supplied together or
+            both omitted), or if the ``source`` annotation carries no
+            ``document`` to ground the response to (a malformed input).
+        :raises KeyError: if ``source`` does not resolve to an
+            annotation in the MMIF.
         """
         if bool(origins) != bool(origination):
             raise ValueError(
@@ -1056,6 +1072,20 @@ class ClamsPromptableApp(ClamsApp):
                 f"origins={origins!r}, origination={origination!r}."
             )
         td = view.new_textdocument(text=response)
+        # Ground the TextDocument to the medium it describes: copy `document`
+        # from the source annotation (e.g. the parent TimeFrame's video) onto
+        # the TD, so it records which document the response pertains to. A
+        # grounded response must be traceable to a document, so a source that
+        # carries no `document` means the upstream MMIF is malformed -- raise
+        # rather than silently drop the grounding.
+        source_ann = view._parent_mmif[source]
+        source_doc = source_ann.get_property('document')
+        if not source_doc:
+            raise ValueError(
+                f"source annotation {source!r} has no `document` property to "
+                f"ground the response to; the input MMIF is malformed."
+            )
+        td.add_property('document', source_doc)
         if origins:
             td.add_property('origins', origins)
             td.add_property('origination', origination)
@@ -1065,13 +1095,52 @@ class ClamsPromptableApp(ClamsApp):
             target=td.id,
         )
         if reasoning_trace is not None:
-            raise NotImplementedError(
-                "Reasoning-trace storage convention is not yet defined; "
-                "tracked at clamsproject/clams-python#263."
-            )
+            # Store the trace as a property on the TD rather than a separate
+            # document: keeps the type-level output shape invariant (same
+            # annotation, same `contains`, same graph) whether or not a trace is
+            # present -- a strict enrichment, independent of whatever `response`
+            # the caller put in `text`. Property name provisional pending
+            # clamsproject/clams-vocabulary#11.
+            td.add_property('modelReasoningTrace', reasoning_trace)
         return td, align
 
-
+    @staticmethod
+    def split_tagged_reasoning_trace(
+            text: str,
+            open_tag: str = '<think>',
+            close_tag: str = '</think>',
+    ) -> Tuple[str, Optional[str]]:
+        """
+        Split a reasoning model's output into ``(answer, trace)`` for the
+        inline XML-tag style: a single reasoning block delimited by
+        ``open_tag`` / ``close_tag`` (default ``<think>`` / ``</think>``)
+        embedded in the decoded text, e.g. as emitted by DeepSeek-R1 or
+        Qwen3.
+
+        It does NOT handle models that isolate reasoning in a separate
+        token-delimited channel rather than an inline tag block (e.g.
+        gpt-oss, Gemma 4); those need their own parsing in the app. Trace
+        handling is the app's responsibility either way -- call this when
+        the model fits the inline-tag style, or parse it yourself.
+
+        ``answer`` is everything after the final ``close_tag`` (stripped);
+        ``trace`` is the text between the tags, or ``None`` when no closed
+        block is present -- so it is safe to call on non-reasoning output,
+        which returns ``(text.strip(), None)``.
+
+        :param text: raw decoded model output.
+        :param open_tag: opening marker of the inline reasoning block.
+        :param close_tag: closing marker of the inline reasoning block.
+        :return: ``(answer, trace_or_None)``.
+        """
+        ci = text.rfind(close_tag)
+        if ci == -1:
+            return text.strip(), None
+        answer = text[ci + len(close_tag):].strip()
+        oi = text.find(open_tag)
+        trace = (text[oi + len(open_tag):ci].strip()
+                 if oi != -1 and oi < ci else None)
+        return answer, trace
 class ClamsHFPromptableApp(ClamsPromptableApp):
     """
     Base class for promptable CLAMS apps backed by a local
@@ -1289,7 +1358,7 @@ class ClamsHFPromptableApp(ClamsPromptableApp):
             dtype=self.DTYPE,
             padding_side=self.PADDING_SIDE,
             revision=revision,
-            model_kwargs=self.MODEL_KWARGS,
+            model_kwargs=self.model_load_kwargs(model_id, revision),
             processor_kwargs=self.PROCESSOR_KWARGS,
         )
         self.logger.info(f"HF model loaded on {triple[2]}")
@@ -1297,6 +1366,32 @@ class ClamsHFPromptableApp(ClamsPromptableApp):
         self.processor, self.model, self.device = triple
         return triple
 
+    def model_load_kwargs(self, model_id: str, revision: str) -> dict:
+        """
+        The ``model_kwargs`` forwarded to
+        :func:`~clams.backends.hf.load_hf_model` (and on to
+        ``from_pretrained``) for a SPECIFIC family member. The base
+        implementation returns a copy of the class-level
+        :py:attr:`MODEL_KWARGS`, applied uniformly to every variant.
+
+        Override when a family mixes per-variant load requirements that
+        a single class-level ``MODEL_KWARGS`` cannot express -- e.g. a
+        ``analyzer_versions`` family whose members span full-precision,
+        FP8, and GPTQ-Int4 builds, where only the quantized members need
+        a ``quantization_config``::
+
+            def model_load_kwargs(self, model_id, revision):
+                kw = super().model_load_kwargs(model_id, revision)
+                if model_id.endswith('-GPTQ-Int4'):
+                    kw['quantization_config'] = ...   # gptq config
+                return kw
+
+        :param model_id: resolved HF model id (no ``@revision`` suffix).
+        :param revision: resolved commit/revision being loaded.
+        :return: ``model_kwargs`` dict for this variant.
+        """
+        return dict(self.MODEL_KWARGS or {})
+
     def generate(
             self,
             prompt: List[str],
@@ -1341,6 +1436,7 @@ class ClamsHFPromptableApp(ClamsPromptableApp):
         if n == 0:
             return []
         gen_kwargs = self.build_gen_kwargs(**generation_params)
+        template_kwargs = self.build_template_kwargs(**generation_params)
         try:
             conversations = [
                 self.build_conversation(
@@ -1357,6 +1453,7 @@ class ClamsHFPromptableApp(ClamsPromptableApp):
                 return_dict=True,
                 padding=True,
                 return_tensors="pt",
+                **template_kwargs,
             )
             inputs = inputs.to(self.device)
             if (self.DTYPE is not None
@@ -1405,6 +1502,28 @@ class ClamsHFPromptableApp(ClamsPromptableApp):
             })
         return gen_kwargs
 
+    def build_template_kwargs(self, **generation_params) -> dict:
+        """
+        Extra keyword arguments to pass to
+        ``processor.apply_chat_template`` in :py:meth:`generate`, beyond
+        the SDK-fixed ones (``add_generation_prompt``, ``tokenize``,
+        ``return_dict``, ``padding``, ``return_tensors``). The base
+        implementation returns ``{}``.
+
+        Override to inject model-specific chat-template controls without
+        having to reimplement :py:meth:`generate`. Common cases:
+
+        * ``{'enable_thinking': False}`` to run a reasoning ("thinking")
+          model in non-thinking mode;
+        * ``{'tools': [...]}`` or ``{'documents': [...]}`` for tool-use /
+          RAG chat templates.
+
+        Keys MUST NOT collide with the SDK-fixed kwargs above. Unknown
+        keys are passed through to the template's render context, where
+        a template that does not reference them simply ignores them.
+        """
+        return {}
+
 
 class ParameterCaster(object):
 

{clams_python-1.7.1 → clams_python-1.7.2/clams_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clams-python
-Version: 1.7.1
+Version: 1.7.2
 Summary: A collection of APIs to develop CLAMS app for python
 License-Expression: Apache-2.0
 Project-URL: homepage, https://clams.ai

{clams_python-1.7.1 → clams_python-1.7.2}/clams_python.egg-info/SOURCES.txt

@@ -50,6 +50,8 @@ clams_python.egg-info/SOURCES.txt
 clams_python.egg-info/dependency_links.txt
 clams_python.egg-info/entry_points.txt
 clams_python.egg-info/requires.txt
+clams_python.egg-info/scm_file_list.json
+clams_python.egg-info/scm_version.json
 clams_python.egg-info/top_level.txt
 container/Containerfile
 container/ffmpeg-hf.containerfile
@@ -87,6 +89,7 @@ documentation/target-versions.csv
 documentation/tutorial.md
 documentation/autodoc/clams.app.rst
 documentation/autodoc/clams.appmetadata.rst
+documentation/autodoc/clams.backends.rst
 documentation/autodoc/clams.mmif_utils.rst
 documentation/autodoc/clams.restify.rst
 tests/metadata.py

clams_python-1.7.2/clams_python.egg-info/scm_file_list.json

@@ -0,0 +1,96 @@
+{
+  "files": [
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+    ".pytype.cfg",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    ".gitignore",
+    "build-tools/publish.py",
+    "build-tools/prep_release.py",
+    "build-tools/build.py",
+    "build-tools/docs.py",
+    "build-tools/clean.py",
+    "build-tools/test.py",
+    "clams/__init__.py",
+    "clams/develop/__init__.py",
+    "clams/develop/templates/gha/for-clams-team.md.template",
+    "clams/develop/templates/gha/workflows/issue-assign.yml.template",
+    "clams/develop/templates/gha/workflows/publish.yml.template",
+    "clams/develop/templates/gha/workflows/issue-apps-project.yml.template",
+    "clams/develop/templates/gha/workflows/issue-close.yml.template",
+    "clams/develop/templates/utl-tf/__init__.py.template",
+    "clams/develop/templates/utl-tf/timeframe.py.template",
+    "clams/develop/templates/app/Containerfile.template",
+    "clams/develop/templates/app/metadata.py.template",
+    "clams/develop/templates/app/README.md.template",
+    "clams/develop/templates/app/.dockerignore.template",
+    "clams/develop/templates/app/requirements.txt.template",
+    "clams/develop/templates/app/LICENSE.template",
+    "clams/develop/templates/app/.gitignore.template",
+    "clams/develop/templates/app/app.py.template",
+    "clams/develop/templates/app/cli.py.template",
+    "clams/restify/__init__.py",
+    "clams/envelop/__init__.py",
+    "clams/appmetadata/__init__.py",
+    "clams/app/__init__.py",
+    "clams/serve/__init__.py",
+    "clams/ver/__init__.py",
+    "clams/backends/__init__.py",
+    "clams/backends/hf.py",
+    "documentation/modules.rst",
+    "documentation/target-versions.csv",
+    "documentation/app-baseclasses.rst",
+    "documentation/gpu-apps.rst",
+    "documentation/clamsapp.rst",
+    "documentation/appdirectory.rst",
+    "documentation/index.rst",
+    "documentation/tutorial.md",
+    "documentation/introduction.rst",
+    "documentation/appmetadata.rst",
+    "documentation/cli.rst",
+    "documentation/runtime-params.rst",
+    "documentation/input-output.rst",
+    "documentation/conf.py",
+    "documentation/autodoc/clams.restify.rst",
+    "documentation/autodoc/clams.app.rst",
+    "documentation/autodoc/clams.backends.rst",
+    "documentation/autodoc/clams.mmif_utils.rst",
+    "documentation/autodoc/clams.appmetadata.rst",
+    "tests/test_promptable.py",
+    "tests/pillow-logo.png",
+    "tests/test_backends_hf.py",
+    "tests/test_envelope.py",
+    "tests/metadata.py",
+    "tests/test_clamsapp.py",
+    "container/tf2.containerfile",
+    "container/opencv4-hf.containerfile",
+    "container/torch2.containerfile",
+    "container/opencv4-hf4.containerfile",
+    "container/Containerfile",
+    "container/hf4.containerfile",
+    "container/ffmpeg-hf.containerfile",
+    "container/ffmpeg-tf2.containerfile",
+    "container/generate_containers_yml.py",
+    "container/opencv4-tf2.containerfile",
+    "container/opencv4-torch2.containerfile",
+    "container/hf.containerfile",
+    "container/jdk8.containerfile",
+    "container/hf5.containerfile",
+    "container/ffmpeg.containerfile",
+    "container/ffmpeg-hf5.containerfile",
+    "container/ffmpeg-hf4.containerfile",
+    "container/opencv4-hf5.containerfile",
+    "container/ffmpeg-torch2.containerfile",
+    "container/opencv4.containerfile",
+    ".github/workflows/container.yml",
+    ".github/workflows/containers.yml",
+    ".github/workflows/issue-close.yml",
+    ".github/workflows/codecov.yml",
+    ".github/workflows/release-check.yml",
+    ".github/workflows/issue-infra-project.yml",
+    ".github/workflows/issue-assign.yml",
+    ".github/workflows/publish.yml"
+  ]
+}

clams_python-1.7.2/clams_python.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.7.2",
+  "distance": 0,
+  "node": "g874f55164c482ad4c7896c6bfd8d6a69649eb66b",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-07"
+}

clams_python-1.7.2/documentation/autodoc/clams.backends.rst

@@ -0,0 +1,15 @@
+clams.backends package
+======================
+
+.. automodule:: clams.backends
+
+Submodules
+----------
+
+clams.backends.hf
+^^^^^^^^^^^^^^^^^
+
+.. automodule:: clams.backends.hf
+   :members:
+   :undoc-members:
+   :show-inheritance:

{clams_python-1.7.1 → clams_python-1.7.2}/documentation/target-versions.csv

@@ -1,4 +1,5 @@
 "``clams-python`` version","``mmif-python`` version","Target MMIF Specification"
+`1.7.2 <https://pypi.org/project/clams-python/1.7.2/>`__,`1.5.1 <https://pypi.org/project/mmif-python/1.5.1/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.7.1 <https://pypi.org/project/clams-python/1.7.1/>`__,`1.5.1 <https://pypi.org/project/mmif-python/1.5.1/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.7.0 <https://pypi.org/project/clams-python/1.7.0/>`__,`1.5.0 <https://pypi.org/project/mmif-python/1.5.0/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.6.0 <https://pypi.org/project/clams-python/1.6.0/>`__,`1.4.0 <https://pypi.org/project/mmif-python/1.4.0/>`__,`1.1.1 <https://mmif.clams.ai/1.1.1/>`__

{clams_python-1.7.1 → clams_python-1.7.2}/tests/test_promptable.py

@@ -10,7 +10,7 @@ single-turn / turn-taking / user-only modes, and the
 """
 import unittest
 
-from mmif import AnnotationTypes, DocumentTypes, Mmif
+from mmif import AnnotationTypes, Document, DocumentTypes, Mmif
 
 from clams import AppMetadata, ClamsPromptableApp
 
@@ -326,6 +326,19 @@ class TestStoreResponse(unittest.TestCase):
     def setUp(self):
         self.app = make_test_app(make_metadata(call_helper=True))
         self.mmif = Mmif(validate=False)
+        # upstream: a media document and an annotation anchored to it, which
+        # serves as the response's `source`.
+        vdoc = Document()
+        vdoc.at_type = DocumentTypes.VideoDocument
+        vdoc.id = 'v1'
+        vdoc.location = 'file:///video.mp4'
+        self.mmif.add_document(vdoc)
+        self.doc_id = vdoc.id
+        src_view = self.mmif.new_view()
+        src_view.metadata.app = 'http://upstream/1'
+        self.src = src_view.new_annotation(
+            AnnotationTypes.TimeFrame, document=vdoc.id, label='scene')
+        # the current app's view
         self.view = self.mmif.new_view()
         self.app.sign_view(self.view, {})
         self.view.new_contain(DocumentTypes.TextDocument)
@@ -333,22 +346,34 @@ class TestStoreResponse(unittest.TestCase):
 
     def test_happy_path_creates_textdocument_and_alignment(self):
         td, align = self.app.response_to_grounded_textdocument(
-            self.view, source='src1', response='generated text')
+            self.view, source=self.src.id, response='generated text')
         self.assertEqual(td.text_value, 'generated text')
-        self.assertEqual(align.get_property('source'), 'src1')
+        # the TD inherits the source annotation's document
+        self.assertEqual(td.get_property('document'), self.doc_id)
+        self.assertEqual(align.get_property('source'), self.src.id)
         self.assertEqual(align.get_property('target'), td.id)
 
-    def test_reasoning_trace_none_does_not_raise(self):
-        # no exception
-        self.app.response_to_grounded_textdocument(
-            self.view, source='src1', response='text',
+    def test_source_without_document_raises(self):
+        # a source annotation carrying no `document` means a malformed input
+        ungrounded = self.view.new_annotation(AnnotationTypes.TimeFrame)
+        with self.assertRaises(ValueError):
+            self.app.response_to_grounded_textdocument(
+                self.view, source=ungrounded.id, response='text')
+
+    def test_reasoning_trace_none_stores_no_property(self):
+        td, _ = self.app.response_to_grounded_textdocument(
+            self.view, source=self.src.id, response='text',
             reasoning_trace=None)
+        self.assertNotIn('modelReasoningTrace', td.properties)
 
-    def test_reasoning_trace_not_none_raises_not_implemented(self):
-        with self.assertRaises(NotImplementedError):
-            self.app.response_to_grounded_textdocument(
-                self.view, source='src1', response='text',
-                reasoning_trace='intermediate reasoning')
+    def test_reasoning_trace_stored_on_textdocument(self):
+        td, _ = self.app.response_to_grounded_textdocument(
+            self.view, source=self.src.id, response='the answer',
+            reasoning_trace='step 1 ... step 2 ...')
+        # trace lives in the property; the TD text stays answer-only
+        self.assertEqual(
+            td.get_property('modelReasoningTrace'), 'step 1 ... step 2 ...')
+        self.assertEqual(td.text_value, 'the answer')
 
     # TODO (krim @ 05/28/26): this test case belongs upstream in the
     # vocabulary type definition (the `origins`/`origination` pairing
@@ -359,11 +384,11 @@ class TestStoreResponse(unittest.TestCase):
     # underlying TD.
     def test_origins_and_origination_written_together(self):
         td, align = self.app.response_to_grounded_textdocument(
-            self.view, source='tf1', response='caption text',
+            self.view, source=self.src.id, response='caption text',
             origins=['tp1'], origination='derived')
         self.assertEqual(td.get_property('origins'), ['tp1'])
         self.assertEqual(td.get_property('origination'), 'derived')
-        self.assertEqual(align.get_property('source'), 'tf1')
+        self.assertEqual(align.get_property('source'), self.src.id)
         self.assertEqual(align.get_property('target'), td.id)
 
     def test_unpaired_origins_or_origination_raises(self):
@@ -377,6 +402,51 @@ class TestStoreResponse(unittest.TestCase):
                     self.view, source='src1', response='text', **kwargs)
 
 
+# ---------------------------------------------------------------------------
+# Reasoning-trace split helper
+# ---------------------------------------------------------------------------
+
+class TestSplitReasoningTrace(unittest.TestCase):
+    """:meth:`ClamsPromptableApp.split_tagged_reasoning_trace` (static)."""
+
+    split = staticmethod(ClamsPromptableApp.split_tagged_reasoning_trace)
+
+    def test_closed_block_splits_answer_and_trace(self):
+        answer, trace = self.split('<think>reasoning</think>The answer.')
+        self.assertEqual(answer, 'The answer.')
+        self.assertEqual(trace, 'reasoning')
+
+    def test_no_tags_returns_text_as_answer_none_trace(self):
+        answer, trace = self.split('just an answer')
+        self.assertEqual(answer, 'just an answer')
+        self.assertIsNone(trace)
+
+    def test_unterminated_block_not_overstripped(self):
+        # No closing tag (e.g. ran out of tokens mid-thought): return the
+        # raw text rather than discard a possibly-real answer.
+        raw = '<think>thinking with no close'
+        answer, trace = self.split(raw)
+        self.assertEqual(answer, raw)
+        self.assertIsNone(trace)
+
+    def test_uses_final_close_tag(self):
+        answer, trace = self.split(
+            '<think>a</think>mid<think>b</think>final')
+        self.assertEqual(answer, 'final')
+
+    def test_custom_tags(self):
+        answer, trace = self.split(
+            '[R]why[/R]done', open_tag='[R]', close_tag='[/R]')
+        self.assertEqual(answer, 'done')
+        self.assertEqual(trace, 'why')
+
+    def test_non_thinking_output_safe_to_call(self):
+        # Safe to call unconditionally even when thinking is disabled.
+        answer, trace = self.split('   plain caption   ')
+        self.assertEqual(answer, 'plain caption')
+        self.assertIsNone(trace)
+
+
 # ---------------------------------------------------------------------------
 # Transport-neutral parameter casting
 # ---------------------------------------------------------------------------
@@ -580,6 +650,56 @@ class TestHFPromptableAppClassAttrs(unittest.TestCase):
         finally:
             restore()
 
+    def test_build_template_kwargs_default_empty(self):
+        restore, _ = self._patch_load()
+        try:
+            app = self._make_subclass(analyzer_versions=self.SINGLETON_AV)()
+            self.assertEqual(app.build_template_kwargs(), {})
+        finally:
+            restore()
+
+    def test_model_load_kwargs_default_is_model_kwargs_copy(self):
+        restore, calls = self._patch_load()
+        try:
+            app = self._make_subclass(
+                analyzer_versions=self.SINGLETON_AV,
+                MODEL_KWARGS={'trust_remote_code': True},
+            )()
+            # eager singleton load forwarded the class-level MODEL_KWARGS
+            self.assertEqual(
+                calls[0]['model_kwargs'], {'trust_remote_code': True})
+            # and it's a copy, not the same object
+            self.assertIsNot(
+                app.model_load_kwargs('org/fake-model', 'deadbee'),
+                app.MODEL_KWARGS)
+        finally:
+            restore()
+
+    def test_model_load_kwargs_override_is_per_variant(self):
+        restore, calls = self._patch_load()
+        try:
+            def per_variant(self, model_id, revision):
+                kw = {'base': True}
+                if model_id.endswith('small-model'):
+                    kw['quantized'] = True
+                return kw
+
+            cls = self._make_subclass(
+                analyzer_versions=self.MULTI_AV,
+                model_load_kwargs=per_variant,
+            )
+            app = cls()  # multi-member: no eager load
+            self.assertEqual(len(calls), 0)
+            app.load_model('org/large-model')
+            app.load_model('org/small-model')
+            large = next(c for c in calls if c['model_id'] == 'org/large-model')
+            small = next(c for c in calls if c['model_id'] == 'org/small-model')
+            self.assertEqual(large['model_kwargs'], {'base': True})
+            self.assertEqual(
+                small['model_kwargs'], {'base': True, 'quantized': True})
+        finally:
+            restore()
+
 
 if __name__ == '__main__':
     unittest.main()