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

clams_python-1.7.2/.github/workflows/release-check.yml

@@ -0,0 +1,11 @@
+name: "🔖 Release PR check"
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, edited]
+
+jobs:
+  release-check:
+    name: "🤙 Call SDK release-check workflow"
+    uses: clamsproject/.github/.github/workflows/sdk-release-check.yml@main

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

@@ -1,4 +1,25 @@
 
+## 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.
+
+### Additions
+* `ClamsPromptableApp`, a new specialized base class (subclassing `ClamsApp`) for prompt-driven, instruction-tuned LLM apps with pre-equipped with commonly used runtime parameter set (`prompt`, `systemPrompt`, `promptMode`, `maxNewTokens`, `temperature`, `topP`, `topK`, `parallelPrompts`). Plus, `ClamsHFPromptableApp` (subclassing `ClamsPromptableApp`) for the common case of "promptable app + local HuggingFace `transformers` model". This subclass should significanly simplify wrapping HF models into a CLAMS app. See https://clams.ai/clams-python/app-baseclasses.html for the developer guide. (https://github.com/clamsproject/clams-python/pull/291)
+* `clams.backends.hf` (new module) with two general HF loaders: `load_hf_model` (`from_pretrained` flow) and `load_hf_pipeline` (`transformers.pipeline` flow). Wraps the device auto-detection, revision pinning, dtype handling, and kwargs pass-through that every HF-backed CLAMS app does identically; used internally by `ClamsHFPromptableApp` and callable directly from any non-promptable HF app. Requires the `[hf]` extra (`pip install clams-python[hf]`) to keep `torch` and `transformers` out of the base install.
+* `clams develop --recipe utl-tf` scaffold drops a `utils/timeframe.py` into the new app that factors out the canonical TimeFrame iteration / `vdh.extract_images_by_mode_with_sources` / TimePoint-on-fallback / task-tuple pattern. (7bc91d97ff0af2a2253ca24b00afa8b554ad5849)
+* `appTags` field on `AppMetadata`, a sibling to https://github.com/clamsproject/mmif/pull/253. Allows categorization of CLAMS apps for app-directory search / filtering. (https://github.com/clamsproject/clams-python/pull/290)
+
+### Changes
+* Updated to the latest `mmif-python` SDK (1.5.0).
+* Tightened the semantics of the `AppMetadata.analyzer_versions` field (introduced in 1.4.0) for CHFPApp-based development. When an app subclasses `ClamsHFPromptableApp`, the dict is now the source of truth for the family of supported HF model IDs and their pinned commit hashes: the SDK auto-derives a `model` runtime parameter from the dict's keys, and the HF base class refines `model=<id>` into `model=<id>@<revision>` on output so the resolved revision lands in `view.metadata.appConfiguration` automatically.
+* `clams develop` scaffold templates (`app.py.template`, `metadata.py.template`) updated with commented-out blocks for both promptable variants.
+
+
 ## releasing 1.6.0 (2026-05-19)
 ### Overview
 

{clams_python-1.7.0 → clams_python-1.7.2}/CONTRIBUTING.md

@@ -75,6 +75,13 @@ from clams.ver import __version__
 For a dev install without a matching tag, `setuptools-scm` generates a
 version like `1.4.1.dev20+gaf551a4e4.d20260325`.
 
+## Releases
+
+Release PRs (from `develop` to `main`) are gated by the `release-check` CI workflow. Before opening one:
+
+1. Title the PR exactly `releasing X.Y.Z` (strict semver); `release-check` reads the version from the title.
+2. Run `python build-tools/prep_release.py X.Y.Z` and commit its changes. See inside the prep script to see what's actually prepared.
+
 ## Migration from Makefile
 
 The old `Makefile` and `setup.py` have been removed. If you are

