@memvid/sdk 2.0.113

package/dist/index.js

@@ -0,0 +1,458 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_DIMENSIONS = exports.getEmbedder = exports.VoyageEmbeddings = exports.CohereEmbeddings = exports.OpenAIEmbeddings = exports.CorruptFileError = exports.VecIndexDisabledError = exports.FrameNotFoundError = exports.MemoryAlreadyBoundError = exports.ApiKeyRequiredError = exports.LockedError = exports.VerificationFailedError = exports.TimeIndexMissingError = exports.LexIndexDisabledError = exports.TicketReplayError = exports.TicketInvalidError = exports.CapacityExceededError = exports.MemvidError = exports.use = exports.GeminiEntities = exports.ClaudeEntities = exports.OpenAIEntities = exports.LocalNER = exports.getEntityExtractor = exports.GeminiClip = exports.OpenAIClip = exports.LocalClip = exports.getClipProvider = exports.entities = exports.clip = void 0;
+exports.create = create;
+exports.maskPii = maskPii;
+const registry_1 = require("./registry");
+const error_1 = require("./error");
+// Adapter registrations (side effects)
+require("./adapters/basic");
+require("./adapters/langchain");
+require("./adapters/llamaindex");
+require("./adapters/crewai");
+require("./adapters/vercel_ai");
+require("./adapters/openai");
+require("./adapters/autogen");
+require("./adapters/haystack");
+require("./adapters/langgraph");
+require("./adapters/semantic_kernel");
+require("./adapters/google_adk");
+require("./adapters/mcp");
+// Export CLIP and entities modules
+exports.clip = __importStar(require("./clip"));
+exports.entities = __importStar(require("./entities"));
+// Re-export provider factories for convenience
+var clip_1 = require("./clip");
+Object.defineProperty(exports, "getClipProvider", { enumerable: true, get: function () { return clip_1.getClipProvider; } });
+Object.defineProperty(exports, "LocalClip", { enumerable: true, get: function () { return clip_1.LocalClip; } });
+Object.defineProperty(exports, "OpenAIClip", { enumerable: true, get: function () { return clip_1.OpenAIClip; } });
+Object.defineProperty(exports, "GeminiClip", { enumerable: true, get: function () { return clip_1.GeminiClip; } });
+var entities_1 = require("./entities");
+Object.defineProperty(exports, "getEntityExtractor", { enumerable: true, get: function () { return entities_1.getEntityExtractor; } });
+Object.defineProperty(exports, "LocalNER", { enumerable: true, get: function () { return entities_1.LocalNER; } });
+Object.defineProperty(exports, "OpenAIEntities", { enumerable: true, get: function () { return entities_1.OpenAIEntities; } });
+Object.defineProperty(exports, "ClaudeEntities", { enumerable: true, get: function () { return entities_1.ClaudeEntities; } });
+Object.defineProperty(exports, "GeminiEntities", { enumerable: true, get: function () { return entities_1.GeminiEntities; } });
+const addon = require("../index.node");
+function normaliseApiKey(apikey) {
+    if (!apikey) {
+        return undefined;
+    }
+    if (typeof apikey === "string") {
+        return { default: apikey };
+    }
+    if ("provider" in apikey && "key" in apikey) {
+        return { [apikey.provider]: apikey.key };
+    }
+    const map = {};
+    for (const [provider, key] of Object.entries(apikey)) {
+        if (key) {
+            map[provider] = String(key);
+        }
+    }
+    return Object.keys(map).length > 0 ? map : undefined;
+}
+function normalisePutArgs(input) {
+    const payload = {
+        title: input.title,
+        label: input.label,
+        metadata: input.metadata,
+        text: input.text,
+        file: input.file,
+        uri: input.uri,
+        tags: input.tags,
+        labels: input.labels,
+        kind: input.kind,
+        track: input.track,
+        search_text: input.searchText,
+        enable_embedding: input.enableEmbedding,
+        auto_tag: input.autoTag,
+        extract_dates: input.extractDates,
+        vector_compression: input.vectorCompression,
+    };
+    return payload;
+}
+function normaliseFindOptions(opts) {
+    if (!opts) {
+        return undefined;
+    }
+    const payload = {
+        k: opts.k,
+        snippetChars: opts.snippetChars,
+        scope: opts.scope,
+        cursor: opts.cursor,
+        asOfFrame: opts.asOfFrame,
+        asOfTs: opts.asOfTs,
+    };
+    if (payload.k == null &&
+        payload.snippetChars == null &&
+        payload.scope == null &&
+        payload.cursor == null &&
+        payload.asOfFrame == null &&
+        payload.asOfTs == null) {
+        return undefined;
+    }
+    return payload;
+}
+function normaliseAskOptions(opts) {
+    if (!opts) {
+        return undefined;
+    }
+    const payload = {
+        k: opts.k,
+        mode: opts.mode,
+        snippetChars: opts.snippetChars,
+        scope: opts.scope,
+        since: opts.since,
+        until: opts.until,
+        contextOnly: opts.contextOnly,
+        model: opts.model,
+        llmContextChars: opts.llmContextChars,
+        modelApiKey: opts.modelApiKey,
+        asOfFrame: opts.asOfFrame,
+        asOfTs: opts.asOfTs,
+    };
+    if (payload.k == null &&
+        payload.mode == null &&
+        payload.snippetChars == null &&
+        payload.scope == null &&
+        payload.since == null &&
+        payload.until == null &&
+        payload.contextOnly == null &&
+        payload.model == null &&
+        payload.llmContextChars == null &&
+        payload.modelApiKey == null &&
+        payload.asOfFrame == null &&
+        payload.asOfTs == null) {
+        return undefined;
+    }
+    return payload;
+}
+function normaliseTimelineOptions(opts) {
+    if (!opts) {
+        return undefined;
+    }
+    const payload = {
+        limit: opts.limit,
+        since: opts.since,
+        until: opts.until,
+        reverse: opts.reverse,
+        asOfFrame: opts.asOfFrame,
+        asOfTs: opts.asOfTs,
+    };
+    if (payload.limit == null &&
+        payload.since == null &&
+        payload.until == null &&
+        payload.reverse == null &&
+        payload.asOfFrame == null &&
+        payload.asOfTs == null) {
+        return undefined;
+    }
+    return payload;
+}
+/**
+ * Helper to wrap async operations and convert native errors to MemvidError.
+ */
+async function wrapAsync(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            throw (0, error_1.wrapNativeError)(err);
+        }
+        throw err;
+    }
+}
+class MemvidImpl {
+    constructor(kind, core, attachments) {
+        this.kind = kind;
+        this.core = core;
+        this.tools = attachments.tools;
+        this.functions = attachments.functions;
+        this.nodes = attachments.nodes;
+        this.asQueryEngine = attachments.asQueryEngine ?? null;
+    }
+    async put(data) {
+        return wrapAsync(async () => {
+            // Set vector compression mode if requested
+            if (data.vectorCompression) {
+                await this.core.setVectorCompression(true);
+            }
+            return this.core.put(normalisePutArgs(data));
+        });
+    }
+    async putMany(requests, options) {
+        return wrapAsync(async () => {
+            // Convert to native format
+            const nativeRequests = requests.map((req) => ({
+                title: req.title,
+                text: req.text,
+                uri: req.uri,
+                labels: req.labels,
+                tags: req.tags,
+                metadata: req.metadata,
+                embedding: req.embedding,
+            }));
+            const nativeOptions = options
+                ? { compression_level: options.compressionLevel }
+                : undefined;
+            return this.core.putMany(nativeRequests, nativeOptions);
+        });
+    }
+    async find(query, opts) {
+        return wrapAsync(async () => {
+            const options = normaliseFindOptions(opts);
+            return this.core.find(query, options);
+        });
+    }
+    async ask(question, opts) {
+        return wrapAsync(async () => {
+            const options = normaliseAskOptions(opts);
+            const response = await this.core.ask(question, options);
+            // Apply PII masking if requested
+            if (opts?.maskPii) {
+                // Note: napi-rs converts snake_case to camelCase, so mask_pii becomes maskPii
+                const maskPiiFn = addon.maskPii;
+                // Mask the aggregated context
+                if (response.context) {
+                    response.context = maskPiiFn(response.context);
+                }
+                // Mask the answer
+                if (response.answer) {
+                    response.answer = maskPiiFn(response.answer);
+                }
+                // Mask answer_lines
+                if (response.answer_lines && Array.isArray(response.answer_lines)) {
+                    response.answer_lines = response.answer_lines.map((line) => maskPiiFn(line));
+                }
+                // Mask text in each hit
+                if (response.hits && Array.isArray(response.hits)) {
+                    for (const hit of response.hits) {
+                        if (hit.text) {
+                            hit.text = maskPiiFn(hit.text);
+                        }
+                        if (hit.chunk_text) {
+                            hit.chunk_text = maskPiiFn(hit.chunk_text);
+                        }
+                        if (hit.snippet) {
+                            hit.snippet = maskPiiFn(hit.snippet);
+                        }
+                        if (hit.tags && Array.isArray(hit.tags)) {
+                            hit.tags = hit.tags.map((tag) => maskPiiFn(tag));
+                        }
+                        if (hit.labels && Array.isArray(hit.labels)) {
+                            hit.labels = hit.labels.map((label) => maskPiiFn(label));
+                        }
+                    }
+                }
+                // Mask context_fragments
+                if (response.context_fragments && Array.isArray(response.context_fragments)) {
+                    for (const fragment of response.context_fragments) {
+                        if (fragment.text) {
+                            fragment.text = maskPiiFn(fragment.text);
+                        }
+                    }
+                }
+                // Mask sources
+                if (response.sources && Array.isArray(response.sources)) {
+                    for (const source of response.sources) {
+                        if (source.snippet) {
+                            source.snippet = maskPiiFn(source.snippet);
+                        }
+                        if (source.tags && Array.isArray(source.tags)) {
+                            source.tags = source.tags.map((tag) => maskPiiFn(tag));
+                        }
+                        if (source.labels && Array.isArray(source.labels)) {
+                            source.labels = source.labels.map((label) => maskPiiFn(label));
+                        }
+                    }
+                }
+                // Mask primary_source
+                if (response.primary_source) {
+                    if (response.primary_source.snippet) {
+                        response.primary_source.snippet = maskPiiFn(response.primary_source.snippet);
+                    }
+                    if (response.primary_source.tags && Array.isArray(response.primary_source.tags)) {
+                        response.primary_source.tags = response.primary_source.tags.map((tag) => maskPiiFn(tag));
+                    }
+                    if (response.primary_source.labels && Array.isArray(response.primary_source.labels)) {
+                        response.primary_source.labels = response.primary_source.labels.map((label) => maskPiiFn(label));
+                    }
+                }
+            }
+            return response;
+        });
+    }
+    async timeline(opts) {
+        return wrapAsync(async () => {
+            const options = normaliseTimelineOptions(opts);
+            return this.core.timeline(options);
+        });
+    }
+    async stats() {
+        return wrapAsync(() => this.core.stats());
+    }
+    async seal() {
+        return wrapAsync(() => this.core.seal());
+    }
+    async enableLex() {
+        return wrapAsync(() => this.core.enableLex());
+    }
+    async setVectorCompression(enabled) {
+        return wrapAsync(() => this.core.setVectorCompression(enabled));
+    }
+    async applyTicket(ticket) {
+        return wrapAsync(() => this.core.applyTicket(ticket));
+    }
+    async getMemoryBinding() {
+        return wrapAsync(() => this.core.getMemoryBinding());
+    }
+    async unbindMemory() {
+        return wrapAsync(() => this.core.unbindMemory());
+    }
+    async getCapacity() {
+        return wrapAsync(() => this.core.getCapacity());
+    }
+    async currentTicket() {
+        return wrapAsync(() => this.core.currentTicket());
+    }
+    async syncTickets(memoryId, apiKey, apiUrl) {
+        return wrapAsync(() => this.core.syncTickets(memoryId, apiKey, apiUrl));
+    }
+    async putPdfTables(pdfPath, embedRows) {
+        return wrapAsync(() => this.core.putPdfTables(pdfPath, embedRows ?? true));
+    }
+    async listTables() {
+        return wrapAsync(() => this.core.listTables());
+    }
+    async getTable(tableId, format) {
+        return wrapAsync(() => this.core.getTable(tableId, format ?? "dict"));
+    }
+}
+const useImpl = (async (kind, filename, apiKey, options) => {
+    const normalised = normaliseApiKey(apiKey);
+    const mode = options?.mode ?? "open";
+    // Extract the API key string for the native layer
+    // Use the "default" key from normalized map, or the first available key
+    let apiKeyStr;
+    if (normalised) {
+        apiKeyStr = normalised.default ?? Object.values(normalised)[0];
+    }
+    let core;
+    try {
+        core = addon.openMemvid(filename, mode, true, true, apiKeyStr);
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            throw (0, error_1.wrapNativeError)(err);
+        }
+        throw err;
+    }
+    const attachments = await (0, registry_1.resolve)(kind, core, normalised);
+    return new MemvidImpl(kind, core, attachments);
+});
+useImpl.verify = async (path, options) => {
+    const nativeOptions = options ? { deep: options.deep } : undefined;
+    return addon.verifyMemvid(path, nativeOptions);
+};
+useImpl.doctor = async (path, options) => {
+    if (!options) {
+        return addon.doctorMemvid(path, undefined);
+    }
+    const nativeOptions = {
+        rebuild_time_index: options.rebuildTimeIndex,
+        rebuild_lex_index: options.rebuildLexIndex,
+        rebuild_vec_index: options.rebuildVecIndex,
+        vacuum: options.vacuum,
+        dry_run: options.dryRun,
+    };
+    return addon.doctorMemvid(path, nativeOptions);
+};
+exports.use = useImpl;
+exports.default = useImpl;
+async function create(filename, kind = "basic", apiKey) {
+    return useImpl(kind, filename, apiKey, { mode: "create" });
+}
+// Re-export error classes for catch handling
+var error_2 = require("./error");
+Object.defineProperty(exports, "MemvidError", { enumerable: true, get: function () { return error_2.MemvidError; } });
+Object.defineProperty(exports, "CapacityExceededError", { enumerable: true, get: function () { return error_2.CapacityExceededError; } });
+Object.defineProperty(exports, "TicketInvalidError", { enumerable: true, get: function () { return error_2.TicketInvalidError; } });
+Object.defineProperty(exports, "TicketReplayError", { enumerable: true, get: function () { return error_2.TicketReplayError; } });
+Object.defineProperty(exports, "LexIndexDisabledError", { enumerable: true, get: function () { return error_2.LexIndexDisabledError; } });
+Object.defineProperty(exports, "TimeIndexMissingError", { enumerable: true, get: function () { return error_2.TimeIndexMissingError; } });
+Object.defineProperty(exports, "VerificationFailedError", { enumerable: true, get: function () { return error_2.VerificationFailedError; } });
+Object.defineProperty(exports, "LockedError", { enumerable: true, get: function () { return error_2.LockedError; } });
+Object.defineProperty(exports, "ApiKeyRequiredError", { enumerable: true, get: function () { return error_2.ApiKeyRequiredError; } });
+Object.defineProperty(exports, "MemoryAlreadyBoundError", { enumerable: true, get: function () { return error_2.MemoryAlreadyBoundError; } });
+Object.defineProperty(exports, "FrameNotFoundError", { enumerable: true, get: function () { return error_2.FrameNotFoundError; } });
+Object.defineProperty(exports, "VecIndexDisabledError", { enumerable: true, get: function () { return error_2.VecIndexDisabledError; } });
+Object.defineProperty(exports, "CorruptFileError", { enumerable: true, get: function () { return error_2.CorruptFileError; } });
+// Re-export embeddings module
+var embeddings_1 = require("./embeddings");
+Object.defineProperty(exports, "OpenAIEmbeddings", { enumerable: true, get: function () { return embeddings_1.OpenAIEmbeddings; } });
+Object.defineProperty(exports, "CohereEmbeddings", { enumerable: true, get: function () { return embeddings_1.CohereEmbeddings; } });
+Object.defineProperty(exports, "VoyageEmbeddings", { enumerable: true, get: function () { return embeddings_1.VoyageEmbeddings; } });
+Object.defineProperty(exports, "getEmbedder", { enumerable: true, get: function () { return embeddings_1.getEmbedder; } });
+Object.defineProperty(exports, "MODEL_DIMENSIONS", { enumerable: true, get: function () { return embeddings_1.MODEL_DIMENSIONS; } });
+/**
+ * Mask PII (Personally Identifiable Information) in text.
+ *
+ * Detects and replaces common PII patterns with placeholder tokens:
+ * - Email addresses → [EMAIL]
+ * - US Social Security Numbers → [SSN]
+ * - Phone numbers → [PHONE]
+ * - Credit card numbers → [CREDIT_CARD]
+ * - IPv4 addresses → [IP_ADDRESS]
+ * - API keys/tokens → [API_KEY]
+ *
+ * @param text - The text to mask
+ * @returns Text with PII replaced by placeholder tokens
+ *
+ * @example
+ * ```typescript
+ * import { maskPii } from 'memvid-sdk';
+ *
+ * const text = "Contact john@example.com at 555-123-4567";
+ * const masked = maskPii(text);
+ * console.log(masked); // "Contact [EMAIL] at [PHONE]"
+ * ```
+ */
+function maskPii(text) {
+    // Note: napi-rs converts snake_case to camelCase
+    return addon.maskPii(text);
+}

