@brainpilot/runtime 0.0.9 → 0.0.10

package/dist/tools/kb/search-papers.js

@@ -0,0 +1,188 @@
+/**
+ * Multi-criteria paper search over the local ``source/KB_source.json``
+ * library written by ``scripts/extract_meta.py``.
+ *
+ * Mirrors `tools.py:search_papers` (the function that powers the v3 KB on
+ * the legacy MCP server):
+ *
+ *   - Filters: title (exact), authors (any-overlap exact), journal (exact),
+ *     published_year (year prefix). Each filter is OPTIONAL.
+ *   - Ranking: count whole-word keyword matches against title + abstract,
+ *     and optionally the full .mmd body in full-paper mode. Ties break by
+ *     publication date desc.
+ *   - Output: "meta-data" returns metadata + keyword_hits. "full-paper"
+ *     additionally returns a `mmd_content` segment + `segment_info` so
+ *     long papers can be paged through.
+ *
+ * Internal-only fields (``mmd_path``, ``extraction_status``) are stripped
+ * from every returned record so they never leak to an agent.
+ */
+import { readFile } from "node:fs/promises";
+import { resolveKbPaths } from "./paths.js";
+const SEGMENT_CHARS = 20_000;
+const INTERNAL_FIELDS = new Set(["mmd_path", "extraction_status"]);
+function stripInternal(d) {
+    const out = {};
+    for (const [k, v] of Object.entries(d)) {
+        if (!INTERNAL_FIELDS.has(k))
+            out[k] = v;
+    }
+    return out;
+}
+function normalizeStrList(value) {
+    if (value === undefined || value === null)
+        return null;
+    let items;
+    if (typeof value === "string") {
+        items = value.split(",").map((s) => s.trim());
+    }
+    else {
+        items = value.map((s) => String(s).trim());
+    }
+    items = items.filter(Boolean);
+    return items.length ? items : null;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function countKeywordHits(text, patterns) {
+    if (!text)
+        return 0;
+    let n = 0;
+    for (const p of patterns) {
+        const m = text.match(p);
+        if (m)
+            n += m.length;
+    }
+    return n;
+}
+async function readMmd(path) {
+    if (!path)
+        return "";
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+let SOURCE_CACHE = null;
+async function loadSource(kbSourceJson) {
+    // Cheap freshness check via mtime — extract_meta.py writes atomically, so
+    // a changed mtime always reflects a new generation we should pick up.
+    const { stat } = await import("node:fs/promises");
+    let mtimeMs = 0;
+    try {
+        mtimeMs = (await stat(kbSourceJson)).mtimeMs;
+    }
+    catch {
+        /* file may not exist yet — surface a clean error below */
+    }
+    if (SOURCE_CACHE && SOURCE_CACHE.path === kbSourceJson && SOURCE_CACHE.mtimeMs === mtimeMs) {
+        return SOURCE_CACHE.papers;
+    }
+    let raw;
+    try {
+        raw = await readFile(kbSourceJson, "utf8");
+    }
+    catch (err) {
+        throw new Error(`KB_source.json not found at ${kbSourceJson}: ${err.message}`);
+    }
+    const data = JSON.parse(raw);
+    const papers = Array.isArray(data.papers) ? data.papers : [];
+    SOURCE_CACHE = { path: kbSourceJson, mtimeMs, papers };
+    return papers;
+}
+export async function searchPapers(args) {
+    const mode = args.mode ?? "meta-data";
+    if (mode !== "meta-data" && mode !== "full-paper") {
+        throw new Error(`mode must be 'meta-data' or 'full-paper', got '${mode}'`);
+    }
+    const topk = Math.max(1, Math.floor(args.topk ?? 5));
+    const segment = Math.max(1, Math.floor(args.segment ?? 1));
+    const authors = normalizeStrList(args.authors);
+    const keywords = normalizeStrList(args.keywords);
+    const kb = resolveKbPaths(args.kbRoot);
+    const papers = await loadSource(kb.kbSourceJson);
+    // Filter
+    const filtered = [];
+    for (const paper of papers) {
+        if (typeof paper !== "object" || paper === null)
+            continue;
+        if (args.title !== undefined && paper.title !== args.title)
+            continue;
+        if (authors !== null) {
+            const pa = Array.isArray(paper.authors) ? paper.authors : [];
+            if (!authors.some((a) => pa.includes(a)))
+                continue;
+        }
+        if (args.journal !== undefined && paper.journal !== args.journal)
+            continue;
+        if (args.published_year !== undefined) {
+            const pd = typeof paper.published_date === "string" ? paper.published_date : "";
+            if (!pd.startsWith(String(args.published_year)))
+                continue;
+        }
+        filtered.push(paper);
+    }
+    // Rank
+    let ranked = [];
+    if (keywords) {
+        const patterns = [];
+        for (const kw of keywords) {
+            try {
+                patterns.push(new RegExp(`\\b${escapeRegex(kw)}\\b`, "gi"));
+            }
+            catch {
+                /* skip un-compilable */
+            }
+        }
+        for (const p of filtered) {
+            const mmd = await readMmd(p.mmd_path);
+            const blob = `${p.title ?? ""} ${p.abstract ?? ""} ${mmd}`;
+            const hits = countKeywordHits(blob, patterns);
+            ranked.push({ paper: p, hits, mmd });
+        }
+        ranked.sort((a, b) => {
+            if (b.hits !== a.hits)
+                return b.hits - a.hits;
+            const yearA = Number((a.paper.published_date ?? "").slice(0, 4)) || 0;
+            const yearB = Number((b.paper.published_date ?? "").slice(0, 4)) || 0;
+            return yearB - yearA;
+        });
+    }
+    else {
+        ranked = filtered.map((p) => ({ paper: p, hits: 0, mmd: "" }));
+    }
+    const top = ranked.slice(0, topk);
+    if (mode === "meta-data") {
+        return top.map(({ paper, hits }) => ({
+            ...stripInternal(paper),
+            keyword_hits: hits,
+        }));
+    }
+    // full-paper
+    const out = [];
+    for (const { paper, hits, mmd } of top) {
+        const content = mmd || (await readMmd(paper.mmd_path));
+        const totalChars = content.length;
+        const totalSegments = totalChars > 0
+            ? Math.ceil(totalChars / SEGMENT_CHARS)
+            : 1;
+        const seg = Math.max(1, Math.min(segment, totalSegments));
+        const start = (seg - 1) * SEGMENT_CHARS;
+        const end = Math.min(start + SEGMENT_CHARS, totalChars);
+        out.push({
+            metadata: { ...stripInternal(paper), keyword_hits: hits },
+            mmd_content: content.slice(start, end),
+            segment_info: {
+                segment: seg,
+                total_segments: totalSegments,
+                total_chars: totalChars,
+                has_more: seg < totalSegments,
+            },
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=search-papers.js.map

package/dist/tools/kb/search-papers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-papers.js","sourceRoot":"","sources":["../../../src/tools/kb/search-papers.ts"],"names":[],"mappings":"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"}

package/dist/tools/kb/sidecar.d.ts

@@ -0,0 +1,11 @@
+/** Return the sidecar URL, starting the child if needed. Concurrent callers
+ *  share a single startup promise. */
+export declare function ensureSidecar(rootOverride?: string): Promise<string>;
+/** Best-effort shutdown — called from server.ts on signal. */
+export declare function stopSidecar(): void;
+/** Read-only inspection helper for the health UI. */
+export declare function sidecarStatus(): {
+    running: boolean;
+    url?: string;
+};
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/tools/kb/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../../src/tools/kb/sidecar.ts"],"names":[],"mappings":"AA6JA;sCACsC;AACtC,wBAAsB,aAAa,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc1E;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,IAAI,IAAI,CAKlC;AAED,qDAAqD;AACrD,wBAAgB,aAAa,IAAI;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAElE"}

package/dist/tools/kb/sidecar.js

@@ -0,0 +1,161 @@
+/**
+ * Lazy bge model sidecar.
+ *
+ * bge-m3 and bge-reranker-v2-m3 take 5–20 s to load and ~2.5 GB of RAM —
+ * way too much for a per-query cost. The runtime keeps ONE shared Python
+ * sub-process running for the lifetime of the BrainPilot session and
+ * routes every embed/rerank call to it over loopback HTTP.
+ *
+ * Lifecycle:
+ *   - cold:   no child, no port, no readiness — first caller triggers start()
+ *   - starting:  child spawned with --port 0, port file polled until readable
+ *               then `/health` polled until `embedder_loaded === true`
+ *   - ready:  every caller resolves to the same { url } record
+ *   - dead:   if the process exits, the next call retries from cold
+ *
+ * The user can bypass the sidecar entirely by setting `BP_KB_SERVER_URL`
+ * (point at a pre-existing model server). In that case we skip the spawn
+ * and just probe that URL.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveKbPaths } from "./paths.js";
+import { resolveKbPython } from "./python.js";
+const HEALTH_TIMEOUT_MS = 60_000; // first PyTorch load can be slow on CPU
+const POLL_INTERVAL_MS = 500;
+let STATE = null;
+async function pollPortFile(path, deadlineMs) {
+    while (Date.now() < deadlineMs) {
+        if (existsSync(path)) {
+            try {
+                const text = (await readFile(path, "utf8")).trim();
+                const port = Number(text);
+                if (Number.isInteger(port) && port > 0)
+                    return port;
+            }
+            catch {
+                /* race: writer mid-write, keep polling */
+            }
+        }
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+    throw new Error(`sidecar did not publish its port within ${HEALTH_TIMEOUT_MS}ms`);
+}
+async function pollHealth(url, deadlineMs) {
+    let lastErr = null;
+    while (Date.now() < deadlineMs) {
+        try {
+            const r = await fetch(url + "/health");
+            if (r.ok) {
+                const h = (await r.json());
+                if (h.embedder_loaded && h.reranker_loaded)
+                    return;
+            }
+        }
+        catch (err) {
+            lastErr = err;
+        }
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+    throw new Error(`sidecar at ${url} not ready in ${HEALTH_TIMEOUT_MS}ms${lastErr ? `: ${lastErr.message}` : ""}`);
+}
+async function startSidecar(rootOverride) {
+    // Honour an out-of-process server set by the operator. Useful for: shared
+    // GPU box, dev iteration without restarting BrainPilot, integration tests.
+    const overrideUrl = process.env.BP_KB_SERVER_URL?.trim();
+    if (overrideUrl) {
+        await pollHealth(overrideUrl, Date.now() + HEALTH_TIMEOUT_MS);
+        return overrideUrl;
+    }
+    const paths = resolveKbPaths(rootOverride);
+    if (!existsSync(paths.serverScript)) {
+        throw new Error(`KnowledgeBase model_server.py not found at ${paths.serverScript} — ` +
+            `is the KnowledgeBase/ directory present alongside the runtime install?`);
+    }
+    if (!existsSync(paths.embedModelDir) || !existsSync(paths.rerankerModelDir)) {
+        throw new Error(`bge model weights missing under ${paths.modelsDir} — ` +
+            `run "python KnowledgeBase/scripts/setup_models.py" first.`);
+    }
+    const dir = await mkdtemp(join(tmpdir(), "bp-kb-"));
+    const portFile = join(dir, "port");
+    const child = spawn(resolveKbPython(paths.root), [paths.serverScript, "--kb-root", paths.root, "--port", "0", "--port-file", portFile], {
+        stdio: ["ignore", "inherit", "inherit"],
+        env: {
+            ...process.env,
+            BP_KB_ROOT: paths.root,
+        },
+    });
+    child.on("exit", (code, sig) => {
+        // eslint-disable-next-line no-console
+        console.warn(`[kb-sidecar] exited code=${code} signal=${sig}`);
+        // Drop the cached state so the next caller respawns.
+        if (STATE && STATE.proc === child) {
+            STATE.proc = undefined;
+            STATE.port = undefined;
+            STATE.url = undefined;
+            STATE.ready = null;
+        }
+    });
+    const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+    let port;
+    try {
+        port = await pollPortFile(portFile, deadline);
+    }
+    catch (err) {
+        child.kill("SIGTERM");
+        throw err;
+    }
+    finally {
+        void unlink(portFile).catch(() => { });
+    }
+    const url = `http://127.0.0.1:${port}`;
+    try {
+        await pollHealth(url, deadline);
+    }
+    catch (err) {
+        child.kill("SIGTERM");
+        throw err;
+    }
+    // eslint-disable-next-line no-console
+    console.info(`[kb-sidecar] ready at ${url}`);
+    if (STATE) {
+        STATE.proc = child;
+        STATE.port = port;
+        STATE.url = url;
+    }
+    return url;
+}
+/** Return the sidecar URL, starting the child if needed. Concurrent callers
+ *  share a single startup promise. */
+export async function ensureSidecar(rootOverride) {
+    const paths = resolveKbPaths(rootOverride);
+    if (!STATE || STATE.paths.root !== paths.root) {
+        STATE = { paths, ready: null };
+    }
+    if (STATE.url)
+        return STATE.url;
+    if (!STATE.ready) {
+        STATE.ready = startSidecar(rootOverride).catch((err) => {
+            // Clear so the next call retries instead of returning a rejected promise forever.
+            if (STATE)
+                STATE.ready = null;
+            throw err;
+        });
+    }
+    return STATE.ready;
+}
+/** Best-effort shutdown — called from server.ts on signal. */
+export function stopSidecar() {
+    if (STATE?.proc && !STATE.proc.killed) {
+        STATE.proc.kill("SIGTERM");
+    }
+    STATE = null;
+}
+/** Read-only inspection helper for the health UI. */
+export function sidecarStatus() {
+    return { running: !!STATE?.url, url: STATE?.url };
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/tools/kb/sidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.js","sourceRoot":"","sources":["../../../src/tools/kb/sidecar.ts"],"names":[],"mappings":"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"}

package/dist/tools/kb/store.d.ts

@@ -0,0 +1,45 @@
+import { type KbPaths } from "./paths.js";
+export interface ChunkMetadata {
+    title?: string;
+    authors?: string[];
+    journal?: string;
+    published_date?: string;
+    abstract?: string;
+    pdf_url?: string;
+    mmd_path?: string;
+    chunk_index?: number;
+    char_start?: number;
+    char_end?: number;
+}
+export interface ChunkRecord {
+    chunk_id: string;
+    text: string;
+    metadata: ChunkMetadata;
+}
+interface CacheEntry {
+    embeddings: Float32Array;
+    chunks: ChunkRecord[];
+    count: number;
+    dim: number;
+    metaCount: number;
+}
+/**
+ * Load (or return the cached) vector store. If meta.json on disk reports a
+ * different row count than the cached entry, transparently reload — that's
+ * how a freshly-vectorized batch becomes visible to a running runtime
+ * without restart.
+ */
+export declare function getStore(rootOverride?: string): Promise<CacheEntry & {
+    paths: KbPaths;
+}>;
+/** Best-effort sanity probe used by health endpoints / UI. */
+export declare function storeHealth(rootOverride?: string): Promise<{
+    ready: boolean;
+    count: number;
+    reason?: string;
+    updatedAt?: string;
+}>;
+/** Drop the in-process cache (mainly for tests). */
+export declare function clearStoreCache(): void;
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/tools/kb/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/tools/kb/store.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,UAAU,UAAU;IAClB,UAAU,EAAE,YAAY,CAAC;IACzB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAuGD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAY9F;AAED,8DAA8D;AAC9D,wBAAsB,WAAW,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAkBD;AAED,oDAAoD;AACpD,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/tools/kb/store.js

@@ -0,0 +1,157 @@
+/**
+ * In-process load of the vector store written by ``scripts/vectorize.py``.
+ *
+ * The store is three small files:
+ *   embeddings.npy  — float32 (N, 1024), L2-normalised rows
+ *   chunks.jsonl    — one chunk per line, same row order as embeddings
+ *   meta.json       — {count, dim, model, updated_at, normalized}
+ *
+ * The matrix and the chunk list are cached for the lifetime of the process
+ * and reloaded transparently when ``meta.json`` reports a different count
+ * (i.e. the build pipeline appended new chunks since the last query).
+ *
+ * NPY parsing: we only support the exact file shape ``vectorize.py`` writes
+ * (float32, C-order, 2D). Anything else throws — the user re-ran some
+ * other tool against the store and we'd rather fail loud than mis-cast.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolveKbPaths } from "./paths.js";
+let CACHE = null;
+/**
+ * Read meta.json to learn the on-disk row count without loading the matrix.
+ * Returns null if meta.json is missing/unparseable — caller treats as cold.
+ */
+async function readMetaCount(kb) {
+    try {
+        const raw = await readFile(kb.metaJson, "utf8");
+        const v = JSON.parse(raw)?.count;
+        return typeof v === "number" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Minimal numpy .npy v1.0/v2.0 reader for the exact shape vectorize.py writes.
+ * Format: '\x93NUMPY' magic, 1-byte major, 1-byte minor, header-length
+ * (uint16 in v1, uint32 in v2), header dict text, then row-major data.
+ */
+function parseNpyFloat32(buf) {
+    if (buf.length < 10)
+        throw new Error(".npy: file too small");
+    if (buf[0] !== 0x93 ||
+        buf.slice(1, 6).toString("ascii") !== "NUMPY") {
+        throw new Error(".npy: bad magic");
+    }
+    const major = buf[1 + 5] ?? 0;
+    let headerLen;
+    let headerStart;
+    if (major === 1) {
+        headerLen = buf.readUInt16LE(8);
+        headerStart = 10;
+    }
+    else if (major === 2 || major === 3) {
+        headerLen = buf.readUInt32LE(8);
+        headerStart = 12;
+    }
+    else {
+        throw new Error(`.npy: unsupported major version ${major}`);
+    }
+    const header = buf.slice(headerStart, headerStart + headerLen).toString("ascii");
+    // Header is a Python dict literal. Pull just the bits we need with regex —
+    // bringing in a Python literal parser for this would be overkill.
+    const descrMatch = header.match(/'descr':\s*'([^']+)'/);
+    const fortranMatch = header.match(/'fortran_order':\s*(True|False)/);
+    const shapeMatch = header.match(/'shape':\s*\(\s*(\d+)\s*,\s*(\d+)\s*\)/);
+    if (!descrMatch || !fortranMatch || !shapeMatch) {
+        throw new Error(`.npy: cannot parse header: ${header}`);
+    }
+    const descr = descrMatch[1];
+    if (descr !== "<f4" && descr !== "|f4" && descr !== "=f4") {
+        throw new Error(`.npy: only float32 (<f4) supported, got ${descr}`);
+    }
+    if (fortranMatch[1] === "True") {
+        throw new Error(".npy: fortran-order not supported");
+    }
+    const rows = Number(shapeMatch[1]);
+    const cols = Number(shapeMatch[2]);
+    const dataStart = headerStart + headerLen;
+    const expectedBytes = rows * cols * 4;
+    if (buf.length - dataStart < expectedBytes) {
+        throw new Error(`.npy: short data (need ${expectedBytes} bytes, have ${buf.length - dataStart})`);
+    }
+    // Float32Array view on the underlying ArrayBuffer (no copy).
+    const data = new Float32Array(buf.buffer, buf.byteOffset + dataStart, rows * cols);
+    return { data, rows, cols };
+}
+async function readChunksJsonl(path, expected) {
+    const raw = await readFile(path, "utf8");
+    const records = [];
+    // Split on \n, drop trailing empty line. Each line is one chunk.
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        records.push(JSON.parse(line));
+    }
+    if (records.length !== expected) {
+        throw new Error(`vector store mismatch: embeddings=${expected} chunks.jsonl=${records.length}`);
+    }
+    return records;
+}
+async function loadFresh(kb) {
+    if (!existsSync(kb.embeddingsNpy) || !existsSync(kb.chunksJsonl)) {
+        throw new Error(`vector store not found in ${kb.vectorstoreDir} — ` +
+            `run the build pipeline (scripts/build_kb.py) first.`);
+    }
+    const buf = await readFile(kb.embeddingsNpy);
+    const { data, rows, cols } = parseNpyFloat32(buf);
+    const chunks = await readChunksJsonl(kb.chunksJsonl, rows);
+    const metaCount = (await readMetaCount(kb)) ?? rows;
+    return { embeddings: data, chunks, count: rows, dim: cols, metaCount };
+}
+/**
+ * Load (or return the cached) vector store. If meta.json on disk reports a
+ * different row count than the cached entry, transparently reload — that's
+ * how a freshly-vectorized batch becomes visible to a running runtime
+ * without restart.
+ */
+export async function getStore(rootOverride) {
+    const kb = resolveKbPaths(rootOverride);
+    if (CACHE && CACHE.paths.root === kb.root) {
+        const diskCount = await readMetaCount(kb);
+        if (diskCount === null || diskCount === CACHE.entry.metaCount) {
+            return { ...CACHE.entry, paths: kb };
+        }
+        // stale — fall through to a fresh load
+    }
+    const entry = await loadFresh(kb);
+    CACHE = { paths: kb, entry };
+    return { ...entry, paths: kb };
+}
+/** Best-effort sanity probe used by health endpoints / UI. */
+export async function storeHealth(rootOverride) {
+    const kb = resolveKbPaths(rootOverride);
+    if (!existsSync(kb.embeddingsNpy) || !existsSync(kb.chunksJsonl)) {
+        return { ready: false, count: 0, reason: "vector store not built yet" };
+    }
+    try {
+        const meta = JSON.parse(await readFile(kb.metaJson, "utf8"));
+        return {
+            ready: typeof meta.count === "number" && meta.count > 0,
+            count: meta.count ?? 0,
+            updatedAt: meta.updated_at,
+        };
+    }
+    catch {
+        // meta.json missing but embeddings/chunks exist — still considered ready,
+        // just without the freshness metadata.
+        const st = await stat(kb.embeddingsNpy);
+        return { ready: true, count: 0, updatedAt: st.mtime.toISOString() };
+    }
+}
+/** Drop the in-process cache (mainly for tests). */
+export function clearStoreCache() {
+    CACHE = null;
+}
+//# sourceMappingURL=store.js.map

package/dist/tools/kb/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/tools/kb/store.ts"],"names":[],"mappings":"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"}

package/dist/tools/kb/tools.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pi-native SystemTool factories for the local knowledge base:
+ *
+ *   get_domain_knowledge_local
+ *     RAG over the local vector store (bge-m3 + bge-reranker-v2-m3).
+ *     Mirrors the legacy ``tools.py:get_domain_knowledge`` we shipped on the
+ *     central MCP server, but everything is computed in-process: a sidecar
+ *     Python child holds the model in memory and answers HTTP requests on
+ *     loopback.
+ *
+ *   search_papers_local
+ *     Multi-criteria search over ``source/KB_source.json``. Same surface as
+ *     ``tools.py:search_papers``.
+ *
+ * Both tools return STRINGS. Errors are returned as ``"ERROR: ..."`` strings
+ * (with the tool result also marked ``isError: true`` so Pi surfaces it as
+ * a failed call) — never thrown. This matches the legacy contract and lets
+ * agents react to a missing KB or an unreachable sidecar by simply reading
+ * the result.
+ */
+import type { SystemTool } from "../../types.js";
+export declare function createGetDomainKnowledgeLocalTool(): SystemTool;
+export declare function createSearchPapersLocalTool(): SystemTool;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools/kb/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/tools/kb/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAqDjD,wBAAgB,iCAAiC,IAAI,UAAU,CAqF9D;AAID,wBAAgB,2BAA2B,IAAI,UAAU,CA8ExD"}