@memvid/sdk 2.0.113

package/dist/adapters/llamaindex.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * LlamaIndex adapter exposing Memvid helpers as FunctionTool and QueryEngineTool.
+ *
+ * LlamaIndex.TS uses FunctionTool for wrapping functions and QueryEngineTool
+ * for wrapping query engines. This adapter provides:
+ * - memvid_put: Store documents in memory
+ * - memvid_find: Search for relevant documents
+ * - memvid_ask: Query with RAG-style answer synthesis
+ * - asQueryEngine(): Factory for creating a LlamaIndex QueryEngine
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("llamaindex", "knowledge.mv2");
+ *
+ *    // Access tools for LlamaIndex agents
+ *    const tools = mem.tools; // Array of FunctionTool objects
+ *
+ *    // Use with LlamaIndex agent
+ *    import { OpenAIAgent } from "llamaindex";
+ *
+ *    const agent = new OpenAIAgent({
+ *      tools: mem.tools,
+ *    });
+ *    const response = await agent.chat({ message: "What do you know about X?" });
+ *
+ *    // Or use as a QueryEngine
+ *    const queryEngine = mem.asQueryEngine();
+ *    const result = await queryEngine.query({ query: "Summarize the key points" });
+ *
+ * Note: Requires llamaindex package to be installed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "llamaindex";
+// Dynamic import helper to avoid TypeScript module resolution issues
+async function tryImportLlamaIndex() {
+    try {
+        // Use require for better compatibility with npm module resolution
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const llamaindexModule = require("llamaindex");
+        return {
+            FunctionTool: llamaindexModule.FunctionTool,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+(0, registry_1.register)(KIND, async (core, _apiKey) => {
+    // Try to import LlamaIndex
+    const imports = await tryImportLlamaIndex();
+    if (!imports) {
+        return {
+            tools: (0, noop_1.createNoOp)("llamaindex adapter unavailable; install 'llamaindex' to enable", "memvid.adapters.llamaindex.tools"),
+            functions: [],
+            nodes: (0, noop_1.createNoOp)("llamaindex adapter nodes unavailable", "memvid.adapters.llamaindex.nodes"),
+            asQueryEngine: null,
+        };
+    }
+    const { FunctionTool } = imports;
+    // Define memvid_put function
+    async function memvidPut(params) {
+        const frameId = await core.put({
+            title: params.title,
+            label: params.label,
+            text: params.text,
+            metadata: params.metadata ?? {},
+            enable_embedding: true,
+            auto_tag: true,
+            extract_dates: true,
+        });
+        return `Document stored with frame_id: ${frameId}`;
+    }
+    // Define memvid_find function
+    async function memvidFind(params) {
+        const response = (await core.find(params.query, {
+            k: params.top_k ?? 5,
+        }));
+        const hits = response.hits ?? [];
+        if (hits.length === 0) {
+            return `No results found for query: '${params.query}'`;
+        }
+        const results = [];
+        for (let i = 0; i < hits.length; i++) {
+            const hit = hits[i];
+            const title = hit.title ?? "Untitled";
+            const snippet = (hit.text ?? hit.snippet ?? "").slice(0, 200);
+            const score = hit.score ?? 0;
+            results.push(`${i + 1}. [${title}] (score: ${score.toFixed(2)}): ${snippet}...`);
+        }
+        return `Found ${hits.length} results:\n${results.join("\n")}`;
+    }
+    // Define memvid_ask function
+    async function memvidAsk(params) {
+        const response = (await core.ask(params.question, {
+            mode: params.mode ?? "auto",
+        }));
+        const answer = response.answer ?? "No answer generated";
+        const sources = response.sources ?? [];
+        let result = `Answer: ${answer}`;
+        if (sources.length > 0) {
+            const sourceTitles = sources.slice(0, 3).map((s) => s.title ?? "Unknown");
+            result += `\n\nSources: ${sourceTitles.join(", ")}`;
+        }
+        return result;
+    }
+    // JSON schemas for LlamaIndex FunctionTool
+    const putSchema = {
+        type: "object",
+        properties: {
+            title: { type: "string", description: "Title of the document" },
+            label: { type: "string", description: "Category or label for the document" },
+            text: { type: "string", description: "Text content to store" },
+            metadata: {
+                type: "object",
+                description: "Optional key-value metadata",
+                additionalProperties: true,
+            },
+        },
+        required: ["title", "label", "text"],
+    };
+    const findSchema = {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "Search query string" },
+            top_k: { type: "number", description: "Number of results to return (default: 5)" },
+        },
+        required: ["query"],
+    };
+    const askSchema = {
+        type: "object",
+        properties: {
+            question: { type: "string", description: "Question to answer" },
+            mode: {
+                type: "string",
+                enum: ["auto", "lex", "sem"],
+                description: "Search mode: 'auto' (hybrid), 'lex' (keyword), or 'sem' (semantic)",
+            },
+        },
+        required: ["question"],
+    };
+    // Create FunctionTool instances
+    const tools = [
+        FunctionTool.from(memvidPut, {
+            name: "memvid_put",
+            description: "Store a document in Memvid memory. Use this to save information " +
+                "that should be retrievable later.",
+            parameters: putSchema,
+        }),
+        FunctionTool.from(memvidFind, {
+            name: "memvid_find",
+            description: "Search Memvid memory for documents matching a query. " +
+                "Returns the most relevant documents with snippets.",
+            parameters: findSchema,
+        }),
+        FunctionTool.from(memvidAsk, {
+            name: "memvid_ask",
+            description: "Ask a question and get an answer synthesized from Memvid memory " +
+                "using retrieval-augmented generation.",
+            parameters: askSchema,
+        }),
+    ];
+    // Query engine factory
+    const asQueryEngine = () => {
+        // Return a simple query engine-like object
+        // Note: For full LlamaIndex QueryEngine, users should use the native LlamaIndex integration
+        return {
+            async query(params) {
+                const queryStr = typeof params === "string" ? params : params.query;
+                const response = (await core.ask(queryStr));
+                const answer = response.answer ?? "No answer generated";
+                const sources = response.sources ?? [];
+                // Build source text
+                let sourceText = "";
+                if (sources.length > 0) {
+                    const sourceTitles = sources.slice(0, 3).map((s) => s.title ?? "Unknown");
+                    sourceText = `\n\nSources: ${sourceTitles.join(", ")}`;
+                }
+                return {
+                    response: answer + sourceText,
+                    sourceNodes: sources,
+                };
+            },
+        };
+    };
+    return {
+        tools,
+        functions: [memvidPut, memvidFind, memvidAsk],
+        nodes: (0, noop_1.createNoOp)("llamaindex adapter nodes not provided", "memvid.adapters.llamaindex.nodes"),
+        asQueryEngine,
+    };
+});

package/dist/adapters/mcp.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/mcp.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "mcp";
+(0, registry_1.register)(KIND, async () => ({
+    tools: (0, noop_1.createNoOp)("mcp adapter unavailable; provide your MCP client configuration", "memvid.adapters.mcp.tools"),
+    functions: [],
+    nodes: (0, noop_1.createNoOp)("mcp adapter nodes unavailable", "memvid.adapters.mcp.nodes"),
+    asQueryEngine: null,
+}));

package/dist/adapters/openai.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OpenAI adapter exposing Memvid core methods as OpenAI function calling tools.
+ *
+ * This adapter provides tools formatted for OpenAI's function calling API.
+ * The tools can be used directly with the OpenAI Chat Completions API.
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("openai", "knowledge.mv2");
+ *
+ *    // Access tools for OpenAI function calling
+ *    const tools = mem.tools; // Array of OpenAI tool definitions
+ *
+ *    // Use with OpenAI API
+ *    import OpenAI from "openai";
+ *
+ *    const client = new OpenAI();
+ *    const response = await client.chat.completions.create({
+ *      model: "gpt-4o-mini",
+ *      messages: [...],
+ *      tools: mem.tools,
+ *      tool_choice: "auto",
+ *    });
+ */
+export {};

package/dist/adapters/openai.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * OpenAI adapter exposing Memvid core methods as OpenAI function calling tools.
+ *
+ * This adapter provides tools formatted for OpenAI's function calling API.
+ * The tools can be used directly with the OpenAI Chat Completions API.
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("openai", "knowledge.mv2");
+ *
+ *    // Access tools for OpenAI function calling
+ *    const tools = mem.tools; // Array of OpenAI tool definitions
+ *
+ *    // Use with OpenAI API
+ *    import OpenAI from "openai";
+ *
+ *    const client = new OpenAI();
+ *    const response = await client.chat.completions.create({
+ *      model: "gpt-4o-mini",
+ *      messages: [...],
+ *      tools: mem.tools,
+ *      tool_choice: "auto",
+ *    });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "openai";
+(0, registry_1.register)(KIND, async (core, apiKey) => {
+    // Set up API key if provided
+    const key = apiKey?.openai ?? apiKey?.default;
+    if (key && !process.env.OPENAI_API_KEY) {
+        process.env.OPENAI_API_KEY = key;
+    }
+    // Define OpenAI-format tool definitions
+    const tools = [
+        {
+            type: "function",
+            function: {
+                name: "memvid_put",
+                description: "Store a document in Memvid memory for later retrieval. " +
+                    "Use this to save information that should be searchable later.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        title: {
+                            type: "string",
+                            description: "Title of the document",
+                        },
+                        label: {
+                            type: "string",
+                            description: "Category or label for the document",
+                        },
+                        text: {
+                            type: "string",
+                            description: "Text content to store",
+                        },
+                        metadata: {
+                            type: "object",
+                            description: "Optional key-value metadata",
+                            additionalProperties: true,
+                        },
+                    },
+                    required: ["title", "label", "text"],
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "memvid_find",
+                description: "Search Memvid memory for documents matching a query. " +
+                    "Returns the most relevant documents with snippets.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Search query string",
+                        },
+                        top_k: {
+                            type: "number",
+                            description: "Number of results to return (default: 5)",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "memvid_ask",
+                description: "Ask a question and get an answer synthesized from Memvid memory " +
+                    "using retrieval-augmented generation.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        question: {
+                            type: "string",
+                            description: "Question to answer",
+                        },
+                        mode: {
+                            type: "string",
+                            enum: ["auto", "lex", "sem"],
+                            description: "Search mode: 'auto' (hybrid), 'lex' (keyword), or 'sem' (semantic)",
+                        },
+                    },
+                    required: ["question"],
+                },
+            },
+        },
+    ];
+    // Create executor functions for each tool
+    const executors = {
+        memvid_put: async (args) => {
+            const frameId = await core.put({
+                title: args.title,
+                label: args.label,
+                text: args.text,
+                metadata: args.metadata ?? {},
+                enable_embedding: true,
+                auto_tag: true,
+                extract_dates: true,
+            });
+            return `Document stored with frame_id: ${frameId}`;
+        },
+        memvid_find: async (args) => {
+            const query = args.query;
+            const topK = args.top_k ?? 5;
+            const response = (await core.find(query, { k: topK }));
+            const hits = response.hits ?? [];
+            if (hits.length === 0) {
+                return `No results found for query: '${query}'`;
+            }
+            const results = [];
+            for (let i = 0; i < hits.length; i++) {
+                const hit = hits[i];
+                const title = hit.title ?? "Untitled";
+                const snippet = (hit.text ?? hit.snippet ?? "").slice(0, 200);
+                const score = hit.score ?? 0;
+                results.push(`${i + 1}. [${title}] (score: ${score.toFixed(2)}): ${snippet}...`);
+            }
+            return `Found ${hits.length} results:\n${results.join("\n")}`;
+        },
+        memvid_ask: async (args) => {
+            const question = args.question;
+            const mode = args.mode ?? "auto";
+            const response = (await core.ask(question, { mode }));
+            const answer = response.answer ?? "No answer generated";
+            const sources = response.sources ?? [];
+            let result = `Answer: ${answer}`;
+            if (sources.length > 0) {
+                const sourceTitles = sources.slice(0, 3).map((s) => s.title ?? "Unknown");
+                result += `\n\nSources: ${sourceTitles.join(", ")}`;
+            }
+            return result;
+        },
+    };
+    // Return both tools and executors
+    return {
+        tools,
+        functions: executors, // Executors keyed by tool name
+        nodes: (0, noop_1.createNoOp)("openai adapter does not provide nodes", "memvid.adapters.openai.nodes"),
+        asQueryEngine: null,
+    };
+});

