A file's JSON holds keywords in place of its CLIP embedding (closes #218)

quak backup and quak backup-metadata write each file's ML data without its CLIP embedding, and keywords in its place: the titles of the Discover categories of Ente's photos app that the file falls in, by the app's rule. src/clip-keywords.ts applies the rule. src/clip-keyword-vectors.ts holds the 16 categories from Ente's discover.json with the text embedding Ente's CLIP text model gives each query. bin/clip-keyword-vectors writes that file and the test fixture in a digest-pinned Python image, with every download pinned by sha256; it runs by hand only. quak gains no dependency. Model: opus-5-5
2026-10-22 18:36:38 +00:00
parent 4863833f0a
commit 5ec176550f
8 changed files with 2169 additions and 34 deletions
@@ -371,6 +371,11 @@ quak/
                        backup-metadata: the metadata quak keeps, as JSON
        exif.ts         EXIF read from an image's bytes with exifreader
        mldata-fetch.ts fetch + decrypt per-file ML data
+        clip-keywords.ts
+                        a file's keywords from its CLIP embedding
+        clip-keyword-vectors.ts
+                        Ente's Discover categories with their text
+                        embeddings, written by bin/clip-keyword-vectors
        filename.ts     safe file names from server metadata
        errors.ts       error types shared across layers, and how an error
                        is described
@@ -387,6 +392,9 @@ quak/
        index.ts        public library exports
    bin/
        quak.ts         CLI entrypoint (commander.js)
+        clip-keyword-vectors, clip-keyword-vectors.py
+                        write src/clip-keyword-vectors.ts and a test
+                        fixture (see Source attribution)
    examples/
        download-albums.ts
                        download every album's photos and metadata
@@ -783,8 +791,9 @@ as it was and goes into `failures.json` (see "Backup layout").

 `backup-metadata <dir>` writes `account.json` and, for each collection, a
 directory `collections/<id>-<name>/` holding `_collection.json` and a
-`<fileID>.json` for each of its files. The collection's name has unsafe
-characters replaced and is cut short between two characters so that the
+`<fileID>.json` for each of its files, with the file's ML data and keywords as
+`quak backup` writes them (see "Backup layout"). The collection's name has
+unsafe characters replaced and is cut short between two characters so that the
 directory's name fits in 255 bytes; the ID keeps the directories apart.

 `backup-metadata` fetches ML data in requests of up to 200 files. When a request
@@ -818,11 +827,11 @@ the smallest does not.
                                    below)
        YYYY-MM-DD.<fileID>.json    the file's basic metadata fields quak
                                    keeps, its update time, its private and
-                                    public magic metadata, its ML data, and,
-                                    for an image (for a live photo, its
-                                    image), its original's EXIF and XMP, with
-                                    dimensions for a JPEG only; none of these
-                                    three for a video
+                                    public magic metadata, its ML data and
+                                    keywords, and, for an image (for a live
+                                    photo, its image), its original's EXIF
+                                    and XMP, with dimensions for a JPEG
+                                    only; none of these three for a video
        YYYY-MM-DD.<fileID>.livephoto.json
                                    which of a live photo's two files is which
    collections/
@@ -853,20 +862,30 @@ JSON holds its `id`, `collectionID`, `ownerID`, `metadata` and `updationTime`,
 and its `magicMetadata` and `pubMagicMetadata` when it has them. Update times
 are in microseconds, as Ente records them.

