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

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

@@ -1,4 +1,21 @@
 
+## releasing 1.7.2 (2026-07-07)
+### Overview
+This patch adds experimental handling of "reasoning traces" of propmtable apps
+
+### Additions
+* common parameter `useReasoning` (bool) is added
+* when reasoning is on, in-line tagged reasoning traces (commonly within `<think>...</think>`) are separately stored in `modelReasoningTrace` of the TextDocument 
+
+> [!NOTE]
+> The new names are tentative and can be changed in the near future.
+
+
+## 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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clams-python
-Version: 1.7.1
+Version: 1.7.3
 Summary: A collection of APIs to develop CLAMS app for python
 License-Expression: Apache-2.0
 Project-URL: homepage, https://clams.ai
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mmif-python==1.5.1
+Requires-Dist: mmif-python==1.5.3
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20

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

@@ -711,6 +711,26 @@ class ClamsPromptableApp(ClamsApp):
                 'values grow the KV cache linearly and increase GPU memory '
                 'usage; reduce if VRAM is constrained.',
         },
+        {
+            'name': 'useReasoning', 'type': 'boolean', 'default': False,
+            'description':
+                'Request the model\'s reasoning ("thinking") mode. Off by '
+                'default. Honored only by apps whose backing model has a '
+                'distinct reasoning mode; apps without one ignore it. When '
+                'honored and enabled, the reasoning trace is split from the '
+                'answer and stored in the ``modelReasoningTrace`` property of '
+                'the output ``TextDocument`` (kept out of the document text). '
+                'Reasoning is markedly slower and far more token-hungry: the '
+                'whole trace is generated before the answer and drawn from the '
+                'same budget capped by ``maxNewTokens``, so raise '
+                '``maxNewTokens`` substantially (thousands of tokens, not '
+                'hundreds) when enabling this, or the trace may consume the '
+                'entire budget and the answer be truncated or empty. Small '
+                'reasoning models (as a rule of thumb, roughly 4B parameters '
+                'and under) are especially prone to non-terminating "thinking '
+                'loops" that exhaust the budget without producing an answer; '
+                'validate termination per model before relying on it.',
+        },
         {
             'name': 'temperature', 'type': 'number', 'default': 0.0,
             'description':
@@ -1005,8 +1025,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 +1050,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 +1066,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 +1092,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 +1115,71 @@ 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>',
+            assume_open: bool = False,
+    ) -> Tuple[str, Optional[str]]:
+        """
+        Split a reasoning model's output into ``(answer, trace)`` for the
+        inline XML-tag style: a reasoning block delimited by ``open_tag`` /
+        ``close_tag`` (default ``<think>`` / ``</think>``), e.g. as emitted
+        by DeepSeek-R1 or Qwen3.5.
+
+        Prefilled opening tags: some chat templates inject the OPENING tag
+        into the prompt when reasoning is enabled (Qwen3.5 does this), so the
+        decoded output carries only the CLOSING tag -- the model never emits
+        the opener. Pass ``assume_open=True`` in that situation (typically
+        wired to the app's reasoning toggle) so the trace is still recovered.
+        The cases:
+
+        * close tag present: ``answer`` is the text after it; ``trace`` is the
+          text between the tags, or everything before the close tag when the
+          opening tag is absent (prefilled).
+        * close tag absent, ``assume_open=True``: the output is unterminated
+          reasoning (e.g. the trace overran ``maxNewTokens`` before closing) --
+          there is no answer, so returns ``('', text.strip())``.
+        * close tag absent, ``assume_open=False`` (default): treated as a
+          plain, non-reasoning answer -- returns ``(text.strip(), None)``.
+
+        Only the inline-tag style is handled; models that isolate reasoning in
+        a separate token-delimited channel (e.g. gpt-oss, Gemma) need their own
+        parsing in the app.
+
+        :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.
+        :param assume_open: treat the text as the body of a reasoning block
+            whose opening tag was prefilled into the prompt, so a missing close
+            tag means unterminated reasoning (empty answer) rather than a plain
+            answer.
+        :return: ``(answer, trace_or_None)``.
+        """
+        ci = text.rfind(close_tag)
+        if ci == -1:
+            return ('', text.strip()) if assume_open else (text.strip(), None)
+        answer = text[ci + len(close_tag):].strip()
+        oi = text.find(open_tag)
+        if oi != -1 and oi < ci:
+            trace = text[oi + len(open_tag):ci].strip()
+        elif assume_open:
+            # opening tag was prefilled into the prompt (not generated), so the
+            # trace is everything up to the close tag
+            trace = text[:ci].strip()
+        else:
+            trace = None
+        return answer, trace
 class ClamsHFPromptableApp(ClamsPromptableApp):
     """
     Base class for promptable CLAMS apps backed by a local
@@ -1289,7 +1397,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 +1405,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 +1475,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 +1492,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 +1541,31 @@ 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`. This is where an app
+        honors the SDK ``useReasoning`` parameter, mapping it onto the
+        backend's reasoning switch. Common cases:
+
+        * ``{'enable_thinking': bool(generation_params.get('use_reasoning'))}``
+          to bind ``useReasoning`` to a reasoning ("thinking") model's
+          template switch;
+        * ``{'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.3}/clams/develop/templates/app/cli.py.template

@@ -6,13 +6,17 @@ DO NOT CHANGE the name of the file
 """
 
 import argparse
