mmif-python 1.5.1__tar.gz → 1.5.3__tar.gz

{mmif_python-1.5.1 → mmif_python-1.5.3}/CHANGELOG.md

@@ -1,4 +1,15 @@
 
+## releasing 1.5.2 (2026-07-07)
+### Overview
+This is a quick patch on the bug that when MMIF is deserialized, the annotation ID counts in the views weren't properly initialized. This should not be a real bug since new annotations should always written to new views (of current processing app) but not to existing views (where annotation count > 0), however, bugs in app code can trigger this condition, and this patch preventively fixes such cases.
+
+
+
+## releasing 1.5.1 (2026-06-19)
+### Overview
+This patch contains a bug fix in VDH that couldn't handle some mkv-contained video files (https://github.com/clamsproject/mmif-python/issues/390) , and some other minor documentation generation bugs.
+
+
 ## releasing 1.5.0 (2026-05-27)
 ### Overview
 

{mmif_python-1.5.1 → mmif_python-1.5.3}/CONTRIBUTING.md

@@ -162,7 +162,7 @@ To build documentation for a specific historical version (e.g., `v1.0.0`):
 python3 build-tools/docs.py --build-ver v1.0.0
 ```
 
-This runs the build in a sandboxed temporary directory. The output will be in `docs-test/<version>`.
+This runs the build in a sandboxed temporary directory. A single `--build-ver` places the built docs **flat** in the output directory (`docs-test/` by default). The batch `--build-all-since` mode instead nests each version under a `<version>/` subdirectory of the output directory, so multiple versions can coexist. The flat single-version layout is what the CI docs-publish workflow relies on — it invokes `docs.py --build-ver <ver> --output-dir _docs` and uploads `_docs/` as-is, without needing to know whether the project is versioned.
 
 > [!NOTE]
 > In CI, documentation is built and published automatically by the `publish.yml` workflow via the shared `sdk-docs.yml`. The CI calls `docs.py --build-ver <version> --output-dir _docs`. All CLAMS SDK repos use the same `docs.py` CLI interface (`--build-ver`, `--output-dir`).

{mmif_python-1.5.1 → mmif_python-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.5.1
+Version: 1.5.3
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 License-Expression: Apache-2.0
 Project-URL: homepage, https://mmif.clams.ai

{mmif_python-1.5.1 → mmif_python-1.5.3}/build-tools/docs.py

@@ -188,7 +188,8 @@ def linkcode_resolve(domain, info):
     return docs_build_dir
 
 
-def build_docs_for_version(version: str, output_base_dir: Path, repo_path: Path = None):
+def build_docs_for_version(version: str, output_base_dir: Path, repo_path: Path = None,
+                           versioned_subdir: bool = True):
     """
     Builds docs for a specific version in a sandbox.
     Uses local repo copy instead of cloning for efficiency.
@@ -197,6 +198,12 @@ def build_docs_for_version(version: str, output_base_dir: Path, repo_path: Path
         version: Git tag/ref to build
         output_base_dir: Directory to output built docs
         repo_path: Path to local repo to copy from (defaults to cwd)
+        versioned_subdir: when True (batch/from-scratch rebuild), the built
+            docs are placed under ``output_base_dir/<version>/`` so multiple
+            versions can coexist. When False (single build, as used by CI),
+            the docs are placed flat into ``output_base_dir`` so the shared
+            docs-publish workflow can upload them as-is without knowing about
+            versioning.
     """
     print(f"--- Running in Version Build Mode for version: {version} ---")
 
@@ -226,13 +233,19 @@ def build_docs_for_version(version: str, output_base_dir: Path, repo_path: Path
         built_docs_path = build_versioned_docs(env, source_path, version)
 
         print(f"\n--- Step 4: Copying built artifacts to output directory ---")
-        version_output_dir = output_base_dir / version
-        if version_output_dir.exists():
-            print(f"Removing existing directory: {version_output_dir}")
-            shutil.rmtree(version_output_dir)
-        shutil.copytree(built_docs_path, version_output_dir)
+        if versioned_subdir:
+            dest = output_base_dir / version
+            if dest.exists():
+                print(f"Removing existing directory: {dest}")
+                shutil.rmtree(dest)
+            shutil.copytree(built_docs_path, dest)
+        else:
+            # flat: place the built docs directly into output_base_dir
+            output_base_dir.mkdir(parents=True, exist_ok=True)
+            shutil.copytree(built_docs_path, output_base_dir, dirs_exist_ok=True)
+            dest = output_base_dir
 
-        print(f"\nDocumentation for {version} built successfully in: {version_output_dir}")
+        print(f"\nDocumentation for {version} built successfully in: {dest}")
 
 
 def get_all_tags():
@@ -317,7 +330,9 @@ def main():
             for version, error in failed:
                 print(f"  {version}: {error}")
     elif args.build_ver:
-        build_docs_for_version(args.build_ver, output_dir)
+        # single build (CI + local single-version): flat output so the
+        # shared docs-publish workflow uploads it version-agnostically
+        build_docs_for_version(args.build_ver, output_dir, versioned_subdir=False)
     else:
         build_docs_local(Path.cwd(), output_dir)
 

{mmif_python-1.5.1 → mmif_python-1.5.3}/documentation/target-versions.csv

@@ -1,4 +1,6 @@
 "``mmif-python`` version","Target MMIF Specification"
+`1.5.3 <https://pypi.org/project/mmif-python/1.5.3/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
+`1.5.2 <https://pypi.org/project/mmif-python/1.5.2/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.5.1 <https://pypi.org/project/mmif-python/1.5.1/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.5.0 <https://pypi.org/project/mmif-python/1.5.0/>`__,`1.2.0 <https://mmif.clams.ai/1.2.0/>`__
 `1.4.0 <https://pypi.org/project/mmif-python/1.4.0/>`__,`1.1.1 <https://mmif.clams.ai/1.1.1/>`__

