@fangorn-network/westmarch 0.0.8-dev → 0.0.10-dev

package/consume/embed.js

@@ -152,12 +152,14 @@ export function packVec(vec) {
     return btoa(s);
 }
 
-/** base64 int8 → Float32Array. Returns null on anything malformed — a bad vector
+/** base64 int8 → Float16Array (Float32Array where there is none). Returns null on anything malformed — a bad vector
  *  must degrade that row to lexical, never throw mid-search. */
 export function unpackVec(b64) {
     try {
         const s = atob(b64);
-        const out = new Float32Array(s.length);
+        // Half the memory of Float32 where the browser has it: every row holds one of these, and
+        // an int8 source loses nothing at 16 bits. Consumers read plain numbers either way.
+        const out = new (globalThis.Float16Array ?? Float32Array)(s.length);
         for (let i = 0; i < s.length; i++) {
             const b = s.charCodeAt(i);
             out[i] = (b > 127 ? b - 256 : b) / 127;

package/consume/taste.js

@@ -120,11 +120,22 @@ export const GAMMA = 0.6;
  */
 export const score = (row, t) => {
     if (!row?.vector || !t) return null;
-    const r = { vector: row.vector, norm: row.norm ?? norm(row.vector) };
-    const pos = cosine(r, t.q, norm(t.q));
+    // Called once per row of the catalog: the taste's own norms are the same for every one of them, so they are
+    // worked out once per taste (not per row, which doubled discover's time at 124k rows), and a row that already
+    // carries its norm (every shard row does) is used as it is rather than copied.
+    const n = normsOf(t);
+    const r = row.norm ? row : { vector: row.vector, norm: norm(row.vector) };
+    const pos = cosine(r, t.q, n.q);
     if (!t.no) return pos;
-    return pos - GAMMA * Math.max(0, cosine(r, t.no, norm(t.no)));
+    return pos - GAMMA * Math.max(0, cosine(r, t.no, n.no));
 };
+// Keyed on the vectors, not the taste object: a caller that swaps `t.q` (importTaste, a drifted copy) gets fresh norms.
+const _norms = new WeakMap();
+function normsOf(t) {
+    let n = _norms.get(t);
+    if (!n || n.qv !== t.q || n.nov !== t.no) _norms.set(t, (n = { qv: t.q, nov: t.no, q: norm(t.q), no: t.no ? norm(t.no) : 1 }));
+    return n;
+}
 
 /** The best `limit` rows for a taste. `exclude` drops rows the taste was built
  *  from — recommending someone the thing they just told you they liked is the
@@ -164,9 +175,18 @@ export function discover(rows, likes = [], dislikes = [], { limit = 20, seed = 1
     const t = taste(likes, dislikes, { drift: knobs.lookahead });
     if (!t) return { taste: null, knobs: { ...knobs, seed }, picks: [] };
     const skip = new Set([...exclude, ...likes.map((x) => x.id), ...dislikes.map((x) => x.id)]);
-    let ranked = rows.filter((r) => r.vector && !skip.has(r.id)).map((row) => ({ row, s: score(row, t) })).sort((a, b) => b.s - a.s);
-    const start = Math.round(knobs.reach * Math.min(400, ranked.length / 4));
-    ranked = ranked.slice(start, start + 300);
+    // Only the top `start + 300` are ever looked at, so keep just those as the rows go by instead of sorting the
+    // whole catalog (the same order a stable sort gives: a tie stays behind the row it tied with).
+    const pool = rows.filter((r) => r.vector && !skip.has(r.id));
+    const start = Math.round(knobs.reach * Math.min(400, pool.length / 4)), keep = start + 300;
+    const top = [];
+    for (const row of pool) {
+        const s = score(row, t);
+        if (top.length === keep && !(s > top[keep - 1].s)) continue;
+        let i = top.length; while (i > 0 && top[i - 1].s < s) i--;
+        top.splice(i, 0, { row, s }); if (top.length > keep) top.pop();
+    }
+    let ranked = top.slice(start);
     if (knobs.surprise) {
         let a = (Number(seed) >>> 0) || 1;
         const rand = () => { a = (a + 0x6d2b79f5) >>> 0; let x = Math.imul(a ^ (a >>> 15), 1 | a); x ^= x + Math.imul(x ^ (x >>> 7), 61 | x); return ((x ^ (x >>> 14)) >>> 0) / 4294967296; };

package/dist/ts/eval.js

@@ -94,7 +94,8 @@ async function grade(rows, roles, checks, qv, known) {
         }
         else {
             const k = c.k ?? 5, ok = compile(c.expect);
-            const hits = search(rows, c.q, roles, { qv: await qv(c.q), limit: k }).map((h) => byId.get(h.id));
+            // `of` scopes the search to the rows a surface searches (a page tab, a tool's filter).
+            const hits = search(c.of ? rows.filter(compile(c.of)) : rows, c.q, roles, { qv: await qv(c.q), limit: k }).map((h) => byId.get(h.id));
             const score = round(hits.filter(ok).length / k);
             out.push({ id: c.id, kind: "search", score, pass: score >= (c.min ?? 0), top: hits.slice(0, 3).map((r) => titleOf(r, roles).slice(0, 90)), ...goal });
         }
@@ -271,6 +272,8 @@ async function selfcheck() {
     assert(r.wells.score === 0 && !r.wells.pass, "a count with nothing to reach fails (min defaults to 1)");
     assert(r.addresses.score === 25 && r.addresses.pass, `records is a percentage: ${r.addresses.score}`);
     const [scoped] = await grade(rows, roles, [{ id: "s", kind: "records", of: { where: { city: "Stevens Point" } }, expect: { match: { text: "Rd" } }, max_pct: 100 }], async () => null, 0);
+    const [sq] = await grade(rows, roles, [{ id: "sq", q: "rezoning", of: { where: { city: "Stevens Point" } }, expect: { match: { heading: "rezon" } }, k: 1 }], async () => null, 0);
+    assert(sq.score === 0 && !/Rezoning/.test(sq.top?.join() ?? ""), `\`of\` scopes a search check to its rows: ${JSON.stringify(sq)}`);
     assert(scoped.score === 50, `\`of\` narrows the rows a record check counts: ${scoped.score}`);
     assert(r["known@10"].score === 1, "every title finds its own row");
     // Coverage, and goals scored apart.

package/docs/app-to-agent.md

@@ -134,6 +134,10 @@ any fall fails, because a recipe that loses a town has dropped its records.
 `match` (a field, or several joined by `|`, to a regex; case-insensitive unless written
 `/re/flags`), `not`. Relevance is a predicate and not a list of record ids, because ids
 are content hashes and a recipe change that re-parses records changes every one.
+The same predicate as `of` scopes a check to some rows: on a `records` or `coverage` check
+it narrows what is counted, and on a search check it narrows what is searched, to match a
+surface that filters (a page tab for people, a type an agent tool reads), so one type of
+record growing cannot crowd the questions another surface answers.
 Without labels, it also searches 200 sampled rows by their own titles (`known@1`, `known@10`).
 
 Worse is: mean precision or `known@10` down more than 0.05, any question the base

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangorn-network/westmarch",
-  "version": "0.0.8-dev",
+  "version": "0.0.10-dev",
   "description": "Publisher and consumer surfaces for a Fangorn app: shape a graph, publish it, read it back as a searchable, agent-drivable catalog",
   "license": "MIT",
   "type": "module",

package/publish/eval.ts

@@ -56,7 +56,7 @@ import { EMBED_MODEL, embedQueryDirect } from "@fangorn-network/westmarch/embed"
 
 type Pred = { where?: Record<string, string>; match?: Record<string, string>; not?: Pred };
 type Check = { id: string; goal?: string } & (
-    | { kind?: "search"; q: string; k?: number; expect: Pred; min?: number }
+    | { kind?: "search"; q: string; k?: number; of?: Pred; expect: Pred; min?: number }
     | { kind: "count"; where?: Record<string, string>; expect?: Pred; min?: number; max?: number }
     | { kind: "records"; of?: Pred; expect: Pred; max_pct: number; hard?: boolean }
     | { kind: "coverage"; field: string; values: string[]; weights?: Record<string, number>; of?: Pred; min?: number });
@@ -107,7 +107,8 @@ async function grade(rows: Row[], roles: Roles, checks: Check[], qv: QueryVector
             out.push({ id: c.id, kind: "coverage", score, pass: score >= (c.min ?? 0), top: missing.slice(0, 10), ...goal });
         } else {
             const k = c.k ?? 5, ok = compile(c.expect);
-            const hits = search(rows, c.q, roles, { qv: await qv(c.q), limit: k }).map((h) => byId.get(h.id)!);
+            // `of` scopes the search to the rows a surface searches (a page tab, a tool's filter).
+            const hits = search(c.of ? rows.filter(compile(c.of)) : rows, c.q, roles, { qv: await qv(c.q), limit: k }).map((h) => byId.get(h.id)!);
             const score = round(hits.filter(ok).length / k);
             out.push({ id: c.id, kind: "search", score, pass: score >= (c.min ?? 0), top: hits.slice(0, 3).map((r) => titleOf(r, roles).slice(0, 90)), ...goal });
         }
@@ -276,6 +277,8 @@ async function selfcheck() {
     assert(r.wells.score === 0 && !r.wells.pass, "a count with nothing to reach fails (min defaults to 1)");
     assert(r.addresses.score === 25 && r.addresses.pass, `records is a percentage: ${r.addresses.score}`);
     const [scoped] = await grade(rows, roles, [{ id: "s", kind: "records", of: { where: { city: "Stevens Point" } }, expect: { match: { text: "Rd" } }, max_pct: 100 }], async () => null, 0);
+    const [sq] = await grade(rows, roles, [{ id: "sq", q: "rezoning", of: { where: { city: "Stevens Point" } }, expect: { match: { heading: "rezon" } }, k: 1 }], async () => null, 0);
+    assert(sq.score === 0 && !/Rezoning/.test(sq.top?.join() ?? ""), `\`of\` scopes a search check to its rows: ${JSON.stringify(sq)}`);
     assert(scoped.score === 50, `\`of\` narrows the rows a record check counts: ${scoped.score}`);
     assert(r["known@10"].score === 1, "every title finds its own row");