sensemaking 0.15.4 → 0.16.0

package/dist/esm/embed/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/embed/identity.ts"],"sourcesContent":["import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\n\n// HF cache layout, no network: ~/.sense/models/models--<org>--<name>/{refs/main,\n// snapshots/<sha>/<files>}, files stored directly (hf_hub's blobs/symlinks layer skipped).\n\nexport const MODEL_FILES = ['model.safetensors', 'tokenizer.json'];\n// The pair, for messages that name what a local model directory must contain.\nexport const MODEL_FILENAMES = MODEL_FILES.join(' and ');\n\n// A Hugging Face repo id: one slash, HF's charset. Anything else is a path, used as one rather\n// than resolved against the HF cache.\nconst HF_MODEL_ID = /^[A-Za-z0-9][\\w.-]*\\/[A-Za-z0-9][\\w.-]*$/;\n\nexport function isDownloadable(model: string): boolean {\n  return HF_MODEL_ID.test(model);\n}\n\nfunction repoDir(model: string): string {\n  const [org, name] = model.split('/');\n  return join(homedir(), '.sense', 'models', `models--${org}--${name}`);\n}\n\nexport function refsMainPath(model: string): string {\n  return join(repoDir(model), 'refs', 'main');\n}\n\n// What `main` last resolved to, read from disk -- no network. Undefined until some resolution\n// (a download or an explicit prefetch) has written it once.\nexport function readRef(model: string): string | undefined {\n  const p = refsMainPath(model);\n  if (!existsSync(p)) return undefined;\n  const sha = readFileSync(p, 'utf8').trim();\n  return sha.length > 0 ? sha : undefined;\n}\n\n// A recorded ref pins until its snapshot directory is removed; nothing here re-resolves it.\nexport function writeRef(model: string, sha: string): void {\n  mkdirSync(join(repoDir(model), 'refs'), { recursive: true });\n  writeFileSync(refsMainPath(model), sha);\n}\n\nexport function snapshotDir(model: string, sha: string): string {\n  return join(repoDir(model), 'snapshots', sha);\n}\n\n// Languages describe the repo, not one weight snapshot, so this lives beside refs/, not\n// inside a snapshot dir.\nexport function languagesPath(model: string): string {\n  return join(repoDir(model), 'languages.json');\n}\n\n// undefined means \"never resolved yet\"; an empty array is a resolved fact (checked, none\n// declared) and is cached the same way, so a languageless model is not re-fetched every run.\nexport function readLanguages(model: string): string[] | undefined {\n  const p = languagesPath(model);\n  if (!existsSync(p)) return undefined;\n  try {\n    return JSON.parse(readFileSync(p, 'utf8'));\n  } catch {\n    return undefined;\n  }\n}\n\nexport function writeLanguages(model: string, languages: string[]): void {\n  mkdirSync(repoDir(model), { recursive: true });\n  writeFileSync(languagesPath(model), JSON.stringify(languages));\n}\n\n// A local directory the caller manages, or the resolved snapshot once `main` is pinned; an HF\n// id with no recorded ref yet has no known snapshot, so this names the (fileless) repo dir.\nexport function modelDir(model: string): string {\n  if (!isDownloadable(model)) return model;\n  const sha = readRef(model);\n  return sha ? snapshotDir(model, sha) : repoDir(model);\n}\n\n// Both files, so an interrupted download reads as absent and the next one resumes it.\nexport function hasModelFiles(model: string): boolean {\n  const dir = modelDir(model);\n  return MODEL_FILES.every((file) => existsSync(join(dir, file)));\n}\n\n// Weight identity for the signature, no network: a HF id's resolved sha, or the two\n// files' size+mtime for a local path. Undefined when nothing is known yet.\nexport function modelIdentity(model: string): string | undefined {\n  if (isDownloadable(model)) return readRef(model);\n  const dir = modelDir(model);\n  const parts: string[] = [];\n  for (const file of MODEL_FILES) {\n    try {\n      const st = statSync(join(dir, file));\n      parts.push(`${st.size}:${Math.trunc(st.mtimeMs)}`);\n    } catch {\n      return undefined;\n    }\n  }\n  return parts.join(',');\n}\n"],"names":["existsSync","mkdirSync","readFileSync","statSync","writeFileSync","homedir","join","MODEL_FILES","MODEL_FILENAMES","HF_MODEL_ID","isDownloadable","model","test","repoDir","org","name","split","refsMainPath","readRef","p","undefined","sha","trim","length","writeRef","recursive","snapshotDir","languagesPath","readLanguages","JSON","parse","writeLanguages","languages","stringify","modelDir","hasModelFiles","dir","every","file","modelIdentity","parts","st","push","size","Math","trunc","mtimeMs"],"mappings":"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"}

package/dist/esm/embed/langfit.d.ts

@@ -0,0 +1,6 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { EmbedProvider } from './types.js';
+type LangCounts = Record<string, number>;
+export declare function languageDistribution(db: DatabaseSync): LangCounts | undefined;
+export declare function checkLanguageFit(db: DatabaseSync, provider: EmbedProvider, texts: string[]): Promise<void>;
+export {};

package/dist/esm/embed/langfit.js

@@ -0,0 +1,44 @@
+import { getMeta, setMeta } from '../db/shared.js';
+import { SenseError } from '../errors.js';
+import { toIso3 } from './languages.js';
+const META_KEY = 'embed_languages';
+// franc's own reliability floor is a handful of characters; this is a cheap upper bound, not a
+// per-chunk minimum -- a short chunk is simply more likely to come back 'und' (unclassified).
+const SAMPLE_CHARS = 300;
+// A majority computed over a handful of chunks is noise, not a corpus signal; the decision rule
+// never fires below this many classified chunks, declared languages or not.
+const MIN_CLASSIFIED = 10;
+export function languageDistribution(db) {
+    const raw = getMeta(db, META_KEY);
+    return raw ? JSON.parse(raw) : undefined;
+}
+function classify(franc, text) {
+    const code = franc(text.slice(0, SAMPLE_CHARS));
+    return code === 'und' ? undefined : code;
+}
+// Merges chunk texts into the persisted distribution; throws (without persisting) if the model
+// declares languages and a clear majority classified so far is not among them.
+export async function checkLanguageFit(db, provider, texts) {
+    var _languageDistribution;
+    if (texts.length === 0) return;
+    const { franc } = await import('franc-min');
+    const persisted = (_languageDistribution = languageDistribution(db)) !== null && _languageDistribution !== void 0 ? _languageDistribution : {};
+    const merged = {
+        ...persisted
+    };
+    for (const text of texts){
+        var _merged_code;
+        const code = classify(franc, text);
+        if (code) merged[code] = ((_merged_code = merged[code]) !== null && _merged_code !== void 0 ? _merged_code : 0) + 1;
+    }
+    const total = Object.values(merged).reduce((a, b)=>a + b, 0);
+    if (provider.languages && provider.languages.length > 0 && total >= MIN_CLASSIFIED) {
+        const declared = new Set(provider.languages.map(toIso3));
+        const [majorityLang, majorityCount] = Object.entries(merged).sort((a, b)=>b[1] - a[1])[0];
+        if (majorityCount / total >= 0.5 && !declared.has(majorityLang)) {
+            const pct = Math.round(majorityCount / total * 100);
+            throw new SenseError('EMBED_MODEL_MISMATCH', `embed model ${provider.id} declares languages [${provider.languages.join(', ')}], but ${pct}% of this tree's classified text is "${majorityLang}" (ISO 639-3), which is not among them; choose a model for this tree's languages: \`sense init --model ...\`, see the sense-setup skill or INTEGRATIONS.md`);
+        }
+    }
+    setMeta(db, META_KEY, JSON.stringify(merged));
+}