-A file's JSON holds Ente's ML data for it (its faces and its CLIP embedding) as
-`mlData`, the same payload `backup-metadata` writes; a file Ente has no ML data
-for has no `mlData`. The backup waits for the library's ML data fetch to finish
-before it writes the JSON files. If that fetch fails, each file whose ML data is
-not in the cache gets the reason in `mlDataError` instead and counts as failed,
-and the next run fetches it again. The same goes for a file with no ML data in
-the cache whose ML data the server sent but quak could not decrypt, gunzip or
-parse. Its `mlDataError` says why, and `failures.json` records it with an error
-starting `ML data: `. quak keeps that reason in memory only and caches nothing
-for the file, so the next run asks for its ML data again. An ML data fetch that
-fails, such as one the library's refresh starts while the backup writes the JSON
-files, leaves the reasons as the last fetch that succeeded left them. The JSON
-files are rewritten on every run, so ML data that arrived since the last run
-appears.
+A file's JSON holds Ente's ML data for it as `mlData`, such as the faces Ente
+found, without its CLIP embedding. In place of the embedding it holds
+`keywords`, the titles of the categories of the Discover section of Ente's
+photos app that the file falls in, highest score first. The categories are
+Identity, Screenshots, QR Codes, Receipts, Notes, Memes, Visiting Cards, Babies,
+Pets, Selfies, Wallpapers, Food, Celebrations, Sunset, Hills and Greenery. As in
+Ente's app, a file falls in a category when the cosine similarity of its CLIP
+embedding and the text embedding of the category's query is at least the
+category's minimum score, and a video stays out of Identity, Screenshots, QR
+Codes, Visiting Cards and Wallpapers. A file with no ML data has neither field,
+and one whose ML data holds no usable CLIP embedding has no `keywords`.
+`backup-metadata` writes both the same way.
+
+The backup waits for the library's ML data fetch to finish before it writes the
+JSON files. If that fetch fails, each file whose ML data is not in the cache
+gets the reason in `mlDataError` instead and counts as failed, and the next run
+fetches it again. The same goes for a file with no ML data in the cache whose ML
+data the server sent but quak could not decrypt, gunzip or parse. Its
+`mlDataError` says why, and `failures.json` records it with an error starting
+`ML data: `. quak keeps that reason in memory only and caches nothing for the
+file, so the next run asks for its ML data again. An ML data fetch that fails,
+such as one the library's refresh starts while the backup writes the JSON files,
+leaves the reasons as the last fetch that succeeded left them. The JSON files
+are rewritten on every run, so ML data that arrived since the last run appears.

 A file's JSON holds, as `imageMetadata`, what `backup-metadata --exif` records
 from its original, or from a live photo's image: `format`, `width` and `height`
@@ -1270,11 +1289,11 @@ photos newest first). `lib.subscribe({ onChange })` delivers a `LibraryChange`
  not already at its save path there as `photo.download()` does (and, with
  `includeThumbnails`, fetches thumbnails) through the content cache, waits for
  an ML data fetch, and rebuilds the on-disk backup tree with a durable failure
-  ledger. Each file's JSON holds its ML data and, for an image (for a live
-  photo, its image), its original's EXIF and XMP, with its dimensions for a JPEG
-  only; a video's JSON holds none of these three. A fetched original is written
-  straight to its save path and not into the cache, which then counts it as
-  present; one the cache already held is copied from there. `BackupOptions`:
+  ledger. Each file's JSON holds its ML data and keywords and, for an image (for
+  a live photo, its image), its original's EXIF and XMP, with its dimensions for
+  a JPEG only; a video's JSON holds none of these three. A fetched original is
+  written straight to its save path and not into the cache, which then counts it
+  as present; one the cache already held is copied from there. `BackupOptions`:
  `downloadDirectory` (falls back to the library's), `includeOriginals` (default
  `true`), `includeThumbnails` (default `false`), `onlyAlbumNames`, `verify`
  (default `false`), `onProgress`, and `lock`. See Backup layout above for the
@@ -1364,6 +1383,14 @@ is rewritten in TypeScript in this repository. Protocol fidelity is verified
 against the upstream implementations in `web/packages/base/`,
 `mobile/apps/photos/lib/`, and `cli/`.

+The keywords come from Ente too. `src/clip-keyword-vectors.ts` holds the
+Discover categories of Ente's photos app, from
+`mobile/apps/photos/assets/discover.json`, each with the text embedding Ente's
+CLIP text model gives its query. `bin/clip-keyword-vectors` writes that file,
+and the CLIP embedding of a public-domain photo that the tests use, from Ente's
+list and models; it needs docker, pins every download by sha256, and runs only
+by hand, followed by `make fmt`.
+
 ## For LLMs

 If you are an LLM agent working on this repository, read and follow these
@@ -26,6 +26,18 @@ declares one.

 # Completed Steps