package/dist/adapters/semantic_kernel.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/semantic_kernel.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "semantic-kernel";
+(0, registry_1.register)(KIND, async () => ({
+    tools: (0, noop_1.createNoOp)("semantic-kernel adapter unavailable; install 'semantic-kernel' to enable", "memvid.adapters.semantic-kernel.tools"),
+    functions: [],
+    nodes: (0, noop_1.createNoOp)("semantic-kernel adapter nodes unavailable", "memvid.adapters.semantic-kernel.nodes"),
+    asQueryEngine: null,
+}));

package/dist/adapters/vercel_ai.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Vercel AI SDK adapter exposing Memvid core methods as Vercel AI tools.
+ *
+ * This adapter provides tools formatted for Vercel AI SDK's tool calling API.
+ * The tools can be used directly with generateText, streamText, and other AI SDK functions.
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("vercel-ai", "knowledge.mv2");
+ *
+ *    // Access tools for Vercel AI SDK
+ *    const tools = mem.tools; // Object with tool definitions
+ *
+ *    // Use with Vercel AI SDK
+ *    import { generateText } from "ai";
+ *    import { openai } from "@ai-sdk/openai";
+ *
+ *    const result = await generateText({
+ *      model: openai("gpt-4o-mini"),
+ *      tools: mem.tools,
+ *      prompt: "Search for information about...",
+ *    });
+ *
+ * Note: Requires zod to be installed for schema definitions.
+ */
+export {};