package/dist/esm/embed/langfit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/embed/langfit.ts"],"sourcesContent":["import type { DatabaseSync } from 'node:sqlite';\nimport { getMeta, setMeta } from '../db/shared.ts';\nimport { SenseError } from '../errors.ts';\nimport { toIso3 } from './languages.ts';\nimport type { EmbedProvider } from './types.ts';\n\nconst META_KEY = 'embed_languages';\n// franc's own reliability floor is a handful of characters; this is a cheap upper bound, not a\n// per-chunk minimum -- a short chunk is simply more likely to come back 'und' (unclassified).\nconst SAMPLE_CHARS = 300;\n// A majority computed over a handful of chunks is noise, not a corpus signal; the decision rule\n// never fires below this many classified chunks, declared languages or not.\nconst MIN_CLASSIFIED = 10;\n\ntype LangCounts = Record<string, number>;\n\nexport function languageDistribution(db: DatabaseSync): LangCounts | undefined {\n  const raw = getMeta(db, META_KEY);\n  return raw ? JSON.parse(raw) : undefined;\n}\n\nfunction classify(franc: (text: string) => string, text: string): string | undefined {\n  const code = franc(text.slice(0, SAMPLE_CHARS));\n  return code === 'und' ? undefined : code;\n}\n\n// Merges chunk texts into the persisted distribution; throws (without persisting) if the model\n// declares languages and a clear majority classified so far is not among them.\nexport async function checkLanguageFit(db: DatabaseSync, provider: EmbedProvider, texts: string[]): Promise<void> {\n  if (texts.length === 0) return;\n  const { franc } = await import('franc-min');\n  const persisted = languageDistribution(db) ?? {};\n  const merged = { ...persisted };\n  for (const text of texts) {\n    const code = classify(franc, text);\n    if (code) merged[code] = (merged[code] ?? 0) + 1;\n  }\n\n  const total = Object.values(merged).reduce((a, b) => a + b, 0);\n  if (provider.languages && provider.languages.length > 0 && total >= MIN_CLASSIFIED) {\n    const declared = new Set(provider.languages.map(toIso3));\n    const [majorityLang, majorityCount] = Object.entries(merged).sort((a, b) => b[1] - a[1])[0];\n    if (majorityCount / total >= 0.5 && !declared.has(majorityLang)) {\n      const pct = Math.round((majorityCount / total) * 100);\n      throw new SenseError(\n        'EMBED_MODEL_MISMATCH',\n        `embed model ${provider.id} declares languages [${provider.languages.join(', ')}], but ${pct}% of this tree's classified text is \"${majorityLang}\" (ISO 639-3), which is not among them; choose a model for this tree's languages: \\`sense init --model ...\\`, see the sense-setup skill or INTEGRATIONS.md`\n      );\n    }\n  }\n  setMeta(db, META_KEY, JSON.stringify(merged));\n}\n"],"names":["getMeta","setMeta","SenseError","toIso3","META_KEY","SAMPLE_CHARS","MIN_CLASSIFIED","languageDistribution","db","raw","JSON","parse","undefined","classify","franc","text","code","slice","checkLanguageFit","provider","texts","length","persisted","merged","total","Object","values","reduce","a","b","languages","declared","Set","map","majorityLang","majorityCount","entries","sort","has","pct","Math","round","id","join","stringify"],"mappings":"AACA,SAASA,OAAO,EAAEC,OAAO,QAAQ,kBAAkB;AACnD,SAASC,UAAU,QAAQ,eAAe;AAC1C,SAASC,MAAM,QAAQ,iBAAiB;AAGxC,MAAMC,WAAW;AACjB,+FAA+F;AAC/F,8FAA8F;AAC9F,MAAMC,eAAe;AACrB,gGAAgG;AAChG,4EAA4E;AAC5E,MAAMC,iBAAiB;AAIvB,OAAO,SAASC,qBAAqBC,EAAgB;IACnD,MAAMC,MAAMT,QAAQQ,IAAIJ;IACxB,OAAOK,MAAMC,KAAKC,KAAK,CAACF,OAAOG;AACjC;AAEA,SAASC,SAASC,KAA+B,EAAEC,IAAY;IAC7D,MAAMC,OAAOF,MAAMC,KAAKE,KAAK,CAAC,GAAGZ;IACjC,OAAOW,SAAS,QAAQJ,YAAYI;AACtC;AAEA,+FAA+F;AAC/F,+EAA+E;AAC/E,OAAO,eAAeE,iBAAiBV,EAAgB,EAAEW,QAAuB,EAAEC,KAAe;QAG7Eb;IAFlB,IAAIa,MAAMC,MAAM,KAAK,GAAG;IACxB,MAAM,EAAEP,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC;IAC/B,MAAMQ,aAAYf,wBAAAA,qBAAqBC,iBAArBD,mCAAAA,wBAA4B,CAAC;IAC/C,MAAMgB,SAAS;QAAE,GAAGD,SAAS;IAAC;IAC9B,KAAK,MAAMP,QAAQK,MAAO;YAEEG;QAD1B,MAAMP,OAAOH,SAASC,OAAOC;QAC7B,IAAIC,MAAMO,MAAM,CAACP,KAAK,GAAG,EAACO,eAAAA,MAAM,CAACP,KAAK,cAAZO,0BAAAA,eAAgB,KAAK;IACjD;IAEA,MAAMC,QAAQC,OAAOC,MAAM,CAACH,QAAQI,MAAM,CAAC,CAACC,GAAGC,IAAMD,IAAIC,GAAG;IAC5D,IAAIV,SAASW,SAAS,IAAIX,SAASW,SAAS,CAACT,MAAM,GAAG,KAAKG,SAASlB,gBAAgB;QAClF,MAAMyB,WAAW,IAAIC,IAAIb,SAASW,SAAS,CAACG,GAAG,CAAC9B;QAChD,MAAM,CAAC+B,cAAcC,cAAc,GAAGV,OAAOW,OAAO,CAACb,QAAQc,IAAI,CAAC,CAACT,GAAGC,IAAMA,CAAC,CAAC,EAAE,GAAGD,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;QAC3F,IAAIO,gBAAgBX,SAAS,OAAO,CAACO,SAASO,GAAG,CAACJ,eAAe;YAC/D,MAAMK,MAAMC,KAAKC,KAAK,CAAC,AAACN,gBAAgBX,QAAS;YACjD,MAAM,IAAItB,WACR,wBACA,CAAC,YAAY,EAAEiB,SAASuB,EAAE,CAAC,qBAAqB,EAAEvB,SAASW,SAAS,CAACa,IAAI,CAAC,MAAM,OAAO,EAAEJ,IAAI,qCAAqC,EAAEL,aAAa,0JAA0J,CAAC;QAEhT;IACF;IACAjC,QAAQO,IAAIJ,UAAUM,KAAKkC,SAAS,CAACrB;AACvC"}

package/dist/esm/embed/languages.d.ts

@@ -0,0 +1,3 @@
+export declare function isKnownLanguageTag(tag: string): boolean;
+export declare function toIso3(code: string): string;
+export declare const MEASURED_MODEL_LANGUAGES: Record<string, string[]>;

package/dist/esm/embed/languages.js

