@memvid/sdk 2.0.147 → 2.0.149

package/dist/analytics.js

@@ -134,6 +134,8 @@ function trackEvent(event) {
                 // Silently ignore errors
             });
         }, FLUSH_INTERVAL_MS);
+        // Don't prevent process exit while waiting for flush
+        flushTimer.unref();
     }
     // Force flush if queue is getting large
     if (eventQueue.length >= MAX_BATCH_SIZE) {
@@ -209,9 +211,5 @@ async function flush() {
     }
     await flushEvents();
 }
-// Flush on process exit
-if (typeof process !== "undefined") {
-    process.on("beforeExit", () => {
-        flush().catch(() => { });
-    });
-}
+// Note: No beforeExit handler needed - timer.unref() allows process to exit
+// Events may be lost on quick CLI exits, but that's acceptable for UX

package/dist/documents/docx.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Word Document Parser with error handling
+ * Uses officeparser v6 - no Rust fallback available for DOCX
+ */
+import type { ParseOptions, ParseResult } from "./types";
+export declare function parseDocx(filePath: string, _options?: ParseOptions): Promise<ParseResult>;

package/dist/documents/docx.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Word Document Parser with error handling
+ * Uses officeparser v6 - no Rust fallback available for DOCX
+ */
+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.parseDocx = parseDocx;
+async function parseDocx(filePath, _options) {
+    const filename = filePath.split("/").pop() || filePath;
+    try {
+        const officeParser = await Promise.resolve().then(() => __importStar(require("officeparser")));
+        const ast = await officeParser.parseOffice(filePath);
+        // Get full text content
+        const content = ast.toText();
+        const items = [];
+        if (content && content.trim().length > 0) {
+            items.push({
+                number: 1,
+                text: content,
+            });
+        }
+        else {
+            console.warn(`[memvid] No text content found in ${filename}`);
+        }
+        return {
+            type: "docx",
+            filename,
+            totalItems: 1,
+            items,
+        };
+    }
+    catch (err) {
+        // For DOCX, we don't have a Rust fallback, so throw a descriptive error
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse Word file "${filename}": ${message}. ` +
+            `Ensure the file is a valid .docx/.doc file.`);
+    }
+}

package/dist/documents/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Document Parsing Module
+ *
+ * Auto-detects file type and parses PDF, XLSX, PPTX, DOCX documents.
+ * Includes fallback support for PDF using Rust core.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from "@memvid/sdk/documents";
+ *
+ * const result = await parse("./report.pdf");
+ * if (result) {
+ *   console.log(result.items.length); // number of pages
+ * }
+ * ```
+ */
+import type { ParseOptions, ParseResult } from "./types";
+export * from "./types";
+export { parsePdf } from "./pdf";
+export { parseXlsx } from "./xlsx";
+export { parsePptx } from "./pptx";
+export { parseDocx } from "./docx";
+/**
+ * Parse a document file with automatic format detection.
+ *
+ * Supported formats:
+ * - PDF (.pdf) - per-page extraction (with Rust fallback)
+ * - Excel (.xlsx, .xls) - per-sheet extraction
+ * - PowerPoint (.pptx, .ppt) - per-slide extraction
+ * - Word (.docx, .doc) - full document extraction
+ *
+ * @param filePath - Path to the document file
+ * @param options - Parsing options
+ * @returns ParseResult with items, or null for PDF if JS parser failed (signals Rust fallback)
+ */
+export declare function parse(filePath: string, options?: ParseOptions): Promise<ParseResult | null>;
+/**
+ * Check if a file extension is supported for document parsing.
+ */
+export declare function isSupportedFormat(filePath: string): boolean;
+/**
+ * Get the document type from a file path.
+ */
+export declare function getDocumentType(filePath: string): string | null;

package/dist/documents/index.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Document Parsing Module
+ *
+ * Auto-detects file type and parses PDF, XLSX, PPTX, DOCX documents.
+ * Includes fallback support for PDF using Rust core.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from "@memvid/sdk/documents";
+ *
+ * const result = await parse("./report.pdf");
+ * if (result) {
+ *   console.log(result.items.length); // number of pages
+ * }
+ * ```
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDocx = exports.parsePptx = exports.parseXlsx = exports.parsePdf = void 0;
+exports.parse = parse;
+exports.isSupportedFormat = isSupportedFormat;
+exports.getDocumentType = getDocumentType;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const pdf_1 = require("./pdf");
+const xlsx_1 = require("./xlsx");
+const pptx_1 = require("./pptx");
+const docx_1 = require("./docx");
+__exportStar(require("./types"), exports);
+var pdf_2 = require("./pdf");
+Object.defineProperty(exports, "parsePdf", { enumerable: true, get: function () { return pdf_2.parsePdf; } });
+var xlsx_2 = require("./xlsx");
+Object.defineProperty(exports, "parseXlsx", { enumerable: true, get: function () { return xlsx_2.parseXlsx; } });
+var pptx_2 = require("./pptx");
+Object.defineProperty(exports, "parsePptx", { enumerable: true, get: function () { return pptx_2.parsePptx; } });
+var docx_2 = require("./docx");
+Object.defineProperty(exports, "parseDocx", { enumerable: true, get: function () { return docx_2.parseDocx; } });
+/**
+ * Parse a document file with automatic format detection.
+ *
+ * Supported formats:
+ * - PDF (.pdf) - per-page extraction (with Rust fallback)
+ * - Excel (.xlsx, .xls) - per-sheet extraction
+ * - PowerPoint (.pptx, .ppt) - per-slide extraction
+ * - Word (.docx, .doc) - full document extraction
+ *
+ * @param filePath - Path to the document file
+ * @param options - Parsing options
+ * @returns ParseResult with items, or null for PDF if JS parser failed (signals Rust fallback)
+ */
+async function parse(filePath, options) {
+    if (!(0, fs_1.existsSync)(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    const ext = (0, path_1.extname)(filePath).toLowerCase();
+    switch (ext) {
+        case ".pdf":
+            // PDF parser returns null if unpdf fails, signaling to use Rust fallback
+            return (0, pdf_1.parsePdf)(filePath, options);
+        case ".xlsx":
+        case ".xls":
+            return (0, xlsx_1.parseXlsx)(filePath, options);
+        case ".pptx":
+        case ".ppt":
+            return (0, pptx_1.parsePptx)(filePath, options);
+        case ".docx":
+        case ".doc":
+            return (0, docx_1.parseDocx)(filePath, options);
+        default:
+            throw new Error(`Unsupported file format: ${ext}. Supported: .pdf, .xlsx, .xls, .pptx, .ppt, .docx, .doc`);
+    }
+}
+/**
+ * Check if a file extension is supported for document parsing.
+ */
+function isSupportedFormat(filePath) {
+    const ext = (0, path_1.extname)(filePath).toLowerCase();
+    return [".pdf", ".xlsx", ".xls", ".pptx", ".ppt", ".docx", ".doc"].includes(ext);
+}
+/**
+ * Get the document type from a file path.
+ */
+function getDocumentType(filePath) {
+    const ext = (0, path_1.extname)(filePath).toLowerCase();
+    switch (ext) {
+        case ".pdf":
+            return "pdf";
+        case ".xlsx":
+        case ".xls":
+            return "xlsx";
+        case ".pptx":
+        case ".ppt":
+            return "pptx";
+        case ".docx":
+        case ".doc":
+            return "docx";
+        default:
+            return null;
+    }
+}

package/dist/documents/pdf.d.ts

@@ -0,0 +1,7 @@
+/**
+ * PDF Parser with fallback support
+ * Primary: unpdf (Mozilla pdf.js)
+ * Fallback: Returns null to signal using Rust core's pdf_extract
+ */
+import type { ParseOptions, ParseResult } from "./types";
+export declare function parsePdf(filePath: string, options?: ParseOptions): Promise<ParseResult | null>;

package/dist/documents/pdf.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * PDF Parser with fallback support
+ * Primary: unpdf (Mozilla pdf.js)
+ * Fallback: Returns null to signal using Rust core's pdf_extract
+ */
+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.parsePdf = parsePdf;
+const fs_1 = require("fs");
+async function parsePdf(filePath, options) {
+    const filename = filePath.split("/").pop() || filePath;
+    try {
+        const { extractText } = await Promise.resolve().then(() => __importStar(require("unpdf")));
+        const buffer = (0, fs_1.readFileSync)(filePath);
+        const { text, totalPages } = await extractText(new Uint8Array(buffer), {
+            mergePages: false,
+        });
+        const textArray = text;
+        const maxItems = options?.maxItems || textArray.length;
+        const items = [];
+        for (let i = 0; i < Math.min(textArray.length, maxItems); i++) {
+            const pageText = textArray[i];
+            if (pageText && pageText.trim().length > 0) {
+                items.push({
+                    number: i + 1,
+                    text: pageText,
+                });
+            }
+        }
+        return {
+            type: "pdf",
+            filename,
+            totalItems: totalPages,
+            items,
+        };
+    }
+    catch (err) {
+        // Log warning and return null to signal fallback to Rust core
+        console.warn(`[memvid] unpdf failed for ${filename}, using Rust fallback: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}

package/dist/documents/pptx.d.ts

@@ -0,0 +1,6 @@
+/**
+ * PowerPoint Parser with error handling
+ * Uses officeparser v6 - no Rust fallback available for PPTX
+ */
+import type { ParseOptions, ParseResult } from "./types";
+export declare function parsePptx(filePath: string, options?: ParseOptions): Promise<ParseResult>;

package/dist/documents/pptx.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * PowerPoint Parser with error handling
+ * Uses officeparser v6 - no Rust fallback available for PPTX
+ */
+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.parsePptx = parsePptx;
+async function parsePptx(filePath, options) {
+    const filename = filePath.split("/").pop() || filePath;
+    try {
+        const officeParser = await Promise.resolve().then(() => __importStar(require("officeparser")));
+        const ast = await officeParser.parseOffice(filePath, {
+            ignoreNotes: false, // Include speaker notes
+        });
+        const items = [];
+        // Get full text content
+        const content = ast.toText();
+        if (!content || content.trim().length === 0) {
+            console.warn(`[memvid] No text content found in ${filename}`);
+            return {
+                type: "pptx",
+                filename,
+                totalItems: 0,
+                items: [],
+            };
+        }
+        // Split content into slides (officeparser separates with double newlines)
+        const slides = content.split(/\n\s*\n/).filter((s) => s.trim());
+        const maxItems = options?.maxItems || slides.length;
+        for (let i = 0; i < Math.min(slides.length, maxItems); i++) {
+            const slideText = slides[i].trim();
+            if (slideText.length > 0) {
+                // Try to extract title (first line)
+                const lines = slideText.split("\n");
+                const title = lines[0]?.trim();
+                items.push({
+                    number: i + 1,
+                    title: title || undefined,
+                    text: slideText,
+                });
+            }
+        }
+        return {
+            type: "pptx",
+            filename,
+            totalItems: items.length,
+            items,
+        };
+    }
+    catch (err) {
+        // For PPTX, we don't have a Rust fallback, so throw a descriptive error
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse PowerPoint file "${filename}": ${message}. ` +
+            `Ensure the file is a valid .pptx/.ppt file.`);
+    }
+}

package/dist/documents/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Document Parsing Types
+ */
+export interface ParseOptions {
+    /** Enable OCR for scanned pages (default: false) */
+    ocr?: boolean;
+    /** Extract tables as structured arrays (default: true) */
+    extractTables?: boolean;
+    /** Limit pages/sheets/slides to process */
+    maxItems?: number;
+}
+export interface DocumentItem {
+    /** 1-based item number (page/slide) or 0-based (sheet) */
+    number: number;
+    /** Sheet name for XLSX */
+    name?: string;
+    /** Extracted text content */
+    text: string;
+    /** Slide title for PPTX */
+    title?: string;
+}
+export interface ParseResult {
+    /** Detected document type */
+    type: "pdf" | "xlsx" | "pptx" | "docx";
+    /** Original filename */
+    filename: string;
+    /** Total items (pages/sheets/slides) */
+    totalItems: number;
+    /** Parsed items */
+    items: DocumentItem[];
+}
+export interface PutFileOptions {
+    /** Label for all frames (default: "document") */
+    label?: string;
+    /** Additional metadata to attach */
+    metadata?: Record<string, unknown>;
+}
+export interface PutFileResult {
+    /** Number of frames added */
+    framesAdded: number;
+    /** Document type detected */
+    type: string;
+    /** Original filename */
+    filename: string;
+}
+export interface PutFilesOptions extends PutFileOptions {
+    /** File extensions to process (default: all supported) */
+    extensions?: string[];
+}
+export interface PutFilesResult {
+    /** Number of files processed */
+    filesProcessed: number;
+    /** Total frames added */
+    framesAdded: number;
+    /** Results per file */
+    files: Array<{
+        filename: string;
+        framesAdded: number;
+        type: string;
+    }>;
+}

package/dist/documents/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Document Parsing Types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/documents/xlsx.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Excel Parser with error handling
+ * Uses exceljs - no Rust fallback available for XLSX
+ */
+import type { ParseOptions, ParseResult } from "./types";
+export declare function parseXlsx(filePath: string, options?: ParseOptions): Promise<ParseResult>;

package/dist/documents/xlsx.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Excel Parser with error handling
+ * Uses exceljs - no Rust fallback available for XLSX
+ */
+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.parseXlsx = parseXlsx;
+/** Extract the display value from an exceljs cell */
+function getCellValue(cellValue) {
+    if (cellValue == null || cellValue === "")
+        return null;
+    // Handle formula cells - exceljs returns { formula, result }
+    if (typeof cellValue === "object" && cellValue !== null) {
+        const obj = cellValue;
+        // Formula cell with result
+        if ("result" in obj && obj.result != null) {
+            return String(obj.result);
+        }
+        // Rich text - array of text runs
+        if ("richText" in obj && Array.isArray(obj.richText)) {
+            return obj.richText.map((r) => r.text || "").join("");
+        }
+        // Error value
+        if ("error" in obj) {
+            return `#${obj.error}`;
+        }
+        // Date object
+        if (cellValue instanceof Date) {
+            return cellValue.toISOString().split("T")[0];
+        }
+        // Unknown object - skip to avoid [object Object]
+        return null;
+    }
+    return String(cellValue);
+}
+async function parseXlsx(filePath, options) {
+    const filename = filePath.split("/").pop() || filePath;
+    try {
+        const ExcelJS = await Promise.resolve().then(() => __importStar(require("exceljs")));
+        const workbook = new ExcelJS.default.Workbook();
+        await workbook.xlsx.readFile(filePath);
+        const maxItems = options?.maxItems || workbook.worksheets.length;
+        const items = [];
+        for (let i = 0; i < Math.min(workbook.worksheets.length, maxItems); i++) {
+            const worksheet = workbook.worksheets[i];
+            const textLines = [];
+            worksheet.eachRow((row) => {
+                const values = [];
+                row.eachCell((cell) => {
+                    const value = getCellValue(cell.value);
+                    if (value != null) {
+                        values.push(value);
+                    }
+                });
+                if (values.length > 0) {
+                    textLines.push(values.join(" | "));
+                }
+            });
+            if (textLines.length > 0) {
+                items.push({
+                    number: i,
+                    name: worksheet.name,
+                    text: textLines.join("\n"),
+                });
+            }
+        }
+        // If no sheets with content, return empty but valid result
+        if (items.length === 0) {
+            console.warn(`[memvid] No content found in ${filename}`);
+        }
+        return {
+            type: "xlsx",
+            filename,
+            totalItems: workbook.worksheets.length,
+            items,
+        };
+    }
+    catch (err) {
+        // For XLSX, we don't have a Rust fallback, so throw a descriptive error
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse Excel file "${filename}": ${message}. ` +
+            `Ensure the file is a valid .xlsx/.xls file.`);
+    }
+}

package/dist/index.js

@@ -900,6 +900,7 @@ function normaliseAskOptions(opts) {
         minRelevancy: opts.minRelevancy,
         maxK: opts.maxK,
         adaptiveStrategy: opts.adaptiveStrategy,
+        showChunks: opts.showChunks,
     };
     if (payload.k == null &&
         payload.mode == null &&
@@ -917,7 +918,8 @@ function normaliseAskOptions(opts) {
         payload.adaptive == null &&
         payload.minRelevancy == null &&
         payload.maxK == null &&
-        payload.adaptiveStrategy == null) {
+        payload.adaptiveStrategy == null &&
+        payload.showChunks == null) {
         return undefined;
     }
     return payload;
@@ -1690,6 +1692,13 @@ class MemvidImpl {
     async seal() {
         return wrapAsync(() => this.core.seal());
     }
+    /**
+     * Rebuild the time index. Call this after using putMany() if you need
+     * time-based queries (like ask() with temporal context).
+     */
+    async rebuildTimeIndex() {
+        await this.doctor({ rebuildTimeIndex: true, quiet: true });
+    }
     async enableLex() {
         return wrapAsync(() => this.core.enableLex());
     }
@@ -1839,6 +1848,182 @@ class MemvidImpl {
     async addMemoryCards(cards) {
         return wrapAsync(() => this.core.addMemoryCards(cards));
     }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Document Parsing & Ingestion
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Ingest a document file with automatic parsing and per-page/sheet/slide storage.
+     *
+     * Supported formats:
+     * - PDF (.pdf) - stores each page as a separate frame
+     * - Excel (.xlsx, .xls) - stores each sheet as a separate frame
+     * - PowerPoint (.pptx, .ppt) - stores each slide as a separate frame
+     * - Word (.docx, .doc) - stores the document as a single frame
+     *
+     * @example
+     * ```typescript
+     * const mv = await create('memory.mv2');
+     * await mv.putFile('./report.pdf');
+     * await mv.putFile('./data.xlsx');
+     * await mv.putFile('./slides.pptx');
+     * ```
+     *
+     * @param filePath - Path to the document file
+     * @param options - Optional label and metadata
+     * @returns Result with framesAdded count
+     */
+    async putFile(filePath, options) {
+        const { parse, getDocumentType } = await Promise.resolve().then(() => __importStar(require("./documents/index.js")));
+        const { basename } = await Promise.resolve().then(() => __importStar(require("path")));
+        const filename = basename(filePath);
+        const docType = getDocumentType(filePath);
+        const label = options?.label || "document";
+        const baseMetadata = options?.metadata || {};
+        const embedder = options?.embedder;
+        // Try JS-based parsing first
+        const result = await parse(filePath);
+        // PDF fallback: if parse() returns null, use Rust core's built-in pdf_extract
+        if (result === null && docType === "pdf") {
+            console.log(`[memvid] Using Rust pdf_extract for ${filename}`);
+            // For PDF fallback with external embedder, we can't easily extract text first
+            // so we fall back to the internal embedding model
+            await this.put({
+                file: filePath,
+                label,
+                metadata: {
+                    ...baseMetadata,
+                    doc_name: filename,
+                    doc_type: "pdf",
+                    fallback: "rust_pdf_extract",
+                },
+                enableEmbedding: embedder ? true : options?.enableEmbedding,
+                embeddingModel: embedder ? undefined : options?.embeddingModel,
+                vectorCompression: options?.vectorCompression,
+                autoTag: options?.autoTag,
+                extractDates: options?.extractDates,
+            });
+            (0, analytics_1.trackCommand)(this.filename, "putFile", true);
+            return { framesAdded: 1, type: "pdf", filename };
+        }
+        // If result is null and not PDF, something went wrong
+        if (result === null) {
+            throw new Error(`Failed to parse document: ${filename}`);
+        }
+        // Build items for batch processing with putMany (6x faster than individual put())
+        const items = [];
+        for (const item of result.items) {
+            let title;
+            let metadata;
+            if (result.type === "pdf") {
+                title = `${result.filename} [Page ${item.number}]`;
+                metadata = {
+                    ...baseMetadata,
+                    doc_name: result.filename,
+                    doc_type: result.type,
+                    page_number: item.number,
+                    total_pages: result.totalItems,
+                };
+            }
+            else if (result.type === "xlsx") {
+                title = `${result.filename} [Sheet: ${item.name}]`;
+                metadata = {
+                    ...baseMetadata,
+                    doc_name: result.filename,
+                    doc_type: result.type,
+                    sheet_name: item.name,
+                    sheet_index: item.number,
+                    total_sheets: result.totalItems,
+                };
+            }
+            else if (result.type === "pptx") {
+                title = `${result.filename} [Slide ${item.number}]`;
+                metadata = {
+                    ...baseMetadata,
+                    doc_name: result.filename,
+                    doc_type: result.type,
+                    slide_number: item.number,
+                    slide_title: item.title,
+                    total_slides: result.totalItems,
+                };
+            }
+            else {
+                // docx
+                title = result.filename;
+                metadata = {
+                    ...baseMetadata,
+                    doc_name: result.filename,
+                    doc_type: result.type,
+                };
+            }
+            items.push({
+                title,
+                labels: label ? [label] : undefined,
+                text: item.text,
+                metadata,
+            });
+        }
+        // Use putMany for fast batch ingestion
+        // Note: Call rebuildTimeIndex() after seal() if using ask() with temporal queries
+        await this.putMany(items, {
+            embedder,
+            enableEmbedding: embedder ? undefined : options?.enableEmbedding,
+            embeddingModel: embedder ? undefined : options?.embeddingModel,
+        });
+        (0, analytics_1.trackCommand)(this.filename, "putFile", true);
+        return { framesAdded: items.length, type: result.type, filename: result.filename };
+    }
+    /**
+     * Ingest multiple document files from a directory.
+     *
+     * @example
+     * ```typescript
+     * const mv = await create('memory.mv2');
+     * const result = await mv.putFiles('./documents/');
+     * console.log(`Processed ${result.filesProcessed} files, ${result.framesAdded} frames`);
+     * ```
+     *
+     * @param dirPath - Path to directory containing documents
+     * @param options - Optional label, extensions filter, and metadata
+     * @returns Result with filesProcessed and framesAdded counts
+     */
+    async putFiles(dirPath, options) {
+        const { readdirSync } = await Promise.resolve().then(() => __importStar(require("fs")));
+        const { join } = await Promise.resolve().then(() => __importStar(require("path")));
+        const extensions = options?.extensions || [
+            ".pdf",
+            ".xlsx",
+            ".xls",
+            ".pptx",
+            ".ppt",
+            ".docx",
+            ".doc",
+        ];
+        const files = readdirSync(dirPath).filter((f) => extensions.some((ext) => f.toLowerCase().endsWith(ext)));
+        let filesProcessed = 0;
+        let framesAdded = 0;
+        const results = [];
+        for (const file of files) {
+            const result = await this.putFile(join(dirPath, file), {
+                label: options?.label,
+                metadata: options?.metadata,
+                enableEmbedding: options?.enableEmbedding,
+                embeddingModel: options?.embeddingModel,
+                embedder: options?.embedder,
+                vectorCompression: options?.vectorCompression,
+                autoTag: options?.autoTag,
+                extractDates: options?.extractDates,
+            });
+            filesProcessed++;
+            framesAdded += result.framesAdded;
+            results.push({
+                filename: result.filename,
+                framesAdded: result.framesAdded,
+                type: result.type,
+            });
+        }
+        (0, analytics_1.trackCommand)(this.filename, "putFiles", true);
+        return { filesProcessed, framesAdded, files: results };
+    }
 }
 const useImpl = (async (kind, filename, apiKeyOrOptions, options) => {
     const { apiKey, options: resolvedOptions } = splitUseArgs(apiKeyOrOptions, options);
@@ -1887,6 +2072,7 @@ useImpl.doctor = async (path, options) => {
         rebuildVecIndex: options.rebuildVecIndex,
         vacuum: options.vacuum,
         dryRun: options.dryRun,
+        quiet: options.quiet,
     };
     return wrapAsync(() => addon.doctorMemvid(path, nativeOptions));
 };

package/dist/types.d.ts

@@ -103,6 +103,8 @@ export interface AskInput {
     minRelevancy?: number;
     maxK?: number;
     adaptiveStrategy?: "relative" | "absolute" | "cliff" | "elbow" | "combined";
+    /** Include full chunk content in response (default: false) */
+    showChunks?: boolean;
 }
 export interface TimelineInput {
     limit?: number;
@@ -245,6 +247,7 @@ export interface NativeAskOptions {
     minRelevancy?: number;
     maxK?: number;
     adaptiveStrategy?: string;
+    showChunks?: boolean;
 }
 export interface NativeTimelineOptions {
     limit?: number;
@@ -693,6 +696,7 @@ export interface UseDoctorOptions {
     rebuildVecIndex?: boolean;
     vacuum?: boolean;
     dryRun?: boolean;
+    quiet?: boolean;
 }
 export interface LockOptions {
     /** Output file path (default: input.mv2e) */
@@ -819,6 +823,7 @@ export type NativeDoctorOptions = {
     rebuildVecIndex?: boolean;
     vacuum?: boolean;
     dryRun?: boolean;
+    quiet?: boolean;
 };
 export type NativeCapsuleOptions = {
     output?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memvid/sdk",
-  "version": "2.0.147",
+  "version": "2.0.149",
   "description": "Single-file AI memory system for Node.js. Store, search, and query documents with built-in RAG.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -41,10 +41,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@memvid/sdk-darwin-arm64": "2.0.147",
-    "@memvid/sdk-darwin-x64": "2.0.147",
-    "@memvid/sdk-linux-x64-gnu": "2.0.147",
-    "@memvid/sdk-win32-x64-msvc": "2.0.147"
+    "@memvid/sdk-darwin-arm64": "2.0.149",
+    "@memvid/sdk-darwin-x64": "2.0.149",
+    "@memvid/sdk-linux-x64-gnu": "2.0.149",
+    "@memvid/sdk-win32-x64-msvc": "2.0.149"
   },
   "peerDependencies": {
     "@langchain/core": ">=0.3.0",
@@ -76,6 +76,9 @@
     "typescript": "^5.4.0"
   },
   "dependencies": {
+    "unpdf": "^1.4.0",
+    "exceljs": "^4.4.0",
+    "officeparser": "^6.0.2",
     "@ai-sdk/openai": "^1.0.0",
     "@google/generative-ai": "^0.24.0",
     "@langchain/langgraph": ">=0.2.0",