OCR Direction 2: keep the N most diverse word samples, not just the newest #16

Merged
daniel merged 4 commits from agent/ocr-sample-diversity into main 2026-10-20 16:37:32 +02:00
Collaborator

Part of #13 (Direction 2, store schema & caps — issue #13 part 1 slice + part 3 word-sample retention). Independent of !12; touches only src/ocr/samples.ts, so it can land in parallel with the scaling MR (!15) and with !12.

Why

addSample (src/ocr/samples.ts:119) keeps only the newest PER_WORD = 3 samples per word:

store.words[word] = [...(store.words[word] ?? []), round(strokes)].slice(-PER_WORD);

The #5 spike showed accumulated samples clearly help, and the scaling headroom is there (DTW ran the full labelled set in well under a second). Keeping the newest 3 is wasteful when the owner writes a word many times: three near-duplicate recent samples cover one way of writing it, while an earlier, differently-slanted/joined instance that would match a future remark is discarded. The whole-word reader (WordReader, src/ocr/words.ts) checks owner samples first, so sample diversity directly drives recall on the owner's own hand.

What to change (src/ocr/samples.ts only)

  1. Raise the per-word cap (e.g. PER_WORD 3 → 8–12; justify against the latency budget the scaling MR !15 establishes — note the two MRs are complementary: !15 bounds read-time work so a larger store stays in budget, this MR grows the store without keeping junk).
  2. Replace the newest-wins .slice(-PER_WORD) in addSample with diversity-preserving retention: when a word is over cap, drop the sample that is most redundant (closest to another kept sample) rather than the oldest, so the kept set spans the owner's variation. Use a cheap shape distance for "closest" — traceOf + dtw from words.ts, or a cloudOf/matchDistance proxy from recognize.ts. Keep newest-last ordering for callers that rely on recency, and keep the existing early-return for empty word/strokes.

Keep addSample's signature and the SampleStore.words: Record<string, Point[][][]> shape unchanged — this is retention policy only, no schema/format change (so no migration needed; a store with ≤3 samples stays valid).

Scope boundary

  • NOT letter/join templates and NOT touching WordReader internals — richer-store child issue, after !12.
  • NOT the read-time shortlisting/latency caps — that is MR !15.
  • NOT the remark/correction caps (REMARKS_KEPT/CORRECTIONS_KEPT) — leave prune alone.

Validation contract

npx vitest run src/__tests__ → PASS, plus a new test in src/__tests__/samples.test.ts (or a new file) that:

  • Red gate (must fail before the change): build a word's samples so the newest PER_WORD are near-duplicates of one style and an earlier sample is the only cover for a second style; a held-out read of the second style via WordReader seeded from store.words is wrong under newest-3 retention. With diversity retention it reads correctly → the test passes only after the change.
  • Assert the kept-sample count respects the new cap, and that adding a near-duplicate of an existing kept sample does not evict a distinct one.

(No flake.nix; use npm install + npx vitest.)

Part of #13 (Direction 2, store schema & caps — issue #13 part 1 slice + part 3 word-sample retention). Independent of !12; touches only `src/ocr/samples.ts`, so it can land in parallel with the scaling MR (!15) and with !12. ## Why `addSample` (`src/ocr/samples.ts:119`) keeps only the newest `PER_WORD = 3` samples per word: ```ts store.words[word] = [...(store.words[word] ?? []), round(strokes)].slice(-PER_WORD); ``` The #5 spike showed accumulated samples clearly help, and the scaling headroom is there (DTW ran the full labelled set in well under a second). Keeping the newest 3 is wasteful when the owner writes a word many times: three near-duplicate recent samples cover one way of writing it, while an earlier, differently-slanted/joined instance that would match a future remark is discarded. The whole-word reader (`WordReader`, `src/ocr/words.ts`) checks owner samples first, so **sample diversity directly drives recall** on the owner's own hand. ## What to change (`src/ocr/samples.ts` only) 1. Raise the per-word cap (e.g. `PER_WORD` 3 → 8–12; justify against the latency budget the scaling MR !15 establishes — note the two MRs are complementary: !15 bounds read-time work so a larger store stays in budget, this MR grows the store without keeping junk). 2. Replace the newest-wins `.slice(-PER_WORD)` in `addSample` with **diversity-preserving** retention: when a word is over cap, drop the sample that is most redundant (closest to another kept sample) rather than the oldest, so the kept set spans the owner's variation. Use a cheap shape distance for "closest" — `traceOf` + `dtw` from `words.ts`, or a `cloudOf`/`matchDistance` proxy from `recognize.ts`. Keep newest-last ordering for callers that rely on recency, and keep the existing early-return for empty word/strokes. Keep `addSample`'s signature and the `SampleStore.words: Record<string, Point[][][]>` shape unchanged — this is retention policy only, no schema/format change (so no migration needed; a store with ≤3 samples stays valid). ## Scope boundary - NOT letter/join templates and NOT touching `WordReader` internals — richer-store child issue, after !12. - NOT the read-time shortlisting/latency caps — that is MR !15. - NOT the remark/correction caps (`REMARKS_KEPT`/`CORRECTIONS_KEPT`) — leave `prune` alone. ## Validation contract `npx vitest run src/__tests__` → PASS, plus a new test in `src/__tests__/samples.test.ts` (or a new file) that: - **Red gate (must fail before the change):** build a word's samples so the newest `PER_WORD` are near-duplicates of one style and an earlier sample is the only cover for a second style; a held-out read of the second style via `WordReader` seeded from `store.words` is wrong under newest-3 retention. With diversity retention it reads correctly → the test passes only after the change. - Assert the kept-sample count respects the new cap, and that adding a near-duplicate of an existing kept sample does not evict a distinct one. (No `flake.nix`; use `npm install` + `npx vitest`.)
claude self-assigned this 2026-10-20 15:32:41 +02:00
Author
Collaborator