package/dist/noop.d.ts

@@ -0,0 +1,2 @@
+export type NoOpFunction = (...args: unknown[]) => undefined;
+export declare function createNoOp(message: string, key: string): NoOpFunction;

package/dist/noop.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNoOp = createNoOp;
+const warned = new Set();
+function createNoOp(message, key) {
+    const warn = () => {
+        if (!warned.has(key)) {
+            warned.add(key);
+            console.warn(message);
+        }
+    };
+    const base = () => {
+        warn();
+        return undefined;
+    };
+    const handler = {
+        apply: () => {
+            warn();
+            return undefined;
+        },
+        get: (_target, prop) => {
+            warn();
+            if (prop === Symbol.toPrimitive) {
+                return () => {
+                    warn();
+                    return 0;
+                };
+            }
+            if (prop === "valueOf") {
+                return () => {
+                    warn();
+                    return 0;
+                };
+            }
+            if (prop === "toString") {
+                return () => {
+                    warn();
+                    return "";
+                };
+            }
+            if (prop === Symbol.iterator) {
+                return function* iterator() {
+                    warn();
+                };
+            }
+            return proxy;
+        },
+        has: () => {
+            warn();
+            return false;
+        },
+    };
+    const proxy = new Proxy(base, handler);
+    return proxy;
+}

