clapback-client 0.1.0__tar.gz

clapback_client-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+.eggs/
+*.egg-info/
+*.egg
+
+# uv — `ADR-0005` point 7. The workspace has exactly one lock, at the root, and it
+# is committed. A lock never ships in a wheel: what `clapback-embed`'s dependents
+# resolve comes from its `dependencies` ranges, so committing this cannot pin them.
+# What it does pin is development, CI and the deployed image, which previously
+# resolved fresh on every Docker build.
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Docker
+data/
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Package venvs and exported model artifacts (614 MB, produced by scripts/export_models.py)
+packages/*/.venv/
+*.onnx
+*.onnx.data

clapback_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Crouse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clapback_client-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: clapback-client
+Version: 0.1.0
+Summary: Contribute to and look up the clapback commons — the contract a tool follows, with no dependency beyond the standard library
+Project-URL: Homepage, https://clapback.seethroughlab.com
+Project-URL: Repository, https://github.com/seethroughlab/clapback
+Project-URL: Decisions, https://github.com/seethroughlab/clapback/tree/main/docs/decisions
+Author-email: Jeff Crouse <jeff@seethroughlab.com>
+License: MIT License
+        
+        Copyright (c) 2026 Jeff Crouse
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: acoustid,audio,clap,commons,embeddings,music
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clapback-client
+
+The contract a tool follows to take part in the [clapback](https://clapback.seethroughlab.com)
+commons — look up before you contribute, send what the records require, back off when told to —
+with no dependency beyond the standard library.
+
+```bash
+pip install clapback-client
+```
+
+```python
+from clapback_client import Corpus, fingerprint_file, hash_fingerprint
+
+key = hash_fingerprint(fingerprint_file("track.flac"))
+corpus = Corpus()
+
+row = corpus.lookup(key, pipeline_version)
+if row is not None:
+    vector = row["embedding"]          # the commons already had it — skip the model
+else:
+    vector = my_embedder(path)         # your pipeline, declared by `pipeline_version`
+    corpus.contribute(
+        fingerprint_hash=key,
+        embedding=vector,
+        pipeline_version=pipeline_version,
+        client_id=client_id,
+    )
+```
+
+## What a tool has to do
+
+Four things. Each is decided in one of the project's
+[records](https://github.com/seethroughlab/clapback/tree/main/docs/decisions), and this package
+is those decisions as code so a tool does not have to reimplement them.
+
+1. **Fingerprint the audio and hash it canonically.** `hash_fingerprint` is SHA256 of the
+   AcoustID fingerprint exactly as chromaprint returns it — not as your database happened to
+   store it. That distinction split a corpus once; `canonical()` is the guard.
+2. **Produce the vector through a declared pipeline.** This package never embeds. The reference
+   pipeline is [`clapback-embed`](https://pypi.org/project/clapback-embed/), whose
+   `PIPELINE_VERSION` is the identity to send. A tool with its own pipeline declares its own
+   identity, and its vectors are comparable with each other rather than with the reference's.
+3. **Look up before contributing.** `Corpus.has` or `Corpus.lookup`. A repeat submission is
+   recorded as *agreement*, so a tool that re-sent its library would manufacture evidence of one
+   install agreeing with itself — the one measurement the commons exists to make honestly.
+4. **Send `client_id` and `pipeline_version`.** Both are required by `Corpus.contribute` and have
+   no defaults. `client_id` is a random UUID minted once per install — `identity.mint_client_id`
+   — on the first contribution, never on install, and stored where the user can find and delete
+   it.
+
+## What you get back
+
+- **Skip the recompute.** `lookup` returns the stored vector for a recording the commons already
+  holds under your pipeline.
+- **Similarity across libraries you do not own** — `/v1/similar`, once the corpus's recording-id
+  key lands.
+- **Confirmation** — whether your vector for a recording agrees with others' independently
+  computed one.
+
+The commons is worth exactly its coverage of the library asking. Early on, expect misses.
+
+## Fingerprinting needs chromaprint, and only fingerprinting does
+
+```bash
+brew install chromaprint     # or: apt install libchromaprint-tools
+pip install pyacoustid
+```
+
+`fingerprint_file` runs it out of process, because chromaprint is a C library that crashes rather
+than raises on some malformed inputs and one bad file must not end a run. If your tool already has
+fingerprints — beets' `chroma` plugin stores them, Picard computes them natively — hand them to
+`hash_fingerprint` directly and skip this.
+
+## Opt-in, off by default
+
+Nothing in this package sends anything until you call `contribute`. A tool that embeds this should
+keep contribution a separate, explicit setting from lookup, and should tell the user what leaves
+the machine — a 512-float vector and a one-way hash, never audio, filenames, or metadata — before
+the first time it does.

clapback_client-0.1.0/README.md

@@ -0,0 +1,79 @@
+# clapback-client
+
+The contract a tool follows to take part in the [clapback](https://clapback.seethroughlab.com)
+commons — look up before you contribute, send what the records require, back off when told to —
+with no dependency beyond the standard library.
+
+```bash
+pip install clapback-client
+```
+
+```python
+from clapback_client import Corpus, fingerprint_file, hash_fingerprint
+
+key = hash_fingerprint(fingerprint_file("track.flac"))
+corpus = Corpus()
+
+row = corpus.lookup(key, pipeline_version)
+if row is not None:
+    vector = row["embedding"]          # the commons already had it — skip the model
+else:
+    vector = my_embedder(path)         # your pipeline, declared by `pipeline_version`
+    corpus.contribute(
+        fingerprint_hash=key,
+        embedding=vector,
+        pipeline_version=pipeline_version,
+        client_id=client_id,
+    )
+```
+
+## What a tool has to do
+
+Four things. Each is decided in one of the project's
+[records](https://github.com/seethroughlab/clapback/tree/main/docs/decisions), and this package
+is those decisions as code so a tool does not have to reimplement them.
+
+1. **Fingerprint the audio and hash it canonically.** `hash_fingerprint` is SHA256 of the
+   AcoustID fingerprint exactly as chromaprint returns it — not as your database happened to
+   store it. That distinction split a corpus once; `canonical()` is the guard.
+2. **Produce the vector through a declared pipeline.** This package never embeds. The reference
+   pipeline is [`clapback-embed`](https://pypi.org/project/clapback-embed/), whose
+   `PIPELINE_VERSION` is the identity to send. A tool with its own pipeline declares its own
+   identity, and its vectors are comparable with each other rather than with the reference's.
+3. **Look up before contributing.** `Corpus.has` or `Corpus.lookup`. A repeat submission is
+   recorded as *agreement*, so a tool that re-sent its library would manufacture evidence of one
+   install agreeing with itself — the one measurement the commons exists to make honestly.
+4. **Send `client_id` and `pipeline_version`.** Both are required by `Corpus.contribute` and have
+   no defaults. `client_id` is a random UUID minted once per install — `identity.mint_client_id`
+   — on the first contribution, never on install, and stored where the user can find and delete
+   it.
+
+## What you get back
+
+- **Skip the recompute.** `lookup` returns the stored vector for a recording the commons already
+  holds under your pipeline.
+- **Similarity across libraries you do not own** — `/v1/similar`, once the corpus's recording-id
+  key lands.
+- **Confirmation** — whether your vector for a recording agrees with others' independently
+  computed one.
+
+The commons is worth exactly its coverage of the library asking. Early on, expect misses.
+
+## Fingerprinting needs chromaprint, and only fingerprinting does
+
+```bash
+brew install chromaprint     # or: apt install libchromaprint-tools
+pip install pyacoustid
+```
+
+`fingerprint_file` runs it out of process, because chromaprint is a C library that crashes rather
+than raises on some malformed inputs and one bad file must not end a run. If your tool already has
+fingerprints — beets' `chroma` plugin stores them, Picard computes them natively — hand them to
+`hash_fingerprint` directly and skip this.
+
+## Opt-in, off by default
+
+Nothing in this package sends anything until you call `contribute`. A tool that embeds this should
+keep contribution a separate, explicit setting from lookup, and should tell the user what leaves
+the machine — a 512-float vector and a one-way hash, never audio, filenames, or metadata — before
+the first time it does.

clapback_client-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "clapback-client"
+version = "0.1.0"
+description = "Contribute to and look up the clapback commons — the contract a tool follows, with no dependency beyond the standard library"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "Jeff Crouse", email = "jeff@seethroughlab.com" }]
+keywords = ["clap", "audio", "embeddings", "music", "acoustid", "commons"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+]
+
+# `ADR-0011` point 2: nothing beyond the standard library. A tool that already has
+# an embedder and only wants to contribute under its own pipeline identity must not
+# have to install ONNX Runtime to do so. Fingerprinting shells out to pyacoustid in a
+# subprocess and is optional at import time — see `fingerprint.py`.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4.0", "ruff>=0.1.0"]
+
+[project.urls]
+Homepage = "https://clapback.seethroughlab.com"
+Repository = "https://github.com/seethroughlab/clapback"
+Decisions = "https://github.com/seethroughlab/clapback/tree/main/docs/decisions"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clapback_client"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

clapback_client-0.1.0/src/clapback_client/__init__.py

@@ -0,0 +1,46 @@
+"""`clapback-client` — the contract a tool follows to take part in the commons.
+
+`ADR-0011` point 2. A tool that contributes has four obligations, each decided in
+an earlier record, and this package is those obligations as code:
+
+1. Fingerprint the audio and hash it canonically — `hash_fingerprint`,
+   `fingerprint_file`. `ADR-0010`.
+2. Produce the vector through a declared pipeline — the caller's job; this
+   package never embeds. `clapback-embed` is the reference pipeline, and a tool
+   with its own declares its own identity.
+3. Look up before contributing — `Corpus.has`, `Corpus.lookup`. `ADR-0008`.
+4. Send `client_id` and `pipeline_version` — `Corpus.contribute`, `identity`.
+   `ADR-0004`, `ADR-0006`.
+
+Nothing beyond the standard library, on purpose: a tool that has an embedder and
+only wants to contribute must not have to install ONNX Runtime to do so.
+
+    from clapback_client import Corpus, fingerprint_file, hash_fingerprint
+
+    key = hash_fingerprint(fingerprint_file(path))
+    corpus = Corpus()
+    row = corpus.lookup(key, pipeline_version)
+    if row is None:
+        corpus.contribute(
+            fingerprint_hash=key,
+            embedding=vector,
+            pipeline_version=pipeline_version,
+            client_id=client_id,
+        )
+"""
+
+from .corpus import DEFAULT_BASE_URL, Corpus, CorpusError
+from .fingerprint import FingerprintUnavailable, canonical, fingerprint_file, hash_fingerprint
+from .identity import ensure_client_id, mint_client_id
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Corpus",
+    "CorpusError",
+    "FingerprintUnavailable",
+    "canonical",
+    "ensure_client_id",
+    "fingerprint_file",
+    "hash_fingerprint",
+    "mint_client_id",
+]

clapback_client-0.1.0/src/clapback_client/corpus.py

@@ -0,0 +1,163 @@
+"""Talking to the commons over HTTP, and only over HTTP.
+
+This is the client half of the contract `ADR-0011` publishes: look up before you
+contribute, send what the records require, and back off when told to. A tool that
+imports this and `fingerprint.py` has everything it needs to be a contributor,
+and nothing it does not.
+
+`ADR-0005` point 12: the API is the only way in. Every guarantee the corpus makes
+— revocation, quotas, the row ceiling, agreement recording — is code on the write
+path, so a client that reached the database directly would be a second write path
+with none of them.
+
+`urllib` rather than `httpx` or `requests` on purpose. This package's argument is
+that it is small enough to install next to anything; two calls against a JSON API
+do not justify a dependency, and the one place that matters — retrying a 429 — is
+a loop either way.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+
+DEFAULT_BASE_URL = "https://clapback.seethroughlab.com"
+
+#: The server rate-limits contributions. Backing off politely is the difference
+#: between a slow client and a client the operator has to block, and a long run
+#: will meet this: Familiar's backfill of 26,431 tracks took roughly 80 minutes
+#: of paced lookups.
+_RETRY_DELAYS = (2.0, 5.0, 15.0)
+
+
+class CorpusError(RuntimeError):
+    """The corpus could not be reached, or refused something it should not have."""
+
+
+class Corpus:
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> tuple[int, dict | None]:
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(
+            f"{self.base_url}{path}",
+            data=data,
+            method=method,
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                # Say who is calling. Not identity — `ADR-0004` point 1 keeps that
+                # to `client_id` in the body — but an operator reading logs should
+                # be able to tell this tool from a browser.
+                "User-Agent": "clapback-client",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read()
+                return resp.status, (json.loads(raw) if raw else None)
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            try:
+                payload = json.loads(raw) if raw else None
+            except json.JSONDecodeError:
+                payload = None
+            return exc.code, payload
+        except urllib.error.URLError as exc:
+            raise CorpusError(f"{self.base_url} is unreachable: {exc.reason}") from exc
+        except TimeoutError as exc:
+            raise CorpusError(f"{self.base_url} timed out after {self.timeout}s") from exc
+
+    def health(self) -> bool:
+        status, _ = self._request("GET", "/health")
+        return status == 200
+
+    def lookup(self, fingerprint_hash: str, pipeline_version: str) -> dict | None:
+        """The corpus's row for this recording from this pipeline, or None.
+
+        The row carries `embedding` (512 floats), `contributor_count`, and the
+        pipeline it was produced by. A tool that gets a row back here does not
+        need to run the model: that is the whole exchange a plug-in makes, and
+        on a Raspberry Pi it is minutes per track.
+
+        Only a row from the *same* pipeline is returned. Two vectors are comparable
+        exactly when their pipeline identities match (`ADR-0006`), so a vector from
+        another pipeline would be a wrong answer wearing the right shape.
+        """
+        # The pipeline identity is `+`-joined, and `+` means a space in a query
+        # string. `ADR-0006`'s Implementation block records what an unescaped one
+        # costs: a 404 that looks exactly like the recording being absent.
+        from urllib.parse import quote
+
+        status, payload = self._request(
+            "GET",
+            f"/v1/embeddings/{fingerprint_hash}?pipeline_version={quote(pipeline_version, safe='')}",
+        )
+        if status == 200:
+            return payload
+        if status == 404:
+            return None
+        raise CorpusError(f"lookup returned {status}")
+
+    def has(self, fingerprint_hash: str, pipeline_version: str) -> bool:
+        """Whether the corpus already holds this recording from this pipeline.
+
+        **Asked before every contribution, and that is not an optimisation.** A
+        repeat POST of a vector that is already there increments
+        `contributor_count` and records a `submission_agreement` row, so a client
+        that re-sent its library would manufacture evidence of one installation
+        independently agreeing with itself — which is precisely the measurement
+        `ADR-0008` is built on. Two clients have learned this now; it is why the
+        contract publishes the check rather than trusting each tool to write it.
+        """
+        return self.lookup(fingerprint_hash, pipeline_version) is not None
+
+    def contribute(
+        self,
+        *,
+        fingerprint_hash: str,
+        embedding: list[float],
+        pipeline_version: str,
+        client_id: str,
+        clap_model_version: str | None = None,
+        analysis_version: int = 1,
+    ) -> str:
+        """POST one embedding. Returns a short word describing what happened.
+
+        `pipeline_version` and `client_id` are what the records require of a
+        contribution (`ADR-0006` point 4, `ADR-0004` point 1) and have no
+        defaults. The other two are recorded columns the key no longer includes:
+        `clap_model_version` defaults to the first component of the pipeline
+        identity, which is the checkpoint, so the two cannot disagree about one
+        fact; `analysis_version` is the caller's own counter and starts at 1.
+        """
+        body = {
+            "fingerprint_hash": fingerprint_hash,
+            "embedding": embedding,
+            "pipeline_version": pipeline_version,
+            "clap_model_version": clap_model_version or pipeline_version.split("+")[0],
+            "analysis_version": analysis_version,
+            "client_id": client_id,
+        }
+        for attempt, delay in enumerate((*_RETRY_DELAYS, None)):
+            status, payload = self._request("POST", "/v1/embeddings", body)
+            if status in (200, 201):
+                return "contributed"
+            if status == 429:
+                if delay is None:
+                    break
+                time.sleep(delay)
+                continue
+            if status == 422:
+                detail = (payload or {}).get("detail")
+                raise CorpusError(f"the corpus refused the submission as malformed: {detail}")
+            if status == 507 or (status == 403 and "ceiling" in str(payload).lower()):
+                # `ADR-0004` point 9's row ceiling. A refusal here is the corpus
+                # working, not failing — stop rather than hammering it.
+                raise CorpusError("the corpus is full and is refusing writes (ADR-0004 point 9)")
+            raise CorpusError(f"contribute returned {status}: {payload}")
+        raise CorpusError("rate limited repeatedly; try again later")

clapback_client-0.1.0/src/clapback_client/fingerprint.py

@@ -0,0 +1,127 @@
+"""The corpus key's other half: `ADR-0010`.
+
+`fingerprint_hash` is SHA256 of the AcoustID fingerprint **as chromaprint returned
+it** — the base64 ASCII string — and of nothing else. The rule exists because it
+was broken: Familiar hashed whatever its column happened to hold, and that column
+held the same fingerprint in two encodings (14,284 hex-escaped against 11,364
+raw, measured 2026-09-10), both of which are live keys in the corpus today.
+
+So the rule is "hash what you computed, not what you stored", and this module is
+where this tool computes it. Nothing here reads a database, which is the point:
+the value goes from chromaprint into `sha256` without passing through storage, so
+there is no encoding for storage to apply.
+
+`canonical()` exists anyway, for the case where a fingerprint *has* been through
+something. It is the one place that knows what a re-encoding looks like.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+import subprocess
+import sys
+
+
+class FingerprintUnavailable(RuntimeError):
+    """chromaprint is missing or refused the file.
+
+    `ADR-0009` point 5: the local half of this tool — index, search, duplicates —
+    works without chromaprint and must never be made to depend on it. Only talking
+    to the corpus needs a fingerprint, so this is raised there and nowhere else.
+    """
+
+
+def canonical(fingerprint: str | bytes) -> bytes:
+    """The bytes to hash, whatever shape the fingerprint arrives in.
+
+    A fingerprint from chromaprint is already canonical and passes through. The
+    one transformation undone here is Postgres's hex output format — a `text`
+    column that once held `bytea` renders as `\\x` followed by hex, and hashing
+    that string keys the row to a fact about somebody's schema history rather
+    than about the recording. `ADR-0010` point 2.
+
+    The check is deliberately narrow. `\\x` plus an even number of hex digits
+    that decode to printable ASCII is not something a chromaprint fingerprint can
+    be — its alphabet is base64 and it never begins with a backslash — so this
+    cannot misfire on a real fingerprint, and anything it does not recognise is
+    left alone rather than guessed at.
+    """
+    if isinstance(fingerprint, bytes):
+        raw = fingerprint
+    else:
+        raw = fingerprint.encode()
+
+    if raw.startswith(b"\\x") and len(raw) % 2 == 0:
+        body = raw[2:]
+        try:
+            decoded = bytes.fromhex(body.decode("ascii"))
+        except (ValueError, UnicodeDecodeError):
+            return raw
+        # Only accept the decode if it produced something that looks like a
+        # fingerprint rather than arbitrary bytes that happened to be valid hex.
+        if decoded and all(32 <= b < 127 for b in decoded):
+            return decoded
+    return raw
+
+
+def hash_fingerprint(fingerprint: str | bytes) -> str:
+    """SHA256 of the canonical fingerprint, hex-digested — the corpus key.
+
+    One-way on purpose: contributing says "I have this recording" without saying
+    which recording it is, which is what lets somebody contribute from a library
+    they would rather not publish. It is also why no server-side migration could
+    ever repair a bad key — the corpus never learns the fingerprint, so only a
+    client holding it can compute a different hash for the same recording.
+    """
+    return hashlib.sha256(canonical(fingerprint)).hexdigest()
+
+
+def fingerprint_file(path: str) -> str:
+    """The AcoustID fingerprint of one file, exactly as chromaprint gives it.
+
+    Run out of process for the reason `ADR-0009` point 5 gives: chromaprint is a
+    C library that crashes rather than raises on some malformed inputs, and a
+    segfault in a library of 20,000 files must cost one file rather than the run.
+    A crashed child is a non-zero exit code here.
+    """
+    if shutil.which("fpcalc") is None:
+        try:
+            import acoustid  # noqa: F401
+        except ImportError as exc:
+            raise FingerprintUnavailable(
+                "chromaprint is not installed, so this tool cannot talk to the corpus. "
+                "Install it (`brew install chromaprint`, `apt install libchromaprint-tools`) "
+                "and `pip install pyacoustid`. Indexing, search and duplicates do not need it."
+            ) from exc
+
+    try:
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-c",
+                (
+                    "import acoustid, json, sys; "
+                    "d, f = acoustid.fingerprint_file(sys.argv[1]); "
+                    "print(json.dumps(f.decode() if isinstance(f, bytes) else f))"
+                ),
+                path,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise FingerprintUnavailable(f"fingerprinting timed out: {path}") from exc
+
+    if result.returncode != 0 or not result.stdout.strip():
+        detail = (result.stderr or "").strip().splitlines()
+        raise FingerprintUnavailable(detail[-1] if detail else f"exit {result.returncode}")
+
+    import json
+
+    value = json.loads(result.stdout.strip())
+    if not isinstance(value, str) or not value:
+        raise FingerprintUnavailable(f"chromaprint returned nothing usable for {path}")
+    return value

clapback_client-0.1.0/src/clapback_client/identity.py

@@ -0,0 +1,48 @@
+"""The identifier a contribution carries — `ADR-0004` point 1.
+
+An opaque per-install UUID, minted once and never derived from anything about the
+machine or its owner. It exists so the corpus can tell two contributions apart
+from one client retrying, which is the distinction `contributor_count` cannot make
+on its own. It is not an identity: there is no registration, no lookup, and the
+server never needs to know more.
+
+Two rules the caller has to keep, because this module cannot keep them for it:
+
+**Mint it on first contribution, not on install.** `ADR-0009` point 4 — nothing
+leaves the machine by default — covers the fact that an install exists. A tool
+whose user only ever searched their own files has no reason to carry one, and a
+dry run should not create one.
+
+**Store it somewhere the user can find and delete.** Deleting it makes the user a
+new contributor and changes nothing else. A tool that hides it has broken the one
+promise the identifier makes.
+"""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+
+def mint_client_id() -> str:
+    """A fresh identifier. Call it once per install, and only when contributing."""
+    return str(uuid.uuid4())
+
+
+def ensure_client_id(path: str | Path) -> str:
+    """The identifier stored at `path`, minting and writing one if there is none.
+
+    For tools with no better place to keep it. A tool that already has a settings
+    store — Familiar's `settings.json`, beets' config, the CLI's `index.json` —
+    should keep it there and call `mint_client_id` itself, so the user has one
+    place to look rather than two.
+    """
+    p = Path(path)
+    if p.exists():
+        existing = p.read_text().strip()
+        if existing:
+            return existing
+    fresh = mint_client_id()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(fresh + "\n")
+    return fresh

clapback_client-0.1.0/tests/test_corpus.py

@@ -0,0 +1,197 @@
+"""What goes over the wire, and what the client does when the corpus pushes back.
+
+No network. `urllib.request.urlopen` is replaced with a fake that records every
+request and answers from a script, so each test states exactly which HTTP
+exchange it is about. The properties here are the ones a plug-in author would
+otherwise have to rediscover: the query-string escaping that turns a `+` into a
+miss, the lookup that must precede every write, the defaults derived from the
+pipeline identity, and the backoff that keeps a tool from being the client an
+operator has to block.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import urllib.error
+import urllib.request
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+
+from clapback_client import corpus as corpus_mod
+from clapback_client.corpus import Corpus, CorpusError
+
+PIPELINE = "laion/clap-htsat-unfused+frontend1+artifact1+pool1+fp32"
+HASH = "d1" * 32
+VECTOR = [0.0] * 511 + [1.0]
+
+
+class FakeResponse(io.BytesIO):
+    def __init__(self, status: int, body: dict | None):
+        super().__init__(json.dumps(body).encode() if body is not None else b"")
+        self.status = status
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self.close()
+
+
+@pytest.fixture
+def wire(monkeypatch):
+    """A scripted server. Append (status, body) answers; read `.requests` back."""
+    log = []
+    answers = []
+
+    def fake_urlopen(req, timeout=None):
+        log.append(req)
+        status, body = answers.pop(0)
+        if status >= 400:
+            raise urllib.error.HTTPError(
+                req.full_url, status, "err", {}, io.BytesIO(json.dumps(body or {}).encode())
+            )
+        return FakeResponse(status, body)
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+    monkeypatch.setattr(corpus_mod.time, "sleep", lambda s: log.append(("slept", s)))
+
+    class Wire:
+        requests = log
+
+        @staticmethod
+        def answer(status, body=None):
+            answers.append((status, body))
+
+    return Wire
+
+
+class TestTheLookup:
+    def test_the_pipeline_identity_is_escaped(self, wire):
+        """`+` means a space in a query string, so an unescaped identity 404s as
+        though the recording were absent. `ADR-0006` records what that cost."""
+        wire.answer(404)
+        Corpus("https://x.invalid").lookup(HASH, PIPELINE)
+        url = wire.requests[0].full_url
+        assert "+" not in urlsplit(url).query
+        assert parse_qs(urlsplit(url).query)["pipeline_version"] == [PIPELINE]
+
+    def test_a_row_comes_back_whole(self, wire):
+        row = {"fingerprint_hash": HASH, "embedding": VECTOR, "contributor_count": 2}
+        wire.answer(200, row)
+        assert Corpus("https://x.invalid").lookup(HASH, PIPELINE) == row
+
+    def test_absent_is_none_and_has_is_false(self, wire):
+        wire.answer(404)
+        wire.answer(404)
+        c = Corpus("https://x.invalid")
+        assert c.lookup(HASH, PIPELINE) is None
+        assert c.has(HASH, PIPELINE) is False
+
+    def test_anything_else_is_an_error_not_a_miss(self, wire):
+        """A 500 that read as 'absent' would contribute a duplicate on the retry.
+        Familiar's backfill made exactly this distinction for the same reason."""
+        wire.answer(500)
+        with pytest.raises(CorpusError):
+            Corpus("https://x.invalid").lookup(HASH, PIPELINE)
+
+
+class TestTheContribution:
+    def _sent(self, wire):
+        return json.loads(wire.requests[-1].data)
+
+    def test_it_sends_what_the_records_require(self, wire):
+        """`ADR-0006` point 4 and `ADR-0004` point 1: no defaults for these two."""
+        wire.answer(201, {"status": "created"})
+        Corpus("https://x.invalid").contribute(
+            fingerprint_hash=HASH, embedding=VECTOR, pipeline_version=PIPELINE, client_id="c-1"
+        )
+        body = self._sent(wire)
+        assert body["pipeline_version"] == PIPELINE
+        assert body["client_id"] == "c-1"
+        assert body["fingerprint_hash"] == HASH
+        assert len(body["embedding"]) == 512
+
+    def test_the_checkpoint_is_derived_from_the_identity(self, wire):
+        """Taken from the identity rather than written twice, so the two cannot
+        disagree about one fact."""
+        wire.answer(201, {})
+        Corpus("https://x.invalid").contribute(
+            fingerprint_hash=HASH, embedding=VECTOR, pipeline_version=PIPELINE, client_id="c"
+        )
+        assert self._sent(wire)["clap_model_version"] == "laion/clap-htsat-unfused"
+        assert self._sent(wire)["analysis_version"] == 1
+
+    def test_a_caller_may_override_the_recorded_columns(self, wire):
+        wire.answer(201, {})
+        Corpus("https://x.invalid").contribute(
+            fingerprint_hash=HASH,
+            embedding=VECTOR,
+            pipeline_version=PIPELINE,
+            client_id="c",
+            clap_model_version="laion/clap-htsat-unfused:v1",
+            analysis_version=8,
+        )
+        assert self._sent(wire)["clap_model_version"] == "laion/clap-htsat-unfused:v1"
+        assert self._sent(wire)["analysis_version"] == 8
+
+    def test_it_names_itself(self, wire):
+        """Not identity — that is `client_id` — but an operator reading logs
+        should be able to tell this from a browser."""
+        wire.answer(201, {})
+        Corpus("https://x.invalid").contribute(
+            fingerprint_hash=HASH, embedding=VECTOR, pipeline_version=PIPELINE, client_id="c"
+        )
+        assert wire.requests[-1].get_header("User-agent") == "clapback-client"
+
+
+class TestWhenTheCorpusPushesBack:
+    def test_a_rate_limit_is_waited_out_then_retried(self, wire):
+        wire.answer(429)
+        wire.answer(429)
+        wire.answer(201, {})
+        result = Corpus("https://x.invalid").contribute(
+            fingerprint_hash=HASH, embedding=VECTOR, pipeline_version=PIPELINE, client_id="c"
+        )
+        assert result == "contributed"
+        posts = [r for r in wire.requests if not isinstance(r, tuple)]
+        sleeps = [r for r in wire.requests if isinstance(r, tuple)]
+        assert len(posts) == 3
+        assert [s for _, s in sleeps] == list(corpus_mod._RETRY_DELAYS[:2])
+
+    def test_a_persistent_rate_limit_gives_up_cleanly(self, wire):
+        for _ in range(len(corpus_mod._RETRY_DELAYS) + 1):
+            wire.answer(429)
+        with pytest.raises(CorpusError, match="rate limited"):
+            Corpus("https://x.invalid").contribute(
+                fingerprint_hash=HASH, embedding=VECTOR, pipeline_version=PIPELINE, client_id="c"
+            )
+
+    def test_a_malformed_submission_is_reported_not_retried(self, wire):
+        """A 422 is the server saying what was wrong. Retrying it is noise."""
+        wire.answer(422, {"detail": "pipeline_version: field required"})
+        with pytest.raises(CorpusError, match="malformed"):
+            Corpus("https://x.invalid").contribute(
+                fingerprint_hash=HASH, embedding=VECTOR, pipeline_version=PIPELINE, client_id="c"
+            )
+        assert len([r for r in wire.requests if not isinstance(r, tuple)]) == 1
+
+    def test_a_full_corpus_is_the_corpus_working(self, wire):
+        """`ADR-0004` point 9's ceiling. Stop rather than hammer it."""
+        wire.answer(507, {"detail": "ceiling"})
+        with pytest.raises(CorpusError, match="full"):
+            Corpus("https://x.invalid").contribute(
+                fingerprint_hash=HASH, embedding=VECTOR, pipeline_version=PIPELINE, client_id="c"
+            )
+
+
+class TestTheContractIsOnlyHTTP:
+    def test_nothing_here_opens_a_database(self):
+        """`ADR-0005` point 12: a direct connection is a second write path with
+        none of the guarantees. A client must not even be able to."""
+        import inspect
+
+        src = inspect.getsource(corpus_mod)
+        for forbidden in ("psycopg", "asyncpg", "sqlalchemy", "postgresql://"):
+            assert forbidden not in src

clapback_client-0.1.0/tests/test_fingerprint.py

@@ -0,0 +1,80 @@
+"""`ADR-0010`: the corpus key is a function of the audio.
+
+The defect this guards against did not look like a bug. Familiar hashed the
+fingerprint it had stored, which was correct code given a canonical input and was
+never given one — so the same recording reached the corpus under two keys
+depending on a column's migration history. These tests are the rule stated as
+assertions, because the failure is silent: a wrong key is a well-formed 64-character
+hex string that simply matches nothing.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from clapback_client.fingerprint import canonical, hash_fingerprint
+
+#: A real-shaped chromaprint fingerprint: base64 alphabet, starts `AQAD`.
+RAW = "AQADtJESbVkUhYL84z4CnwZ4HsdxHD6P4_hx_EAO_cjx"
+
+#: The same value after a `bytea` → `text` column migration renders it in
+#: Postgres's hex output format. Not a different fingerprint — the same ASCII.
+ESCAPED = "\\x" + RAW.encode().hex()
+
+
+def test_escaped_and_raw_are_the_same_fingerprint():
+    """The premise. If this fails the rest of the file is measuring nothing."""
+    assert bytes.fromhex(ESCAPED[2:]).decode() == RAW
+
+
+def test_the_two_encodings_hash_alike():
+    """The whole point of `ADR-0010`.
+
+    Before it, these differed, and that difference is what split the corpus into
+    14,284 rows keyed one way and 11,364 the other.
+    """
+    assert hash_fingerprint(RAW) == hash_fingerprint(ESCAPED)
+
+
+def test_the_hash_is_of_the_fingerprint_itself():
+    """Canonical means the bytes chromaprint returned, not a form of our choosing.
+
+    Pinned against `hashlib` directly rather than against `hash_fingerprint`'s own
+    output, so that a change to the canonical form fails here instead of quietly
+    re-keying the corpus.
+    """
+    assert hash_fingerprint(RAW) == hashlib.sha256(RAW.encode()).hexdigest()
+
+
+def test_bytes_and_str_agree():
+    """`acoustid` returns bytes on some paths and str on others."""
+    assert hash_fingerprint(RAW.encode()) == hash_fingerprint(RAW)
+
+
+def test_a_real_fingerprint_is_never_mistaken_for_an_encoding():
+    """The decode must not misfire on the values it will actually see.
+
+    A chromaprint fingerprint is base64 and cannot begin with a backslash, which
+    is what makes the narrow check safe.
+    """
+    assert canonical(RAW) == RAW.encode()
+    assert not RAW.startswith("\\x")
+
+
+def test_unrecognised_shapes_are_left_alone():
+    """Anything not recognisably a re-encoding passes through unchanged.
+
+    Guessing would be worse than not trying: a wrong guess produces a key that is
+    wrong in a new way, and nothing downstream can tell.
+    """
+    for odd in ("\\xZZZZ", "\\x41514", "\\x", "not a fingerprint", ""):
+        assert canonical(odd) == odd.encode()
+
+
+def test_escaped_non_ascii_is_not_decoded():
+    """Valid hex that decodes to arbitrary bytes is not a re-encoded fingerprint.
+
+    `\\x00ff` is well-formed hex, so only the printable-ASCII test separates it
+    from an escaped fingerprint.
+    """
+    assert canonical("\\x00ff") == b"\\x00ff"

clapback_client-0.1.0/tests/test_identity.py

@@ -0,0 +1,36 @@
+"""`ADR-0004` point 1 — an identifier, not an identity."""
+
+from __future__ import annotations
+
+import uuid
+
+from clapback_client.identity import ensure_client_id, mint_client_id
+
+
+class TestMinting:
+    def test_it_is_a_uuid_and_nothing_else(self):
+        """Derived from nothing about the machine or its owner: two mints on the
+        same machine differ, and each parses as a random UUID."""
+        a, b = mint_client_id(), mint_client_id()
+        assert a != b
+        assert uuid.UUID(a).version == 4
+
+
+class TestTheFileHelper:
+    def test_it_mints_once_and_then_returns_the_same_one(self, tmp_path):
+        p = tmp_path / "deep" / "client_id"
+        first = ensure_client_id(p)
+        assert p.read_text().strip() == first
+        assert ensure_client_id(p) == first
+
+    def test_deleting_it_makes_a_new_contributor(self, tmp_path):
+        """The one promise the identifier makes to the user."""
+        p = tmp_path / "client_id"
+        first = ensure_client_id(p)
+        p.unlink()
+        assert ensure_client_id(p) != first
+
+    def test_an_empty_file_is_treated_as_absent(self, tmp_path):
+        p = tmp_path / "client_id"
+        p.write_text("\n")
+        assert uuid.UUID(ensure_client_id(p))