🤖 Agent is working on this — turn 35

Last activity: assistant message — updated 14:34:41 UTC

Last message:

Conflict resolved. Summary:

  • Cause: main advanced with !15 (read-time scaling) and the Direction-1 letter-learning work. Both also edit src/ocr/samples.ts, which was the only conflicting file.
  • Resolution: Merged origin/main into the branch and unioned the overlapping header region:
    • Import now includes both cloudOf/matchDistance (my diversity retention) and cutLetters (main's letter learning), plus the shared splitLineInto/splitWords/Point.
    • Kept my exported PER_WORD = 10 and keepDiverse, and kept main's PER_LETTER/LETTER_PLACES + learnLetters.
    • addSample stays word-only; learnCorrection calls both addSample and learnLetters (main's split), so no behavior was dropped on either side. No schema/format change.
  • Verified: tsc -noEmit clean, eslint clean on changed files, npx vitest run src/__tests__ → 677 passed (60 files), including the 24 samples.test.ts cases and the diversity red-gate test.
  • State: merge commit e128695 committed, pushed, and the MR is open and mergeable again. Attestation recorded and a delta comment posted.

Self-merge isn't offered for this project, so I've left it for review.

🤖 **Agent is working on this** — turn 35 _Last activity: assistant message — updated 14:34:41 UTC_ **Last message:** > Conflict resolved. Summary: > > - **Cause:** `main` advanced with !15 (read-time scaling) and the Direction-1 letter-learning work. Both also edit `src/ocr/samples.ts`, which was the only conflicting file. > - **Resolution:** Merged `origin/main` into the branch and unioned the overlapping header region: > - Import now includes both `cloudOf`/`matchDistance` (my diversity retention) and `cutLetters` (main's letter learning), plus the shared `splitLineInto`/`splitWords`/`Point`. > - Kept my exported `PER_WORD = 10` and `keepDiverse`, and kept main's `PER_LETTER`/`LETTER_PLACES` + `learnLetters`. > - `addSample` stays word-only; `learnCorrection` calls both `addSample` and `learnLetters` (main's split), so no behavior was dropped on either side. No schema/format change. > - **Verified:** `tsc -noEmit` clean, `eslint` clean on changed files, `npx vitest run src/__tests__` → **677 passed (60 files)**, including the 24 `samples.test.ts` cases and the diversity red-gate test. > - **State:** merge commit `e128695` committed, pushed, and the MR is open and mergeable again. Attestation recorded and a delta comment posted. > > Self-merge isn't offered for this project, so I've left it for review.
Raise PER_WORD 3 → 10 and, when a word is over cap, drop the most
redundant sample (closest in $P cloud distance to another kept sample)
instead of the oldest. The kept set then spans the owner's variation in
slant/join rather than collapsing onto the newest way of writing a word,
which directly drives WordReader recall on the owner's own hand.

Retention policy only: addSample's signature and the
SampleStore.words shape are unchanged, so a store written with the old
cap stays valid with no migration.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
Author
Collaborator

What changed

  • src/ocr/samples.ts: raised PER_WORD 3 → 10 and replaced newest-wins .slice(-PER_WORD) in addSample with diversity-preserving retention (keepDiverse) — when a word is over cap, the most redundant sample (nearest in $P cloud distance, via cloudOf/matchDistance from recognize.ts) is dropped, not the oldest. Survivors keep newest-last order; ties drop the older sample so recency still breaks even cases.
  • Retention policy only: addSample's signature and SampleStore.words shape are unchanged, so an old ≤3-sample store stays valid — no migration. prune/remark caps untouched; WordReader internals untouched.
  • src/__tests__/samples.test.ts: new diversity-preserving sample retention block + rewrote the old "keeps three samples" test for the new cap.

Verify

Red gate confirmed: with PER_WORD bumped but retention left as newest-wins, the new diversity tests fail at the trusted assertion (the earlier distinct-style sample is evicted); after switching to keepDiverse they pass. The test seeds a WordReader over store.words and reads a held-out remark in a second style whose only cover is an earlier sample — read correctly (trusted:true) only under diversity retention. Also asserts kept count respects the cap and that a near-duplicate never evicts a distinct sample. Full suite npx vitest run src/__tests__ → 671 pass; tsc -noEmit and eslint clean. (No MR test pipeline is configured for this repo — .forgejo/.github workflows are scheduled/tag-triggered only; validation is the local vitest contract.)

Follow-ups

None. Scope boundaries respected — read-time shortlisting/latency caps remain !15's; richer letter/join templates remain the post-!12 child issue.

## What changed - `src/ocr/samples.ts`: raised `PER_WORD` 3 → 10 and replaced newest-wins `.slice(-PER_WORD)` in `addSample` with diversity-preserving retention (`keepDiverse`) — when a word is over cap, the most *redundant* sample (nearest in `$P` cloud distance, via `cloudOf`/`matchDistance` from `recognize.ts`) is dropped, not the oldest. Survivors keep newest-last order; ties drop the older sample so recency still breaks even cases. - Retention policy only: `addSample`'s signature and `SampleStore.words` shape are unchanged, so an old ≤3-sample store stays valid — no migration. `prune`/remark caps untouched; `WordReader` internals untouched. - `src/__tests__/samples.test.ts`: new `diversity-preserving sample retention` block + rewrote the old "keeps three samples" test for the new cap. ## Verify Red gate confirmed: with `PER_WORD` bumped but retention left as newest-wins, the new diversity tests **fail** at the `trusted` assertion (the earlier distinct-style sample is evicted); after switching to `keepDiverse` they **pass**. The test seeds a `WordReader` over `store.words` and reads a held-out remark in a second style whose only cover is an earlier sample — read correctly (`trusted:true`) only under diversity retention. Also asserts kept count respects the cap and that a near-duplicate never evicts a distinct sample. Full suite `npx vitest run src/__tests__` → **671 pass**; `tsc -noEmit` and `eslint` clean. (No MR test pipeline is configured for this repo — `.forgejo`/`.github` workflows are scheduled/tag-triggered only; validation is the local vitest contract.) ## Follow-ups None. Scope boundaries respected — read-time shortlisting/latency caps remain !15's; richer letter/join templates remain the post-!12 child issue.
Owner

@claude resolve merge conflicts

@claude resolve merge conflicts
Author
Collaborator

Since my last update: resolved the merge conflict with main. main had advanced with !15 (read-time scaling) and the Direction-1 letter-learning work, both of which also touch src/ocr/samples.ts — the only conflicting file. I merged origin/main into the branch and unioned the overlap: the import now pulls both cloudOf/matchDistance (diversity) and cutLetters (letter learning); PER_WORD = 10 and keepDiverse are kept alongside main's PER_LETTER/LETTER_PLACES and learnLetters. addSample stays word-only and learnCorrection calls both, matching main's split — no logic lost on either side. No schema/format change.

Verify: tsc -noEmit clean, eslint clean on the changed files, npx vitest run src/__tests__ → 677 passed (60 files), including the diversity red-gate test. Merge commit e128695 pushed; MR is mergeable again.

Since my last update: resolved the merge conflict with `main`. `main` had advanced with !15 (read-time scaling) and the Direction-1 letter-learning work, both of which also touch `src/ocr/samples.ts` — the only conflicting file. I merged `origin/main` into the branch and unioned the overlap: the import now pulls both `cloudOf`/`matchDistance` (diversity) and `cutLetters` (letter learning); `PER_WORD = 10` and `keepDiverse` are kept alongside main's `PER_LETTER`/`LETTER_PLACES` and `learnLetters`. `addSample` stays word-only and `learnCorrection` calls both, matching main's split — no logic lost on either side. No schema/format change. Verify: `tsc -noEmit` clean, `eslint` clean on the changed files, `npx vitest run src/__tests__` → **677 passed (60 files)**, including the diversity red-gate test. Merge commit `e128695` pushed; MR is mergeable again.
daniel merged commit bf62ee3f37 into main 2026-10-20 16:37:32 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
daniel/obsidian-remarkable-round-trip!16
No description provided.