nlm-memory 0.19.0 → 0.20.1

package/dist/core/embedding/pg-embed-backfill.js

@@ -0,0 +1,264 @@
+/**
+ * pg-embed-backfill -- re-embed every session in the Postgres store into
+ * session_embedding_chunks. Mirrors reembedCorpus from embed-backfill.ts
+ * but drives a pg Pool instead of a SQLite file.
+ *
+ * Resumable via a JSON state file at $NLM_EMBED_STATE (default
+ * ~/.nlm/embed_reembed_pg.state). Same SAVE_EVERY = 25 checkpoint cadence.
+ *
+ * When the probed dim/model/provider differs from the stored embedding_config
+ * row, both vector tables are rebuilt: rows cleared, the embedding column
+ * altered to the new dimension, and indexes recreated. Facts (superseded_by
+ * IS NULL AND retired_at IS NULL) are reembedded after the session loop.
+ * Same-config reruns skip the rebuild.
+ *
+ * CRITICAL: the final config write is an awaited pool.query() INSERT ON
+ * CONFLICT -- never routed through PgEmbeddingConfigStore.upsertLane, which
+ * is fire-and-forget and can be lost when pool.end() follows.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { Pool } from "pg";
+import { LLMUnreachableError } from "../../ports/llm-client.js";
+import { chunkSessionText } from "../embedding/chunk-body.js";
+const DEFAULT_STATE_PATH = join(homedir(), ".nlm", "embed_reembed_pg.state");
+const SAVE_EVERY = 25;
+function loadStateData(path) {
+    if (!existsSync(path))
+        return { done: new Set() };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return { done: new Set(raw.done ?? []), ...(raw.config ? { config: raw.config } : {}) };
+    }
+    catch {
+        return { done: new Set() };
+    }
+}
+function saveState(path, done, config) {
+    mkdirSync(dirname(path), { recursive: true });
+    const data = { done: [...done].sort() };
+    if (config)
+        data.config = config;
+    writeFileSync(path, JSON.stringify(data));
+}
+export async function reembedCorpusPg(opts) {
+    const statePath = opts.statePath ?? DEFAULT_STATE_PATH;
+    const pool = new Pool({ connectionString: opts.pgUrl });
+    try {
+        const tableCheck = await pool.query("SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_schema = 'public' AND table_name = 'embedding_config') AS exists");
+        if (!tableCheck.rows[0]?.exists) {
+            throw new Error("embedding_config table not found; run `nlm migrate` to apply pending migrations");
+        }
+        const probeResult = await opts.embedder.embed("nlm dimension probe", "query");
+        const dim = probeResult.vector.length;
+        const model = probeResult.model;
+        const provider = opts.embedderProvider ?? process.env["NLM_EMBED_PROVIDER"] ?? "ollama";
+        const cfgRows = await pool.query("SELECT provider, model, dim FROM embedding_config WHERE lane = 'prose'");
+        const storedConfig = cfgRows.rows[0] ?? null;
+        const stateData = loadStateData(statePath);
+        let configMatch = false;
+        let needsRebuild = false;
+        if (storedConfig !== null) {
+            configMatch =
+                storedConfig.provider === provider &&
+                    storedConfig.model === model &&
+                    storedConfig.dim === dim;
+            if (!configMatch) {
+                const stateConfigMatches = stateData.config !== undefined &&
+                    stateData.config.provider === provider &&
+                    stateData.config.model === model &&
+                    stateData.config.dim === dim;
+                if (!stateConfigMatches) {
+                    needsRebuild = true;
+                }
+            }
+        }
+        // Resume state: stored config differs from runtime, but the state file already
+        // carries the new config (tables were rebuilt in a prior interrupted run).
+        // No column alter is needed, but facts must still be reembedded to finish the run.
+        const isResumeState = storedConfig !== null && !configMatch && !needsRebuild;
+        if (opts.dryRun) {
+            if (needsRebuild) {
+                const stored = storedConfig;
+                process.stderr.write(`[pg-embed-backfill] dim mismatch: stored ${stored.provider}/${stored.model}@${stored.dim},` +
+                    ` runtime ${provider}/${model}@${dim}.` +
+                    ` Would ALTER session_embedding_chunks and fact_embeddings to vector(${dim}).\n`);
+            }
+            else if (isResumeState) {
+                const stored = storedConfig;
+                process.stderr.write(`[pg-embed-backfill] resume state: interrupted rebuild detected.` +
+                    ` Stored config ${stored.provider}/${stored.model}@${stored.dim}` +
+                    ` differs from runtime ${provider}/${model}@${dim},` +
+                    ` but state file already matches runtime.` +
+                    ` No column alter; facts would be reembedded to complete the interrupted rebuild.\n`);
+            }
+            else {
+                process.stderr.write(`[pg-embed-backfill] dry-run: config matches (${provider}/${model}@${dim}), no rebuild needed.\n`);
+            }
+            let dryRunFactCount = 0;
+            if (isResumeState) {
+                const countResult = await pool.query("SELECT COUNT(*) AS cnt FROM facts WHERE superseded_by IS NULL AND retired_at IS NULL");
+                dryRunFactCount = Number(countResult.rows[0]?.cnt ?? 0);
+            }
+            return {
+                total: 0,
+                processed: 0,
+                succeeded: 0,
+                failed: 0,
+                skippedAlreadyDone: 0,
+                dbMissing: false,
+                dryRun: true,
+                rebuilt: needsRebuild,
+                factsReembedded: dryRunFactCount,
+            };
+        }
+        if (needsRebuild) {
+            const stored = storedConfig;
+            process.stderr.write(`[pg-embed-backfill] rebuilding vec tables: stored ${stored.provider}/${stored.model}@${stored.dim}` +
+                ` vs runtime ${provider}/${model}@${dim}\n`);
+            process.stderr.write(`[pg-embed-backfill] DELETE FROM session_embedding_chunks\n`);
+            await pool.query("DELETE FROM session_embedding_chunks");
+            await pool.query("DROP INDEX IF EXISTS session_chunks_embedding_idx");
+            await pool.query(`ALTER TABLE session_embedding_chunks ALTER COLUMN embedding TYPE vector(${dim})`);
+            await pool.query(`CREATE INDEX session_chunks_embedding_idx` +
+                ` ON session_embedding_chunks USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)`);
+            process.stderr.write(`[pg-embed-backfill] rebuilding fact_embeddings to vector(${dim})\n`);
+            await pool.query("DELETE FROM fact_embeddings");
+            await pool.query("DROP INDEX IF EXISTS fact_embeddings_idx");
+            await pool.query(`ALTER TABLE fact_embeddings ALTER COLUMN embedding TYPE vector(${dim})`);
+            await pool.query(`CREATE INDEX fact_embeddings_idx` +
+                ` ON fact_embeddings USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)`);
+            stateData.done = new Set();
+        }
+        const limitClause = opts.limit ? ` LIMIT ${Math.trunc(opts.limit)}` : "";
+        const sessionResult = await pool.query("SELECT id, label, summary, body FROM sessions" +
+            " WHERE body IS NOT NULL OR summary IS NOT NULL OR label IS NOT NULL" +
+            " ORDER BY started_at" +
+            limitClause);
+        const rows = sessionResult.rows;
+        const total = rows.length;
+        const done = stateData.done;
+        let succeeded = 0;
+        let failed = 0;
+        let skipped = 0;
+        for (let i = 0; i < rows.length; i++) {
+            const row = rows[i];
+            const idx = i + 1;
+            if (done.has(row.id)) {
+                skipped += 1;
+                continue;
+            }
+            const chunks = chunkSessionText({
+                label: row.label,
+                summary: row.summary,
+                body: row.body,
+            });
+            if (chunks.length === 0) {
+                failed += 1;
+                opts.onProgress?.(idx, total, row.id, "SKIP (no text)");
+                continue;
+            }
+            await pool.query("DELETE FROM session_embedding_chunks WHERE session_id = $1", [row.id]);
+            const vectors = [];
+            let chunkSkipped = 0;
+            for (let c = 0; c < chunks.length; c++) {
+                const chunk = chunks[c];
+                let lastErr;
+                for (let attempt = 0; attempt < 2; attempt++) {
+                    try {
+                        const out = await opts.embedder.embed(chunk, "document");
+                        vectors.push({ idx: c, vec: out.vector });
+                        lastErr = undefined;
+                        break;
+                    }
+                    catch (e) {
+                        lastErr = e;
+                        if (!(e instanceof LLMUnreachableError))
+                            throw e;
+                        if (attempt === 0)
+                            await new Promise((r) => setTimeout(r, 200));
+                    }
+                }
+                if (lastErr !== undefined)
+                    chunkSkipped += 1;
+            }
+            if (vectors.length === 0) {
+                failed += 1;
+                opts.onProgress?.(idx, total, row.id, `FAIL (embedder, ${chunkSkipped}/${chunks.length} chunks)`);
+                continue;
+            }
+            try {
+                for (const { idx: cidx, vec } of vectors) {
+                    const vecStr = `[${Array.from(vec).join(",")}]`;
+                    const ins = await pool.query(`INSERT INTO session_embedding_chunks (session_id, chunk_idx, embedding)
+             VALUES ($1, $2, $3::vector) RETURNING chunk_id`, [row.id, cidx, vecStr]);
+                    const chunkId = ins.rows[0].chunk_id;
+                    await pool.query("INSERT INTO session_chunk_map (chunk_id, session_id, chunk_idx) VALUES ($1, $2, $3)", [chunkId, row.id, cidx]);
+                }
+            }
+            catch (e) {
+                failed += 1;
+                opts.onProgress?.(idx, total, row.id, `FAIL (db): ${e.message}`);
+                continue;
+            }
+            done.add(row.id);
+            succeeded += 1;
+            const status = chunkSkipped === 0
+                ? `OK (${vectors.length} chunks)`
+                : `PARTIAL (${vectors.length}/${chunks.length} chunks, ${chunkSkipped} skipped)`;
+            opts.onProgress?.(idx, total, row.id, status);
+            if (succeeded % SAVE_EVERY === 0)
+                saveState(statePath, done, { provider, model, dim });
+        }
+        // Reembed facts whenever the stored config does not match the runtime config
+        // (storedConfig exists but configMatch is false). This covers both fresh
+        // rebuilds and interrupted rebuilds that resume: the embedding_config row
+        // is only updated on successful completion, so storedConfig still holds
+        // the old values during a partial run. Gating on needsRebuild alone skips
+        // facts in that resume path.
+        let factsReembedded = 0;
+        if (storedConfig !== null && !configMatch) {
+            const factResult = await pool.query("SELECT id, subject, predicate, value FROM facts" +
+                " WHERE superseded_by IS NULL AND retired_at IS NULL");
+            for (const fact of factResult.rows) {
+                const factText = `${fact.subject} ${fact.predicate} ${fact.value}`.trim();
+                if (!factText)
+                    continue;
+                try {
+                    const out = await opts.embedder.embed(factText, "document");
+                    const vecStr = `[${Array.from(out.vector).join(",")}]`;
+                    await pool.query(`INSERT INTO fact_embeddings (fact_id, embedding)
+             VALUES ($1, $2::vector)
+             ON CONFLICT (fact_id) DO UPDATE SET embedding = EXCLUDED.embedding`, [fact.id, vecStr]);
+                    factsReembedded += 1;
+                }
+                catch {
+                    // Best-effort: fact row survives; semantic recall misses it until re-run.
+                }
+            }
+        }
+        await pool.query(`INSERT INTO embedding_config (lane, provider, model, dim, updated_at)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (lane) DO UPDATE SET
+         provider   = EXCLUDED.provider,
+         model      = EXCLUDED.model,
+         dim        = EXCLUDED.dim,
+         updated_at = EXCLUDED.updated_at`, ["prose", provider, model, dim, new Date().toISOString()]);
+        saveState(statePath, done, { provider, model, dim });
+        return {
+            total,
+            processed: succeeded + failed + skipped,
+            succeeded,
+            failed,
+            skippedAlreadyDone: skipped,
+            dbMissing: false,
+            rebuilt: needsRebuild,
+            factsReembedded,
+        };
+    }
+    finally {
+        await pool.end();
+    }
+}
+//# sourceMappingURL=pg-embed-backfill.js.map

package/dist/core/embedding/pg-embed-backfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-embed-backfill.js","sourceRoot":"","sources":["../../../src/core/embedding/pg-embed-backfill.ts"],"names":[],"mappings":"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"}

package/dist/core/entities/dedup-suggest.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Conservative lexical dedup suggestion for the entity table.
+ *
+ * No embedding similarity in v1: the workstream matcher falsification showed
+ * lexical-adjacent-but-different entities are exactly where embeddings
+ * over-merge. Start conservative; tighten only after adjudication data exists.
+ */
+export interface EntityInput {
+    readonly canonical: string;
+    readonly sessionCount: number;
+    readonly status: string;
+}
+export interface MergeSuggestion {
+    readonly source: string;
+    readonly target: string;
+    readonly cls: "safe" | "likely";
+}
+/**
+ * Suggest merge pairs from a flat list of entities.
+ *
+ * Groups by fold key, then checks likely patterns within each group.
+ * Never suggests a pair twice; never chains (one target per group, all
+ * remaining members are sources into that target).
+ */
+export declare function suggestMerges(entities: ReadonlyArray<EntityInput>): ReadonlyArray<MergeSuggestion>;

