cjm-speaker-diarization-adapter-interface 0.0.1__tar.gz

cjm_speaker_diarization_adapter_interface-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2022, fastai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cjm_speaker_diarization_adapter_interface-0.0.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: cjm-speaker-diarization-adapter-interface
+Version: 0.0.1
+Summary: Typed speaker-diarization task-adapter interface — SpeakerDiarizationAdapter ABC + GenericSpeakerDiarizationAdapter (thin pass-through around a diarization tool) and the SpeakerDiarizationToolProtocol. The SpeakerDiarizationResult data noun lives in cjm-capability-primitives; turns are ANONYMOUS clusters — identity is the correction TUI's assignment lane, never this interface's job.
+Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/cj-mills/cjm-speaker-diarization-adapter-interface
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cjm-substrate>=0.0.58
+Requires-Dist: cjm-capability-primitives>=0.0.12
+Dynamic: license-file
+
+# cjm-speaker-diarization-adapter-interface
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Adapter interface for speaker-diarization capabilities — the speaker_diarization task-channel contract (audio → typed SpeakerTurn/SpeakerDiarizationResult) that capability libs implement and workflow cores consume; the generic adapter owns the SQLite cache bookends (content-addressed, speaker-count hints fold into the config hash).
+
+## Modules
+
+- **`cjm_speaker_diarization_adapter_interface.__init__`**
+- **`cjm_speaker_diarization_adapter_interface.adapter`** — The typed speaker-diarization task contract — the `SpeakerDiarizationAdapter` ABC + the `SpeakerDiarizationToolProtocol` structural contract (capability-unit Option C; session-D DECs 18d7de80 + d6df3a8e).
+- **`cjm_speaker_diarization_adapter_interface.generic`** — The generic (tool-agnostic) speaker-diarization adapter — cache-check, invoke the bound tool's pure-compute `diarize`, persist. Reused across every tool capability satisfying `SpeakerDiarizationToolProtocol`, exactly as `GenericVADAdapter` is reused across VAD tools.
+- **`cjm_speaker_diarization_adapter_interface.storage`** — Standardized SQLite storage for speaker-diarization results with content hashing.
+
+## API
+
+### `cjm_speaker_diarization_adapter_interface.adapter`
+
+- `SpeakerDiarizationAdapter` _class_ — Typed speaker-diarization task adapter: source audio path in,
+- `SpeakerDiarizationToolProtocol` _class_ — Structural contract for speaker-diarization tool capabilities.
+
+### `cjm_speaker_diarization_adapter_interface.generic`
+
+- `GenericSpeakerDiarizationAdapter` _class_ — Generic speaker-diarization adapter: cache-check -> pure-compute tool -> persist.
+
+### `cjm_speaker_diarization_adapter_interface.storage`
+
+- `SpeakerDiarizationRow` _class_ — A single row from the speaker_diarization_results table.
+- `SpeakerDiarizationStorage` _class_ — Standardized SQLite storage for speaker-diarization results.
+
+## Dependencies
+
+**Depends on:** `cjm-capability-primitives`, `cjm-substrate`
+**Used by:** `cjm-capability-pyannote`

cjm_speaker_diarization_adapter_interface-0.0.1/README.md

@@ -0,0 +1,33 @@
+# cjm-speaker-diarization-adapter-interface
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Adapter interface for speaker-diarization capabilities — the speaker_diarization task-channel contract (audio → typed SpeakerTurn/SpeakerDiarizationResult) that capability libs implement and workflow cores consume; the generic adapter owns the SQLite cache bookends (content-addressed, speaker-count hints fold into the config hash).
+
+## Modules
+
+- **`cjm_speaker_diarization_adapter_interface.__init__`**
+- **`cjm_speaker_diarization_adapter_interface.adapter`** — The typed speaker-diarization task contract — the `SpeakerDiarizationAdapter` ABC + the `SpeakerDiarizationToolProtocol` structural contract (capability-unit Option C; session-D DECs 18d7de80 + d6df3a8e).
+- **`cjm_speaker_diarization_adapter_interface.generic`** — The generic (tool-agnostic) speaker-diarization adapter — cache-check, invoke the bound tool's pure-compute `diarize`, persist. Reused across every tool capability satisfying `SpeakerDiarizationToolProtocol`, exactly as `GenericVADAdapter` is reused across VAD tools.
+- **`cjm_speaker_diarization_adapter_interface.storage`** — Standardized SQLite storage for speaker-diarization results with content hashing.
+
+## API
+
+### `cjm_speaker_diarization_adapter_interface.adapter`
+
+- `SpeakerDiarizationAdapter` _class_ — Typed speaker-diarization task adapter: source audio path in,
+- `SpeakerDiarizationToolProtocol` _class_ — Structural contract for speaker-diarization tool capabilities.
+
+### `cjm_speaker_diarization_adapter_interface.generic`
+
+- `GenericSpeakerDiarizationAdapter` _class_ — Generic speaker-diarization adapter: cache-check -> pure-compute tool -> persist.
+
+### `cjm_speaker_diarization_adapter_interface.storage`
+
+- `SpeakerDiarizationRow` _class_ — A single row from the speaker_diarization_results table.
+- `SpeakerDiarizationStorage` _class_ — Standardized SQLite storage for speaker-diarization results.
+
+## Dependencies
+
+**Depends on:** `cjm-capability-primitives`, `cjm-substrate`
+**Used by:** `cjm-capability-pyannote`

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface/adapter.py