{clams_python-1.7.0/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.0
+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
@@ -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.0
+Requires-Dist: mmif-python==1.5.1
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20

clams_python-1.7.2/build-tools/prep_release.py

@@ -0,0 +1,104 @@
+"""
+Prepare release artifacts for the clams-python package.
+
+Run while preparing a release PR, passing the version being released::
+
+    python build-tools/prep_release.py X.Y.Z
+
+Currently this adds a row to ``documentation/target-versions.csv`` for
+the release version. The ``mmif-python`` column is read from this
+package's pinned dependency in ``pyproject.toml``, and the target MMIF
+spec version from the installed ``mmif.__specver__``. This script is the
+single place that writes the target-versions table; the docs build only
+renders it, and CI verifies (on the release PR) that a row for the PR's
+version exists.
+
+Requires an editable install (``pip install -e .``) so that
+``mmif.__specver__`` is importable.
+"""
+import argparse
+import re
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).parent.parent
+CSV_PATH = PROJECT_ROOT / 'documentation' / 'target-versions.csv'
+PYPROJECT_PATH = PROJECT_ROOT / 'pyproject.toml'
+
+VERSION_RE = re.compile(r'^\d+\.\d+\.\d+$')
+TOP_ROW_RE = re.compile(r'`(\d+\.\d+\.\d+) <')
+MMIF_PIN_RE = re.compile(r'mmif-python\s*==\s*(\d+\.\d+\.\d+)')
+
+
+def _row(version, mmif_ver, specver):
+    return (
+        f'`{version} <https://pypi.org/project/clams-python/{version}/>`__,'
+        f'`{mmif_ver} <https://pypi.org/project/mmif-python/{mmif_ver}/>`__,'
+        f'`{specver} <https://mmif.clams.ai/{specver}/>`__'
+    )
+
+
+def _version_tuple(v):
+    return tuple(int(x) for x in v.split('.'))
+
+
+def _top_version(data_lines):
+    if not data_lines:
+        return None
+    m = TOP_ROW_RE.match(data_lines[0])
+    return m.group(1) if m else None
+
+
+def _pinned_mmif_version():
+    m = MMIF_PIN_RE.search(PYPROJECT_PATH.read_text())
+    if not m:
+        sys.exit("Error: could not find a pinned 'mmif-python==X.Y.Z' "
+                 "dependency in pyproject.toml.")
+    return m.group(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Prepare release artifacts for clams-python."
+    )
+    parser.add_argument(
+        "version", metavar="X.Y.Z",
+        help="the release version being prepared",
+    )
+    args = parser.parse_args()
+    version = args.version
+
+    if not VERSION_RE.match(version):
+        sys.exit(f"Error: '{version}' is not a valid X.Y.Z version.")
+
+    mmif_ver = _pinned_mmif_version()
+    try:
+        import mmif
+        specver = mmif.__specver__
+    except (ImportError, AttributeError):
+        sys.exit("Error: cannot read mmif.__specver__. "
+                 "Run `pip install -e .` first.")
+
+    lines = CSV_PATH.read_text().splitlines()
+    header, data = lines[0], lines[1:]
+    top = _top_version(data)
+
+    if top is not None and _version_tuple(version) < _version_tuple(top):
+        sys.exit(f"Error: {version} is older than the current top row "
+                 f"{top}; refusing to insert an out-of-order version.")
+
+    new_row = _row(version, mmif_ver, specver)
+    if top == version:
+        data[0] = new_row            # update in place
+        action = "updated"
+    else:
+        data.insert(0, new_row)      # prepend as the new latest
+        action = "added"
+
+    CSV_PATH.write_text('\n'.join([header] + data) + '\n')
+    print(f"target-versions.csv: {action} row {version} "
+          f"-> mmif-python {mmif_ver}, MMIF spec {specver}")
+
+
+if __name__ == "__main__":
+    main()

{clams_python-1.7.0 → 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.0 → 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.0
+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
@@ -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.0
+Requires-Dist: mmif-python==1.5.1
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20

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

@@ -12,9 +12,11 @@ pyproject.toml
 .github/workflows/issue-close.yml
 .github/workflows/issue-infra-project.yml
 .github/workflows/publish.yml
+.github/workflows/release-check.yml
 build-tools/build.py
 build-tools/clean.py
 build-tools/docs.py
+build-tools/prep_release.py
 build-tools/publish.py
 build-tools/test.py
 clams/__init__.py
@@ -48,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
@@ -85,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.0 → clams_python-1.7.2}/clams_python.egg-info/requires.txt

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

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.0 → clams_python-1.7.2}/documentation/conf.py