package/dist/core/entities/dedup-suggest.js

@@ -0,0 +1,107 @@
+/**
+ * Conservative lexical dedup suggestion for the entity table.
+ *
+ * No embedding similarity in v1: the workstream matcher falsification showed
+ * lexical-adjacent-but-different entities are exactly where embeddings
+ * over-merge. Start conservative; tighten only after adjudication data exists.
+ */
+/**
+ * Fold for safe-class comparison: lowercase, strip spaces, hyphens,
+ * underscores, and dots.
+ */
+function safeFold(s) {
+    return s.toLowerCase().replace(/[\s\-_.]+/g, "");
+}
+// Checked against the already-folded form (hyphens stripped by safeFold).
+const REPO_SUFFIXES_FOLDED = ["ts", "js", "py", "rs", "go"];
+function stripRepoSuffix(folded) {
+    for (const suf of REPO_SUFFIXES_FOLDED) {
+        if (folded.endsWith(suf) && folded.length > suf.length) {
+            return folded.slice(0, -suf.length);
+        }
+    }
+    return folded;
+}
+function isSingularPlural(a, b) {
+    return b === a + "s" || a === b + "s";
+}
+function isRepoSuffixPair(a, b) {
+    const baseA = stripRepoSuffix(a);
+    const baseB = stripRepoSuffix(b);
+    if (a === baseA && b === baseB)
+        return false;
+    return baseA === baseB;
+}
+/**
+ * Pick the target: higher sessionCount wins; on tie, lexicographically smaller
+ * canonical is the target (deterministic).
+ */
+function pickTarget(a, b) {
+    if (a.sessionCount !== b.sessionCount) {
+        return a.sessionCount > b.sessionCount
+            ? { target: a, source: b }
+            : { target: b, source: a };
+    }
+    return a.canonical <= b.canonical
+        ? { target: a, source: b }
+        : { target: b, source: a };
+}
+/**
+ * Suggest merge pairs from a flat list of entities.
+ *
+ * Groups by fold key, then checks likely patterns within each group.
+ * Never suggests a pair twice; never chains (one target per group, all
+ * remaining members are sources into that target).
+ */
+export function suggestMerges(entities) {
+    const active = entities.filter((e) => e.status !== "retired");
+    const safeGroups = new Map();
+    for (const e of active) {
+        const key = safeFold(e.canonical);
+        if (!safeGroups.has(key))
+            safeGroups.set(key, []);
+        safeGroups.get(key).push(e);
+    }
+    // Emission-order invariant the CLI applier depends on: every pair that uses
+    // an entity as TARGET is emitted before the (single) pair that consumes it as
+    // SOURCE, so sequential application never merges into an already-retired row.
+    // Reordering emissions (or applying suggestions out of list order) breaks this.
+    const suggestions = [];
+    const consumedAsSource = new Set();
+    for (const group of safeGroups.values()) {
+        if (group.length < 2)
+            continue;
+        const sorted = [...group].sort((a, b) => {
+            if (b.sessionCount !== a.sessionCount)
+                return b.sessionCount - a.sessionCount;
+            return a.canonical <= b.canonical ? -1 : 1;
+        });
+        const target = sorted[0];
+        for (let i = 1; i < sorted.length; i++) {
+            const source = sorted[i];
+            if (consumedAsSource.has(source.canonical))
+                continue;
+            suggestions.push({ source: source.canonical, target: target.canonical, cls: "safe" });
+            consumedAsSource.add(source.canonical);
+        }
+    }
+    const activeNonSafe = active.filter((e) => !consumedAsSource.has(e.canonical));
+    for (let i = 0; i < activeNonSafe.length; i++) {
+        for (let j = i + 1; j < activeNonSafe.length; j++) {
+            const a = activeNonSafe[i];
+            const b = activeNonSafe[j];
+            if (consumedAsSource.has(a.canonical) || consumedAsSource.has(b.canonical))
+                continue;
+            const fa = safeFold(a.canonical);
+            const fb = safeFold(b.canonical);
+            const isLikely = isSingularPlural(fa, fb) || isRepoSuffixPair(fa, fb);
+            if (!isLikely)
+                continue;
+            const { target, source } = pickTarget(a, b);
+            suggestions.push({ source: source.canonical, target: target.canonical, cls: "likely" });
+            consumedAsSource.add(source.canonical);
+        }
+    }
+    return suggestions;
+}
+//# sourceMappingURL=dedup-suggest.js.map