@@ -0,0 +1,70 @@
+"""The typed speaker-diarization task contract — the `SpeakerDiarizationAdapter` ABC + the `SpeakerDiarizationToolProtocol` structural contract (capability-unit Option C; session-D DECs 18d7de80 + d6df3a8e)."""
+
+from abc import abstractmethod
+from typing import Any, ClassVar, Dict, Protocol, runtime_checkable
+
+from cjm_capability_primitives.speaker_diarization import SpeakerDiarizationResult
+from cjm_substrate.core.adapter import TaskAdapter
+
+
+# Canonical home (PILLAR 1c): the data noun lives in cjm-capability-primitives,
+# so the tool capability depends on it, never on this adapter machinery.
+# SCOPE (physical-speaker principle, DEC 44afb2df): this interface carries
+# DIARIZATION only — audio in, ANONYMOUS time-ranged turns out. Mapping
+# clusters to named identities is the correction TUI's assignment lane
+# (human judgment); assignment semantics never enter this contract.
+
+
+@runtime_checkable
+class SpeakerDiarizationToolProtocol(Protocol):
+    """Structural contract for speaker-diarization tool capabilities.
+
+    `diarize` reads the original source audio (path) and returns time-ordered
+    anonymous speaker turns in that audio's coordinates. `get_current_config`
+    supplies the effective config whose canonical hash joins downstream
+    identity/provenance composites."""
+    def diarize(self, audio: str, **kwargs) -> SpeakerDiarizationResult: ...
+    def get_current_config(self) -> Dict[str, Any]: ...
+
+
+class SpeakerDiarizationAdapter(TaskAdapter):
+    """Typed speaker-diarization task adapter: source audio path in,
+    `SpeakerDiarizationResult` (anonymous time-ranged turns) out.
+
+    Input contract: the caller passes a path to the audio whose COORDINATES it
+    needs preserved — turn times always index into exactly that audio (a tool
+    that resamples internally must report source-coordinate times). Cluster
+    labels are result-scoped only.
+
+    Speaker-count hints ride kwargs (`num_speakers`, `min_speakers`,
+    `max_speakers`) — optional, tool-interpreted; a tool without count control
+    ignores them.
+
+    No cache/persist bookends in v0: the transcription workflow persists
+    results on its own run manifests (turns ride BESIDE transcripts,
+    a9cadfec), and diarization runs once per source per config — a cache DB
+    can land in a generic-adapter revision if re-run pressure appears.
+
+    Implementations run in-worker beside their tool capability and are
+    constructed with the bound tool instance: `AdapterClass(tool)`. The result
+    DTO is wire-registered ("speaker_diarization.result"): returned values
+    cross the worker boundary typed.
+    """
+
+    task_name: ClassVar[str] = "speaker_diarization"
+    required_tool_protocol: ClassVar[type] = SpeakerDiarizationToolProtocol
+
+    def __init__(
+        self,
+        tool: SpeakerDiarizationToolProtocol,  # The bound tool capability instance (worker-side binding)
+    ):
+        self.tool = tool
+
+    @abstractmethod
+    def diarize(
+        self,
+        audio: str,  # Path to the source audio to diarize (turn times index into THIS audio)
+        **kwargs,    # Speaker-count hints + provenance + tool options
+    ) -> SpeakerDiarizationResult:  # Time-ordered anonymous speaker turns
+        """Diarize audio into time-ordered anonymous speaker turns."""
+        ...

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface/generic.py