@@ -14,8 +14,6 @@ import datetime
 import inspect
 import json
 import os
-import re
-import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -196,24 +194,6 @@ def generate_jsonschema(app):
         json.dump(schema_dict, f, indent=2)
 
 
-def update_target_spec(app):
-    target_vers_csv = Path(__file__).parent / 'target-versions.csv'
-    version = _get_version('clams-python')
-    # Skip dev/dummy versions to avoid dirtying the git-tracked CSV
-    if 'dev' in version or not re.match(r'^\d+\.\d+\.\d+$', version):
-        return
-    mmifver = mmif.__version__
-    specver = mmif.__specver__
-    with open(target_vers_csv) as in_f, open(f'{target_vers_csv}.new', 'w') as out_f:
-        lines = in_f.readlines()
-        if not lines[1].startswith(f"`{version}"):
-            lines.insert(1, f"`{version} <https://pypi.org/project/clams-python/{version}/>`__,`{mmifver} <https://pypi.org/project/mmif-python/{mmifver}/>`__,`{specver} <https://mmif.clams.ai/{specver}/>`__\n")
-        for line in lines:
-            out_f.write(line)
-        shutil.move(out_f.name, in_f.name)
-
-
 def setup(app):
     app.connect('builder-inited', generate_whatsnew_rst)
     app.connect('builder-inited', generate_jsonschema)
-    app.connect('builder-inited', update_target_spec)

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

@@ -1,4 +1,10 @@
 "``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/>`__
+`1.5.0 <https://pypi.org/project/clams-python/1.5.0/>`__,`1.3.1 <https://pypi.org/project/mmif-python/1.3.1/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
+`1.4.0 <https://pypi.org/project/clams-python/1.4.0/>`__,`1.2.1 <https://pypi.org/project/mmif-python/1.2.1/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
 `1.3.3 <https://pypi.org/project/clams-python/1.3.3/>`__,`1.1.2 <https://pypi.org/project/mmif-python/1.1.2/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
 `1.3.2 <https://pypi.org/project/clams-python/1.3.2/>`__,`1.1.1 <https://pypi.org/project/mmif-python/1.1.1/>`__,`1.1.0 <https://mmif.clams.ai/1.1.0/>`__
 `1.3.1 <https://pypi.org/project/clams-python/1.3.1/>`__,`1.0.19 <https://pypi.org/project/mmif-python/1.0.19/>`__,`1.0.5 <https://mmif.clams.ai/1.0.5/>`__
@@ -50,4 +56,4 @@
 `0.1.7 <https://pypi.org/project/clams-python/0.1.7/>`__,`0.2.2 <https://pypi.org/project/mmif-python/0.2.2/>`__,`0.2.1 <https://mmif.clams.ai/0.2.1/>`__
 `0.1.6 <https://pypi.org/project/clams-python/0.1.6/>`__,`0.2.1 <https://pypi.org/project/mmif-python/0.2.1/>`__,`0.2.1 <https://mmif.clams.ai/0.2.1/>`__
 `0.1.5 <https://pypi.org/project/clams-python/0.1.5/>`__,`0.2.1 <https://pypi.org/project/mmif-python/0.2.1/>`__,`0.2.1 <https://mmif.clams.ai/0.2.1/>`__
-`0.1.4 <https://pypi.org/project/clams-python/0.1.4/>`__,`0.2.1 <https://pypi.org/project/mmif-python/0.2.1/>`__,`0.2.1 <https://mmif.clams.ai/0.2.1/>`__
+`0.1.4 <https://pypi.org/project/clams-python/0.1.4/>`__,`0.2.1 <https://pypi.org/project/mmif-python/0.2.1/>`__,`0.2.1 <https://mmif.clams.ai/0.2.1/>`__

{clams_python-1.7.0 → clams_python-1.7.2}/pyproject.toml

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

{clams_python-1.7.0 → 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()