clapback-cli 0.1.0__py3-none-any.whl

clapback_cli/__init__.py

@@ -0,0 +1,8 @@
+"""clapback — search your own music by description, and find duplicates.
+
+`ADR-0009`: the tool must be worth running with the corpus empty. Everything it
+does locally needs no network, no account and no fingerprinting.
+"""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

clapback_cli/cli.py

@@ -0,0 +1,282 @@
+"""`clapback` — search your own music by description, and find duplicates.
+
+`ADR-0009` point 8 of `ADR-0001` is the brief: **the tool must be worth running
+with the corpus empty.** So everything here works offline, against your own
+files, with the commons unreachable. Contributing is something it can also do.
+
+    clapback index ~/Music
+    clapback search "dreamy ambient with piano"
+    clapback duplicates
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .corpus import DEFAULT_BASE_URL as DEFAULT_CORPUS_URL
+from .store import Store
+
+#: What we will try to embed. `clapback-embed` decodes through soundfile and
+#: librosa; anything they refuse is skipped with a line rather than a traceback,
+#: because one unreadable file in a library of 20,000 must not end the run.
+AUDIO_SUFFIXES = {".flac", ".mp3", ".m4a", ".ogg", ".opus", ".wav", ".aiff", ".aif", ".wma"}
+
+#: `ADR-0009` point 8. Two rips of one recording measure 0.9972–0.9995 under this
+#: pipeline, and genuinely different music sits far below; 0.995 is inside that
+#: band and adjustable, because "duplicate" is partly a judgement — a remaster is
+#: a different master and sometimes a different recording.
+DEFAULT_DUPLICATE_THRESHOLD = 0.995
+
+
+def _embedder():
+    """Import lazily, so `--help` and a missing model do not look like the same failure."""
+    try:
+        import clapback_embed
+    except ImportError:
+        sys.exit("clapback-embed is not installed. pip install clapback")
+    return clapback_embed
+
+
+def cmd_index(args: argparse.Namespace) -> int:
+    embed = _embedder()
+    store = Store(args.home).load()
+    known = store.known()
+
+    files = [
+        p for p in sorted(Path(args.directory).rglob("*"))
+        if p.suffix.lower() in AUDIO_SUFFIXES and p.is_file()
+    ]
+    print(f"{len(files):,} audio files under {args.directory}")
+
+    added = skipped = failed = 0
+    for path in files:
+        key = str(path.resolve())
+        stat = path.stat()
+        prior = known.get(key)
+        # Re-embedding a file that has not changed costs seconds of CPU for an
+        # identical vector. mtime and size together are enough: a file edited in
+        # place without changing either is not a case worth slowing every run for.
+        if prior and prior.mtime == stat.st_mtime and prior.size == stat.st_size:
+            skipped += 1
+            continue
+        try:
+            vector = embed.embed_file(str(path))
+        except embed.ArtifactsMissing:
+            sys.exit(
+                "The ONNX encoders are missing. They are 614 MB and not bundled — "
+                "export them once with clapback-embed's scripts/export_models.py, "
+                "or set CLAPBACK_MODEL_DIR to where they already are."
+            )
+        except Exception as exc:  # noqa: BLE001 - one bad file must not end the run
+            print(f"  skipped {path.name}: {exc}")
+            failed += 1
+            continue
+        store.add(key, stat.st_mtime, stat.st_size, vector)
+        added += 1
+        if added % 50 == 0:
+            print(f"  {added:,} embedded")
+
+    store.pipeline_version = embed.PIPELINE_VERSION
+    store.save()
+    print(f"indexed {added:,} · unchanged {skipped:,} · unreadable {failed:,}")
+    print(f"store: {store.home}")
+    return 0
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    embed = _embedder()
+    store = Store(args.home).load()
+    if not len(store.vectors):
+        sys.exit("Nothing indexed yet. Try: clapback index ~/Music")
+
+    query = embed.embed_text(args.description)
+    for i, score in store.nearest(query, args.limit):
+        print(f"{score:.4f}  {store.entries[i].path}")
+    return 0
+
+
+def cmd_duplicates(args: argparse.Namespace) -> int:
+    import numpy as np
+
+    store = Store(args.home).load()
+    n = len(store.vectors)
+    if n < 2:
+        sys.exit("Need at least two indexed tracks.")
+
+    # The full n×n similarity matrix, which at a personal library's scale is
+    # cheaper than being clever: 20,000 tracks is a 1.6 GB float32 matrix, so it
+    # goes in blocks rather than all at once.
+    seen: set[tuple[int, int]] = set()
+    block = 2000
+    for start in range(0, n, block):
+        sims = store.vectors[start : start + block] @ store.vectors.T
+        for local, row in enumerate(sims):
+            i = start + local
+            for j in np.nonzero(row >= args.threshold)[0]:
+                j = int(j)
+                if i < j:
+                    seen.add((i, j))
+
+    if not seen:
+        print(f"No pairs at or above {args.threshold}.")
+        return 0
+    print(f"{len(seen):,} pair(s) at or above {args.threshold}:\n")
+    for i, j in sorted(seen, key=lambda p: -float(store.vectors[p[0]] @ store.vectors[p[1]])):
+        score = float(store.vectors[i] @ store.vectors[j])
+        print(f"{score:.4f}")
+        print(f"  {store.entries[i].path}")
+        print(f"  {store.entries[j].path}")
+    return 0
+
+
+#: This tool's own counter, and nothing more. `ADR-0006` points 2 and 3 took
+#: `analysis_version` out of the key and left it as a recorded column, so it is no
+#: longer a claim about whether two vectors are comparable — `pipeline_version` is.
+#: A new client therefore starts at 1 rather than pretending to share Familiar's
+#: history, which is what the number used to imply.
+ANALYSIS_VERSION = 1
+
+#: How long to wait between writes. The server rate-limits contributions and the
+#: client backs off on 429; pacing just means it rarely has to.
+CONTRIBUTE_PACE_SECONDS = 0.15
+
+
+def cmd_contribute(args: argparse.Namespace) -> int:
+    """`ADR-0009` point 6 — the byproduct, and the only reason the corpus grows.
+
+    Everything this tool does locally works with the commons unreachable and this
+    command never run. That is `ADR-0001` point 8 and it is the whole argument:
+    a donation client with no local value has no first contributor.
+    """
+    import time
+
+    from .corpus import Corpus, CorpusError
+    from .fingerprint import FingerprintUnavailable, fingerprint_file, hash_fingerprint
+
+    embed = _embedder()
+    store = Store(args.home).load()
+    if not len(store.vectors):
+        sys.exit("Nothing indexed yet. Try: clapback index ~/Music")
+
+    # **A store indexed by a different pipeline cannot be contributed.** Since
+    # `ADR-0006` phase 4 the pipeline identity is half the corpus key, so sending
+    # these vectors under the installed embedder's identity would assert that a
+    # pipeline produced vectors it did not. Re-indexing is the honest fix and it
+    # is the one the record chose (`ADR-0006` point 5: recomputed, not relabelled).
+    if store.pipeline_version and store.pipeline_version != embed.PIPELINE_VERSION:
+        sys.exit(
+            f"This store was indexed by {store.pipeline_version}\n"
+            f"and the installed embedder is  {embed.PIPELINE_VERSION}.\n"
+            "Contributing would key these vectors to a pipeline that did not produce "
+            "them. Re-index first: clapback index <directory>"
+        )
+
+    corpus = Corpus(args.url)
+    pipeline_version = embed.PIPELINE_VERSION
+    # The checkpoint is already the first component of the pipeline identity, so
+    # taking it from there keeps the two from ever disagreeing about one fact.
+    clap_model_version = pipeline_version.split("+")[0]
+
+    entries = store.entries[: args.limit] if args.limit else store.entries
+    print(f"{len(entries):,} indexed track(s)")
+    print(f"corpus:   {corpus.base_url}")
+    print(f"pipeline: {pipeline_version}")
+
+    if args.dry_run:
+        need = sum(1 for e in entries if not e.fingerprint_hash)
+        print("\ndry run — nothing will be sent.")
+        print(f"{need:,} would need fingerprinting first.")
+        return 0
+
+    client_id = store.ensure_client_id()
+    print(f"client:   {client_id}\n")
+
+    sent = present = unfingerprintable = missing = 0
+    try:
+        # `entries` is a prefix of `store.entries`, so the loop index addresses
+        # the matching row of `store.vectors` directly. Looking the entry up by
+        # value instead would be quadratic, and would pick the wrong vector for
+        # two entries that happen to compare equal.
+        for idx, entry in enumerate(entries):
+            n = idx + 1
+            if not entry.fingerprint_hash:
+                if not Path(entry.path).exists():
+                    missing += 1
+                    continue
+                try:
+                    entry.fingerprint_hash = hash_fingerprint(fingerprint_file(entry.path))
+                except FingerprintUnavailable as exc:
+                    # Point 5: a missing chromaprint is a plain statement, not a
+                    # traceback, and it is fatal only because nothing downstream
+                    # can proceed without it.
+                    if "not installed" in str(exc):
+                        store.save()
+                        sys.exit(f"\n{exc}")
+                    unfingerprintable += 1
+                    continue
+
+            try:
+                if corpus.has(entry.fingerprint_hash, pipeline_version):
+                    present += 1
+                    continue
+                corpus.contribute(
+                    fingerprint_hash=entry.fingerprint_hash,
+                    embedding=[float(x) for x in store.vectors[idx]],
+                    pipeline_version=pipeline_version,
+                    clap_model_version=clap_model_version,
+                    analysis_version=ANALYSIS_VERSION,
+                    client_id=client_id,
+                )
+                sent += 1
+                time.sleep(CONTRIBUTE_PACE_SECONDS)
+            except CorpusError as exc:
+                store.save()
+                sys.exit(f"\nstopped at {n:,}: {exc}")
+
+            if n % 25 == 0:
+                # Save as we go: fingerprints cost a subprocess each, and an
+                # interrupted run must not throw that away.
+                store.save()
+                print(f"  {n:,}/{len(entries):,} · contributed {sent:,} · already there {present:,}")
+    finally:
+        store.save()
+
+    print(
+        f"\ncontributed {sent:,} · already in corpus {present:,} · "
+        f"no fingerprint {unfingerprintable:,} · file gone {missing:,}"
+    )
+    return 0
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="clapback", description=__doc__.split("\n")[0])
+    p.add_argument("--home", type=Path, default=None, help="store directory (default ~/.clapback)")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    ix = sub.add_parser("index", help="embed a directory of audio into the local store")
+    ix.add_argument("directory")
+    ix.set_defaults(func=cmd_index)
+
+    se = sub.add_parser("search", help="find tracks matching a description")
+    se.add_argument("description")
+    se.add_argument("--limit", type=int, default=10)
+    se.set_defaults(func=cmd_search)
+
+    du = sub.add_parser("duplicates", help="find near-duplicates across formats and masters")
+    du.add_argument("--threshold", type=float, default=DEFAULT_DUPLICATE_THRESHOLD)
+    du.set_defaults(func=cmd_duplicates)
+
+    co = sub.add_parser("contribute", help="send your embeddings to the commons (opt-in)")
+    co.add_argument("--url", default=DEFAULT_CORPUS_URL, help="corpus base URL")
+    co.add_argument("--limit", type=int, default=0, help="stop after this many tracks")
+    co.add_argument("--dry-run", action="store_true", help="say what would be sent, send nothing")
+    co.set_defaults(func=cmd_contribute)
+
+    args = p.parse_args()
+    raise SystemExit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

clapback_cli/corpus.py

@@ -0,0 +1,133 @@
+"""Talking to the commons over HTTP, and only over HTTP.
+
+`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-cli",
+            },
+        )
+        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 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. Familiar's backfill learned this the same way.
+        """
+        # 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, _ = self._request(
+            "GET",
+            f"/v1/embeddings/{fingerprint_hash}?pipeline_version={quote(pipeline_version, safe='')}",
+        )
+        if status == 200:
+            return True
+        if status == 404:
+            return False
+        raise CorpusError(f"lookup returned {status}")
+
+    def contribute(
+        self,
+        *,
+        fingerprint_hash: str,
+        embedding: list[float],
+        pipeline_version: str,
+        clap_model_version: str,
+        analysis_version: int,
+        client_id: str,
+    ) -> str:
+        """POST one embedding. Returns a short word describing what happened."""
+        body = {
+            "fingerprint_hash": fingerprint_hash,
+            "embedding": embedding,
+            "pipeline_version": pipeline_version,
+            "clap_model_version": clap_model_version,
+            "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 and delay is not None:
+                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_cli/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_cli/store.py

@@ -0,0 +1,124 @@
+"""Where the vectors live: a directory the user owns, holding two files.
+
+`ADR-0009` point 4 — "the store is a local file the user owns, and nothing leaves
+the machine by default". Point 3 rules out an index, so this is deliberately not
+a database: brute force needs every vector in memory anyway, and a `.npy` loads
+into exactly that with no query layer in between.
+
+Two files rather than one because they change at different rates and for
+different reasons. `vectors.npy` is 2 KB per track and rewritten whole;
+`index.json` is small, human-readable, and the thing you would look at to answer
+"did it index the file I think it did".
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+DEFAULT_HOME = Path.home() / ".clapback"
+
+
+@dataclass
+class Entry:
+    path: str
+    mtime: float
+    size: int
+    #: The corpus key for this recording, cached after the first time chromaprint
+    #: is asked. `None` means "not fingerprinted", which is the normal state: the
+    #: local half of this tool never needs one (`ADR-0009` point 5), so the cost
+    #: is only paid by somebody who contributes.
+    #:
+    #: Cached rather than recomputed because fingerprinting spawns a process per
+    #: file, and a contribute run that is interrupted should not start over.
+    fingerprint_hash: str | None = None
+
+
+class Store:
+    """Vectors and the files they came from, kept in step by position."""
+
+    def __init__(self, home: Path | None = None) -> None:
+        self.home = Path(home) if home else DEFAULT_HOME
+        self.vectors_path = self.home / "vectors.npy"
+        self.index_path = self.home / "index.json"
+        self.vectors: np.ndarray = np.zeros((0, 512), dtype=np.float32)
+        self.entries: list[Entry] = []
+        self.pipeline_version: str | None = None
+        #: `ADR-0004` point 1: an opaque per-install identifier, generated once and
+        #: never derived from anything about the machine or its owner. It exists so
+        #: the corpus can tell two submissions from one client retrying, which is
+        #: the distinction `contributor_count` cannot make.
+        self.client_id: str | None = None
+
+    def load(self) -> Store:
+        if self.index_path.exists():
+            data = json.loads(self.index_path.read_text())
+            # Tolerate keys this version does not know: a store written by a
+            # newer clapback must not make an older one delete the library.
+            fields = {f.name for f in dataclasses.fields(Entry)}
+            self.entries = [
+                Entry(**{k: v for k, v in e.items() if k in fields})
+                for e in data.get("entries", [])
+            ]
+            self.pipeline_version = data.get("pipeline_version")
+            self.client_id = data.get("client_id")
+        if self.vectors_path.exists():
+            self.vectors = np.load(self.vectors_path)
+        # A store whose two halves disagree is worse than an empty one: every
+        # result would be attributed to the wrong file. Rebuilding is cheap
+        # relative to explaining a wrong answer.
+        if len(self.entries) != len(self.vectors):
+            self.entries, self.vectors = [], np.zeros((0, 512), dtype=np.float32)
+        return self
+
+    def save(self) -> None:
+        self.home.mkdir(parents=True, exist_ok=True)
+        np.save(self.vectors_path, self.vectors)
+        self.index_path.write_text(
+            json.dumps(
+                {
+                    "pipeline_version": self.pipeline_version,
+                    "client_id": self.client_id,
+                    "entries": [e.__dict__ for e in self.entries],
+                },
+                indent=1,
+            )
+        )
+
+    def ensure_client_id(self) -> str:
+        """The identifier this install contributes under, minted on first use.
+
+        Deliberately not minted at `index` time. A store that has only ever been
+        searched locally has no reason to carry an identifier, and `ADR-0009`
+        point 4 is that nothing leaves the machine by default — including the fact
+        that this install exists.
+        """
+        if not self.client_id:
+            self.client_id = str(uuid.uuid4())
+        return self.client_id
+
+    def known(self) -> dict[str, Entry]:
+        return {e.path: e for e in self.entries}
+
+    def add(self, path: str, mtime: float, size: int, vector: list[float]) -> None:
+        self.entries.append(Entry(path=path, mtime=mtime, size=size))
+        v = np.asarray(vector, dtype=np.float32).reshape(1, -1)
+        self.vectors = np.vstack([self.vectors, v]) if len(self.vectors) else v
+
+    def nearest(self, query: np.ndarray, limit: int) -> list[tuple[int, float]]:
+        """Cosine similarity against everything, sorted.
+
+        The vectors are unit length, so a dot product *is* the cosine — no
+        normalisation, no distance-to-similarity conversion, and nothing to get
+        the sign of wrong.
+        """
+        if not len(self.vectors):
+            return []
+        sims = self.vectors @ np.asarray(query, dtype=np.float32)
+        top = np.argsort(-sims)[:limit]
+        return [(int(i), float(sims[i])) for i in top]

clapback_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: clapback-cli
+Version: 0.1.0
+Summary: Search your own music by description, and find duplicates across formats and masters
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: clapback-embed<0.2,>=0.1.0
+Requires-Dist: numpy>=1.24.0
+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
+
+Search your own music by description, and find duplicates across formats and masters.
+
+```bash
+pip install clapback-cli
+
+clapback index ~/Music
+clapback search "dreamy ambient with piano"
+clapback duplicates
+```
+
+## What it does
+
+**Search by description.** CLAP puts audio and text in one space, so "something
+slow with brushed drums" is a query rather than a keyword match against filenames
+you may never have typed.
+
+**Find near-duplicates.** Two rips of one recording measure 0.9972–0.9995 under
+this pipeline; genuinely different music sits far below. That gap is what makes
+duplicate detection across formats and masters work — a FLAC and a V0 of the same
+master are obvious, and so is the same recording on two different releases.
+
+Both run against your own files, offline. There is no account, no key, and
+nothing is sent anywhere.
+
+**Contribute, if you want to.** Opt-in and off unless you type it:
+
+```bash
+clapback contribute --dry-run   # say what would be sent, send nothing
+clapback contribute
+```
+
+This sends the vectors — never your audio, never filenames, never your library's
+contents. A recording is identified by the SHA256 of its AcoustID fingerprint,
+which is one-way: the corpus learns that somebody has a recording without learning
+which recording it is.
+
+Every track is looked up before it is offered, so re-running contributes only
+what is new. That is not politeness about bandwidth — a repeat submission is
+recorded as agreement, and one install agreeing with itself would corrupt the one
+measurement the commons exists to make.
+
+Contributing needs `chromaprint`, and only contributing does:
+
+```bash
+brew install chromaprint     # or: apt install libchromaprint-tools
+pip install pyacoustid
+```
+
+Without it, indexing, search and duplicates work exactly as well.
+
+## Why `clapback-cli` and not `clapback`
+
+The bare name on PyPI belongs to an unrelated package from 2018 that adds clap
+emojis to sentences. The distribution is therefore `clapback-cli`, matching
+`clapback-embed`; the command you type is still `clapback`.
+
+## What it needs
+
+`clapback-embed`, which arrives with it, and the ONNX encoders it runs on. Those
+are **614 MB and not bundled** — a package that downloaded them on install would
+be lying about its size. Export them once:
+
+```bash
+pip install 'clapback-embed[export]'
+python -m clapback_embed.scripts.export_models --out ~/.cache/clapback/models
+```
+
+Or point `CLAPBACK_MODEL_DIR` at them if you already have them.
+
+## Where things are kept
+
+`~/.clapback/` — a `vectors.npy` and an `index.json`, both yours. Deleting the
+directory loses nothing but the time to rebuild it.
+
+If you contribute, `index.json` also holds a `client_id`: a random UUID minted the
+first time you contribute and never before, derived from nothing about you or your
+machine. It exists so the corpus can tell two contributions apart from one client
+retrying. Delete it and you are a new contributor; nothing else changes.
+
+## What it is not
+
+Not a player, not a tagger, not a library manager, not a downloader. It does the
+two things a CLAP embedding makes uniquely easy and stops.
+
+## Why it exists
+
+It is the reference implementation's first real client, and the argument for it
+is in [`ADR-0009`](../../docs/decisions/ADR-0009-the-tool-is-useful-before-the-corpus-is.md):
+a donation client with no local value has no first contributor, and this project
+has measured proof that passive accumulation does not happen. What the tool does
+locally is the draw; contributing to the [commons](https://clapback.seethroughlab.com)
+is a byproduct of it.

clapback_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+clapback_cli/__init__.py,sha256=eNj8LihuI82SU1SG6uGzJ0814wvVKSTmaIB3tIrT0uU,274
+clapback_cli/cli.py,sha256=IpmzaIgrRkBNKE8vXxoJVCwGlQr-edleiWHnftyi6vA,11580
+clapback_cli/corpus.py,sha256=COFGJevTo8Mv061q3rSEzuy5uEJuXWNasYIJ8LhQVwY,5751
+clapback_cli/fingerprint.py,sha256=t_O56nQvcOqN3pBJ65K72nnwA0HmD2kOa8FbHXNfscY,5356
+clapback_cli/store.py,sha256=iZVjbqrSeto4OYUm6WFxl2z-SVBuIeHgQ8PWaHjhhwk,5221
+clapback_cli-0.1.0.dist-info/METADATA,sha256=RhlhsrmHtZo0ClOMeperwm8M9lUOSrcFrwdp9fTgEBo,4033
+clapback_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+clapback_cli-0.1.0.dist-info/entry_points.txt,sha256=pDpKDWoHwPBQj3dSLDXYv7nwh7UkA05uVphRHT0_Ncs,51
+clapback_cli-0.1.0.dist-info/licenses/LICENSE,sha256=6Tfw3KwvxvDfednEoMB-s180r3b0xff9qWj57iXpiGs,1068
+clapback_cli-0.1.0.dist-info/RECORD,,

clapback_cli-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_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clapback = clapback_cli.cli:main

clapback_cli-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.