clapback-client 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+clapback_client/__init__.py,sha256=CdrNeGf88SvTvkIzcrolkUG5Ek3EvWW3Cy6KxEJYBps,1704
+clapback_client/corpus.py,sha256=i4wImiAw2sbr6gReWm31JE4CEcS58lfoyoKxi_rwIT4,7459
+clapback_client/fingerprint.py,sha256=t_O56nQvcOqN3pBJ65K72nnwA0HmD2kOa8FbHXNfscY,5356
+clapback_client/identity.py,sha256=SZZRZFRToBWZ5FIunID7cyHl-hUllEYS7waozUG-OLw,1868
+clapback_client-0.1.0.dist-info/METADATA,sha256=7NkeZF_IfRtc0Uhm_Ynm8kz0betVviFDCuGBZu8K8vA,5946
+clapback_client-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+clapback_client-0.1.0.dist-info/licenses/LICENSE,sha256=6Tfw3KwvxvDfednEoMB-s180r3b0xff9qWj57iXpiGs,1068
+clapback_client-0.1.0.dist-info/RECORD,,

clapback_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

clapback_client-0.1.0.dist-info/licenses/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.