package/dist/registry.d.ts

@@ -0,0 +1,5 @@
+import type { AdapterBundle, ApiKeyMap, Kind, NativeMemvid } from "./types";
+type Loader = (core: NativeMemvid, apiKey: ApiKeyMap | undefined) => Promise<AdapterBundle>;
+export declare function register(kind: Kind, loader: Loader): void;
+export declare function resolve(kind: Kind, core: NativeMemvid, apiKey: ApiKeyMap | undefined): Promise<AdapterBundle>;
+export {};

package/dist/registry.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+exports.resolve = resolve;
+const noop_1 = require("./noop");
+const loaders = new Map();
+const cache = new Map();
+function unsupported(kind) {
+    const key = kind.replace(/_/g, "-");
+    return {
+        tools: (0, noop_1.createNoOp)(`kind '${kind}' is not supported`, `memvid.adapters.${key}.tools`),
+        functions: [],
+        nodes: (0, noop_1.createNoOp)(`kind '${kind}' is not supported`, `memvid.adapters.${key}.nodes`),
+        asQueryEngine: null,
+    };
+}
+function failed(kind, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const key = kind.replace(/_/g, "-");
+    return {
+        tools: (0, noop_1.createNoOp)(`failed to load adapter '${kind}': ${reason}`, `memvid.adapters.${key}.tools`),
+        functions: [],
+        nodes: (0, noop_1.createNoOp)(`failed to load adapter '${kind}': ${reason}`, `memvid.adapters.${key}.nodes`),
+        asQueryEngine: null,
+    };
+}
+function register(kind, loader) {
+    const normalised = kind.toLowerCase();
+    if (loaders.has(normalised)) {
+        throw new Error(`adapter '${kind}' already registered`);
+    }
+    loaders.set(normalised, loader);
+}
+async function resolve(kind, core, apiKey) {
+    const key = kind.toLowerCase();
+    if (cache.has(key)) {
+        return cache.get(key);
+    }
+    const loader = loaders.get(key);
+    if (!loader) {
+        const noop = unsupported(kind);
+        cache.set(key, noop);
+        return noop;
+    }
+    try {
+        const loaded = await loader(core, apiKey);
+        cache.set(key, loaded);
+        return loaded;
+    }
+    catch (error) {
+        return failed(kind, error);
+    }
+}