{mmif_python-1.5.1 → mmif_python-1.5.3}/mmif/serialize/mmif.py

@@ -175,6 +175,14 @@ class Mmif(MmifObject):
        all_views = mmif.views[1:4]       # Slice of views
     """
 
+    #: Hardcoded list of property names that must stay at the individual
+    #: annotation level, and never "factored" into the view's ``contains``
+    #: metadata, even when redundant across annotations.
+    _NON_FACTORABLE_PROPS = frozenset({
+        'start', 'end', 'targets', 'source', 'target', 'representatives', 
+        'mime', 'location', 'location_', 'text',
+    })
+
     def __init__(self, mmif_obj: Optional[Union[bytes, str, dict]] = None, *, validate: bool = True) -> None:
         self.metadata: MmifMetadata = MmifMetadata()
         self.documents: DocumentsList = DocumentsList()
@@ -211,26 +219,42 @@ class Mmif(MmifObject):
             json_str = json.loads(json_str)
         jsonschema.validators.validate(json_str, schema)
 
-    def serialize(self, sanitize: bool = False, autogenerate_capital_annotations: bool = True, **kwargs) -> str:
+    def serialize(self,
+                  pretty: bool = False,
+                  include_context: bool = True,
+                  *,
+                  sanitize: bool = False,
+                  autogenerate_capital_annotations: bool = True,
+                  factor_out_shared_properties: bool = True) -> str:
         """
         Serializes the MMIF object to a JSON string.
 
+        :param pretty: If True, returns the string with indentation.
+        :param include_context: If False, excludes contextual attributes (e.g.
+            runtime timestamps) from serialization.
         :param sanitize: If True, performs some sanitization of before returning
             the JSON string. See :meth:`sanitize` for details.
         :param autogenerate_capital_annotations: If True, automatically convert
             any "pending" temporary properties from `Document` objects to
             `Annotation` objects. See :meth:`generate_capital_annotations` for
             details.
