feat(categorisation): bootstrap the classifier from the merchant dictionary

[suiramdev]

Summary

ADR-001 left the classifier a stub "until training data exists", pointing at a k-anonymity contribution endpoint that does not exist yet — so on a fresh instance the trainer had nothing to read. This adds the merchant dictionary as a bootstrap prior (real, licensed, already in the data pipeline), gates the write on held-out precision at the confidence the pipeline actually writes a category at, and measures that the bootstrap fails: 43.4% on a full local build and 72.4% on the CI release data-2026-09-01, against a 75% bar, so no weights are written and the classifier stays inert. The data workflow now runs that trainer and attaches weights to the data-* release only when the gate passes. Read docs/adr/004 §6–7 first — the negative result is the deliverable.

Motivation

• The obvious shortcut — synthesising plausible bank descriptors and fitting to them — would write confident wrong categories into budgets and suppress the corrections that are the only real training signal. §6 closes it with a number instead of an argument.
• Nothing gated model quality: a bad run would have shipped silently.
• The gate needed the right operating point. resolve.ts discarded anything below 0.7 as an unnamed literal while predict() abstained at 0.5; the trainer was measuring a population that never reaches a budget. That floor is now the shared MODEL_ACCEPT_THRESHOLD.
• Training used Math.random(), so the reproducibility ADR-001 claimed was never true.

Drawbacks

• train:model exits non-zero whenever the gate refuses, which is every run today. Intentional — CI must not ship an unevaluated model — but it is not a green command until a model passes.
• A missing dictionary artifact now refuses instead of writing a corrections-only model. That is a deliberate capability regression: such a model cannot be evaluated, so it must not ship.
• The holdout is dictionary-only, so contributed corrections cannot clear this gate by arriving; §4 records that the gate must be revised to hold them out first. Not built, because zero corrections exist anywhere yet.
• Reported precision covers dictionary merchant names, not real bank descriptors. A floor, not a production figure.
• Half the local build's corpus is Wikidata categorised by SIRENE name-matching; the CI release has almost none of it and scores 29 points higher. ADR §7 lists the confounds — it is two observations, not an ablation.

Prior art

• ADR-001 §4 already builds the dictionary from open data (NSI BSD-3-Clause, Wikidata CC0, SIRENE); this reuses that provenance discipline rather than inventing a source.
• Rejected: a random split over strings, which scores aliases of merchants the model trained on and measures memorisation.
• Rejected: pooling country slices into one precision figure, which lets a strong slice carry a weak one — and which slice is weakest is not stable across epoch counts.

Notes

• This branch carries feat(categorisation): run deterministic layers before the AI classifier #9. It was rebased onto main, and since feat(categorisation): run deterministic layers before the AI classifier #9 is still open its two commits (feat: run deterministic layers…, Address PR review feedback) came along. The PR diff is 23 files vs main; my change is the last two commits only — 8 files, git diff bfffdbf..HEAD. Merging this merges feat(categorisation): run deterministic layers before the AI classifier #9's work too. Review feat(categorisation): run deterministic layers before the AI classifier #9 there, or merge it first and this collapses to the two commits.
• No visual change; no user-facing behaviour changes. The 0.7 floor is unchanged in value, only named.
• Tests: new dictionary.test.ts (4 cases, mutation-checked). It occupies the real artifact path, so it restores a leftover backup before swapping — the artifact is gitignored and costs a full build:data to regenerate.
• Docs: docs/adr/004 added, docs/adr/001 cross-referenced, packages/api/data/README.md updated. No apps/fumadocs change — budget.mdx already says the classifier runs only where a trained model is installed, which stays true.
• No artifacts committed. generate-data.yml trains --dictionary-only after the dictionary build and adds model-weights.json to the release tarball only on a gate pass; a refusal (exit 2) keeps the run green with the curves in the job summary. build:data deletes a local weights file before downloading, so only a release installs one. Not yet exercised on GitHub — it triggers on main only; dispatch it once after merge. Still open before a passing model ships: the sparse JSON serialisation is 42.9 MB gzipped, over ADR-001's budget, and model.ts verifies no signature (neither does the CI-built dictionary today — the workflow signs nothing).
• Reviewed via the review gate: approved, empty findings, after three rounds. Every quantitative claim in the ADR and README was reproduced independently against the artifact.
• Verification gap: Docker wedged on my machine partway through, so the 7 Prisma-backed tests could not be re-run at the final commit. They passed 215/215 earlier in the session; 35 DB-free tests pass now, and no Prisma-touching code changed.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 440d54cc-dd58-4dc4-b34e-96106c68ca72

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}