package/dist/core/entities/dedup-suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-suggest.js","sourceRoot":"","sources":["../../../src/core/entities/dedup-suggest.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH;;;GAGG;AACH,SAAS,QAAQ,CAAC,CAAS;IACzB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,0EAA0E;AAC1E,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAE5D,SAAS,eAAe,CAAC,MAAc;IACrC,KAAK,MAAM,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACvC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;YACvD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAS,EAAE,CAAS;IAC5C,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;AACxC,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC7C,OAAO,KAAK,KAAK,KAAK,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,CAAc,EAAE,CAAc;IAChD,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,YAAY,EAAE,CAAC;QACtC,OAAO,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY;YACpC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;YAC1B,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS;QAC/B,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;QAC1B,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAoC;IAEpC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAE9D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAyB,CAAC;IACpD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAClD,UAAU,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IAED,4EAA4E;IAC5E,8EAA8E;IAC9E,8EAA8E;IAC9E,gFAAgF;IAChF,MAAM,WAAW,GAAsB,EAAE,CAAC;IAC1C,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;IAE3C,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QAE/B,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACtC,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,YAAY;gBAAE,OAAO,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;YAC9E,OAAO,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;QAE1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;YAC1B,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC;gBAAE,SAAS;YACrD,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;YACtF,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAE/E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAE,CAAC;YAC5B,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;gBAAE,SAAS;YAErF,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACjC,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAEjC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACtE,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAExB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC5C,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;YACxF,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/core/eval/classifier-fixture-eval.d.ts