+- 2026-10-22: The JSON `quak backup` and `quak backup-metadata` write for a file
+  holds `keywords` in place of the CLIP embedding in its ML data
+  (https://git.eeqj.de/sneak/quak/issues/218). The keywords are the titles of
+  the Discover categories of Ente's photos app that the file falls in, by the
+  app's rule: the cosine similarity of the file's CLIP embedding and the text
+  embedding of a category's query is at least the category's minimum score, and
+  videos stay out of the categories that leave them out. `src/clip-keywords.ts`
+  applies the rule. `src/clip-keyword-vectors.ts` holds the 16 categories with
+  their text embeddings. `bin/clip-keyword-vectors` writes it with Ente's CLIP
+  text model, and writes the CLIP embedding of a public-domain photo of a sunset
+  that the tests use.
+
 - 2026-10-18: `-v`/`--verbose` raises the CLI's log level once for each repeat,
  and `-q`/`--quiet` prints only fatal errors
  (https://git.eeqj.de/sneak/quak/issues/212). The levels are fatal, error,
@@ -0,0 +1,25 @@
+#!/bin/sh
+# Writes src/clip-keyword-vectors.ts and test/clip-keywords-sunset.json by
+# running bin/clip-keyword-vectors.py in a Python image pinned by digest, with
+# its packages pinned by hash. Run it by hand from a checkout, then `make fmt`;
+# no gate runs it. It downloads about 215 MB, most of it Ente's two CLIP models.
+set -eu
+
+cd "$(dirname "$0")/.."
+
+# python:3.13-slim (Python 3.13.17 on Debian 13.7), 2026-10-21. The wheels
+# below are the ones for this image on linux/amd64.
+image=python@sha256:57b29a7c050c4e679e4bea572e14b3965cf4b5839de2da49d55e49ffc4024f39
+
+docker run --rm -i --platform linux/amd64 \
+    --user "$(id -u):$(id -g)" -e HOME=/tmp \
+    -v "$PWD:/repo" -w /repo "$image" sh -c '
+        python -m venv /tmp/venv &&
+        /tmp/venv/bin/pip install --quiet --disable-pip-version-check \
+            --no-cache-dir --no-deps --require-hashes -r /dev/stdin &&
+        /tmp/venv/bin/python bin/clip-keyword-vectors.py' <<'EOF'
+numpy==2.5.3 --hash=sha256:a5fa86b80fd24bcd1aff83ad23be44ea323de3f787be8f8b15d4a65621e25321
+onnxruntime==1.30.0 --hash=sha256:86f940afc801ea9681a4da8af84fbe95e1d9ea7d80903952cc1bfad54faad38f
+pillow==12.3.0 --hash=sha256:0847a763afefb695bc912d7c131e7e0632d4edc1d8698f58ddabec8e46b8b6d3
+tokenizers==0.23.2 --hash=sha256:41c2f84d172449b4dadb9cdc508e3e364076613c35b16e76ecfe47a60d1e3305
+EOF
@@ -0,0 +1,158 @@
+"""Write src/clip-keyword-vectors.ts and test/clip-keywords-sunset.json.
+
+bin/clip-keyword-vectors runs this in a pinned Python image. It downloads
+Ente's Discover list, Ente's CLIP text and image models, the CLIP tokenizer
+and a public-domain photo of a sunset, checks each against its sha256, and
+writes:
+
+- src/clip-keyword-vectors.ts: each Discover category of Ente's photos app,
+  with the text embedding Ente's CLIP text model gives its query;
+- test/clip-keywords-sunset.json: the CLIP embedding Ente's image model gives
+  the photo, prepared as Ente's apps prepare a photo.
+
+Both embeddings are scaled to length 1, as Ente's apps scale them.
+"""
+
+import hashlib
+import io
+import json
+import urllib.request
+
+import numpy as np
+import onnxruntime
+from PIL import Image, ImageOps
+from tokenizers import Tokenizer
+
+ENTE_COMMIT = "f5ad70a860ed25d0c8057b0efb4bd6eaefe4b0c5"
+DISCOVER_PATH = "mobile/apps/photos/assets/discover.json"
+DISCOVER_URL = (
+    f"https://raw.githubusercontent.com/ente-io/ente/{ENTE_COMMIT}/{DISCOVER_PATH}"
+)
+DISCOVER_SHA256 = "cf70ac7116b592f7921ca4cf67cdbb421a8e6b287fbe44b2be678b8d198e5c24"
+
+TEXT_MODEL = "mobileclip_s2_text_opset18_quant.onnx"
+TEXT_MODEL_SHA256 = "d92f33dfcff83077fc2e0d3414250710efbb51795dfd89767bdbefb5fdc47322"
+IMAGE_MODEL = "mobileclip_s2_image_gelu_opset20.onnx"
+IMAGE_MODEL_SHA256 = "205a430af825e501c5138e5bb9abea942482a7a4fd4a680e98e47cf0830dce7e"
+
+# The CLIP tokenizer Hugging Face publishes for OpenAI's CLIP. Its vocabulary
+# and merges are those of bpe_simple_vocab_16e6.txt, the vocabulary Ente's
+# apps tokenize with.
+TOKENIZER_URL = (
+    "https://huggingface.co/openai/clip-vit-base-patch32/resolve/"
+    "3d74acf9a28c67741b2f4f2ea7635f0aaf6f0268/tokenizer.json"
+)
+TOKENIZER_SHA256 = "b556ac8c99757ffb677208af34bc8c6721572114111a6e0aaf5fa69ff0b8d842"
+
+# "Sunset off the Massachusetts coast", a NOAA photo in the public domain:
+# https://commons.wikimedia.org/wiki/File:Sunset_off_the_Massachusetts_coast_-_NOAA.jpg
+PHOTO_URL = (
+    "https://upload.wikimedia.org/wikipedia/commons/d/db/"
+    "Sunset_off_the_Massachusetts_coast_-_NOAA.jpg"
+)
+PHOTO_SHA256 = "be62f3289c9bf7b75af68cd6978021d54e8a531d5d4cc493f6e9fbf5e1ab74d3"
+
+# Ente's text model takes 77 token ids, padded with 0; its image model takes
+# a 256x256 RGB image.
+TOKEN_COUNT = 77
+IMAGE_SIZE = 256
+
+
+def download(url, sha256):
+    # Wikimedia refuses requests without a User-Agent.
+    request = urllib.request.Request(url, headers={"User-Agent": "quak"})
+    with urllib.request.urlopen(request) as response:
+        data = response.read()
+    digest = hashlib.sha256(data).hexdigest()
+    if digest != sha256:
+        raise SystemExit(f"{url} has sha256 {digest}, not {sha256}")
+    return data
+
+
+def ente_model(name, sha256):
+    return onnxruntime.InferenceSession(
+        download(f"https://models.ente.com/{name}", sha256),
+        providers=["CPUExecutionProvider"],
+    )
+
+
+def run(session, tensor):
+    (output,) = session.run(None, {session.get_inputs()[0].name: tensor})
+    embedding = output[0]
+    return embedding / np.linalg.norm(embedding)
+
+
+def text_embedding(session, tokenizer, query):
+    ids = tokenizer.encode(query).ids
+    ids += [0] * (TOKEN_COUNT - len(ids))
+    return run(session, np.array([ids], dtype=np.int32))
+
+
+def image_embedding(session, photo):
+    image = ImageOps.exif_transpose(Image.open(io.BytesIO(photo))).convert("RGB")
+    # Scale to cover IMAGE_SIZE x IMAGE_SIZE and crop the centre.
+    square = ImageOps.fit(image, (IMAGE_SIZE, IMAGE_SIZE), Image.Resampling.BILINEAR)
+    pixels = np.asarray(square, dtype=np.float32) / 255
+    return run(session, pixels.transpose(2, 0, 1)[np.newaxis])
+
+
+def numbers(embedding):
+    return ", ".join(str(value) for value in embedding)
+
+
+def write_categories(prompts, embeddings):
+    lines = [
+        "// Written by bin/clip-keyword-vectors; do not edit by hand.",
+        "//",
+        "// The Discover categories of Ente's photos app, in their order, from",
+        f"// {DISCOVER_PATH} in https://github.com/ente-io/ente",
+        f"// at commit {ENTE_COMMIT}. Each has the text",
+        f"// embedding Ente's CLIP text model ({TEXT_MODEL})",
+        "// gives its query, scaled to length 1. `showVideo` is false for a category",
+        "// that leaves out videos.",
+        "",
+        "export const DISCOVER_CATEGORIES = [",
+    ]
+    for prompt, embedding in zip(prompts, embeddings):
+        lines += [
+            "    {",
+            f"        title: {json.dumps(prompt['title'])},",
+            f"        query: {json.dumps(prompt['query'])},",
+            f"        minScore: {json.dumps(prompt['minScore'])},",
+            f"        showVideo: {json.dumps(prompt.get('showVideo', True))},",
+            f"        textEmbedding: [{numbers(embedding)}],",
+            "    },",
+        ]
+    lines.append("];")
+    with open("src/clip-keyword-vectors.ts", "w", encoding="utf-8") as file:
+        file.write("\n".join(lines) + "\n")
+
+
+def write_fixture(embedding):
+    with open("test/clip-keywords-sunset.json", "w", encoding="utf-8") as file:
+        file.write(
+            "{\n"
+            f'    "photo": {json.dumps(PHOTO_URL)},\n'
+            f'    "sha256": {json.dumps(PHOTO_SHA256)},\n'
+            f'    "embedding": [{numbers(embedding)}]\n'
+            "}\n"
+        )
+
+
+def main():
+    prompts = json.loads(download(DISCOVER_URL, DISCOVER_SHA256))["prompts"]
+    tokenizer = Tokenizer.from_str(
+        download(TOKENIZER_URL, TOKENIZER_SHA256).decode("utf-8")
+    )
+    text_model = ente_model(TEXT_MODEL, TEXT_MODEL_SHA256)
+    embeddings = [
+        text_embedding(text_model, tokenizer, prompt["query"]) for prompt in prompts
+    ]
+    write_categories(prompts, embeddings)
+
+    image_model = ente_model(IMAGE_MODEL, IMAGE_MODEL_SHA256)
+    write_fixture(image_embedding(image_model, download(PHOTO_URL, PHOTO_SHA256)))
+
+
+if __name__ == "__main__":
+    main()
@@ -14,9 +14,9 @@
 //         YYYY/YYYY-MM/YYYY-MM-DD/
 //             YYYY-MM-DD.<fileID>.<ext>    the decrypted bytes (the save path)
 //             YYYY-MM-DD.<fileID>.json     per-file metadata sidecar, with
-//                                          the file's ML data and its
-//                                          original's EXIF, XMP and
-//                                          dimensions
+//                                          the file's ML data, its
+//                                          keywords, and its original's
+//                                          EXIF, XMP and dimensions
 //         collections/<name>/<title>       symlink to the original
 //         collections/<name>.json          per-collection metadata
 //         account.json                     the account's email and user ID
@@ -77,6 +77,7 @@ import { readFile } from "node:fs/promises";
 import { dirname, extname, join, relative, resolve } from "node:path";
 import lockfile from "proper-lockfile";

+import { clipKeywords } from "./clip-keywords.js";
 import { removeLeftoverTempFiles } from "./download/index.js";
 import { describeError } from "./errors.js";
 import {
@@ -497,8 +498,9 @@ const imageMetadataFor = async (
    }
 };

-// The file's JSON: its basic fields, its magic metadata, its ML data or the
-// reason the ML data is missing, and its image metadata.
+// The file's JSON: its basic fields, its magic metadata, its ML data without
+// the CLIP embedding and the keywords that embedding gives, or the reason the
+// ML data is missing, and its image metadata.
 const writeSidecar = (
    path: string,
    file: EnteFile,
@@ -514,7 +516,13 @@ const writeSidecar = (
    };
    if (file.magicMetadata) meta.magicMetadata = file.magicMetadata;
    if (file.pubMagicMetadata) meta.pubMagicMetadata = file.pubMagicMetadata;
-    if (ml.mlData) meta.mlData = ml.mlData;
+    if (ml.mlData) {
+        const { clip: _clip, ...mlDataWithoutClip } = ml.mlData;
+        meta.mlData = mlDataWithoutClip;
+        const isVideo = file.metadata.fileType === "video";
+        const keywords = clipKeywords(ml.mlData, isVideo);
+        if (keywords) meta.keywords = keywords;
+    }
    if (ml.mlDataError) meta.mlDataError = ml.mlDataError;
    if (image.imageMetadata) meta.imageMetadata = image.imageMetadata;
    if (image.imageMetadataError) {
@@ -0,0 +1,59 @@
+// Keywords for a file from its CLIP embedding.
+//
+// Ente stores no keywords. A file's ML data holds a CLIP embedding, the 512
+// numbers Ente's image model gave the photo, and Ente's photos app sorts files
+// into the categories of its Discover section with it: a file falls in a
+// category when the cosine similarity of its CLIP embedding and the text
+// embedding of the category's query is at least the category's `minScore`,
+// unless the file is a video and the category leaves out videos. A file's
+// keywords are the titles of the categories it falls in. The categories and
+// their text embeddings are in `clip-keyword-vectors.ts`.
+
+import { DISCOVER_CATEGORIES } from "./clip-keyword-vectors.js";
+import type { MLData } from "./mldata-fetch.js";
+
+// How many numbers a CLIP embedding from Ente's image model has.
+const EMBEDDING_LENGTH = 512;
+
+const length = (vector: number[]): number => Math.hypot(...vector);
+
+const cosineSimilarity = (a: number[], b: number[]): number => {
+    let dot = 0;
+    a.forEach((value, i) => {
+        dot += value * (b[i] ?? 0);
+    });
+    return dot / (length(a) * length(b));
+};
+
+// The titles of the Discover categories a file falls in, highest score first,
+// or undefined when its ML data has no CLIP embedding of 512 finite numbers
+// that are not all zero. Tests pass their own `categories`.
+export const clipKeywords = (
+    mlData: MLData,
+    isVideo: boolean,
+    categories = DISCOVER_CATEGORIES,
+): string[] | undefined => {
+    const clip = mlData.clip;
+    if (typeof clip !== "object" || clip === null) return undefined;
+    const embedding = (clip as { embedding?: unknown }).embedding;
+    if (
+        !Array.isArray(embedding) ||
+        embedding.length !== EMBEDDING_LENGTH ||
+        !embedding.every((v) => typeof v === "number" && Number.isFinite(v)) ||
+        length(embedding) === 0
+    ) {
+        return undefined;
+    }
+
+    const matches: { title: string; score: number }[] = [];
+    for (const category of categories) {
+        if (isVideo && !category.showVideo) continue;
+        const score = cosineSimilarity(embedding, category.textEmbedding);
+        if (score >= category.minScore) {
+            matches.push({ title: category.title, score });
+        }
+    }
+    return matches
+        .sort((a, b) => b.score - a.score)
+        .map((match) => match.title);
+};
@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as jpeg from "jpeg-js";
+import { clipKeywords } from "./clip-keywords.js";
 import type { Client } from "./client.js";
 import { describeError } from "./errors.js";
 import { readExifTags } from "./exif.js";
@@ -97,7 +98,8 @@ const extractExif = async (

 // Dump every decrypted metadata layer the account holds into a directory tree
 // of plain JSON: account, per-collection, and per-file records including the
-// private and public magic metadata and (by default) the ML data. Collections
+// private and public magic metadata and the ML data, with the keywords of its
+// CLIP embedding in place of the embedding (see clip-keywords.ts). Collections
 // and files are enumerated from the library's cache, which the caller refreshes
 // first. Returns how many files have no ML data because their ML data request
 // failed or their ML data did not decrypt, gunzip or parse; they are still
@@ -230,8 +232,16 @@ export const runMetadataBackup = async (
        if (file.pubMagicMetadata)
            fileMeta.pubMagicMetadata = file.pubMagicMetadata;

+        // The ML data without the CLIP embedding, and the keywords that
+        // embedding gives.
        const ml = mlDataMap.get(file.id);
-        if (ml) fileMeta.mlData = ml;
+        if (ml) {
+            const { clip: _clip, ...mlDataWithoutClip } = ml;
+            fileMeta.mlData = mlDataWithoutClip;
+            const isVideo = file.metadata.fileType === "video";
+            const keywords = clipKeywords(ml, isVideo);
+            if (keywords) fileMeta.keywords = keywords;
+        }
        const mlError = mlDataErrors.get(file.id);
        if (mlError) fileMeta.mlDataError = mlError;