cry-search 2.1.1 → 2.3.0

package/CLAUDE.md

@@ -387,6 +387,7 @@ src/
 │   │   ├── searchAndRank.ts           # Wrapper w/ exactKeysFn boost + fallback
 │   │   ├── scoring.ts                 # scoreOne, scoreOrderAndPresence, scoreBag
 │   │   ├── syncSearchArrayMetadata.ts
+│   │   ├── matchMany.ts                # Mass matching (matchMany / matchManySync)
 │   │   └── AugmentedMetadata.ts
 │   └── SearchUniverse.ts              # Multi-collection manager
 ├── utils/
@@ -399,11 +400,29 @@ src/
 │   ├── sanitiseString.ts
 │   ├── tokenize.ts
 │   └── compareTokenized.ts          # Jaccard token-set similarity (0..1)
+├── vet/                               # Domain extension, published as `cry-search/vet`
+│   ├── index.ts                       # Public API of the subpath
+│   ├── spec.ts                        # vetArtikelSpec / vetQueryOpts (field normalizers)
+│   ├── normalizatorji.ts              # Units, decimals, brands, quantities, sizes, species
+│   ├── ocena.ts                       # oceniPar: score + acceptance rule + reason
+│   ├── uparjanje.ts                   # pripraviVetIndeks, upariArtikle/upariVse(Sync)
+│   └── data/                          # Generated tables (enote.ts, znamke.gen.ts)
 ├── types/
 │   └── index.ts
 └── index.ts                           # Public API
 ```
 
+The core stays domain-free. It only exposes narrow seams for domain modules:
+`SearchableObjectSpec.valueNormalizers` (index side, may return `{ text, classes }`),
+`SearchOpts.queryNormalizers` + `normalizeQueryWithOpts` (query side) and `matchMany` /
+`matchManySync` (mass matching with optional domain `rank`/`accept`). Soft domain data lives
+in `metadata.classes` (never in the token stream, so retrieval speed is unaffected) and is
+read back with `itemClasses(metadata, id)`. Domain rules belong in `src/vet/` (see `VET.md`).
+
+Build note: `cry-vetzdravila` is an optional peer dependency and is marked external in the
+bundles (`bun build --external cry-vetzdravila`), so core consumers do not pull in its
+`xlsx`/`pdfjs-dist` dependencies.
+
 ## Coding rules
 
 1. each function is in separate file
@@ -415,6 +434,13 @@ src/
 
 ## Testing
 
+0. Quality first: `bun test` — thresholds for `cry-search/vet` live in
+   `test/vet/pari.test.ts` (recall@1/3, precision@1 per group) and the golden output in
+   `test/vet/zlati-gw.json`.
+0b. Speed separately: `bun run bench` (not part of `bun test`, not in CI) measures index build
+   and mass-pairing throughput against the stored baseline `test/vet/bench-osnova.json` and
+   fails only when latency grows > 20 % or `uspeh@1` drops > 2 pp. Refresh the baseline
+   deliberately with `bun run bench --zapisi-osnovo`.
 1. Large real-life datasets are in ./test-data (arikli, stranke, pacienti).
 2. tests are in ./test
 3. tests per implementation are in ./test/(IMPLEMENTATION)

package/README.md

@@ -532,6 +532,19 @@ See [CLAUDE.md](./CLAUDE.md) for the complete technical specification including:
 
 See [LICENSE.md](./LICENSE.md) for license terms.
 
+### Measuring performance
+
+Quality thresholds live in the test suite; performance is measured separately (it depends on
+machine load, so it must not fail the quality tests):
+
+```bash
+bun run bench                   # measure and compare against test/vet/bench-osnova.json
+bun run bench --zapisi-osnovo   # deliberately refresh the baseline
+```
+
+The bench fails only when latency grows by more than 20 % or `uspeh@1` drops by more than
+2 percentage points.
+
 ## Domain extensions and the `cry-search/vet` entry point
 
 The core exposes a narrow seam for domain logic (all optional, no behaviour change when unused):
@@ -545,6 +558,31 @@ The core exposes a narrow seam for domain logic (all optional, no behaviour chan
   collection as queries; asynchronous iterator (chunked), top-K candidates per item with scores,
   optional `samoEnolicno` (greedy 1:1), optional domain `rank`/`accept`, and
   `alternativnePoizvedbe` (retry with a narrowed query).
+- `matchManySync(prepared, queries, opts)` — the same in one shot, for callers whose API is not
+  async (no I/O happen in the hot path, so the sync variant is equivalent).
+
+The veterinary module also ships a **bilingual SI↔EN lexicon** (`data/prevodi.ts`, normalizer
+`prevodiNormalizator`): English catalogue names (`Monge dog rabbit rice&potatoes 2,5kg`) pair with
+Slovenian Pantheon names (`MONGE DOG ADULT zajec, riž, krompir 2,5kg`). The same table is applied
+to index values and queries (symmetry is required — one-sided translation makes results worse),
+brand names are never translated, and marketing/connector words (`care`, `for`, `with` …) are
+dropped. `razdeljevalciNormalizator` splits `&`/`+`/`/` inside names, and life stages
+(`puppy`/`kitten`/`adult`/`senior`) become the soft class `starost`.
+
+For a **user-facing search field** the same lexicon must be in the search index, but the
+class-producing normalizers have to stay out (a user searching `200ml`, `PRIB` or `adult` must
+still find those rows). That is what `vetIskalniSpec()` / `vetIskalniQueryOpts()` are for:
+
+```typescript
+import { vetIskalniSpec, vetIskalniQueryOpts } from 'cry-search/vet';
+
+const metadata = createSearchArrayMetadata(data, vetIskalniSpec({ polja: ['acName', 'acIdent'] }));
+searchAndRank('monge rabbit', data, metadata, vetIskalniQueryOpts({ exactKeysFn }));
+// → najde `MONGE DOG ADULT zajec, riž, krompir 2,5kg` (leksikon rabbit → zajec)
+```
+
+With `vrniNesprejete: true` the domain module keeps candidates that fail the acceptance rule and
+marks them (`sprejeto: false`) instead of dropping them — useful in UIs where the user decides.
 
 A ready-made veterinary implementation ships as a subpath (optional peer dependency on
 `cry-vetzdravila`):

package/dist/vet/data/prevodi.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Dvojezični leksikon SI↔EN za veterinarske nazive artikelov (živila + zdravila).
+ *
+ * Zakaj: isti artikel ima v klik.vetu pogosto **angleški** naziv (vnesen po
+ * dobaviteljskem katalogu), v Pantheonu pa **slovenskega** (ali obratno — pri
+ * znamkah N&D/Hills je pantheonov naziv pogosto v angleščini, klik.vetov pa
+ * slovenski). Brez preslikave iskalnik takih parov NE NAJDE, ker se ključne besede
+ * (`rabbit`/`zajec`, `rice`/`riž`, `codfish`/`polenovka`) ne ujemajo:
+ *
+ *   „Monge dog rabbit rice&potatoes 2,5kg“ ↔ „MONGE DOG ADULT zajec, riž, krompir 2,5kg“
+ *   → brez leksikona 0 kandidatov, z leksikonom pravi par prvi (`sprejeto: true`).
+ *
+ * Pravila (izmerjeno na podatkih tackakp + SI_TACKA, 2026-10-04):
+ *   - preslikava je **simetrična**: ista tabela se uporabi na INDEKSU in na
+ *     POIZVEDBI (normalizator + ocenjevalec), zato sta obe strani vedno v kanonični
+ *     obliki — tudi kadar sta obe angleški ali obe slovenski;
+ *   - ključi so normalizirani (male črke, brez šumnikov, brez ločil), kanonične
+ *     vrednosti so prav tako brez šumnikov (jedro jih itak normalizira);
+ *   - **znamk in učinkovin ne prevajamo** (Monge, Royal Canin, N&D, Hills, Brit,
+ *     Flamingo, Trixie, Kong, Kerbl, Rogz, Ferplast, Flexi, JBL, Rinti, Dubex, Sera,
+ *     Oasy, Vetlife, Dingo, Matis, Besta, Ferribella, MEDROL …) — zanje skrbi
+ *     `znamkaNormalizator`; v tem seznamu jih namenoma NI;
+ *   - besed, ki so v obeh jezikih enake (`light`, `mini`, `maxi`, `gel`, `spot`,
+ *     `tuna`, `premium`, `hairball` …), NI na seznamu — preslikava bi bila odveč;
+ *   - okrajšava `MED` (= „medium“) je namenoma izven te tabele: `med` je v slovenščini
+ *     tudi „honey“ („z medom“ je v tackakp 497 artikelov), zato jo rešuje ciljno
+ *     pravilo v `razdeljevalciNormalizator` (`MED&MAXI` → `MEDIUM MAXI`).
+ *
+ * Vzdrževanje: kandidate za dodajanje izlušči diagnostični skript
+ * `panthenImport/src/debug/besedisceZaLeksikon.ts` (`--kandidati`).
+ */
+/**
+ * Angleške (in okrajšane) besede → kanonična slovenska oblika (brez šumnikov).
+ *
+ * Vrednost je lahko tudi večbesedna (`granatno jabolko`), tako se „POMEG“ in
+ * „granatno jabolko“ ujameta kot ista dva žetona.
+ */
+export declare const PREVODI: Record<string, string>;
+/**
+ * Vezniki in marketinške besede, ki ne nosijo pomena izdelka — iz besedila se
+ * ODSTRANIJO (brez razreda). Merjeno: par „urinary care“ ↔ „urinarne“ je imel
+ * zaradi `care` pokritost kandidata 50 % namesto 100 %.
+ */
+export declare const STOP_BESEDE: string[];
+/**
+ * Življenjska stopnja → kanonična oblika, ki postane RAZRED `starost`.
+ *
+ * Stopnja je močan razločevalnik (mladič proti odraslemu je drug izdelek), a jo
+ * nazivi navajajo nedosledno, zato razred (kazen ob nasprotju), ne trdi žeton.
+ * Zajema tudi angleške zapise in okrajšave, ker so v podatkih pogosti.
+ */
+export declare const STAROSTI: Record<string, string>;
+/**
+ * Angleške velikosti → kanonična velikost (isti ključi kot `VELIKOSTI_SINONIMI`).
+ *
+ * `mini` in `maxi` namenoma OSTAJAJO besede: uporablja jih obe strani enako, v
+ * linijah RC/N&D pa pomenita razred velikosti. V razred gredo le nedvoumne.
+ */
+export declare const VELIKOSTI_EN: Record<string, string>;
+/** Okrajšave velikosti, ki se v Pantheonu pojavljajo s `&` (`MED&MAXI`) — ciljno pravilo. */
+export declare const VELIKOSTI_OKRAJSAVE: Record<string, string>;
+/** Izvoz za teste in diagnostične skripte. */
+export declare const PREVODI_VIR = "ro\u010Dno kurirano 2026-10-04 (besedi\u0161\u010De izmerjeno v tackakp + SI_TACKA)";
+//# sourceMappingURL=prevodi.d.ts.map

package/dist/vet/data/prevodi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prevodi.d.ts","sourceRoot":"","sources":["../../../src/vet/data/prevodi.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA0T1C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,EAiB/B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqB3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO/C,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAItD,CAAC;AAEF,8CAA8C;AAC9C,eAAO,MAAM,WAAW,wFAAyE,CAAC"}