-        :param kwargs: Keyword arguments to pass to the parent's ``serialize``
-                       method (e.g., ``pretty=True``, ``include_context=False``).
+        :param factor_out_shared_properties: If True, lift properties shared
+            (same value) across all annotations of a type in a view into the
+            view's ``contains`` metadata. See
+            :meth:`factor_out_shared_properties` for details. Independent of
+            ``autogenerate_capital_annotations``, but runs after it (so
+            freshly-materialized pending properties are included) when both are
+            enabled.
         :return: JSON string of the MMIF object.
         """
         if autogenerate_capital_annotations:
             self.generate_capital_annotations()
+        if factor_out_shared_properties:
+            self.factor_out_shared_properties()
         # sanitization should be done after `Annotation` annotations are generated
         if sanitize:
             self.sanitize()
-        return super().serialize(**kwargs)
+        return super().serialize(pretty=pretty, include_context=include_context)
 
     def _deserialize(self, input_dict: dict) -> None:
         """
@@ -261,9 +285,16 @@ class Mmif(MmifObject):
             for ann in view.get_annotations():
                 ## for "capital" Annotation properties
                 # first add all extrinsic properties to the Annotation objects
-                # as "ephemeral" properties
+                # as "ephemeral" properties. A view-level `contains` default must
+                # not override an annotation-level value that is already present
+                # in `_props_ephemeral` -- namely an alias of a property set on the
+                # annotation itself (put there by `_add_prop_aliases` during the
+                # annotation's own deserialization, which runs earlier). Per the
+                # spec, the annotation-level value takes precedence over the
+                # view-level default.
                 for prop_key, prop_value in extrinsic_props[ann.at_type].items():
-                    ann._props_ephemeral[prop_key] = prop_value
+                    if prop_key not in ann._props_ephemeral:
+                        ann._props_ephemeral[prop_key] = prop_value
                 # then, do the same to associated Document objects. Note that, 
                 # in a view, it is guaranteed that all Annotation objects are not duplicates
                 if ann.at_type == AnnotationTypes.Annotation:
@@ -297,7 +328,7 @@ class Mmif(MmifObject):
                 f"Alignment {alignment_ann.id} has `source` and `target` properties that do not point to Annotation objects.",
                 RuntimeWarning)
         ## caching alignments
-        if all(map(lambda x: x in alignment_ann.properties, ('source', 'target'))):
+        if all(map(lambda x: x in alignment_ann, ('source', 'target'))):
             try:
                 source_ann = self.__getitem__(alignment_ann.get('source'))
                 target_ann = self.__getitem__(alignment_ann.get('target'))
@@ -383,15 +414,51 @@ class Mmif(MmifObject):
                     if view_to_write.metadata.app == current_app and doc_id in view_to_write.annotations:
                         view_to_write[doc_id].properties.update(props)
                     else:
-                        if len(anns_to_write) == 1:
-                            # if there's only one document, we can record the doc_id in the contains metadata
-                            view_to_write.metadata.new_contain(AnnotationTypes.Annotation, document=doc_id)
-                            props.pop('document', None)
-                        else:
-                            # otherwise, doc_id needs to be recorded in the annotation property
-                            props['document'] = doc_id
+                        props['document'] = doc_id
                         view_to_write.new_annotation(AnnotationTypes.Annotation, **props)
 