+import json
 import sys
 from contextlib import redirect_stdout
 
+import jsonschema
+
 import app
 
 import clams.app
 from clams import AppMetadata
+from clams.envelop import EnvelopeError
 
 
 def metadata_to_argparser(app_metadata: AppMetadata) -> argparse.ArgumentParser:
@@ -81,11 +85,24 @@ if __name__ == "__main__":
                 params[pname] = pvalue
             else:
                 params[pname] = [pvalue]
-        if args.OUT_MMIF_FILE.name == '<stdout>':
-            with redirect_stdout(sys.stderr):
+        # Mirror the HTTP server's error handling (see clams.restify): an invalid
+        # input is reported and exits non-zero, while an app-level failure is
+        # recorded as an error view instead of crashing with a raw traceback.
+        try:
+            if args.OUT_MMIF_FILE.name == '<stdout>':
+                with redirect_stdout(sys.stderr):
+                    out_mmif = clamsapp.annotate(in_data, **params)
+            else:
                 out_mmif = clamsapp.annotate(in_data, **params)
-        else:
-            out_mmif = clamsapp.annotate(in_data, **params)
+        except (jsonschema.exceptions.ValidationError, json.JSONDecodeError, EnvelopeError) as e:
+            detail = e.message if isinstance(e, jsonschema.exceptions.ValidationError) else str(e)
+            print(f"Invalid input data. See below for validation error.\n\n{detail}", file=sys.stderr)
+            sys.exit(1)
+        except Exception:
+            clamsapp.logger.exception("Error in annotation")
+            out_mmif = clamsapp.record_error(in_data, **params).serialize(pretty=True)
+            args.OUT_MMIF_FILE.write(out_mmif)
+            sys.exit(1)
         args.OUT_MMIF_FILE.write(out_mmif)
     else:
         arg_parser.print_help()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clams-python
-Version: 1.7.1
+Version: 1.7.3
 Summary: A collection of APIs to develop CLAMS app for python
 License-Expression: Apache-2.0
 Project-URL: homepage, https://clams.ai
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mmif-python==1.5.1
+Requires-Dist: mmif-python==1.5.3
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20

{clams_python-1.7.1 → clams_python-1.7.3}/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.1 → clams_python-1.7.3}/clams_python.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mmif-python==1.5.1
+mmif-python==1.5.3
 Flask>=2
 Flask-RESTful>=0.3.9
 gunicorn>=20

clams_python-1.7.3/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.3/clams_python.egg-info/scm_version.json

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

{clams_python-1.7.1 → clams_python-1.7.3}/documentation/app-baseclasses.rst

@@ -174,6 +174,17 @@ from :class:`~clams.app.ClamsApp`. These names are reserved; see
      - Maximum number of new tokens generated per inference call. Larger values
        grow the KV cache linearly and add to GPU memory usage; reduce if VRAM
        is constrained.
+   * - ``useReasoning``
+     - boolean
+     - ``false``
+     - no
+     - Request the model's reasoning ("thinking") mode. Off by default;
+       honored only by apps whose model has a distinct reasoning mode
+       (others ignore it). Much slower and more token-hungry -- the trace is
+       generated before the answer and drawn from the ``maxNewTokens`` budget,
+       and small models can loop without terminating. When honored, the trace
+       is stored in the ``modelReasoningTrace`` property of the output
+       ``TextDocument``. See :ref:`promptable-reasoning`.
    * - ``temperature``
      - number
      - ``0.0``
@@ -320,6 +331,52 @@ inferences, final reply returned.
 ``turn-taking`` is the default because it costs a single inference call
 and is the more common multi-element pattern.
 