@@ -0,0 +1,79 @@
+"""The generic (tool-agnostic) speaker-diarization adapter — cache-check, invoke the bound tool's pure-compute `diarize`, persist. Reused across every tool capability satisfying `SpeakerDiarizationToolProtocol`, exactly as `GenericVADAdapter` is reused across VAD tools."""
+
+import os
+
+from cjm_capability_primitives.speaker_diarization import SpeakerDiarizationResult, SpeakerTurn
+from cjm_substrate.core.wire import get_call_envelope
+from cjm_substrate.utils.hashing import hash_dict_canonical, hash_file
+
+from .adapter import SpeakerDiarizationAdapter
+from .storage import SpeakerDiarizationStorage
+
+
+class GenericSpeakerDiarizationAdapter(SpeakerDiarizationAdapter):
+    """Generic speaker-diarization adapter: cache-check -> pure-compute tool -> persist.
+
+    Works against ANY tool satisfying `SpeakerDiarizationToolProtocol`. The
+    bookends landed 2026-07-26 (the VAD-adapter precedent this class was born
+    citing): full-source diarization costs ~46s/hour on cuda and sources run
+    multi-hour, so re-runs are worth caching.
+
+      1. cache check (file_path + file_hash + config_hash) BEFORE invoking the
+         tool, so a hit never loads the pipeline;
+      2. the tool's pure-compute `diarize` on a miss / forced call;
+      3. `save_with_logging` (upsert by file_path + config_hash).
+
+    Unlike VAD, `diarize` kwargs are NOT provenance pass-through: the
+    speaker-count hints (num_speakers / min_speakers / max_speakers) steer the
+    clustering, so they FOLD INTO `config_hash` — the same audio diarized
+    under a different hint is a different cache row. `force` rides
+    `CallEnvelope.control` (not a task kwarg, keeping `diarize(audio)` pure).
+    Storage lives at `<CAPABILITY_DATA_DIR>/speaker_diarization.db`; the
+    substrate injects the per-capability `CAPABILITY_DATA_DIR` at spawn.
+    """
+
+    # Per-call kwargs that change the clustering output — cache identity,
+    # mirrored from the pyannote tool's diarize signature.
+    HINT_KEYS = ("num_speakers", "min_speakers", "max_speakers")
+
+    def _get_storage(self) -> SpeakerDiarizationStorage:
+        """Lazily open the per-capability cache DB under the substrate-injected
+        CAPABILITY_DATA_DIR (created at worker spawn)."""
+        if getattr(self, "_storage", None) is None:
+            db_path = os.path.join(os.environ["CAPABILITY_DATA_DIR"], "speaker_diarization.db")
+            self._storage = SpeakerDiarizationStorage(db_path)
+        return self._storage
+
+    def diarize(
+        self,
+        audio: str,  # Path to the source audio to diarize (decoded PCM rendition)
+        **kwargs,    # Speaker-count hints (cache identity) + provenance + tool options
+    ) -> SpeakerDiarizationResult:  # Time-ordered anonymous speaker turns
+        """Cache-check, invoke the bound tool's pure-compute `diarize`, persist."""
+        file_path = str(audio)
+        file_hash = hash_file(file_path)
+        hints = {k: kwargs[k] for k in self.HINT_KEYS if kwargs.get(k) is not None}
+        config_hash = hash_dict_canonical({**self.tool.get_current_config(), **hints})
+
+        env = get_call_envelope()
+        force = bool(env.control.get("force")) if env is not None else False
+
+        storage = self._get_storage()
+        if not force:
+            cached = storage.get_cached(file_path, file_hash, config_hash)
+            if cached is not None:
+                return SpeakerDiarizationResult(
+                    turns=[SpeakerTurn(**t) for t in (cached.turns or [])],
+                    metadata=cached.metadata or {},
+                )
+
+        # Pure compute on the tool (cache miss / forced).
+        result = self.tool.diarize(audio, **kwargs)
+
+        # Persist. Content-addressed row; cache key is (file_path, config_hash)
+        # with file_hash for content-correctness.
+        storage.save_with_logging(
+            file_path=file_path, file_hash=file_hash, config_hash=config_hash,
+            turns=[t.to_dict() for t in result.turns], metadata=result.metadata,
+        )
+        return result

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface/storage.py