+
+    def factor_out_shared_properties(self):
+        """
+        Factor properties that are shared (identical value) across all
+        annotations of a type within a view up into that view's ``contains``
+        metadata, per the MMIF spec recommendation to prefer view-level
+        defaults for properties shared among annotations of a type.
+
+        A property is factored when it is present, with the same value, on
+        **every** annotation of a given ``@type`` in the view, there are at
+        least two such annotations (so the value is genuinely shared), and the
+        key is not in the :attr:`_NON_FACTORABLE_PROPS` protection list.
+        Factored values are mirrored into each annotation's ephemeral props at
+        deserialization time, so in-memory access is unchanged, while the 
+        serialized output carries the value once, in ``contains``.
+        """
+        for view in self.views:
+            by_type = defaultdict(list)
+            for ann in view.get_annotations():
+                by_type[ann.at_type].append(ann)
+            for at_type, anns in by_type.items():
+                if len(anns) < 2:
+                    continue
+                shared = {}
+                for key in list(anns[0].properties.keys()):
+                    if key in self._NON_FACTORABLE_PROPS:
+                        continue
+                    value = anns[0].properties[key]
+                    if all(key in a.properties and a.properties[key] == value
+                           for a in anns):
+                        shared[key] = value
+                if not shared:
+                    continue
+                if at_type not in view.metadata.contains:
+                    view.metadata.new_contain(at_type)
+                contain = view.metadata.contains[at_type]
+                for key, value in shared.items():
+                    contain[key] = value
+                    for a in anns:
+                        del a.properties[key]
+                        a._props_ephemeral[key] = value
+
     def sanitize(self):
         """
         Sanitizes a Mmif object by running some safeguards.

{mmif_python-1.5.1 → mmif_python-1.5.3}/mmif/serialize/view.py

@@ -82,6 +82,25 @@ class View(MmifObject):
         self._required_attributes = ["id", "metadata", "annotations"]
         super().__init__(view_obj)
         self._fix_old_short_ids()
+        self._rebuild_id_counts()
+
+    def _rebuild_id_counts(self):
+        """
+        Re-seed the per-view auto-ID counters from the annotations loaded during
+        deserialization.
+
+        ``_id_counts`` is not serialized, so a view read back from JSON starts
+        with an empty counter. Without this, the next :meth:`new_annotation`
+        regenerates an ID (e.g. ``an_1``) that already exists in the
+        deserialized view and :meth:`AnnotationsList.append` raises ``KeyError``.
+        See issue #393.
+        """
+        for annotation in self.annotations:
+            local_id = annotation.id.split(self.id_delimiter)[-1]
+            prefix, _, num = local_id.rpartition('_')
+            if prefix and num.isdigit():
+                self._id_counts[prefix] = max(
+                    self._id_counts.get(prefix, 0), int(num))
 
     def _fix_old_short_ids(self):
         """

{mmif_python-1.5.1 → mmif_python-1.5.3}/mmif_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmif-python
-Version: 1.5.1
+Version: 1.5.3
 Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
 License-Expression: Apache-2.0
 Project-URL: homepage, https://mmif.clams.ai

{mmif_python-1.5.1 → mmif_python-1.5.3}/mmif_python.egg-info/SOURCES.txt

@@ -63,6 +63,8 @@ mmif_python.egg-info/SOURCES.txt
 mmif_python.egg-info/dependency_links.txt
 mmif_python.egg-info/entry_points.txt
 mmif_python.egg-info/requires.txt
+mmif_python.egg-info/scm_file_list.json
+mmif_python.egg-info/scm_version.json
 mmif_python.egg-info/top_level.txt
 tests/black-2997fps.mp4
 tests/black-2997fps.webm

mmif_python-1.5.3/mmif_python.egg-info/scm_file_list.json