@@ -0,0 +1,29 @@
+import type { ClassifyResult } from "../../ports/llm-client.js";
+export interface FixtureEvalResult {
+    readonly perTranscript: ReadonlyArray<{
+        readonly id: string;
+        readonly schemaValid: boolean;
+        readonly timedOutOrUnreachable: boolean;
+        readonly labelMatch: boolean;
+        readonly entityPrecision: number;
+        readonly entityRecall: number;
+        readonly decisionPrecision: number;
+        readonly decisionRecall: number;
+        readonly confidence: number;
+        readonly confidenceCalibrated: boolean;
+        readonly elapsedMs: number;
+    }>;
+    readonly aggregate: {
+        readonly schemaValidRate: number;
+        readonly labelAccuracy: number;
+        readonly entityF1: number;
+        readonly decisionF1: number;
+        readonly confidenceCalibrationRate: number;
+        readonly p50LatencyMs: number;
+        readonly p95LatencyMs: number;
+        readonly timedOutOrUnreachable: number;
+    };
+}
+export declare function runClassifierFixtureEval(classify: (transcript: string) => Promise<ClassifyResult>, fixturesDir: string, opts?: {
+    readonly limit?: number;
+}): Promise<FixtureEvalResult>;

package/dist/core/eval/classifier-fixture-eval.js