@@ -0,0 +1,203 @@
+"""Standardized SQLite storage for speaker-diarization results with content hashing.
+
+Cache shape follows the VAD-adapter precedent: content-addressed rows upserted
+by (file_path, config_hash) with file_hash for content-correctness. Landed
+2026-07-26 — full-source diarization (~46s/hour on cuda, multi-hour sources)
+made re-runs worth caching, unlike the pysbd-precedent no-cache assessment
+this pair was born under."""
+
+import json
+import logging
+import sqlite3
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from cjm_substrate.core.journal_store import SubstrateEventType
+from cjm_substrate.core.wire import record_account
+from cjm_substrate.utils.hashing import hash_file
+
+
+# CR-14 follow-up: storage events are substrate-family accounts. The helpers
+# below RECORD them (no-op outside a worker call span); the host journals
+# them off the response header with worker_reported=True.
+
+
+@dataclass
+class SpeakerDiarizationRow:
+    """A single row from the speaker_diarization_results table."""
+    file_path: str       # Path to the analyzed (decoded PCM rendition) audio file
+    file_hash: str       # Hash of the analyzed file in "algo:hexdigest" format
+    config_hash: str     # Hash of the diarization config (tool config + speaker-count hints)
+    turns: Optional[List[Dict[str, Any]]] = None  # Diarized speech turns (serialized SpeakerTurns)
+    metadata: Optional[Dict[str, Any]] = None      # Diarization metadata
+    created_at: Optional[float] = None             # Unix timestamp
+
+
+class SpeakerDiarizationStorage:
+    """Standardized SQLite storage for speaker-diarization results."""
+
+    SCHEMA = """
+        CREATE TABLE IF NOT EXISTS speaker_diarization_results (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            file_path TEXT NOT NULL,
+            file_hash TEXT NOT NULL,
+            config_hash TEXT NOT NULL,
+            turns JSON,
+            metadata JSON,
+            created_at REAL NOT NULL,
+            UNIQUE(file_path, config_hash)
+        )
+    """
+
+    INDEX = "CREATE INDEX IF NOT EXISTS idx_speaker_diarization_file_path ON speaker_diarization_results(file_path);"
+
+    def __init__(
+        self,
+        db_path: str  # Absolute path to the SQLite database file
+    ):
+        """Initialize storage and create table if needed."""
+        self.db_path = db_path
+        with sqlite3.connect(self.db_path) as con:
+            con.execute(self.SCHEMA)
+            con.execute(self.INDEX)
+
+    def save(
+        self,
+        file_path: str,     # Path to the analyzed audio file
+        file_hash: str,     # Hash of the analyzed file in "algo:hexdigest" format
+        config_hash: str,   # Hash of the diarization config (tool config + hints)
+        turns: Optional[List[Dict[str, Any]]] = None,  # Diarized speech turns
+        metadata: Optional[Dict[str, Any]] = None       # Diarization metadata
+    ) -> None:
+        """Save or replace a diarization result (upsert by file_path + config_hash)."""
+        with sqlite3.connect(self.db_path) as con:
+            con.execute(
+                """INSERT OR REPLACE INTO speaker_diarization_results
+                   (file_path, file_hash, config_hash, turns, metadata, created_at)
+                   VALUES (?, ?, ?, ?, ?, ?)""",
+                (
+                    file_path,
+                    file_hash,
+                    config_hash,
+                    json.dumps(turns) if turns else None,
+                    json.dumps(metadata) if metadata else None,
+                    time.time()
+                )
+            )
+
+    def save_with_logging(
+        self,
+        *,
+        file_path: str,     # Path to the analyzed audio file
+        file_hash: str,     # Hash of the analyzed file in "algo:hexdigest" format
+        config_hash: str,   # Hash of the diarization config (tool config + hints)
+        turns: Optional[List[Dict[str, Any]]] = None,  # Diarized speech turns
+        metadata: Optional[Dict[str, Any]] = None,      # Diarization metadata
+        logger: Optional[logging.Logger] = None          # Optional logger for success/failure messages
+    ) -> bool:  # True if saved; False if the save failed (error logged, not raised)
+        """Save a result, logging success/failure. Failures are logged and swallowed (returns False).
+
+        CR-14 follow-up: records a RESULT_SAVED account either way (ok flag +
+        file/config references — the journal never carries content) so saves AND
+        swallowed save-failures become auditable journal rows."""
+        try:
+            self.save(
+                file_path=file_path,
+                file_hash=file_hash,
+                config_hash=config_hash,
+                turns=turns,
+                metadata=metadata,
+            )
+            record_account(SubstrateEventType.RESULT_SAVED.value, {
+                "ok": True, "file_path": file_path, "file_hash": file_hash,
+                "config_hash": config_hash,
+            })
+            if logger:
+                logger.info(f"Saved diarization result to DB ({file_path})")
+            return True
+        except Exception as e:
+            record_account(SubstrateEventType.RESULT_SAVED.value, {
+                "ok": False, "file_path": file_path, "file_hash": file_hash,
+                "config_hash": config_hash, "error": str(e),
+            })
+            if logger:
+                logger.error(f"Failed to save to DB: {e}")
+            return False
+
+    def get_cached(
+        self,
+        file_path: str,   # Path to the audio file
+        file_hash: str,   # Content hash of the file (cache miss if the file changed)
+        config_hash: str  # Config hash to match
+    ) -> Optional[SpeakerDiarizationRow]:  # Cached row or None
+        """Retrieve a content-correct cached diarization result.
+
+        Matches on file_path + file_hash + config_hash, so a changed file (new
+        file_hash) misses the cache even though a stale row may still exist at the
+        same (file_path, config_hash) — the next save() replaces it.
+
+        CR-14 follow-up: a hit records a CACHE_HIT account (the cache-serving
+        decision is an account-of-action)."""
+        with sqlite3.connect(self.db_path) as con:
+            cur = con.execute(
+                """SELECT file_path, file_hash, config_hash, turns, metadata, created_at
+                   FROM speaker_diarization_results
+                   WHERE file_path = ? AND file_hash = ? AND config_hash = ?""",
+                (file_path, file_hash, config_hash)
+            )
+            row = cur.fetchone()
+            if not row:
+                return None
+            record_account(SubstrateEventType.CACHE_HIT.value, {
+                "file_path": file_path, "file_hash": file_hash,
+                "config_hash": config_hash,
+            })
+            return SpeakerDiarizationRow(
+                file_path=row[0],
+                file_hash=row[1],
+                config_hash=row[2],
+                turns=json.loads(row[3]) if row[3] else None,
+                metadata=json.loads(row[4]) if row[4] else None,
+                created_at=row[5]
+            )
+
+    def list_jobs(
+        self,
+        limit: int = 100  # Maximum number of rows to return
+    ) -> List[SpeakerDiarizationRow]:  # List of diarization rows
+        """List diarization results ordered by creation time (newest first)."""
+        results = []
+        with sqlite3.connect(self.db_path) as con:
+            cur = con.execute(
+                """SELECT file_path, file_hash, config_hash, turns, metadata, created_at
+                   FROM speaker_diarization_results ORDER BY created_at DESC LIMIT ?""",
+                (limit,)
+            )
+            for row in cur:
+                results.append(SpeakerDiarizationRow(
+                    file_path=row[0],
+                    file_hash=row[1],
+                    config_hash=row[2],
+                    turns=json.loads(row[3]) if row[3] else None,
+                    metadata=json.loads(row[4]) if row[4] else None,
+                    created_at=row[5]
+                ))
+        return results
+
+    def verify_file(
+        self,
+        file_path: str,   # Path to the audio file
+        config_hash: str  # Config hash to look up
+    ) -> Optional[bool]:  # True if file matches, False if changed, None if not found
+        """Verify the analyzed file still matches the hash stored for (file_path, config_hash)."""
+        with sqlite3.connect(self.db_path) as con:
+            cur = con.execute(
+                """SELECT file_hash FROM speaker_diarization_results
+                   WHERE file_path = ? AND config_hash = ?""",
+                (file_path, config_hash)
+            )
+            row = cur.fetchone()
+        if not row:
+            return None
+        return hash_file(file_path) == row[0]

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface.egg-info/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: cjm-speaker-diarization-adapter-interface
+Version: 0.0.1
+Summary: Typed speaker-diarization task-adapter interface — SpeakerDiarizationAdapter ABC + GenericSpeakerDiarizationAdapter (thin pass-through around a diarization tool) and the SpeakerDiarizationToolProtocol. The SpeakerDiarizationResult data noun lives in cjm-capability-primitives; turns are ANONYMOUS clusters — identity is the correction TUI's assignment lane, never this interface's job.
+Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/cj-mills/cjm-speaker-diarization-adapter-interface
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cjm-substrate>=0.0.58
+Requires-Dist: cjm-capability-primitives>=0.0.12
+Dynamic: license-file
+
+# cjm-speaker-diarization-adapter-interface
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Adapter interface for speaker-diarization capabilities — the speaker_diarization task-channel contract (audio → typed SpeakerTurn/SpeakerDiarizationResult) that capability libs implement and workflow cores consume; the generic adapter owns the SQLite cache bookends (content-addressed, speaker-count hints fold into the config hash).
+
+## Modules
+
+- **`cjm_speaker_diarization_adapter_interface.__init__`**
+- **`cjm_speaker_diarization_adapter_interface.adapter`** — The typed speaker-diarization task contract — the `SpeakerDiarizationAdapter` ABC + the `SpeakerDiarizationToolProtocol` structural contract (capability-unit Option C; session-D DECs 18d7de80 + d6df3a8e).
+- **`cjm_speaker_diarization_adapter_interface.generic`** — The generic (tool-agnostic) speaker-diarization adapter — cache-check, invoke the bound tool's pure-compute `diarize`, persist. Reused across every tool capability satisfying `SpeakerDiarizationToolProtocol`, exactly as `GenericVADAdapter` is reused across VAD tools.
+- **`cjm_speaker_diarization_adapter_interface.storage`** — Standardized SQLite storage for speaker-diarization results with content hashing.
+
+## API
+
+### `cjm_speaker_diarization_adapter_interface.adapter`
+
+- `SpeakerDiarizationAdapter` _class_ — Typed speaker-diarization task adapter: source audio path in,
+- `SpeakerDiarizationToolProtocol` _class_ — Structural contract for speaker-diarization tool capabilities.
+
+### `cjm_speaker_diarization_adapter_interface.generic`
+
+- `GenericSpeakerDiarizationAdapter` _class_ — Generic speaker-diarization adapter: cache-check -> pure-compute tool -> persist.
+
+### `cjm_speaker_diarization_adapter_interface.storage`
+
+- `SpeakerDiarizationRow` _class_ — A single row from the speaker_diarization_results table.
+- `SpeakerDiarizationStorage` _class_ — Standardized SQLite storage for speaker-diarization results.
+
+## Dependencies
+
+**Depends on:** `cjm-capability-primitives`, `cjm-substrate`
+**Used by:** `cjm-capability-pyannote`

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+cjm_speaker_diarization_adapter_interface/__init__.py
+cjm_speaker_diarization_adapter_interface/adapter.py
+cjm_speaker_diarization_adapter_interface/generic.py
+cjm_speaker_diarization_adapter_interface/storage.py
+cjm_speaker_diarization_adapter_interface.egg-info/PKG-INFO
+cjm_speaker_diarization_adapter_interface.egg-info/SOURCES.txt
+cjm_speaker_diarization_adapter_interface.egg-info/dependency_links.txt
+cjm_speaker_diarization_adapter_interface.egg-info/requires.txt
+cjm_speaker_diarization_adapter_interface.egg-info/top_level.txt
+tests/test_adapter.py
+tests/test_storage.py

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface.egg-info/requires.txt