@@ -0,0 +1,80 @@
+// HF model cards declare languages as ISO 639-1 tags (e.g. "zh"); franc-min reports ISO 639-3
+// (e.g. "cmn"). This bridges the two for comparison. Limited to franc-min's own 82-language
+// data (README table, https://github.com/wooorm/franc), so every value here is a code franc-min
+// can actually emit; a declared tag with no entry here is compared as-is.
+const ISO_639_1_TO_3 = {
+    ar: 'arb',
+    am: 'amh',
+    az: 'azj',
+    be: 'bel',
+    bg: 'bul',
+    bn: 'ben',
+    bs: 'bos',
+    cs: 'ces',
+    de: 'deu',
+    el: 'ell',
+    en: 'eng',
+    es: 'spa',
+    fa: 'pes',
+    fr: 'fra',
+    gu: 'guj',
+    ha: 'hau',
+    hi: 'hin',
+    hr: 'hrv',
+    hu: 'hun',
+    id: 'ind',
+    ig: 'ibo',
+    it: 'ita',
+    ja: 'jpn',
+    jv: 'jav',
+    kk: 'kaz',
+    kn: 'kan',
+    ko: 'kor',
+    ml: 'mal',
+    mr: 'mar',
+    ms: 'zlm',
+    my: 'mya',
+    ne: 'npi',
+    nl: 'nld',
+    pa: 'pan',
+    pl: 'pol',
+    pt: 'por',
+    ro: 'ron',
+    ru: 'rus',
+    rw: 'kin',
+    si: 'sin',
+    so: 'som',
+    sr: 'srp',
+    su: 'sun',
+    sv: 'swe',
+    sw: 'swh',
+    ta: 'tam',
+    te: 'tel',
+    th: 'tha',
+    tl: 'tgl',
+    tr: 'tur',
+    uk: 'ukr',
+    ur: 'urd',
+    uz: 'uzn',
+    vi: 'vie',
+    yo: 'yor',
+    zh: 'cmn',
+    zu: 'zul'
+};
+export function isKnownLanguageTag(tag) {
+    return tag in ISO_639_1_TO_3;
+}
+// Normalizes a declared or detected language code to ISO 639-3 for comparison; strips a
+// region/script subtag ("zh-cn" -> "zh") first. Codes already in 639-3 form pass through.
+export function toIso3(code) {
+    var _ISO_639_1_TO_3_base;
+    const base = code.toLowerCase().split('-')[0];
+    return (_ISO_639_1_TO_3_base = ISO_639_1_TO_3[base]) !== null && _ISO_639_1_TO_3_base !== void 0 ? _ISO_639_1_TO_3_base : base;
+}
+// Languages this project measured for models whose cards declare none, so the fit check is
+// not silently off for the shipped default; asserted here because it was measured, not attested.
+export const MEASURED_MODEL_LANGUAGES = {
+    'minishlab/potion-retrieval-32M': [
+        'en'
+    ]
+};

package/dist/esm/embed/languages.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/embed/languages.ts"],"sourcesContent":["// HF model cards declare languages as ISO 639-1 tags (e.g. \"zh\"); franc-min reports ISO 639-3\n// (e.g. \"cmn\"). This bridges the two for comparison. Limited to franc-min's own 82-language\n// data (README table, https://github.com/wooorm/franc), so every value here is a code franc-min\n// can actually emit; a declared tag with no entry here is compared as-is.\nconst ISO_639_1_TO_3: Record<string, string> = {\n  ar: 'arb',\n  am: 'amh',\n  az: 'azj',\n  be: 'bel',\n  bg: 'bul',\n  bn: 'ben',\n  bs: 'bos',\n  cs: 'ces',\n  de: 'deu',\n  el: 'ell',\n  en: 'eng',\n  es: 'spa',\n  fa: 'pes',\n  fr: 'fra',\n  gu: 'guj',\n  ha: 'hau',\n  hi: 'hin',\n  hr: 'hrv',\n  hu: 'hun',\n  id: 'ind',\n  ig: 'ibo',\n  it: 'ita',\n  ja: 'jpn',\n  jv: 'jav',\n  kk: 'kaz',\n  kn: 'kan',\n  ko: 'kor',\n  ml: 'mal',\n  mr: 'mar',\n  ms: 'zlm',\n  my: 'mya',\n  ne: 'npi',\n  nl: 'nld',\n  pa: 'pan',\n  pl: 'pol',\n  pt: 'por',\n  ro: 'ron',\n  ru: 'rus',\n  rw: 'kin',\n  si: 'sin',\n  so: 'som',\n  sr: 'srp',\n  su: 'sun',\n  sv: 'swe',\n  sw: 'swh',\n  ta: 'tam',\n  te: 'tel',\n  th: 'tha',\n  tl: 'tgl',\n  tr: 'tur',\n  uk: 'ukr',\n  ur: 'urd',\n  uz: 'uzn',\n  vi: 'vie',\n  yo: 'yor',\n  zh: 'cmn',\n  zu: 'zul',\n};\n\nexport function isKnownLanguageTag(tag: string): boolean {\n  return tag in ISO_639_1_TO_3;\n}\n\n// Normalizes a declared or detected language code to ISO 639-3 for comparison; strips a\n// region/script subtag (\"zh-cn\" -> \"zh\") first. Codes already in 639-3 form pass through.\nexport function toIso3(code: string): string {\n  const base = code.toLowerCase().split('-')[0];\n  return ISO_639_1_TO_3[base] ?? base;\n}\n\n// Languages this project measured for models whose cards declare none, so the fit check is\n// not silently off for the shipped default; asserted here because it was measured, not attested.\nexport const MEASURED_MODEL_LANGUAGES: Record<string, string[]> = {\n  'minishlab/potion-retrieval-32M': ['en'], // BENCHMARKING.md bake-off; token-loss measurements\n};\n"],"names":["ISO_639_1_TO_3","ar","am","az","be","bg","bn","bs","cs","de","el","en","es","fa","fr","gu","ha","hi","hr","hu","id","ig","it","ja","jv","kk","kn","ko","ml","mr","ms","my","ne","nl","pa","pl","pt","ro","ru","rw","si","so","sr","su","sv","sw","ta","te","th","tl","tr","uk","ur","uz","vi","yo","zh","zu","isKnownLanguageTag","tag","toIso3","code","base","toLowerCase","split","MEASURED_MODEL_LANGUAGES"],"mappings":"AAAA,8FAA8F;AAC9F,4FAA4F;AAC5F,gGAAgG;AAChG,0EAA0E;AAC1E,MAAMA,iBAAyC;IAC7CC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;IACJC,IAAI;AACN;AAEA,OAAO,SAASC,mBAAmBC,GAAW;IAC5C,OAAOA,OAAO3D;AAChB;AAEA,wFAAwF;AACxF,0FAA0F;AAC1F,OAAO,SAAS4D,OAAOC,IAAY;QAE1B7D;IADP,MAAM8D,OAAOD,KAAKE,WAAW,GAAGC,KAAK,CAAC,IAAI,CAAC,EAAE;IAC7C,QAAOhE,uBAAAA,cAAc,CAAC8D,KAAK,cAApB9D,kCAAAA,uBAAwB8D;AACjC;AAEA,2FAA2F;AAC3F,iGAAiG;AACjG,OAAO,MAAMG,2BAAqD;IAChE,kCAAkC;QAAC;KAAK;AAC1C,EAAE"}

package/dist/esm/embed/openai.d.ts

@@ -0,0 +1,2 @@
+import type { EmbedProvider } from './types.js';
+export declare function openaiProvider(model: string, url: string | undefined, keyEnv: string | undefined): Promise<EmbedProvider>;

package/dist/esm/embed/openai.js

@@ -0,0 +1,49 @@
+import { SenseError } from '../errors.js';
+import { fetchWithRetry } from './http.js';
+const BATCH_CAP = 64;
+// One POST against any OpenAI-compatible /embeddings endpoint: Ollama, LM Studio, Cloudflare
+// Workers AI, Jina, Voyage, and Gemini's compat base URL all serve this shape.
+export async function openaiProvider(model, url, keyEnv) {
+    if (!url) throw new SenseError('EMBED_MODEL', 'embed.provider "openai" requires a url');
+    const base = url.replace(/\/+$/, '');
+    const headers = {
+        'content-type': 'application/json'
+    };
+    const key = keyEnv ? process.env[keyEnv] : undefined;
+    if (key) headers.authorization = `Bearer ${key}`;
+    async function post(texts) {
+        const res = await fetchWithRetry(`${base}/embeddings`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                model,
+                input: texts
+            })
+        });
+        if (!res.ok) throw new SenseError('EMBED_MODEL', `${base}/embeddings -> HTTP ${res.status}`);
+        const body = await res.json();
+        // The schema carries `index` because response order is not promised, and the caller maps
+        // vectors back to chunks positionally: sort by it whenever every element has one.
+        const data = body.data.every((d)=>typeof d.index === 'number') ? [
+            ...body.data
+        ].sort((a, b)=>a.index - b.index) : body.data;
+        // A server that drops an input (empty or over-length strings are the usual cause) would
+        // otherwise shift every later vector onto the wrong chunk, silently.
+        if (data.length !== texts.length) throw new SenseError('EMBED_MODEL', `${base}/embeddings returned ${data.length} embeddings for ${texts.length} inputs`);
+        return data.map((d)=>Float32Array.from(d.embedding));
+    }
+    const dims = (await post([
+        'dimension probe'
+    ]))[0].length;
+    // Symmetric for now: per-model prefixes (nomic's search_document/search_query) are a
+    // later workstream.
+    return {
+        id: `openai:${base}:${model}`,
+        dims,
+        batchCap: BATCH_CAP,
+        embedDocuments: post,
+        embedQuery: async (text)=>(await post([
+                text
+            ]))[0]
+    };
+}