@@ -0,0 +1,95 @@
+{
+  "files": [
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+    "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",
+    "documentation/target-versions.csv",
+    "documentation/consumer-tutorial.rst",
+    "documentation/target-versions.rst",
+    "documentation/index.rst",
+    "documentation/introduction.rst",
+    "documentation/cli.rst",
+    "documentation/plugins.rst",
+    "documentation/summarizer.rst",
+    "documentation/conf.py",
+    "documentation/_mmif_example_builder/__init__.py",
+    "documentation/_templates/versions.html",
+    "mmif/__init__.py",
+    "mmif/vocabulary/__init__.py",
+    "mmif/vocabulary/base_types.py",
+    "mmif/vocabulary/document_types.py",
+    "mmif/vocabulary/annotation_types.py",
+    "mmif/utils/__init__.py",
+    "mmif/utils/text_document_helper.py",
+    "mmif/utils/timeunit_helper.py",
+    "mmif/utils/workflow_helper.py",
+    "mmif/utils/video_document_helper.py",
+    "mmif/utils/sequence_helper.py",
+    "mmif/utils/summarizer/__init__.py",
+    "mmif/utils/summarizer/config.py",
+    "mmif/utils/summarizer/utils.py",
+    "mmif/utils/summarizer/summary.py",
+    "mmif/utils/summarizer/graph.py",
+    "mmif/utils/summarizer/nodes.py",
+    "mmif/utils/cli/__init__.py",
+    "mmif/utils/cli/source.py",
+    "mmif/utils/cli/rewind.py",
+    "mmif/utils/cli/summarize.py",
+    "mmif/utils/cli/describe.py",
+    "mmif/serialize/model.py",
+    "mmif/serialize/__init__.py",
+    "mmif/serialize/view.py",
+    "mmif/serialize/annotation.py",
+    "mmif/serialize/mmif.py",
+    "mmif/res/__init__.py",
+    "mmif/res/mmif.json",
+    "mmif/ver/__init__.py",
+    "tests/mmif_examples.py",
+    "tests/test_specver.py",
+    "tests/test_utils.py",
+    "tests/test_utils_cli.py",
+    "tests/test_vocab.py",
+    "tests/testsrc-2997fps-ptsoffset.mp4",
+    "tests/test_serialize.py",
+    "tests/black-2997fps.mp4",
+    "tests/black-2997fps.webm",
+    "tests/mmif-examples/README.md",
+    "tests/mmif-examples/examples.json",
+    "tests/mmif-examples/1.0.5-old-shortid.json",
+    "tests/mmif-examples/swt-1.0.mmif",
+    "tests/mmif-examples/segmenter-kaldi-ner/raw.json",
+    "tests/mmif-examples/everything/raw.json",
+    "tests/mmif-examples/others/video-transcript.json",
+    "tests/mmif-examples/others/image-box-ocr-timex.json",
+    "tests/mmif-examples/others/README.md",
+    "tests/mmif-examples/others/video.json",
+    "tests/mmif-examples/others/video-transcript-demux-fa.json",
+    "tests/mmif-examples/others/image.json",
+    "tests/mmif-examples/others/video-transcript-sentencesplit.json",
+    "tests/mmif-examples/others/video-transcript-demux-fa.short.json",
+    "tests/mmif-examples/others/slate-detect.json",
+    "tests/mmif-examples/others/image-box.json",
+    "tests/mmif-examples/others/slate-reco.json",
+    "tests/mmif-examples/others/video-transcript-demux.json",
+    "tests/mmif-examples/others/image-box-ocr.json",
+    "tests/mmif-examples/others/video-demux.json",
+    "tests/mmif-examples/bars-tones-slates/raw.json",
+    "tests/mmif-examples/east-tesseract-typing/raw.json",
+    "mmif_docloc_http/__init__.py",
+    ".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"
+  ]
+}

mmif_python-1.5.3/mmif_python.egg-info/scm_version.json

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

{mmif_python-1.5.1 → mmif_python-1.5.3}/tests/test_serialize.py

@@ -76,7 +76,7 @@ class TestMmif(unittest.TestCase):
                     mmif_obj = Mmif(example)
                 except ValidationError:
                     self.fail(f"example {i}")
-                self.assertEqual(mmif_obj.serialize(True), Mmif(mmif_obj.serialize()).serialize(True), f'Failed on {i}')
+                self.assertEqual(mmif_obj.serialize(pretty=True), Mmif(mmif_obj.serialize()).serialize(pretty=True), f'Failed on {i}')
 
     def test_json_mmif_deserialize(self):
         for i, example in MMIF_EXAMPLES.items():
@@ -91,7 +91,7 @@ class TestMmif(unittest.TestCase):
                 for annotation in view.annotations:
                     self.assertIn('_type', annotation.__dict__)
             self.assertTrue('id' in list(mmif_obj.views._items.values())[0].__dict__)