@@ -0,0 +1,217 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { ClassifierSchemaError, LLMUnreachableError } from "../../ports/llm-client.js";
+import { rate } from "../eval/extraction-scoring.js";
+function loadReference(fixturesDir) {
+    const raw = readFileSync(join(fixturesDir, "reference.json"), "utf-8");
+    return JSON.parse(raw);
+}
+function loadTranscript(fixturesDir, id) {
+    return readFileSync(join(fixturesDir, "transcripts", `${id}.txt`), "utf-8");
+}
+function listTranscriptIds(fixturesDir) {
+    const dir = join(fixturesDir, "transcripts");
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".txt"))
+        .map((f) => basename(f, ".txt"))
+        .sort();
+}
+function normalizeStr(s) {
+    return s.toLowerCase().trim();
+}
+function labelMatches(extracted, ref) {
+    const e = normalizeStr(extracted);
+    const candidates = [ref.label, ...ref.labelAlternates].map(normalizeStr);
+    for (const c of candidates) {
+        if (e === c)
+            return true;
+        if (e.includes(c) || c.includes(e))
+            return true;
+        if (keyTokenOverlap(e, c) >= 0.5)
+            return true;
+    }
+    return false;
+}
+function keyTokenOverlap(a, b) {
+    const tokA = keyTokens(a);
+    const tokB = keyTokens(b);
+    if (tokA.size === 0 || tokB.size === 0)
+        return 0;
+    let hits = 0;
+    for (const t of tokA)
+        if (tokB.has(t))
+            hits++;
+    return hits / Math.max(tokA.size, tokB.size);
+}
+function keyTokens(s) {
+    const STOPWORDS = new Set([
+        "a", "an", "the", "and", "or", "for", "to", "of", "in", "on", "with",
+        "at", "by", "from", "up", "as", "is", "it", "its", "into", "that",
+        "this", "be", "are", "was", "were", "has", "have", "had",
+    ]);
+    return new Set(s
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t)));
+}
+function entityMatchesAny(refEntity, extracted) {
+    const rn = normalizeStr(refEntity);
+    for (const e of extracted) {
+        const en = normalizeStr(e);
+        if (en === rn || en.includes(rn) || rn.includes(en))
+            return true;
+    }
+    return false;
+}
+function decisionMatchesAny(refDecision, extracted) {
+    const refToks = keyTokens(normalizeStr(refDecision));
+    if (refToks.size === 0)
+        return extracted.length > 0;
+    for (const e of extracted) {
+        const eToks = keyTokens(normalizeStr(e));
+        let hits = 0;
+        for (const t of refToks)
+            if (eToks.has(t))
+                hits++;
+        if (refToks.size > 0 && hits / refToks.size >= 0.5)
+            return true;
+    }
+    return false;
+}
+function scoreEntityPrecision(extracted, reference) {
+    if (extracted.length === 0)
+        return reference.length === 0 ? 1 : 0;
+    const hits = extracted.filter((e) => entityMatchesAny(e, reference));
+    return hits.length / extracted.length;
+}
+function scoreEntityRecall(extracted, reference) {
+    if (reference.length === 0)
+        return 1;
+    const verdicts = reference.map((r) => entityMatchesAny(r, extracted));
+    return (rate(verdicts, Boolean) ?? 0);
+}
+function scoreDecisionPrecision(extracted, reference) {
+    if (extracted.length === 0)
+        return reference.length === 0 ? 1 : 0;
+    const hits = extracted.filter((e) => decisionMatchesAny(e, reference));
+    return hits.length / extracted.length;
+}
+function scoreDecisionRecall(extracted, reference) {
+    if (reference.length === 0)
+        return 1;
+    const verdicts = reference.map((r) => decisionMatchesAny(r, extracted));
+    return (rate(verdicts, Boolean) ?? 0);
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.floor((p / 100) * (sorted.length - 1));
+    return sorted[idx] ?? 0;
+}
+function f1(precision, recall) {
+    const denom = precision + recall;
+    if (denom === 0)
+        return 0;
+    return (2 * precision * recall) / denom;
+}
+function macroF1(perRow) {
+    if (perRow.length === 0)
+        return 0;
+    const sum = perRow.reduce((acc, x) => acc + f1(x.p, x.r), 0);
+    return sum / perRow.length;
+}
+export async function runClassifierFixtureEval(classify, fixturesDir, opts) {
+    const allRefs = loadReference(fixturesDir);
+    const allIds = listTranscriptIds(fixturesDir);
+    const refById = new Map(allRefs.map((r) => [r.id, r]));
+    const ids = opts?.limit != null ? allIds.slice(0, opts.limit) : allIds;
+    const perTranscript = [];
+    for (const id of ids) {
+        const ref = refById.get(id);
+        if (ref === undefined)
+            continue;
+        const transcript = loadTranscript(fixturesDir, id);
+        const start = Date.now();
+        let result = null;
+        let schemaValid = true;
+        let timedOutOrUnreachable = false;
+        try {
+            result = await classify(transcript);
+        }
+        catch (err) {
+            if (err instanceof ClassifierSchemaError) {
+                schemaValid = false;
+            }
+            else if (err instanceof LLMUnreachableError) {
+                schemaValid = false;
+                timedOutOrUnreachable = true;
+            }
+            else {
+                throw err;
+            }
+        }
+        const elapsedMs = Date.now() - start;
+        if (!schemaValid || result === null) {
+            perTranscript.push({
+                id,
+                schemaValid: false,
+                timedOutOrUnreachable,
+                labelMatch: false,
+                entityPrecision: 0,
+                entityRecall: 0,
+                decisionPrecision: 0,
+                decisionRecall: 0,
+                confidence: 0,
+                confidenceCalibrated: false,
+                elapsedMs,
+            });
+            continue;
+        }
+        const lm = labelMatches(result.label, ref);
+        const ep = scoreEntityPrecision(result.entities, ref.entities);
+        const er = scoreEntityRecall(result.entities, ref.entities);
+        const dp = scoreDecisionPrecision(result.decisions, ref.decisions);
+        const dr = scoreDecisionRecall(result.decisions, ref.decisions);
+        const confidence = result.confidence;
+        const confidenceCalibrated = ref.expectLowConfidence
+            ? confidence <= 0.4
+            : confidence > 0.4;
+        perTranscript.push({
+            id,
+            schemaValid: true,
+            timedOutOrUnreachable: false,
+            labelMatch: lm,
+            entityPrecision: ep,
+            entityRecall: er,
+            decisionPrecision: dp,
+            decisionRecall: dr,
+            confidence,
+            confidenceCalibrated,
+            elapsedMs,
+        });
+    }
+    const n = perTranscript.length;
+    const schemaValidRate = n === 0 ? 0 : perTranscript.filter((r) => r.schemaValid).length / n;
+    const labelAccuracy = n === 0 ? 0 : perTranscript.filter((r) => r.labelMatch).length / n;
+    const confidenceCalibrationRate = n === 0 ? 0 : perTranscript.filter((r) => r.confidenceCalibrated).length / n;
+    const timedOutOrUnreachable = perTranscript.filter((r) => r.timedOutOrUnreachable).length;
+    const entityF1 = macroF1(perTranscript.map((r) => ({ p: r.entityPrecision, r: r.entityRecall })));
+    const decisionF1 = macroF1(perTranscript.map((r) => ({ p: r.decisionPrecision, r: r.decisionRecall })));
+    const sortedLatency = [...perTranscript.map((r) => r.elapsedMs)].sort((a, b) => a - b);
+    const p50LatencyMs = percentile(sortedLatency, 50);
+    const p95LatencyMs = percentile(sortedLatency, 95);
+    return {
+        perTranscript,
+        aggregate: {
+            schemaValidRate,
+            labelAccuracy,
+            entityF1,
+            decisionF1,
+            confidenceCalibrationRate,
+            p50LatencyMs,
+            p95LatencyMs,
+            timedOutOrUnreachable,
+        },
+    };
+}
+//# sourceMappingURL=classifier-fixture-eval.js.map