package/dist/esm/embed/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/embed/openai.ts"],"sourcesContent":["import { SenseError } from '../errors.ts';\nimport { fetchWithRetry } from './http.ts';\nimport type { EmbedProvider } from './types.ts';\n\nconst BATCH_CAP = 64;\n\n// One POST against any OpenAI-compatible /embeddings endpoint: Ollama, LM Studio, Cloudflare\n// Workers AI, Jina, Voyage, and Gemini's compat base URL all serve this shape.\nexport async function openaiProvider(model: string, url: string | undefined, keyEnv: string | undefined): Promise<EmbedProvider> {\n  if (!url) throw new SenseError('EMBED_MODEL', 'embed.provider \"openai\" requires a url');\n  const base = url.replace(/\\/+$/, '');\n  const headers: Record<string, string> = { 'content-type': 'application/json' };\n  const key = keyEnv ? process.env[keyEnv] : undefined;\n  if (key) headers.authorization = `Bearer ${key}`;\n\n  async function post(texts: string[]): Promise<Float32Array[]> {\n    const res = await fetchWithRetry(`${base}/embeddings`, { method: 'POST', headers, body: JSON.stringify({ model, input: texts }) });\n    if (!res.ok) throw new SenseError('EMBED_MODEL', `${base}/embeddings -> HTTP ${res.status}`);\n    const body = (await res.json()) as { data: Array<{ embedding: number[]; index?: number }> };\n    // The schema carries `index` because response order is not promised, and the caller maps\n    // vectors back to chunks positionally: sort by it whenever every element has one.\n    const data = body.data.every((d) => typeof d.index === 'number') ? [...body.data].sort((a, b) => (a.index as number) - (b.index as number)) : body.data;\n    // A server that drops an input (empty or over-length strings are the usual cause) would\n    // otherwise shift every later vector onto the wrong chunk, silently.\n    if (data.length !== texts.length) throw new SenseError('EMBED_MODEL', `${base}/embeddings returned ${data.length} embeddings for ${texts.length} inputs`);\n    return data.map((d) => Float32Array.from(d.embedding));\n  }\n\n  const dims = (await post(['dimension probe']))[0].length;\n  // Symmetric for now: per-model prefixes (nomic's search_document/search_query) are a\n  // later workstream.\n  return { id: `openai:${base}:${model}`, dims, batchCap: BATCH_CAP, embedDocuments: post, embedQuery: async (text) => (await post([text]))[0] };\n}\n"],"names":["SenseError","fetchWithRetry","BATCH_CAP","openaiProvider","model","url","keyEnv","base","replace","headers","key","process","env","undefined","authorization","post","texts","res","method","body","JSON","stringify","input","ok","status","json","data","every","d","index","sort","a","b","length","map","Float32Array","from","embedding","dims","id","batchCap","embedDocuments","embedQuery","text"],"mappings":"AAAA,SAASA,UAAU,QAAQ,eAAe;AAC1C,SAASC,cAAc,QAAQ,YAAY;AAG3C,MAAMC,YAAY;AAElB,6FAA6F;AAC7F,+EAA+E;AAC/E,OAAO,eAAeC,eAAeC,KAAa,EAAEC,GAAuB,EAAEC,MAA0B;IACrG,IAAI,CAACD,KAAK,MAAM,IAAIL,WAAW,eAAe;IAC9C,MAAMO,OAAOF,IAAIG,OAAO,CAAC,QAAQ;IACjC,MAAMC,UAAkC;QAAE,gBAAgB;IAAmB;IAC7E,MAAMC,MAAMJ,SAASK,QAAQC,GAAG,CAACN,OAAO,GAAGO;IAC3C,IAAIH,KAAKD,QAAQK,aAAa,GAAG,CAAC,OAAO,EAAEJ,KAAK;IAEhD,eAAeK,KAAKC,KAAe;QACjC,MAAMC,MAAM,MAAMhB,eAAe,GAAGM,KAAK,WAAW,CAAC,EAAE;YAAEW,QAAQ;YAAQT;YAASU,MAAMC,KAAKC,SAAS,CAAC;gBAAEjB;gBAAOkB,OAAON;YAAM;QAAG;QAChI,IAAI,CAACC,IAAIM,EAAE,EAAE,MAAM,IAAIvB,WAAW,eAAe,GAAGO,KAAK,oBAAoB,EAAEU,IAAIO,MAAM,EAAE;QAC3F,MAAML,OAAQ,MAAMF,IAAIQ,IAAI;QAC5B,yFAAyF;QACzF,kFAAkF;QAClF,MAAMC,OAAOP,KAAKO,IAAI,CAACC,KAAK,CAAC,CAACC,IAAM,OAAOA,EAAEC,KAAK,KAAK,YAAY;eAAIV,KAAKO,IAAI;SAAC,CAACI,IAAI,CAAC,CAACC,GAAGC,IAAM,AAACD,EAAEF,KAAK,GAAeG,EAAEH,KAAK,IAAeV,KAAKO,IAAI;QACvJ,wFAAwF;QACxF,qEAAqE;QACrE,IAAIA,KAAKO,MAAM,KAAKjB,MAAMiB,MAAM,EAAE,MAAM,IAAIjC,WAAW,eAAe,GAAGO,KAAK,qBAAqB,EAAEmB,KAAKO,MAAM,CAAC,gBAAgB,EAAEjB,MAAMiB,MAAM,CAAC,OAAO,CAAC;QACxJ,OAAOP,KAAKQ,GAAG,CAAC,CAACN,IAAMO,aAAaC,IAAI,CAACR,EAAES,SAAS;IACtD;IAEA,MAAMC,OAAO,AAAC,CAAA,MAAMvB,KAAK;QAAC;KAAkB,CAAA,CAAE,CAAC,EAAE,CAACkB,MAAM;IACxD,qFAAqF;IACrF,oBAAoB;IACpB,OAAO;QAAEM,IAAI,CAAC,OAAO,EAAEhC,KAAK,CAAC,EAAEH,OAAO;QAAEkC;QAAME,UAAUtC;QAAWuC,gBAAgB1B;QAAM2B,YAAY,OAAOC,OAAS,AAAC,CAAA,MAAM5B,KAAK;gBAAC4B;aAAK,CAAA,CAAE,CAAC,EAAE;IAAC;AAC/I"}

package/dist/esm/embed/query.d.ts

@@ -0,0 +1,21 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { Config } from '../config/index.js';
+export declare function toStore(full: Float32Array, dims: number, int8: boolean): {
+    v: Float32Array;
+    scale: number;
+};
+export declare function embedPending(db: DatabaseSync, cfg: Config, baseDir: string): Promise<void>;
+export declare function semanticCandidates(db: DatabaseSync, cfg: Config, terms: string, fetch: number, allowed?: Set<string>): Promise<Array<{
+    path: string;
+    lines: string;
+    similarity: number;
+}>>;
+export declare function hasEmbedding(db: DatabaseSync, path: string): boolean;
+export declare function similarNotes(db: DatabaseSync, _cfg: Config, path: string, opts: {
+    exclude: Set<string>;
+    allowed?: Set<string>;
+    k: number;
+}): Array<{
+    path: string;
+    similarity: number;
+}>;

package/dist/esm/embed/query.js