@@ -0,0 +1,2 @@
+cjm-substrate>=0.0.58
+cjm-capability-primitives>=0.0.12

cjm_speaker_diarization_adapter_interface-0.0.1/cjm_speaker_diarization_adapter_interface.egg-info/top_level.txt

@@ -0,0 +1 @@
+cjm_speaker_diarization_adapter_interface

cjm_speaker_diarization_adapter_interface-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cjm-speaker-diarization-adapter-interface"
+dynamic = ["version"]
+description = "Typed speaker-diarization task-adapter interface — SpeakerDiarizationAdapter ABC + GenericSpeakerDiarizationAdapter (thin pass-through around a diarization tool) and the SpeakerDiarizationToolProtocol. The SpeakerDiarizationResult data noun lives in cjm-capability-primitives; turns are ANONYMOUS clusters — identity is the correction TUI's assignment lane, never this interface's job."
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "Apache-2.0"}
+authors = [{name = "Christian J. Mills", email = "9126128+cj-mills@users.noreply.github.com"}]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = [
+    "cjm-substrate>=0.0.58",
+    "cjm-capability-primitives>=0.0.12",
+]
+
+[project.urls]
+Repository = "https://github.com/cj-mills/cjm-speaker-diarization-adapter-interface"
+
+[tool.setuptools.dynamic]
+version = {attr = "cjm_speaker_diarization_adapter_interface.__version__"}
+
+[tool.setuptools.packages.find]
+include = ["cjm_speaker_diarization_adapter_interface*"]

