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

clams_python-1.7.1/.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.6.0 → clams_python-1.7.1}/CHANGELOG.md

@@ -1,4 +1,38 @@
 
+## 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
+
+This release adds an optional JSON "envelope" input format for passing complex or long runtime parameters to apps, migrates the build system to `pyproject.toml`, and expands runtime-parameter documentation.
+
+### Additions
+
+* Parameter envelope: in addition to query strings or `--flag`-like CLI args, apps now accept a JSON envelope (`{"parameters": {...}, "mmif": {...}}`) as input. This enables long prompts and structured (map/array) parameter values that do not fit nicely in URL query strings. The envelope is auto-detected, explicit parameters (query string or cli flags) take priority over envelope values, and app output is always raw MMIF so existing pipelines are unaffected (https://github.com/clamsproject/clams-python/pull/287).
+* `clams envelop` CLI subcommand and a `clams.create_envelope()` Python API for constructing envelope JSON from a parameter file (or dict) and an MMIF read from a file or stdin (https://github.com/clamsproject/clams-python/pull/287).
+
+### Changes
+
+* Updated to `mmif-python` 1.4.0.
+* Build system migrated from `setup.py` to `pyproject.toml` with `setuptools-scm` versioning; the CI and documentation publishing pipeline was standardized accordingly (https://github.com/clamsproject/clams-python/pull/286).
+* Expanded runtime-parameter documentation, including detailed parameter-type reference and a warning emitted when a colon appears in a `map`-type parameter key (https://github.com/clamsproject/clams-python/pull/284).
+
+
+
 ## releasing 1.5.0 (2026-03-12)
 ### Overview
 
@@ -15,6 +49,7 @@ Adds `tfSamplingMode` as a universal runtime parameter and overhauls container i
 > [!NOTE]
 > This release requires `mmif-python >= 1.3.0` for the sampling mode API.
 
+
 ## releasing 1.4.0 (2025-11-30)
 ### Overview
 This release introduces three new fields to the app metadata to improve the orchestration and handling of large models within apps.
@@ -32,11 +67,13 @@ This release introduces three new fields to the app metadata to improve the orch
 *  VRAM usage record: Apps running on CUDA and `torch` now cache VRAM usage statistics in the local disk cache (typically in `$XDG_CACHE_HOME`) (https://github.com/clamsproject/clams-python/issues/243). Currently, this information is for logging only, and we plan to add a retrieval API in the future. 
     * See current _private_ implementation at https://github.com/clamsproject/clams-python/blob/671560b184a3b73bf417db753d0fa8f1c73d3bda/clams/app/__init__.py#L348-L361
 
+
 ## releasing 1.3.3 (2025-07-28)
 ### Overview
 Updated `mmif-python` version that includes a hotfix for reading 1.0.x MMIF
 
 
+
 ## releasing 1.3.2 (2025-07-26)
 ### Overview
 Patch release, mainly to support new MMIF spec and corresponding `mmif-python` SDK versions, with more base images with HF libraries and miscellaneous fixes. 
@@ -51,6 +88,7 @@ Patch release, mainly to support new MMIF spec and corresponding `mmif-python` S
 * Minor bugfixes and documentation improvements.
 
 
+
 ## releasing 1.3.1 (2024-07-29)
 ### Overview
 This patch includes update to the latest `mmif-python` which contains a hot fix for a critical bug. 
@@ -59,6 +97,7 @@ This patch includes update to the latest `mmif-python` which contains a hot fix
 - based on `mmif-python==1.0.19`
 
 
+
 ## releasing 1.3.0 (2024-07-22)
 ### Overview
 This version added two universal runtime parameters that make some aspects of the runtime environment are recorded in the views' metadata. 
@@ -71,6 +110,7 @@ This version added two universal runtime parameters that make some aspects of th
 
 
 
+
 ## releasing 1.2.6 (2024-07-15)
 ### Overview
 Patch release to update mmif SDK version, and minor improvements
@@ -83,6 +123,7 @@ Patch release to update mmif SDK version, and minor improvements
 - bug fix "raw" runtime parameters weren't properly recorded when an app fails to refine the parameters (https://github.com/clamsproject/clams-python/issues/232) 
 
 
+
 ## releasing 1.2.5 (2024-06-26)
 ### Overview
 Patch release to fix an error in app cookie cutter, also updated to the latest MMIF and mmif-python. 
@@ -91,6 +132,7 @@ Patch release to fix an error in app cookie cutter, also updated to the latest M
 - updated `mmif-python` to 1.0.17
 - fixed `Containerfile` from the app cookie cutter wasn't building an image due to an error
 
+
 ## releasing 1.2.4 (2024-06-14)
 ### Overview
 Patches bug in `clams develop` command and updated in documentation and `mmif-python` version 
@@ -102,6 +144,7 @@ Patches bug in `clams develop` command and updated in documentation and `mmif-py
 * updated app development documentation
 
 
+
 ## releasing 1.2.3 (2024-06-07)
 ### Overview
 This version includes significant change to app development template, with some other changes
@@ -118,6 +161,7 @@ This version includes significant change to app development template, with some
 - updated to `mmif-python` 1.0.15
 
 
+
 ## releasing 1.2.2 (2024-05-14)
 ### Overview
 This is minor patch with bug fix for parameter handling
@@ -127,6 +171,7 @@ This is minor patch with bug fix for parameter handling
 * updated to the latest `mmif-python` (1.0.14)
 
 
+
 ## releasing 1.2.1 (2024-04-21)
 ### Overview
 This release includes documentation updates and bug fixes
@@ -138,6 +183,7 @@ This release includes documentation updates and bug fixes
 * fixed a bug where raw user input parameters with `multivalued=True` were not fully recorded in the output MMIF view metadata (https://github.com/clamsproject/clams-python/issues/214)
 
 
+
 ## releasing 1.2.0 (2024-04-11)
 ### Overview
 This is a minor release that brings improved portability of `clams source` command but also breaks some backward compatibility. If your app is based on clams-python 1.0.x or 1.1.x, please read the changelog carefully. 
@@ -147,6 +193,7 @@ This is a minor release that brings improved portability of `clams source` comma
 - `ClamsApp.sign_view` method now expect the runtime parameters (dict of string to lists of values) as a second argument. Previously the second argument was optional, which is no more. CLAMS app developers who were calling this method in `_annotate()` method must directly pass down the runtime parameters from `_annotate()` argument.
 
 
+
 ## releasing 1.1.6 (2024-04-02)
 ### Overview
 Minor release to update the `mmif-python` dependency to the latest.
@@ -155,6 +202,7 @@ Minor release to update the `mmif-python` dependency to the latest.
 * now based on `mmif-python==1.0.13` including a hotfix for a wrong field name in MMIF serialization.
 
 
+
 ## releasing 1.1.5 (2024-04-01)
 ### Overview
 Hot-fix to fix some compatibility issues in the app develop template 
@@ -163,6 +211,7 @@ Hot-fix to fix some compatibility issues in the app develop template
 * reverted some changes from 3ed54b3 due to broken backward compatibility
 
 
+
 ## releasing 1.1.4 (2024-03-31)
 ### Overview
 This release includes many changes regarding runtime parameters.
@@ -177,6 +226,7 @@ This release includes many changes regarding runtime parameters.
 * input and output type properties can be (under-)specified as wildcards (#194)
 
 
+
 ## releasing 1.1.3 (2024-03-04)
 ### Overview
 This is a minor release to catch up new version of MMIF and `mmif-python`. 
@@ -187,6 +237,7 @@ This is a minor release to catch up new version of MMIF and `mmif-python`.
 
 
 
+
 ## releasing 1.1.2 (2024-02-10)
 ### Overview
 This release updates to the latest MMIF and `mmif-python`
@@ -195,6 +246,7 @@ This release updates to the latest MMIF and `mmif-python`
 * Now based on `mmif-python` 1.0.9 and MMIF 1.0.1
 
 
+
 ## releasing 1.1.1 (2024-02-05)
 ### Overview
 This release contains minor fixes in code and updates in documentations regarding changes in runtime parameter in the previous 1.1.0 release.
@@ -204,6 +256,7 @@ This release contains minor fixes in code and updates in documentations regardin
 * fixed outdated information regarding usage of `get_configuration` in various documentation
 * fixed `properties` in I/O specification in AppMetadata are unfairly restricted to `str` values
 
+
 ## releasing 1.1.0 (2024-01-31)
 ### Overview
 This is a minor-level release that fixes various bugs and adds safeguards for possible inconsistency in output MMIFs. 
@@ -242,6 +295,7 @@ optional arguments:
 * fixed a bug in app metadata generation (https://github.com/clamsproject/clams-python/issues/187) 
 
 
+
 ## releasing 1.0.9 (2023-07-24)
 ### Overview
 Minor release to update small issues in the app develop template. 
@@ -249,6 +303,7 @@ Minor release to update small issues in the app develop template.
 ### Changes
 * `metadata.py` from the template now includes *universal* parameters when printing out the app metadata.
 
+
 ## releasing 1.0.8 (2023-07-24)
 ### Overview
 Minor release to update `mmif-python` version 
@@ -257,6 +312,7 @@ Minor release to update `mmif-python` version
 * updated to `mmif-python==1.0.8`
 * enabled a python logger for clams-apps as `self.logger`
 
+
 ## releasing 1.0.7 (2023-07-20)
 ### Overview
 This release includes a bugfix and update to the latest mmif-python 
@@ -266,6 +322,7 @@ This release includes a bugfix and update to the latest mmif-python
 * fixed some runtime parameters' default values not correctly casted (#173 )
 
 
+
 ## releasing 1.0.6 (2023-07-19)
 ### Overview
 Minor release to update `mmif-python` version 
@@ -274,6 +331,7 @@ Minor release to update `mmif-python` version
 * updated to `mmif-python==1.0.5`
 
 
+
 ## releasing 1.0.5 (2023-07-19)
 ### Overview
 Minor release to update `mmif-python` version 
@@ -282,6 +340,7 @@ Minor release to update `mmif-python` version
 * updated to `mmif-python==1.0.5`
 
 
+
 ## releasing 1.0.4 (2023-07-19)
 ### Overview
 This release include many updates to documentation, and `clams source --scheme` flag. 
@@ -294,6 +353,7 @@ This release include many updates to documentation, and `clams source --scheme`
 * added validation step for parameters with fixed options (#164)  
 
 
+
 ## releasing 1.0.3 (2023-06-14)
 ### Overview
 This release include minor bug fixes. 
@@ -304,6 +364,7 @@ This release include minor bug fixes.
 * fixed #155
 
 
+
 ## releasing 1.0.2 (2023-06-02)
 ### Overview
 This release is a minor patch; see below. 
@@ -311,6 +372,7 @@ This release is a minor patch; see below.
 ### Changes
 * fixed a filename bug that prevented some files from being copied to a newly generate app template. 
 
+
 ## releasing 1.0.1 (2023-05-26)
 ### Overview
 This release is about updating to `mmif-python==1.0.1`, which is based on MMIF 1.0.0. 
@@ -319,6 +381,7 @@ This release is about updating to `mmif-python==1.0.1`, which is based on MMIF 1
 * uses `mmif-python==1.0.1`
 * updated some names for upcoming pedantic v2 update
 
+
 ## releasing 1.0.0 (2023-05-26)
 ### Overview
 This release will be numbered as 1.0.0, but indeed it's a minor update from 0.6.3. 
@@ -351,6 +414,7 @@ optional arguments:
 * "generic" readme file in the app template is replaced with a link to the generic user manual (soon be) published to `apps.clams.ai`. 
 * now based on `mmif-python` and MMIF 1.0.0. 
 
+
 ## releasing 0.6.3 (2023-05-20)
 ### Overview
 This is a minor release
@@ -361,6 +425,7 @@ This is a minor release
 ### Changes
 * protocol string used in the base url to generate app identifiers is now reverted back to `http` from `https` for consistency (all documentations of ours are using `http` in the base URL in any URI/IRI field).
 
+
 ## releasing 0.6.2 (2023-05-19)
 ### Overview
 This release includes all the `clamsproject`-specific GHA workflow files in the PyPI distribution. 
@@ -368,6 +433,7 @@ This release includes all the `clamsproject`-specific GHA workflow files in the
 ### Changes
 * fixed GHA workflow files were missing in the sdist uploaded to PyPI (#143)
 
+
 ## releasing 0.6.1 (2023-05-19)
 ### Overview
 This release is based on a new version of `mmif-python` [0.5.2](https://github.com/clamsproject/mmif-python/blob/main/CHANGELOG.md#releasing-052-2023-05-19). Additionally, this release includes significant updates in documentation both in sphinx API documentation (website) and app starter-kit documentation, huge upgrades in GHA workflows in app-dev template, and finally small (but critical) bug fixes.
@@ -384,6 +450,7 @@ This release is based on a new version of `mmif-python` [0.5.2](https://github.c
 * fixed `@` sign wasn't properly serialized from `metadata.py`.
 
 
+
 ## releasing 0.6.0 (2023-05-03)
 ### Overview
 This release contains big changes and new features, including "breaking" ones. All CLAMS apps using `clams-python==0.5.*` are recommended to update to this release. 
@@ -423,6 +490,7 @@ optional arguments:
     * The big change in the MMIF 0.5.0 is the change in the CLAMS vocab type versioning scheme. And as now the responsibility of vocab type version checking is pushed down to the `mmif-python` library, `clams-python` no longer checks any version numbers in an input MMIF file. 
     * FYI, here's how vocab type versions are "checked" when comparing two `AnnotationTypes.SomeType` enum-like objects: https://github.com/clamsproject/mmif-python/blob/88040395b7349f49058a9bf315628bed426e3d51/templates/python/vocabulary/base_types.txt#L152-L166
 
+
 ## releasing 0.5.3 (2023-03-20)
 ### Overview
 This release includes update to the latest MMIF / `mmif-python`, and big improvements on handling runtime parameters.
@@ -435,12 +503,15 @@ This release includes update to the latest MMIF / `mmif-python`, and big improve
 * fixed bugs around setting default values for `bool` type runtime parameters (#111)
 
 
+
 ## releasing 0.5.2 (2023-02-02)
 This release contains updates of the python version (#102) and "uncapping" of python dependencies (#89), and a small update in handling `pretty` (and future "universal") parameter (#99). 
 
+
 ## releasing 0.5.1 (2022-03-25)
 This release contains fixes in the development pipelines (#97 ) and dependency ( #95). 
 
+
 ## releasing 0.5.0 (2021-07-24)
 This release contains changes in `AppMetadata` scheme and bug fix in `Restifier`.
 
@@ -451,11 +522,13 @@ This release contains changes in `AppMetadata` scheme and bug fix in `Restifier`
   * `wrappee_version` -> `analyzer_version`
   * `wrappee_license` -> `analyzer_license`
 
+
 ## releasing 0.4.4 (2021-07-11)
 This release includes bug fixes from mmif-python package, loosened ML library versions in docker images.
 
 
 
+
 ## releasing 0.4.3 (2021-06-19)
 This release contains various fixes and improvements. 
 
@@ -467,6 +540,7 @@ This release contains various fixes and improvements.
 * (changed) `AppMetadata.add_parameter` now has a proper signature for IDE hints
 
 
+
 ## releasing 0.4.2 (2021-06-17)
 This release contains bugfixes
 
@@ -475,6 +549,7 @@ This release contains bugfixes
 - updated latest mmif-python
 
 
+
 ## releasing 0.4.1 (2021-06-14)
 This release includes minor API improvement ...
 
@@ -482,11 +557,13 @@ This release includes minor API improvement ...
 * `AppMetadata` class can be imported from `clams` package directly
 
 
+
 ## releasing 0.4.0 (2021-06-14)
 This release includes 
 * input MMIF file compatibility check (#60 )
 * upgrade to mmif-python 0.4.x, which includes a lots of breaking changes. 
 
+
 ## releasing 0.3.0 (2021-06-04)
 This new breaking release includes ... 
 
@@ -495,9 +572,11 @@ This new breaking release includes ...
 * changing HTTP code for error responses to 500 (#61 )
 * and minor bugfixes 
 
+
 ## releasing 0.2.4 (2021-05-12)
 This release includes small updates of error handling matching updates on mmif-python side. 
 
+
 ## releasing 0.2.3 (2021-05-01)
 A new release includes
 
@@ -507,6 +586,7 @@ A new release includes
 * and other minor bugfixes 
 
 
+
 ## releasing 0.2.2 (2021-03-30)
 * based on mmif-python 0.3.1 patch
 * more documentation 
@@ -514,9 +594,11 @@ A new release includes
 * interpretation of HTTP parameters into python API arguments
 * dependency for lapps/LIF
 
+
 ## releasing 0.2.1 (2021-03-17)
 This version now based on `mmif-python` 0.3.0, which is based on MMIF spec 0.3.0. It doesn't have breaking changes, but due to the new dependency to `mmif-python` 0.3.0, it might break some apps. Please report here if it breaks your code. 
 
+
 ## releasing 0.2.0 (2021-02-04)
 This PR contains many breaking changes, so when merged, we release as `0.2.0`.
 
@@ -536,6 +618,7 @@ This PR contains many breaking changes, so when merged, we release as `0.2.0`.
   * added `ClamsApp::validate_document_files` (not supporting integrity check such as MD5 yet) (https://github.com/clamsproject/mmif/issues/150)
 
 
+
 ## releasing 0.1.3 (2020-10-09)
 0.1.3 includes; 
 

{clams_python-1.6.0 → clams_python-1.7.1}/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.6.0/clams_python.egg-info → clams_python-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clams-python
-Version: 1.6.0
+Version: 1.7.1
 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.4.0
+Requires-Dist: mmif-python==1.5.1
 Requires-Dist: Flask>=2
 Requires-Dist: Flask-RESTful>=0.3.9
 Requires-Dist: gunicorn>=20
@@ -36,6 +36,11 @@ Requires-Dist: pytype; extra == "test"
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
 Requires-Dist: pillow; extra == "test"
+Provides-Extra: hf
+Requires-Dist: torch; extra == "hf"
+Requires-Dist: transformers; extra == "hf"
+Requires-Dist: pillow; extra == "hf"
+Requires-Dist: tqdm; extra == "hf"
 Dynamic: license-file
 
 ## CLAMS project

clams_python-1.7.1/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()