@@ -0,0 +1,181 @@
+import { join } from 'node:path';
+import { SenseError } from '../errors.js';
+import { embed } from '../features/embed.js';
+import { progress } from '../progress.js';
+import { parseFile } from '../scan.js';
+import { checkLanguageFit } from './langfit.js';
+import { getProvider } from './registry.js';
+// Storage lever fixed by the bake-off (BENCHMARKING.md): int8 at 256 dims is
+// quality-free vs f32-512 when fused. Queries stay f32 at the same dims.
+const STORE_DIMS = 256;
+// Seed chunks that participate in a `related` scan; see similarNotes for the measurement.
+const TARGET_CHUNK_CAP = 16;
+// Slice + re-normalize (Matryoshka); optionally round through int8 storage. Exported for
+// benchmark/lib/embed.mjs, which scores the same lever math offline.
+export function toStore(full, dims, int8) {
+    const v = new Float32Array(dims);
+    let norm = 0;
+    for(let d = 0; d < dims; d++)norm += full[d] * full[d];
+    norm = Math.sqrt(norm) + 1e-32;
+    for(let d = 0; d < dims; d++)v[d] = full[d] / norm;
+    if (!int8) return {
+        v,
+        scale: 1
+    };
+    let max = 0;
+    for(let d = 0; d < dims; d++)max = Math.max(max, Math.abs(v[d]));
+    return {
+        v,
+        scale: max / 127 || 1
+    };
+}
+// Embed rows whose vector is NULL, re-deriving chunk text from the files through the
+// same parse + chunker that stored the rows.
+export async function embedPending(db, cfg, baseDir) {
+    const provider = await getProvider(cfg); // throws EMBED_DISABLED before touching the table
+    const dirty = db.prepare('SELECT "path", chunk FROM embeddings WHERE vector IS NULL ORDER BY "path", chunk').all();
+    if (dirty.length === 0) return;
+    const storeDims = Math.min(STORE_DIMS, provider.dims);
+    const byPath = new Map();
+    for (const row of dirty){
+        var _byPath_get;
+        const list = (_byPath_get = byPath.get(row.path)) !== null && _byPath_get !== void 0 ? _byPath_get : [];
+        list.push(row.chunk);
+        byPath.set(row.path, list);
+    }
+    const jobs = [];
+    for (const [path, chunkIdxs] of byPath){
+        let chunks;
+        try {
+            // presets/embed are irrelevant here -- re-deriving chunk text for a doc that already
+            // has embeddings rows means the tree had an embedding model at reconcile time.
+            chunks = parseFile({
+                relPath: path,
+                absPath: join(baseDir, path),
+                mtimeMs: 0,
+                ctimeMs: 0,
+                size: 0,
+                presets: [],
+                embed: true
+            }, [
+                embed
+            ]).doc.extracted.embed;
+        } catch  {
+            continue; // vanished since reconcile; the next reconcile removes its rows
+        }
+        for (const idx of chunkIdxs)if (chunks[idx]) jobs.push({
+            path,
+            chunk: idx,
+            text: chunks[idx].text
+        });
+    }
+    // Over the exact texts about to be embedded, before any of them are: a mismatch fails
+    // this run loudly instead of quietly storing vectors from the wrong model.
+    await checkLanguageFit(db, provider, jobs.map((j)=>j.text));
+    const update = db.prepare('UPDATE embeddings SET scale = ?, vector = ? WHERE "path" = ? AND chunk = ?');
+    // The lazy build is the one long silence a first search hits (measured 23s at
+    // 26k notes); progress makes it distinguishable from a hang.
+    const report = progress('embedding chunks', jobs.length);
+    for(let i = 0; i < jobs.length; i += provider.batchCap){
+        const batch = jobs.slice(i, i + provider.batchCap);
+        const vectors = await provider.embedDocuments(batch.map((j)=>j.text));
+        db.exec('BEGIN');
+        try {
+            batch.forEach((job, j)=>{
+                const { v, scale } = toStore(vectors[j], storeDims, true);
+                const q = new Int8Array(storeDims);
+                for(let d = 0; d < storeDims; d++)q[d] = Math.round(v[d] / scale);
+                update.run(scale, Buffer.from(q.buffer), job.path, job.chunk);
+            });
+            db.exec('COMMIT');
+        } catch (err) {
+            db.exec('ROLLBACK');
+            throw err;
+        }
+        report.tick(Math.min(i + provider.batchCap, jobs.length));
+    }
+    report.finish();
+}
+// Dequantised int8 dot products land a little either side of a true cosine, so an identical
+// pair prints 1.001 and undermines a column whose whole job is being a bounded number.
+function asCosine(score) {
+    return Math.round(Math.min(1, Math.max(-1, score)) * 1000) / 1000;
+}
+// Best chunk per file by cosine, its line range riding along; FTS5 operators are stripped as
+// lexical syntax. Similarity comes back because the fused score cannot express match quality,
+// and nearest-neighbour search always returns a neighbour however far away.
+export async function semanticCandidates(db, cfg, terms, fetch, allowed) {
+    var _terms_match;
+    const baseDir = cfg.baseDir;
+    if (!baseDir) throw new SenseError('EMBED_MODEL', 'semantic expansion needs a config with baseDir (use loadConfig/open)');
+    await embedPending(db, cfg, baseDir);
+    const provider = await getProvider(cfg);
+    const storeDims = Math.min(STORE_DIMS, provider.dims);
+    const text = ((_terms_match = terms.match(/[\p{L}\p{N}]+/gu)) !== null && _terms_match !== void 0 ? _terms_match : []).filter((t)=>![
+            'AND',
+            'OR',
+            'NOT',
+            'NEAR'
+        ].includes(t)).join(' ');
+    const { v: qv } = toStore(await provider.embedQuery(text), storeDims, false);
+    const rows = db.prepare('SELECT "path", start_line, end_line, scale, vector FROM embeddings WHERE vector IS NOT NULL').all();
+    const best = new Map();
+    for (const row of rows){
+        if (allowed && !allowed.has(row.path)) continue;
+        const q = new Int8Array(row.vector.buffer, row.vector.byteOffset, Math.min(storeDims, row.vector.byteLength));
+        let dot = 0;
+        for(let d = 0; d < q.length; d++)dot += q[d] * qv[d];
+        const score = dot * row.scale;
+        const existing = best.get(row.path);
+        if (!existing || score > existing.score) best.set(row.path, {
+            score,
+            lines: `L${row.start_line}-${row.end_line}`
+        });
+    }
+    return [
+        ...best.entries()
+    ].sort((a, b)=>b[1].score - a[1].score).slice(0, fetch).map(([path, b])=>({
+            path,
+            lines: b.lines,
+            similarity: asCosine(b.score)
+        }));
+}
+// Whether a note has any chunk with a vector. Distinguishes "nothing is near this note" from
+// "this note has no text", which look the same in an empty result.
+export function hasEmbedding(db, path) {
+    const row = db.prepare('SELECT 1 AS ok FROM embeddings WHERE "path" = ? AND vector IS NOT NULL LIMIT 1').get(path);
+    return row !== undefined;
+}
+// Note-to-note similarity is the max cosine over (target chunk, other chunk) pairs, one linear
+// scan of stored vectors. Reads only what is stored, so it stays sync.
+export function similarNotes(db, _cfg, path, opts) {
+    // Cost is target_chunks x stored_chunks, so a heading-dense seed multiplies a full-corpus
+    // scan (12.7s at 201 chunks/note). Sample evenly, so late sections still get a vote.
+    const targetRows = db.prepare('SELECT scale, vector FROM embeddings WHERE "path" = ? AND vector IS NOT NULL ORDER BY chunk').all(path);
+    if (targetRows.length === 0) return [];
+    const step = Math.max(1, Math.ceil(targetRows.length / TARGET_CHUNK_CAP));
+    const target = targetRows.filter((_, i)=>i % step === 0).map((row)=>({
+            v: new Int8Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength),
+            scale: row.scale
+        }));
+    const rows = db.prepare('SELECT "path", scale, vector FROM embeddings WHERE vector IS NOT NULL').all();
+    const best = new Map();
+    for (const row of rows){
+        if (row.path === path || opts.exclude.has(row.path) || opts.allowed && !opts.allowed.has(row.path)) continue;
+        const other = new Int8Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength);
+        for (const t of target){
+            let dot = 0;
+            const len = Math.min(t.v.length, other.length);
+            for(let d = 0; d < len; d++)dot += t.v[d] * other[d];
+            const score = dot * t.scale * row.scale;
+            const existing = best.get(row.path);
+            if (existing === undefined || score > existing) best.set(row.path, score);
+        }
+    }
+    return [
+        ...best.entries()
+    ].sort((a, b)=>b[1] - a[1]).slice(0, opts.k).map(([p, score])=>({
+            path: p,
+            similarity: asCosine(score)
+        }));
+}