cjm_speaker_diarization_adapter_interface-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cjm_speaker_diarization_adapter_interface-0.0.1/tests/test_adapter.py

@@ -0,0 +1,87 @@
+"""Tests for the speaker-diarization adapter interface — protocol conformance + the generic pass-through."""
+from typing import Any, Dict
+
+from cjm_capability_primitives.speaker_diarization import (SpeakerDiarizationResult,
+                                                           SpeakerTurn)
+from cjm_speaker_diarization_adapter_interface.adapter import (
+    SpeakerDiarizationAdapter, SpeakerDiarizationToolProtocol)
+from cjm_speaker_diarization_adapter_interface.generic import (
+    GenericSpeakerDiarizationAdapter)
+
+
+class FakeDiarizerTool:
+    """Minimal tool satisfying the structural protocol: two fixed turns,
+    honoring a num_speakers=1 hint by merging them."""
+
+    def __init__(self):
+        self.calls = 0
+        self.last_kwargs: Dict[str, Any] = {}
+
+    def diarize(self, audio: str, **kwargs) -> SpeakerDiarizationResult:
+        self.calls += 1
+        self.last_kwargs = dict(kwargs)
+        if kwargs.get("num_speakers") == 1:
+            turns = [SpeakerTurn(start=0.2, end=3.9, speaker="SPEAKER_00")]
+        else:
+            turns = [SpeakerTurn(start=0.2, end=1.5, speaker="SPEAKER_00"),
+                     SpeakerTurn(start=1.8, end=3.9, speaker="SPEAKER_01")]
+        return SpeakerDiarizationResult(
+            turns=turns, metadata={"speaker_count": len({t.speaker for t in turns}),
+                                   "audio": audio})
+
+    def get_current_config(self) -> Dict[str, Any]:
+        return {"model_id": "fake-diarizer"}
+
+
+def test_fake_tool_satisfies_protocol():
+    assert isinstance(FakeDiarizerTool(), SpeakerDiarizationToolProtocol)
+
+
+def test_adapter_declares_task_contract():
+    assert SpeakerDiarizationAdapter.task_name == "speaker_diarization"
+    assert (SpeakerDiarizationAdapter.required_tool_protocol
+            is SpeakerDiarizationToolProtocol)
+
+
+def test_generic_adapter_passes_through_with_hints(tmp_path, monkeypatch):
+    monkeypatch.setenv("CAPABILITY_DATA_DIR", str(tmp_path))
+    audio = tmp_path / "source.wav"
+    audio.write_bytes(b"fake-pcm-bytes")
+    tool = FakeDiarizerTool()
+    adapter = GenericSpeakerDiarizationAdapter(tool)
+    result = adapter.diarize(str(audio))
+    assert tool.calls == 1
+    assert [t.speaker for t in result.turns] == ["SPEAKER_00", "SPEAKER_01"]
+    assert result.metadata["audio"] == str(audio)
+    # speaker-count hints ride kwargs untouched — and fold into the cache
+    # key, so the hinted call is a MISS, not a replay of the unhinted row
+    hinted = adapter.diarize(str(audio), num_speakers=1)
+    assert tool.calls == 2
+    assert tool.last_kwargs == {"num_speakers": 1}
+    assert len(hinted.turns) == 1 and hinted.metadata["speaker_count"] == 1
+
+
+def test_generic_adapter_cache_bookends(tmp_path, monkeypatch):
+    monkeypatch.setenv("CAPABILITY_DATA_DIR", str(tmp_path))
+    audio = tmp_path / "source.wav"
+    audio.write_bytes(b"fake-pcm-bytes")
+    tool = FakeDiarizerTool()
+    adapter = GenericSpeakerDiarizationAdapter(tool)
+    first = adapter.diarize(str(audio))
+    assert tool.calls == 1
+    # same audio + same config -> served from cache, tool NOT re-invoked;
+    # turns come back typed
+    replay = adapter.diarize(str(audio))
+    assert tool.calls == 1
+    assert isinstance(replay.turns[0], SpeakerTurn)
+    assert ([(t.start, t.end, t.speaker) for t in replay.turns]
+            == [(t.start, t.end, t.speaker) for t in first.turns])
+    # a hinted call is a DIFFERENT cache row; replaying the same hint hits it
+    adapter.diarize(str(audio), num_speakers=1)
+    assert tool.calls == 2
+    adapter.diarize(str(audio), num_speakers=1)
+    assert tool.calls == 2
+    # content change at the same path -> new file_hash -> miss
+    audio.write_bytes(b"different-pcm-bytes")
+    adapter.diarize(str(audio))
+    assert tool.calls == 3