+.. _promptable-reasoning:
+
+Reasoning traces (``useReasoning``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some models expose a distinct reasoning ("thinking") mode that emits an
+intermediate reasoning trace before the answer. ``useReasoning`` is the
+standard toggle for that mode. It is inert unless the app honors it, and
+honoring is a per-app choice with three wiring points:
+
+- map ``useReasoning`` onto the backend's reasoning switch (for HF chat
+  templates, typically ``enable_thinking``) by overriding
+  :meth:`~clams.app.ClamsHFPromptableApp.build_template_kwargs`;
+- split the trace from the answer with
+  :meth:`~clams.app.ClamsPromptableApp.split_tagged_reasoning_trace`
+  (inline ``<think>...</think>``-style traces only; channel-delimited
+  formats need app-specific parsing). Many chat templates prefill the
+  opening ``<think>`` into the prompt, so only the closing tag appears in
+  the output; pass ``assume_open=True`` (wired to the reasoning toggle) so
+  the trace is still recovered and a missing close tag is read as
+  unterminated reasoning (empty answer) rather than a plain answer;
+- pass the trace to
+  :meth:`~clams.app.ClamsPromptableApp.response_to_grounded_textdocument`
+  through its ``reasoning_trace`` argument, which stores it in the
+  ``modelReasoningTrace`` property of the produced ``TextDocument``,
+  separate from the document text.
+
+An app whose model has no reasoning mode leaves ``useReasoning`` unwired;
+callers may still set it and it has no effect, like ``topK`` under greedy
+decoding.
+
+Cost and failure modes
+""""""""""""""""""""""
+
+Reasoning is much slower and far more token-hungry than a direct answer:
+the entire trace is generated first, from the same budget capped by
+``maxNewTokens``. Enabling ``useReasoning`` without raising ``maxNewTokens``
+substantially (thousands of tokens, not hundreds) risks the trace consuming
+the whole budget, leaving the answer truncated or empty. Small reasoning
+models (as a rule of thumb, roughly 4B parameters and under) are especially
+prone to non-terminating "thinking loops" that never reach an answer; budget
+generously and validate termination per model. When the trace overruns the
+budget before closing, ``assume_open=True`` yields an empty answer plus the
+unterminated trace -- an app should surface that (e.g. a warning and an empty
+``TextDocument``) rather than emitting the raw reasoning as the answer.
+
 Helpers
 ^^^^^^^
 
@@ -512,7 +569,10 @@ supplies:
 * a default
   :py:meth:`~clams.app.ClamsHFPromptableApp.build_gen_kwargs` that
   maps the SDK promptable parameters to HF ``model.generate()``
-  kwargs.
+  kwargs;
+* a :py:meth:`~clams.app.ClamsHFPromptableApp.build_template_kwargs`
+  hook for chat-template controls, the override point for honoring
+  ``useReasoning`` (see :ref:`promptable-reasoning`).
 
 See each method's docstring for full details.
 

clams_python-1.7.3/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.3}/documentation/conf.py

@@ -26,7 +26,9 @@ sys.path.insert(0, str(proj_root_dir))
 
 # -- Project information -----------------------------------------------------
 
-project = proj_root_dir.name
+# The canonical package name — NOT derived from the checkout directory,
+# which is `clone-repo` when the shared docs-publish workflow builds here.
+project = 'clams-python'
 blob_base_url = f'https://github.com/clamsproject/{project}/blob'
 copyright = f'{datetime.date.today().year}, Brandeis LLC'
 author = 'Brandeis LLC'

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

@@ -1,4 +1,6 @@
 "``clams-python`` version","``mmif-python`` version","Target MMIF Specification"
+`1.7.3 <https://pypi.org/project/clams-python/1.7.3/>`__,`1.5.1 <https://pypi.org/project/mmif-python/1.5.1/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
+`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.3}/pyproject.toml

@@ -19,7 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3 :: Only",
 ]
 dependencies = [
-    "mmif-python==1.5.1",
+    "mmif-python==1.5.3",
     "Flask>=2",
     "Flask-RESTful>=0.3.9",
     "gunicorn>=20",

{clams_python-1.7.1 → clams_python-1.7.3}/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,73 @@ 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)
+
+    def test_assume_open_close_present_open_absent(self):
+        # Prefilled opening tag (e.g. Qwen3.5): only the close tag is emitted.
+        answer, trace = self.split(
+            'reasoning body</think>The answer.', assume_open=True)
+        self.assertEqual(answer, 'The answer.')
+        self.assertEqual(trace, 'reasoning body')
+
+    def test_assume_open_no_close_is_unterminated_reasoning(self):
+        # Trace overran the budget before closing: empty answer, whole text is
+        # the unterminated trace.
+        raw = 'still thinking, never closed'
+        answer, trace = self.split(raw, assume_open=True)
+        self.assertEqual(answer, '')
+        self.assertEqual(trace, raw)
+
+    def test_open_absent_default_keeps_backward_compatible(self):
+        # Without assume_open, a lone close tag is not treated as a prefilled
+        # block: answer after the close, no trace.
+        answer, trace = self.split('reasoning body</think>The answer.')
+        self.assertEqual(answer, 'The answer.')
+        self.assertIsNone(trace)
+
+
 # ---------------------------------------------------------------------------
 # Transport-neutral parameter casting
 # ---------------------------------------------------------------------------
@@ -580,6 +672,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()