package/dist/esm/embed/query.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/embed/query.ts"],"sourcesContent":["import { join } from 'node:path';\nimport type { DatabaseSync } from 'node:sqlite';\nimport type { Config, ResolvedConfig } from '../config/index.ts';\nimport { SenseError } from '../errors.ts';\nimport type { Chunk } from '../features/embed.ts';\nimport { embed } from '../features/embed.ts';\nimport { progress } from '../progress.ts';\nimport { parseFile } from '../scan.ts';\nimport { checkLanguageFit } from './langfit.ts';\nimport { getProvider } from './registry.ts';\n\n// Storage lever fixed by the bake-off (BENCHMARKING.md): int8 at 256 dims is\n// quality-free vs f32-512 when fused. Queries stay f32 at the same dims.\nconst STORE_DIMS = 256;\n// Seed chunks that participate in a `related` scan; see similarNotes for the measurement.\nconst TARGET_CHUNK_CAP = 16;\n\n// Slice + re-normalize (Matryoshka); optionally round through int8 storage. Exported for\n// benchmark/lib/embed.mjs, which scores the same lever math offline.\nexport function toStore(full: Float32Array, dims: number, int8: boolean): { v: Float32Array; scale: number } {\n  const v = new Float32Array(dims);\n  let norm = 0;\n  for (let d = 0; d < dims; d++) norm += full[d] * full[d];\n  norm = Math.sqrt(norm) + 1e-32;\n  for (let d = 0; d < dims; d++) v[d] = full[d] / norm;\n  if (!int8) return { v, scale: 1 };\n  let max = 0;\n  for (let d = 0; d < dims; d++) max = Math.max(max, Math.abs(v[d]));\n  return { v, scale: max / 127 || 1 };\n}\n\n// Embed rows whose vector is NULL, re-deriving chunk text from the files through the\n// same parse + chunker that stored the rows.\nexport async function embedPending(db: DatabaseSync, cfg: Config, baseDir: string): Promise<void> {\n  const provider = await getProvider(cfg); // throws EMBED_DISABLED before touching the table\n  const dirty = db.prepare('SELECT \"path\", chunk FROM embeddings WHERE vector IS NULL ORDER BY \"path\", chunk').all() as Array<{ path: string; chunk: number }>;\n  if (dirty.length === 0) return;\n  const storeDims = Math.min(STORE_DIMS, provider.dims);\n\n  const byPath = new Map<string, number[]>();\n  for (const row of dirty) {\n    const list = byPath.get(row.path) ?? [];\n    list.push(row.chunk);\n    byPath.set(row.path, list);\n  }\n\n  const jobs: Array<{ path: string; chunk: number; text: string }> = [];\n  for (const [path, chunkIdxs] of byPath) {\n    let chunks: Chunk[];\n    try {\n      // presets/embed are irrelevant here -- re-deriving chunk text for a doc that already\n      // has embeddings rows means the tree had an embedding model at reconcile time.\n      chunks = parseFile({ relPath: path, absPath: join(baseDir, path), mtimeMs: 0, ctimeMs: 0, size: 0, presets: [], embed: true }, [embed]).doc.extracted.embed as Chunk[];\n    } catch {\n      continue; // vanished since reconcile; the next reconcile removes its rows\n    }\n    for (const idx of chunkIdxs) if (chunks[idx]) jobs.push({ path, chunk: idx, text: chunks[idx].text });\n  }\n\n  // Over the exact texts about to be embedded, before any of them are: a mismatch fails\n  // this run loudly instead of quietly storing vectors from the wrong model.\n  await checkLanguageFit(\n    db,\n    provider,\n    jobs.map((j) => j.text)\n  );\n\n  const update = db.prepare('UPDATE embeddings SET scale = ?, vector = ? WHERE \"path\" = ? AND chunk = ?');\n  // The lazy build is the one long silence a first search hits (measured 23s at\n  // 26k notes); progress makes it distinguishable from a hang.\n  const report = progress('embedding chunks', jobs.length);\n  for (let i = 0; i < jobs.length; i += provider.batchCap) {\n    const batch = jobs.slice(i, i + provider.batchCap);\n    const vectors = await provider.embedDocuments(batch.map((j) => j.text));\n    db.exec('BEGIN');\n    try {\n      batch.forEach((job, j) => {\n        const { v, scale } = toStore(vectors[j], storeDims, true);\n        const q = new Int8Array(storeDims);\n        for (let d = 0; d < storeDims; d++) q[d] = Math.round(v[d] / scale);\n        update.run(scale, Buffer.from(q.buffer), job.path, job.chunk);\n      });\n      db.exec('COMMIT');\n    } catch (err) {\n      db.exec('ROLLBACK');\n      throw err;\n    }\n    report.tick(Math.min(i + provider.batchCap, jobs.length));\n  }\n  report.finish();\n}\n\n// Dequantised int8 dot products land a little either side of a true cosine, so an identical\n// pair prints 1.001 and undermines a column whose whole job is being a bounded number.\nfunction asCosine(score: number): number {\n  return Math.round(Math.min(1, Math.max(-1, score)) * 1000) / 1000;\n}\n\n// Best chunk per file by cosine, its line range riding along; FTS5 operators are stripped as\n// lexical syntax. Similarity comes back because the fused score cannot express match quality,\n// and nearest-neighbour search always returns a neighbour however far away.\nexport async function semanticCandidates(db: DatabaseSync, cfg: Config, terms: string, fetch: number, allowed?: Set<string>): Promise<Array<{ path: string; lines: string; similarity: number }>> {\n  const baseDir = (cfg as Partial<ResolvedConfig>).baseDir;\n  if (!baseDir) throw new SenseError('EMBED_MODEL', 'semantic expansion needs a config with baseDir (use loadConfig/open)');\n  await embedPending(db, cfg, baseDir);\n\n  const provider = await getProvider(cfg);\n  const storeDims = Math.min(STORE_DIMS, provider.dims);\n  const text = (terms.match(/[\\p{L}\\p{N}]+/gu) ?? []).filter((t) => !['AND', 'OR', 'NOT', 'NEAR'].includes(t)).join(' ');\n  const { v: qv } = toStore(await provider.embedQuery(text), storeDims, false);\n\n  const rows = db.prepare('SELECT \"path\", start_line, end_line, scale, vector FROM embeddings WHERE vector IS NOT NULL').all() as Array<{\n    path: string;\n    start_line: number;\n    end_line: number;\n    scale: number;\n    vector: Uint8Array;\n  }>;\n\n  const best = new Map<string, { score: number; lines: string }>();\n  for (const row of rows) {\n    if (allowed && !allowed.has(row.path)) continue;\n    const q = new Int8Array(row.vector.buffer, row.vector.byteOffset, Math.min(storeDims, row.vector.byteLength));\n    let dot = 0;\n    for (let d = 0; d < q.length; d++) dot += q[d] * qv[d];\n    const score = dot * row.scale;\n    const existing = best.get(row.path);\n    if (!existing || score > existing.score) best.set(row.path, { score, lines: `L${row.start_line}-${row.end_line}` });\n  }\n  return [...best.entries()]\n    .sort((a, b) => b[1].score - a[1].score)\n    .slice(0, fetch)\n    .map(([path, b]) => ({ path, lines: b.lines, similarity: asCosine(b.score) }));\n}\n\n// Whether a note has any chunk with a vector. Distinguishes \"nothing is near this note\" from\n// \"this note has no text\", which look the same in an empty result.\nexport function hasEmbedding(db: DatabaseSync, path: string): boolean {\n  const row = db.prepare('SELECT 1 AS ok FROM embeddings WHERE \"path\" = ? AND vector IS NOT NULL LIMIT 1').get(path) as { ok: number } | undefined;\n  return row !== undefined;\n}\n\n// Note-to-note similarity is the max cosine over (target chunk, other chunk) pairs, one linear\n// scan of stored vectors. Reads only what is stored, so it stays sync.\nexport function similarNotes(db: DatabaseSync, _cfg: Config, path: string, opts: { exclude: Set<string>; allowed?: Set<string>; k: number }): Array<{ path: string; similarity: number }> {\n  // Cost is target_chunks x stored_chunks, so a heading-dense seed multiplies a full-corpus\n  // scan (12.7s at 201 chunks/note). Sample evenly, so late sections still get a vote.\n  const targetRows = db.prepare('SELECT scale, vector FROM embeddings WHERE \"path\" = ? AND vector IS NOT NULL ORDER BY chunk').all(path) as Array<{ scale: number; vector: Uint8Array }>;\n  if (targetRows.length === 0) return [];\n  const step = Math.max(1, Math.ceil(targetRows.length / TARGET_CHUNK_CAP));\n  const target = targetRows.filter((_, i) => i % step === 0).map((row) => ({ v: new Int8Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength), scale: row.scale }));\n\n  const rows = db.prepare('SELECT \"path\", scale, vector FROM embeddings WHERE vector IS NOT NULL').all() as Array<{ path: string; scale: number; vector: Uint8Array }>;\n  const best = new Map<string, number>();\n  for (const row of rows) {\n    if (row.path === path || opts.exclude.has(row.path) || (opts.allowed && !opts.allowed.has(row.path))) continue;\n    const other = new Int8Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength);\n    for (const t of target) {\n      let dot = 0;\n      const len = Math.min(t.v.length, other.length);\n      for (let d = 0; d < len; d++) dot += t.v[d] * other[d];\n      const score = dot * t.scale * row.scale;\n      const existing = best.get(row.path);\n      if (existing === undefined || score > existing) best.set(row.path, score);\n    }\n  }\n\n  return [...best.entries()]\n    .sort((a, b) => b[1] - a[1])\n    .slice(0, opts.k)\n    .map(([p, score]) => ({ path: p, similarity: asCosine(score) }));\n}\n"],"names":["join","SenseError","embed","progress","parseFile","checkLanguageFit","getProvider","STORE_DIMS","TARGET_CHUNK_CAP","toStore","full","dims","int8","v","Float32Array","norm","d","Math","sqrt","scale","max","abs","embedPending","db","cfg","baseDir","provider","dirty","prepare","all","length","storeDims","min","byPath","Map","row","list","get","path","push","chunk","set","jobs","chunkIdxs","chunks","relPath","absPath","mtimeMs","ctimeMs","size","presets","doc","extracted","idx","text","map","j","update","report","i","batchCap","batch","slice","vectors","embedDocuments","exec","forEach","job","q","Int8Array","round","run","Buffer","from","buffer","err","tick","finish","asCosine","score","semanticCandidates","terms","fetch","allowed","match","filter","t","includes","qv","embedQuery","rows","best","has","vector","byteOffset","byteLength","dot","existing","lines","start_line","end_line","entries","sort","a","b","similarity","hasEmbedding","undefined","similarNotes","_cfg","opts","targetRows","step","ceil","target","_","exclude","other","len","k","p"],"mappings":"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"}