cjm_speaker_diarization_adapter_interface-0.0.1/tests/test_storage.py

@@ -0,0 +1,71 @@
+"""Tests for the speaker-diarization storage layer — content-correct cache semantics on the VAD-adapter precedent."""
+
+from cjm_substrate.utils.hashing import hash_file
+from cjm_speaker_diarization_adapter_interface.storage import (
+    SpeakerDiarizationRow, SpeakerDiarizationStorage)
+
+
+def _seeded_storage(tmp_path):
+    """Storage with one saved result for a real (tiny) audio file."""
+    storage = SpeakerDiarizationStorage(str(tmp_path / "speaker_diarization.db"))
+    audio = tmp_path / "a.wav"
+    audio.write_bytes(b"pcm-one")
+    turns = [{"start": 0.2, "end": 1.5, "speaker": "SPEAKER_00", "confidence": None},
+             {"start": 1.8, "end": 3.9, "speaker": "SPEAKER_01", "confidence": 0.9}]
+    storage.save(file_path=str(audio), file_hash="sha256:aaa", config_hash="cfg1",
+                 turns=turns, metadata={"speaker_count": 2})
+    return storage, str(audio), turns
+
+
+def test_save_get_cached_and_content_correctness(tmp_path):
+    storage, audio, turns = _seeded_storage(tmp_path)
+    row = storage.get_cached(audio, "sha256:aaa", "cfg1")
+    assert isinstance(row, SpeakerDiarizationRow)
+    assert row.turns == turns
+    assert row.metadata == {"speaker_count": 2}
+    assert row.created_at is not None
+    # changed content (new file_hash) misses even though a row exists at
+    # the same (file_path, config_hash)
+    assert storage.get_cached(audio, "sha256:bbb", "cfg1") is None
+    # unknown config misses
+    assert storage.get_cached(audio, "sha256:aaa", "cfg2") is None
+
+
+def test_insert_or_replace_on_cache_key(tmp_path):
+    storage, audio, _ = _seeded_storage(tmp_path)
+    storage.save(file_path=audio, file_hash="sha256:bbb", config_hash="cfg1",
+                 turns=[{"start": 0.0, "end": 9.9, "speaker": "SPEAKER_00",
+                         "confidence": None}])
+    # upsert replaced the (file_path, cfg1) row — no duplicate
+    assert len(storage.list_jobs()) == 1
+    assert storage.get_cached(audio, "sha256:aaa", "cfg1") is None
+    row = storage.get_cached(audio, "sha256:bbb", "cfg1")
+    assert row.turns[0]["end"] == 9.9
+    assert row.metadata is None
+
+
+def test_save_with_logging_success_and_swallowed_failure(tmp_path):
+    storage, audio, turns = _seeded_storage(tmp_path)
+    assert storage.save_with_logging(file_path=audio, file_hash="sha256:aaa",
+                                     config_hash="cfg2", turns=turns) is True
+
+    def _boom(*args, **kwargs):
+        raise RuntimeError("disk full")
+
+    storage.save = _boom  # instance attribute shadows the method
+    assert storage.save_with_logging(file_path=audio, file_hash="x",
+                                     config_hash="cfg3") is False
+
+
+def test_list_jobs_and_verify_file(tmp_path):
+    storage, audio, _ = _seeded_storage(tmp_path)
+    storage.save(file_path=audio, file_hash="h", config_hash="cfg2")
+    rows = storage.list_jobs()
+    assert len(rows) == 2
+    assert rows[0].created_at >= rows[1].created_at  # newest first
+    # verify_file compares the stored hash against the file's REAL hash
+    storage.save(file_path=audio, file_hash=hash_file(audio),
+                 config_hash="cfg-real")
+    assert storage.verify_file(audio, "cfg-real") is True
+    assert storage.verify_file(audio, "cfg1") is False  # seeded fake hash
+    assert storage.verify_file(audio, "nope") is None