-            self.assertEqual(mmif_obj.serialize(True), Mmif(json.loads(mmif_obj.serialize())).serialize(True), f'Failed on {i}')
+            self.assertEqual(mmif_obj.serialize(pretty=True), Mmif(json.loads(mmif_obj.serialize())).serialize(pretty=True), f'Failed on {i}')
 
     def test_str_vs_json_deserialize(self):
         for i, example in MMIF_EXAMPLES.items():
@@ -99,7 +99,7 @@ class TestMmif(unittest.TestCase):
                 continue
             str_mmif_obj = Mmif(example)
             json_mmif_obj = Mmif(json.loads(example))
-            self.assertEqual(str_mmif_obj.serialize(True), json_mmif_obj.serialize(True), f'Failed on {i}')
+            self.assertEqual(str_mmif_obj.serialize(pretty=True), json_mmif_obj.serialize(pretty=True), f'Failed on {i}')
 
     def test_bad_mmif_deserialize_no_metadata(self):
         self.mmif_examples_json['everything'].pop('metadata')
@@ -1194,6 +1194,35 @@ class TestAnnotation(unittest.TestCase):
             self.assertTrue("nonspeech", tf3.get_property('label'))
             self.assertTrue("speech", tf3.get_property('frameLabel'))
 
+    def test_alias_precedes_view_contains_default(self):
+        # An annotation that sets a property via a deprecated alias (frameType
+        # aliases label) provides an annotation-level value. A view-level
+        # `contains` default for the canonical name must NOT override it -- the
+        # annotation-level value takes precedence over the view-level default.
+        tf = "http://mmif.clams.ai/vocabulary/TimeFrame/v6"
+        raw = {
+            "metadata": {"mmif": "http://mmif.clams.ai/1.2.0"},
+            "documents": [{"@type": "http://mmif.clams.ai/vocabulary/VideoDocument/v1",
+                           "properties": {"id": "m1", "mime": "video/mp4",
+                                          "location": "file:///v.mp4"}}],
+            "views": [{"id": "v1",
+                       "metadata": {"app": "http://x/1", "contains": {tf: {"label": "X"}}},
+                       "annotations": [{"@type": tf,
+                                        "properties": {"id": "v1:a1", "start": 0,
+                                                       "end": 5, "frameType": "bars"}}]}]
+        }
+        mmif_obj = Mmif(json.dumps(raw), validate=False)
+        ann = mmif_obj['v1:a1']
+        # the annotation's own frameType (alias of label) wins over contains
+        self.assertEqual('bars', ann.get_property('label'))
+        self.assertEqual('bars', ann.get_property('frameType'))
+        # a genuine view-level default (not shadowed by any annotation value)
+        # still applies
+        raw['views'][0]['metadata']['contains'][tf] = {"timeUnit": "milliseconds"}
+        raw['views'][0]['annotations'][0]['properties'] = {"id": "v1:a1", "start": 0, "end": 5}
+        ann = Mmif(json.dumps(raw), validate=False)['v1:a1']
+        self.assertEqual('milliseconds', ann.get_property('timeUnit'))
+
     def test_change_id(self):
         anno_obj: Annotation = self.data['everything']['mmif']['v5:bb1']
 
@@ -1451,7 +1480,151 @@ class TestDocument(unittest.TestCase):
             'author'))
         self.assertEqual('you', list(mmif_roundtrip2.views.get_last_contentful_view().get_annotations(AnnotationTypes.Annotation))[
             0].get_property('author'))