package/dist/esm/embed/registry.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from '../config/index.js';
+import type { EmbedProvider } from './types.js';
+export declare function getProvider(cfg: Config): Promise<EmbedProvider>;

package/dist/esm/embed/registry.js

@@ -0,0 +1,45 @@
+import { embedConfig } from '../config/index.js';
+import { SenseError } from '../errors.js';
+import { cohereProvider } from './cohere.js';
+import { openaiProvider } from './openai.js';
+import { staticProvider } from './static.js';
+// One factory per wire protocol: adding a protocol is a new file plus an entry here, not
+// an edit to a dispatch ternary.
+const REGISTRY = {
+    static: (model)=>staticProvider(model),
+    openai: (model, url, key)=>openaiProvider(model, url, key),
+    cohere: (model, url, key)=>cohereProvider(model, url, key)
+};
+const providers = new Map();
+export function getProvider(cfg) {
+    var _e_url, _e_key, _e_languages;
+    const e = embedConfig(cfg);
+    if (!e) throw new SenseError('EMBED_DISABLED', 'this tree has no embedding model: add an "embed" block naming one to sense.config.json; a Hugging Face id fetches automatically at first use, or run `sense download` to prefetch it');
+    const factory = REGISTRY[e.provider];
+    if (!factory) throw new SenseError('EMBED_MODEL', `embed.provider "${e.provider}" has no provider implementation in this build`);
+    // Every input that shapes the provider is in the key: two trees sharing an endpoint and
+    // model but declaring different languages or reading different key env vars are two
+    // providers, not one, however long a process lives.
+    const sig = JSON.stringify([
+        e.provider,
+        e.model,
+        (_e_url = e.url) !== null && _e_url !== void 0 ? _e_url : '',
+        (_e_key = e.key) !== null && _e_key !== void 0 ? _e_key : '',
+        (_e_languages = e.languages) !== null && _e_languages !== void 0 ? _e_languages : []
+    ]);
+    let p = providers.get(sig);
+    if (!p) {
+        p = factory(e.model, e.url, e.key);
+        // Owner-declared languages override a provider's own: the config is the one home for
+        // what no model card can state (http models have no fetchable card here).
+        if (e.languages) p = p.then((prov)=>({
+                ...prov,
+                languages: e.languages
+            }));
+        providers.set(sig, p);
+        // A rejected construction is evicted, so a transient failure retries instead of
+        // poisoning this config for the process lifetime.
+        p.catch(()=>providers.delete(sig));
+    }
+    return p;
+}

package/dist/esm/embed/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/embed/registry.ts"],"sourcesContent":["import type { Config } from '../config/index.ts';\nimport { embedConfig } from '../config/index.ts';\nimport { SenseError } from '../errors.ts';\nimport { cohereProvider } from './cohere.ts';\nimport { openaiProvider } from './openai.ts';\nimport { staticProvider } from './static.ts';\nimport type { EmbedProvider } from './types.ts';\n\ntype ProviderFactory = (model: string, url: string | undefined, key: string | undefined) => Promise<EmbedProvider>;\n\n// One factory per wire protocol: adding a protocol is a new file plus an entry here, not\n// an edit to a dispatch ternary.\nconst REGISTRY: Record<string, ProviderFactory> = {\n  static: (model) => staticProvider(model),\n  openai: (model, url, key) => openaiProvider(model, url, key),\n  cohere: (model, url, key) => cohereProvider(model, url, key),\n};\n\nconst providers = new Map<string, Promise<EmbedProvider>>();\n\nexport function getProvider(cfg: Config): Promise<EmbedProvider> {\n  const e = embedConfig(cfg);\n  if (!e) throw new SenseError('EMBED_DISABLED', 'this tree has no embedding model: add an \"embed\" block naming one to sense.config.json; a Hugging Face id fetches automatically at first use, or run `sense download` to prefetch it');\n  const factory = REGISTRY[e.provider];\n  if (!factory) throw new SenseError('EMBED_MODEL', `embed.provider \"${e.provider}\" has no provider implementation in this build`);\n  // Every input that shapes the provider is in the key: two trees sharing an endpoint and\n  // model but declaring different languages or reading different key env vars are two\n  // providers, not one, however long a process lives.\n  const sig = JSON.stringify([e.provider, e.model, e.url ?? '', e.key ?? '', e.languages ?? []]);\n  let p = providers.get(sig);\n  if (!p) {\n    p = factory(e.model, e.url, e.key);\n    // Owner-declared languages override a provider's own: the config is the one home for\n    // what no model card can state (http models have no fetchable card here).\n    if (e.languages) p = p.then((prov) => ({ ...prov, languages: e.languages }));\n    providers.set(sig, p);\n    // A rejected construction is evicted, so a transient failure retries instead of\n    // poisoning this config for the process lifetime.\n    p.catch(() => providers.delete(sig));\n  }\n  return p;\n}\n"],"names":["embedConfig","SenseError","cohereProvider","openaiProvider","staticProvider","REGISTRY","static","model","openai","url","key","cohere","providers","Map","getProvider","cfg","e","factory","provider","sig","JSON","stringify","languages","p","get","then","prov","set","catch","delete"],"mappings":"AACA,SAASA,WAAW,QAAQ,qBAAqB;AACjD,SAASC,UAAU,QAAQ,eAAe;AAC1C,SAASC,cAAc,QAAQ,cAAc;AAC7C,SAASC,cAAc,QAAQ,cAAc;AAC7C,SAASC,cAAc,QAAQ,cAAc;AAK7C,yFAAyF;AACzF,iCAAiC;AACjC,MAAMC,WAA4C;IAChDC,QAAQ,CAACC,QAAUH,eAAeG;IAClCC,QAAQ,CAACD,OAAOE,KAAKC,MAAQP,eAAeI,OAAOE,KAAKC;IACxDC,QAAQ,CAACJ,OAAOE,KAAKC,MAAQR,eAAeK,OAAOE,KAAKC;AAC1D;AAEA,MAAME,YAAY,IAAIC;AAEtB,OAAO,SAASC,YAAYC,GAAW;QAQYC,QAAaA,QAAaA;IAP3E,MAAMA,IAAIhB,YAAYe;IACtB,IAAI,CAACC,GAAG,MAAM,IAAIf,WAAW,kBAAkB;IAC/C,MAAMgB,UAAUZ,QAAQ,CAACW,EAAEE,QAAQ,CAAC;IACpC,IAAI,CAACD,SAAS,MAAM,IAAIhB,WAAW,eAAe,CAAC,gBAAgB,EAAEe,EAAEE,QAAQ,CAAC,8CAA8C,CAAC;IAC/H,wFAAwF;IACxF,oFAAoF;IACpF,oDAAoD;IACpD,MAAMC,MAAMC,KAAKC,SAAS,CAAC;QAACL,EAAEE,QAAQ;QAAEF,EAAET,KAAK;SAAES,SAAAA,EAAEP,GAAG,cAALO,oBAAAA,SAAS;SAAIA,SAAAA,EAAEN,GAAG,cAALM,oBAAAA,SAAS;SAAIA,eAAAA,EAAEM,SAAS,cAAXN,0BAAAA,eAAe,EAAE;KAAC;IAC7F,IAAIO,IAAIX,UAAUY,GAAG,CAACL;IACtB,IAAI,CAACI,GAAG;QACNA,IAAIN,QAAQD,EAAET,KAAK,EAAES,EAAEP,GAAG,EAAEO,EAAEN,GAAG;QACjC,qFAAqF;QACrF,0EAA0E;QAC1E,IAAIM,EAAEM,SAAS,EAAEC,IAAIA,EAAEE,IAAI,CAAC,CAACC,OAAU,CAAA;gBAAE,GAAGA,IAAI;gBAAEJ,WAAWN,EAAEM,SAAS;YAAC,CAAA;QACzEV,UAAUe,GAAG,CAACR,KAAKI;QACnB,gFAAgF;QAChF,kDAAkD;QAClDA,EAAEK,KAAK,CAAC,IAAMhB,UAAUiB,MAAM,CAACV;IACjC;IACA,OAAOI;AACT"}

package/dist/esm/embed/static.d.ts

@@ -0,0 +1,2 @@
+import type { EmbedProvider } from './types.js';
+export declare function staticProvider(model: string): Promise<EmbedProvider>;

package/dist/esm/embed/static.js

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SenseError } from '../errors.js';
+import { downloadModel, isDownloadable, MODEL_FILENAMES, MODEL_FILES, modelDir, readLanguages } from './store.js';
+const BATCH_CAP = 64;
+// Model2Vec safetensors + pure-JS tokenizer. Encode convention from model2vec/model.py: no
+// special tokens, drop unk ids, mean-pool, L2-normalize.
+export async function staticProvider(model) {
+    var _ref;
+    var _tokenizerJson_model, _tokenizerJson_model_vocab, _tokenizerJson_model1;
+    let dir;
+    let languages;
+    if (isDownloadable(model)) {
+        // Naming a HF id is consent: fetch whatever is missing now, announcing it on stderr.
+        dir = await downloadModel(model, (file, into)=>console.error(`sense: fetching ${model}/${file} into ${into}`));
+        // Cached beside the repo; a local model directory has no card to read, so it has none.
+        const cached = readLanguages(model);
+        languages = cached && cached.length > 0 ? cached : undefined;
+    } else {
+        dir = modelDir(model);
+        for (const file of MODEL_FILES){
+            if (!existsSync(join(dir, file))) {
+                throw new SenseError('EMBED_MODEL_MISSING', `embed model ${model} is not available (looked in ${dir}); expected ${MODEL_FILENAMES} in that directory`);
+            }
+        }
+    }
+    const raw = readFileSync(join(dir, 'model.safetensors'));
+    const headerLen = Number(raw.readBigUInt64LE(0));
+    const header = JSON.parse(raw.subarray(8, 8 + headerLen).toString('utf8'));
+    const entry = Object.entries(header).find(([k])=>k !== '__metadata__');
+    if (!entry || entry[1].dtype !== 'F32') throw new SenseError('EMBED_MODEL', `${model}: expected an F32 safetensors matrix`);
+    const spec = entry[1];
+    const dims = spec.shape[1];
+    const dataStart = raw.byteOffset + 8 + headerLen + spec.data_offsets[0];
+    const matrix = dataStart % 4 === 0 ? new Float32Array(raw.buffer, dataStart, spec.shape[0] * dims) : new Float32Array(raw.buffer.slice(dataStart, dataStart + spec.shape[0] * dims * 4));
+    const tokenizerJson = JSON.parse(readFileSync(join(dir, 'tokenizer.json'), 'utf8'));
+    // Lazy import: the tokenizer loads only on the semantic path, never at CLI startup.
+    const { Tokenizer } = await import('@huggingface/tokenizers');
+    const tok = new Tokenizer(tokenizerJson, {});
+    const unkId = (_ref = (_tokenizerJson_model1 = tokenizerJson.model) === null || _tokenizerJson_model1 === void 0 ? void 0 : (_tokenizerJson_model_vocab = _tokenizerJson_model1.vocab) === null || _tokenizerJson_model_vocab === void 0 ? void 0 : _tokenizerJson_model_vocab[(_tokenizerJson_model = tokenizerJson.model) === null || _tokenizerJson_model === void 0 ? void 0 : _tokenizerJson_model.unk_token]) !== null && _ref !== void 0 ? _ref : -1;
+    function one(text) {
+        // The tokenizer yields undefined (not the unk id) for tokens outside the vocab; an
+        // undefined id would index the matrix at NaN and poison the whole mean-pool -- and the
+        // int8 conversion then stores the NaN vector as all zeros, silently. Keep integers only.
+        const ids = tok.encode(text, {
+            add_special_tokens: false
+        }).ids.filter((id)=>Number.isInteger(id) && id !== unkId);
+        const v = new Float32Array(dims);
+        if (ids.length === 0) return v;
+        for (const id of ids){
+            const off = id * dims;
+            for(let d = 0; d < dims; d++)v[d] += matrix[off + d];
+        }
+        let norm = 0;
+        for(let d = 0; d < dims; d++){
+            v[d] /= ids.length;
+            norm += v[d] * v[d];
+        }
+        norm = Math.sqrt(norm) + 1e-32;
+        for(let d = 0; d < dims; d++)v[d] /= norm;
+        return v;
+    }
+    // Symmetric model: document and query embedding are the same call.
+    return {
+        id: `static:${model}`,
+        dims,
+        batchCap: BATCH_CAP,
+        languages,
+        embedDocuments: async (texts)=>texts.map(one),
+        embedQuery: async (text)=>one(text)
+    };
+}