package/dist/adapters/vercel_ai.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Vercel AI SDK adapter exposing Memvid core methods as Vercel AI tools.
+ *
+ * This adapter provides tools formatted for Vercel AI SDK's tool calling API.
+ * The tools can be used directly with generateText, streamText, and other AI SDK functions.
+ *
+ * Usage:
+ *    import { use } from "memvid-sdk";
+ *
+ *    const mem = await use("vercel-ai", "knowledge.mv2");
+ *
+ *    // Access tools for Vercel AI SDK
+ *    const tools = mem.tools; // Object with tool definitions
+ *
+ *    // Use with Vercel AI SDK
+ *    import { generateText } from "ai";
+ *    import { openai } from "@ai-sdk/openai";
+ *
+ *    const result = await generateText({
+ *      model: openai("gpt-4o-mini"),
+ *      tools: mem.tools,
+ *      prompt: "Search for information about...",
+ *    });
+ *
+ * Note: Requires zod to be installed for schema definitions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const noop_1 = require("../noop");
+const registry_1 = require("../registry");
+const KIND = "vercel-ai";
+// Dynamic import helper for AI SDK tool helper
+function tryImportAI() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const aiModule = require("ai");
+        return { tool: aiModule.tool, jsonSchema: aiModule.jsonSchema };
+    }
+    catch {
+        return null;
+    }
+}
+(0, registry_1.register)(KIND, async (core, _apiKey) => {
+    const imports = tryImportAI();
+    if (!imports) {
+        return {
+            tools: (0, noop_1.createNoOp)("vercel-ai adapter requires 'ai' package; install it to enable", "memvid.adapters.vercel-ai.tools"),
+            functions: [],
+            nodes: (0, noop_1.createNoOp)("vercel-ai adapter does not provide nodes", "memvid.adapters.vercel-ai.nodes"),
+            asQueryEngine: null,
+        };
+    }
+    const { tool, jsonSchema } = imports;
+    // Use JSON schemas directly to avoid Zod version conflicts
+    const putSchema = jsonSchema({
+        type: "object",
+        properties: {
+            title: { type: "string", description: "Title of the document" },
+            label: { type: "string", description: "Category or label for the document" },
+            text: { type: "string", description: "Text content to store" },
+            metadata: { type: "object", description: "Optional key-value metadata" },
+        },
+        required: ["title", "label", "text"],
+    });
+    const findSchema = jsonSchema({
+        type: "object",
+        properties: {
+            query: { type: "string", description: "Search query string" },
+            top_k: { type: "number", description: "Number of results to return (default: 5)" },
+        },
+        required: ["query"],
+    });
+    const askSchema = jsonSchema({
+        type: "object",
+        properties: {
+            question: { type: "string", description: "Question to answer" },
+            mode: { type: "string", enum: ["auto", "lex", "sem"], description: "Search mode: 'auto' (hybrid), 'lex' (keyword), or 'sem' (semantic)" },
+        },
+        required: ["question"],
+    });
+    // Vercel AI SDK v5 uses the tool() helper with inputSchema
+    const tools = {
+        memvid_put: tool({
+            description: "Store a document in Memvid memory for later retrieval. " +
+                "Use this to save information that should be searchable later.",
+            inputSchema: putSchema,
+            execute: async (args) => {
+                const frameId = await core.put({
+                    title: args.title,
+                    label: args.label,
+                    text: args.text,
+                    metadata: args.metadata ?? {},
+                    enable_embedding: true,
+                    auto_tag: true,
+                    extract_dates: true,
+                });
+                return `Document stored with frame_id: ${frameId}`;
+            },
+        }),
+        memvid_find: tool({
+            description: "Search Memvid memory for documents matching a query. " +
+                "Returns the most relevant documents with snippets.",
+            inputSchema: findSchema,
+            execute: async (args) => {
+                const query = args.query;
+                const topK = args.top_k ?? 5;
+                const response = (await core.find(query, { k: topK }));
+                const hits = response.hits ?? [];
+                if (hits.length === 0) {
+                    return `No results found for query: '${query}'`;
+                }
+                const results = [];
+                for (let i = 0; i < hits.length; i++) {
+                    const hit = hits[i];
+                    const title = hit.title ?? "Untitled";
+                    const snippet = (hit.text ?? hit.snippet ?? "").slice(0, 200);
+                    const score = hit.score ?? 0;
+                    results.push(`${i + 1}. [${title}] (score: ${score.toFixed(2)}): ${snippet}...`);
+                }
+                return `Found ${hits.length} results:\n${results.join("\n")}`;
+            },
+        }),
+        memvid_ask: tool({
+            description: "Ask a question and get an answer synthesized from Memvid memory " +
+                "using retrieval-augmented generation.",
+            inputSchema: askSchema,
+            execute: async (args) => {
+                const question = args.question;
+                const mode = args.mode ?? "auto";
+                const response = (await core.ask(question, { mode }));
+                const answer = response.answer ?? "No answer generated";
+                const sources = response.sources ?? [];
+                let result = `Answer: ${answer}`;
+                if (sources.length > 0) {
+                    const sourceTitles = sources.slice(0, 3).map((s) => s.title ?? "Unknown");
+                    result += `\n\nSources: ${sourceTitles.join(", ")}`;
+                }
+                return result;
+            },
+        }),
+    };
+    return {
+        tools,
+        functions: [], // Raw functions not needed for Vercel AI
+        nodes: (0, noop_1.createNoOp)("vercel-ai adapter does not provide nodes", "memvid.adapters.vercel-ai.nodes"),
+        asQueryEngine: null,
+    };
+});