-        
+
+    def test_view_id_counts_rebuilt_on_deserialize(self):
+        # regression for issue #393: `_id_counts` is not serialized, so after
+        # deserialization the next generated id must not collide with an existing
+        # one already present in the view.
+        mmif = Mmif(validate=False)
+        doc = Document(); doc.at_type = DocumentTypes.VideoDocument
+        doc.id = 'd1'; doc.location = 'file:///v.mp4'
+        mmif.add_document(doc)
+        v = mmif.new_view()
+        v.metadata.app = tester_appname
+        a1 = v.new_annotation(AnnotationTypes.Annotation, document='d1', frameCount=10)
+        self.assertTrue(a1.id.endswith('an_1'))
+        # round-trip: the reloaded view still contains `an_1` but starts with an
+        # empty counter unless rebuilt
+        v2 = Mmif(mmif.serialize())[v.id]
+        a2 = v2.new_annotation(AnnotationTypes.Annotation, document='d1', duration=20)
+        self.assertTrue(a2.id.endswith('an_2'))   # must not regenerate an_1
+
+    def test_capital_annotation_no_collision_across_apps(self):
+        # regression for issue #393: a downstream app re-deriving a document
+        # property with a *different* value must not crash on serialize; the
+        # distinct value is recorded as an additional capital annotation
+        # (value-based de-dup preserves both assertions), not a colliding one.
+        m = Mmif(validate=False)
+        d = Document()
+        d.at_type = DocumentTypes.VideoDocument
+        d.id = 'd1'
+        d.location = 'file:///v.mp4'
+        m.add_document(d)
+        v1 = m.new_view(); v1.metadata.app = 'http://app/producer'
+        v1.new_annotation(AnnotationTypes.TimeFrame, label='bars')
+        d.add_property('frameCount', 51248.0)
+        d.add_property('duration', 1709977.0)
+
+        # downstream app loads it and re-derives a *different* duration value
+        m2 = Mmif(m.serialize())
+        d2 = m2['d1']
+        v2 = m2.new_view(); v2.metadata.app = 'http://app/consumer'
+        v2.new_annotation(AnnotationTypes.TimeFrame, label='caption')
+        d2.add_property('frameCount', 51248)      # same value -> de-duped away
+        d2.add_property('duration', 1709975)      # different value -> new annotation
+        out = Mmif(m2.serialize())                # must not raise KeyError
+
+        caps = [a for view in out.views
+                for a in view.get_annotations(AnnotationTypes.Annotation)]
+        durations = {a.get_property('duration') for a in caps if 'duration' in a}
+        # both distinct duration assertions coexist; neither is lost or overwritten
+        self.assertEqual(2, len(caps))
+        self.assertEqual({1709977.0, 1709975}, durations)
+
+    def test_factor_out_shared_properties(self):
+        # A view-level metadata property (document/timeUnit/labelset) shared
+        # across all annotations of a type is factored up into the view's
+        # `contains` on serialize, while instance-level properties (label) and
+        # anchors stay on the annotations.
+        m = Mmif(validate=False)
+        v = m.new_view(); v.metadata.app = tester_appname
+        v.new_annotation(AnnotationTypes.TimeFrame, document='m1', timeUnit='ms',
+                         start=0, end=5, label='bars')
+        v.new_annotation(AnnotationTypes.TimeFrame, document='m1', timeUnit='ms',
+                         start=5, end=9, label='slate')
+        out = json.loads(m.serialize())
+        vout = out['views'][0]
+        tf_key = next(k for k in vout['metadata']['contains'] if 'TimeFrame' in k)
+        contains = vout['metadata']['contains'][tf_key]
+        # shared `document`/`timeUnit` are factored up ...
+        self.assertEqual('m1', contains.get('document'))
+        self.assertEqual('ms', contains.get('timeUnit'))
+        for a in vout['annotations']:
+            # ... and removed from each annotation ...
+            self.assertNotIn('document', a['properties'])
+            self.assertNotIn('timeUnit', a['properties'])
+            # ... while anchors and the differing label stay per-annotation
+            self.assertIn('start', a['properties'])
+            self.assertIn('label', a['properties'])
+        # round-trip: the factored values still resolve per annotation
+        m2 = Mmif(m.serialize())
+        for a in m2.views[0].get_annotations(AnnotationTypes.TimeFrame):
+            self.assertEqual('m1', a.get_property('document'))
+            self.assertEqual('ms', a.get_property('timeUnit'))
+
+    def test_factor_out_protects_listed_props_and_skips_singletons(self):
+        # Blocklisted props (anchors/links) are never factored even when
+        # identical across annotations; a type with a single annotation is
+        # skipped (needs > 1 to be genuinely shared).
+        m = Mmif(validate=False)
+        v = m.new_view(); v.metadata.app = tester_appname
+        tf = v.new_annotation(AnnotationTypes.TimeFrame, start=0, end=5)
+        td1 = v.new_textdocument(text='a'); td2 = v.new_textdocument(text='b')
+        # two Alignments share the same `source` -- must NOT be factored out
+        v.new_annotation(AnnotationTypes.Alignment, source=tf.id, target=td1.id)
+        v.new_annotation(AnnotationTypes.Alignment, source=tf.id, target=td2.id)
+        out = json.loads(m.serialize())
+        aligns = [a for a in out['views'][0]['annotations'] if 'Alignment' in a['@type']]
+        for a in aligns:
+            self.assertIn('source', a['properties'])
+        # a single-annotation type is not factored (threshold)
+        m2 = Mmif(validate=False); v2 = m2.new_view(); v2.metadata.app = tester_appname
+        v2.new_annotation(AnnotationTypes.TimeFrame, document='m1', start=0, end=5)
+        out2 = json.loads(m2.serialize())
+        self.assertIn('document', out2['views'][0]['annotations'][0]['properties'])
+
+    def test_alignment_cached_from_view_level_source_target(self):
+        # regression for the `_cache_alignment` fix: `source`/`target` supplied
+        # as view-level `contains` defaults (distributed to ephemeral, absent
+        # from the annotation's own properties) must still be honored.
+        al = "http://mmif.clams.ai/vocabulary/Alignment/v1"
+        tf = "http://mmif.clams.ai/vocabulary/TimeFrame/v6"
+        td = "http://mmif.clams.ai/vocabulary/TextDocument/v2"
+        raw = {
+            "metadata": {"mmif": "http://mmif.clams.ai/1.2.0"},
+            "documents": [],
+            "views": [{"id": "v1",
+                       "metadata": {"app": "http://x/1", "contains": {
+                           al: {"source": "v1:tf1", "target": "v1:td1"}}},
+                       "annotations": [
+                           {"@type": tf, "properties": {"id": "v1:tf1", "start": 0, "end": 5}},
+                           {"@type": td, "properties": {"id": "v1:td1", "text": {"@value": "x"}}},
+                           {"@type": al, "properties": {"id": "v1:a1"}}]}]
+        }
+        m = Mmif(json.dumps(raw), validate=False)
+        self.assertTrue(list(m['v1:tf1'].get_all_aligned()))
+
+    def test_factor_out_shared_properties_flag(self):
+        # `factor_out_shared_properties` gates factoring independently of
+        # `autogenerate_capital_annotations`.
+        m = Mmif(validate=False)
+        v = m.new_view(); v.metadata.app = tester_appname
+        v.new_annotation(AnnotationTypes.TimeFrame, document='m1', start=0, end=5)
+        v.new_annotation(AnnotationTypes.TimeFrame, document='m1', start=5, end=9)
+        # disabled -> shared `document` stays on each annotation
+        off = json.loads(m.serialize(factor_out_shared_properties=False))
+        for a in off['views'][0]['annotations']:
+            self.assertIn('document', a['properties'])
+        # independent of generation: a reloaded MMIF (props already in
+        # `.properties`) is still factored with capital-annotation generation OFF
+        reloaded = Mmif(m.serialize(factor_out_shared_properties=False))
+        on = json.loads(reloaded.serialize(autogenerate_capital_annotations=False,
+                                           factor_out_shared_properties=True))
+        tf_key = next(k for k in on['views'][0]['metadata']['contains'] if 'TimeFrame' in k)
+        self.assertEqual('m1', on['views'][0]['metadata']['contains'][tf_key].get('document'))
+        for a in on['views'][0]['annotations']:
+            self.assertNotIn('document', a['properties'])
+
     def test_capital_annotation_generation_viewfinder(self):
         mmif = Mmif(validate=False)
         for i in range(1, 3):