README: four sentences fixed for the documents gate (closes #229)
check / check (push) Waiting to run

The documents gate on `next` failed five README sentences
(#219 (comment)). Four
are rewritten after a check against the code:

- the keywords score sentence is split in two;
- `mlData` drops the whole `clip` block, as `src/backup.ts` and
  `src/metadata-backup.ts` do;
- a file name gets its ID past 255 bytes and a collection name past
  250, and either is then cut short, as `uniqueNames` does;
- `lastTriedAt` is taken once per run, after its refresh.

The IDs sentence keeps `-1`: the pinned option parser passes a negative
number to a command with no subcommands as an argument, so
`quak get -1` reaches the ID check. Nothing else changes; `make fmt`
reflowed the touched paragraphs.

Model: fable-5-1 (change); opus-5-5 (landing message)
This commit was merged in pull request #230.
This commit is contained in:
2026-10-26 18:59:28 +01:00
parent b5fcbf4400
commit 67794bf5f8
+15 -13
View File
@@ -692,10 +692,10 @@ Update times are in microseconds, as Ente records them.
The JSON also holds the machine-learning data Ente computed for the photo, as
`mlData`. Ente's apps detect faces in each photo and compute a CLIP embedding
for it, a list of 512 numbers that describes what the photo shows. `mlData`
holds everything but that embedding. In its place the JSON holds `keywords`,
derived from the embedding as described under "Keywords". A file with no
machine-learning data has neither field. A file whose data holds no usable
embedding has no `keywords`.
holds everything but the `clip` block, which holds that embedding. In its place
the JSON holds `keywords`, derived from the embedding as described under
"Keywords". A file with no machine-learning data has neither field. A file whose
data holds no usable embedding has no `keywords`.
The backup waits for the library's fetch of machine-learning data to finish
before it writes the JSON files. When a file's data cannot be fetched,
@@ -748,11 +748,11 @@ derives a file's keywords the way the app sorts it. The categories are:
Each category has a query, and a text embedding of that query from Ente's CLIP
text model. A file's score for a category is the cosine similarity of the file's
embedding and the category's: a number from -1 to 1, higher the more alike the
two embeddings are. The file falls in the category when its score reaches the
category's minimum score. The keywords are the titles of the categories the file
falls in, highest score first. A video never falls in a category marked "no
videos", as in the app.
embedding and the category's. That is a number from -1 to 1; the more alike the
two embeddings are, the higher it is. The file falls in the category when its
score reaches the category's minimum score. The keywords are the titles of the
categories the file falls in, highest score first. A video never falls in a
category marked "no videos", as in the app.
#### Collection directories
@@ -775,9 +775,10 @@ ignoring case, each gets its ID added: two albums named `Trip` become
`Trip (10)/` and `Trip (11)/`. Two files in one collection whose titles match,
ignoring case, get their IDs added before the extension: `IMG_0001 (12345).JPG`
and `IMG_0001 (12346).JPG`. A collection named like another collection's JSON
file, such as `Trip.json` beside `Trip`, also gets its ID added. A name too long
for a file name, which most file systems limit to 255 bytes, gets its ID added
too. It is then cut short before the ID, just far enough to fit. IDs never
file, such as `Trip.json` beside `Trip`, also gets its ID added. A file name
longer than 255 bytes, the limit on most file systems, gets its ID added too. So
does a collection name longer than 250 bytes, which leaves room for `.json`.
Either name is then cut short before the ID, just far enough to fit. IDs never
change, so a name stays the same from run to run until such a clash appears or
goes away.
@@ -834,7 +835,8 @@ Each entry holds:
- `fileID` and `title`;
- `classification`: the kind of failure;
- `attempts`: how many runs in a row have failed the file;
- `lastTriedAt`: when it was last tried, as a Unix time in milliseconds;
- `lastTriedAt`: when the run that last tried it finished its refresh, as a Unix
time in milliseconds;
- `error`: the error, as quak printed it.
The kinds are: