@memvid/sdk 2.0.155 → 2.0.157

package/dist/index.js

@@ -36,10 +36,14 @@ 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.isTelemetryEnabled = exports.flushAnalytics = exports.LOCAL_EMBEDDING_MODELS = exports.MODEL_DIMENSIONS = exports.getEmbedder = exports.OllamaEmbeddings = exports.MistralEmbeddings = exports.GeminiEmbeddings = exports.NvidiaEmbeddings = exports.VoyageEmbeddings = exports.CohereEmbeddings = exports.OpenAIEmbeddings = exports.getErrorSuggestion = exports.QuotaExceededError = exports.EncryptionError = exports.EmbeddingFailedError = exports.VecDimensionMismatchError = exports.CorruptFileError = exports.VecIndexDisabledError = exports.FrameNotFoundError = exports.MemoryAlreadyBoundError = exports.FileNotFoundError = 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.getEmbedder = exports.OllamaEmbeddings = exports.MistralEmbeddings = exports.GeminiEmbeddings = exports.NvidiaEmbeddings = exports.VoyageEmbeddings = exports.CohereEmbeddings = exports.OpenAIEmbeddings = exports.getErrorSuggestion = exports.QuotaExceededError = exports.EncryptionError = exports.EmbeddingFailedError = exports.VecDimensionMismatchError = exports.CorruptFileError = exports.VecIndexDisabledError = exports.FrameNotFoundError = exports.MemoryAlreadyBoundError = exports.FileNotFoundError = exports.ApiKeyRequiredError = exports.LockedError = exports.VerificationFailedError = exports.TimeIndexMissingError = exports.LexIndexDisabledError = exports.TicketReplayError = exports.TicketInvalidError = exports.CapacityExceededError = exports.MemvidError = exports.use = exports.ingestDirectory = exports.ingestImages = exports.ImageIngestor = exports.EasyOCRSubprocess = exports.DocTRSubprocess = exports.TesseractOCR = exports.PaddleOCR = exports.EnsembleOCR = exports.getOCRProvider = exports.GeminiEntities = exports.ClaudeEntities = exports.OpenAIEntities = exports.LocalNER = exports.getEntityExtractor = exports.GeminiClip = exports.OpenAIClip = exports.LocalClip = exports.getClipProvider = exports.imageIngest = exports.ocr = exports.entities = exports.clip = void 0;
+exports.isTelemetryEnabled = exports.flushAnalytics = exports.LOCAL_EMBEDDING_MODELS = exports.MODEL_DIMENSIONS = void 0;
 exports.configure = configure;
 exports.getConfig = getConfig;
 exports.resetConfig = resetConfig;
+exports.getAclScopeFromApiKey = getAclScopeFromApiKey;
+exports.aclContextFromScope = aclContextFromScope;
+exports.aclMetadataFromScope = aclMetadataFromScope;
 exports.validateConfig = validateConfig;
 exports.resolveMemory = resolveMemory;
 exports.createMemory = createMemory;
@@ -79,6 +83,9 @@ require("./adapters/mcp");
 exports.clip = __importStar(require("./clip"));
 exports.entities = __importStar(require("./entities"));
 __exportStar(require("./embeddings"), exports);
+// Export OCR and image ingestion modules
+exports.ocr = __importStar(require("./ocr"));
+exports.imageIngest = __importStar(require("./image-ingest"));
 // Re-export provider factories for convenience
 var clip_1 = require("./clip");
 Object.defineProperty(exports, "getClipProvider", { enumerable: true, get: function () { return clip_1.getClipProvider; } });
@@ -91,6 +98,18 @@ Object.defineProperty(exports, "LocalNER", { enumerable: true, get: function ()
 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; } });
+// Re-export OCR providers and image ingestion
+var ocr_1 = require("./ocr");
+Object.defineProperty(exports, "getOCRProvider", { enumerable: true, get: function () { return ocr_1.getOCRProvider; } });
+Object.defineProperty(exports, "EnsembleOCR", { enumerable: true, get: function () { return ocr_1.EnsembleOCR; } });
+Object.defineProperty(exports, "PaddleOCR", { enumerable: true, get: function () { return ocr_1.PaddleOCR; } });
+Object.defineProperty(exports, "TesseractOCR", { enumerable: true, get: function () { return ocr_1.TesseractOCR; } });
+Object.defineProperty(exports, "DocTRSubprocess", { enumerable: true, get: function () { return ocr_1.DocTRSubprocess; } });
+Object.defineProperty(exports, "EasyOCRSubprocess", { enumerable: true, get: function () { return ocr_1.EasyOCRSubprocess; } });
+var image_ingest_1 = require("./image-ingest");
+Object.defineProperty(exports, "ImageIngestor", { enumerable: true, get: function () { return image_ingest_1.ImageIngestor; } });
+Object.defineProperty(exports, "ingestImages", { enumerable: true, get: function () { return image_ingest_1.ingestImages; } });
+Object.defineProperty(exports, "ingestDirectory", { enumerable: true, get: function () { return image_ingest_1.ingestDirectory; } });
 let globalConfig = {};
 /**
  * Configure global defaults for the Memvid SDK.
@@ -140,6 +159,147 @@ function getConfig() {
  */
 function resetConfig() {
     globalConfig = {};
+    aclScopeCache.clear();
+}
+const DEFAULT_ACL_SCOPE = {
+    tenantId: null,
+    subjectId: null,
+    roles: [],
+    groupIds: [],
+    enforcementMode: "audit",
+};
+const aclScopeCache = new Map();
+function resolveDashboardUrl(override) {
+    return (override ||
+        globalConfig.dashboardUrl ||
+        process.env.MEMVID_DASHBOARD_URL ||
+        "https://memvid.com").replace(/\/$/, "");
+}
+function normalizeAclString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    return trimmed.toLowerCase();
+}
+function normalizeAclStringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const unique = new Set();
+    for (const item of value) {
+        const normalized = normalizeAclString(item);
+        if (normalized) {
+            unique.add(normalized);
+        }
+    }
+    return Array.from(unique).sort();
+}
+function parseTicketEnvelope(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return null;
+    }
+    const root = payload;
+    const data = root.data;
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+        return data;
+    }
+    return root;
+}
+function normalizeApiKeyAclScopePayload(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { ...DEFAULT_ACL_SCOPE };
+    }
+    const source = value;
+    return {
+        tenantId: normalizeAclString(source.tenant_id ?? source.tenantId),
+        subjectId: normalizeAclString(source.subject_id ?? source.subjectId),
+        roles: normalizeAclStringList(source.roles),
+        groupIds: normalizeAclStringList(source.group_ids ?? source.groupIds),
+        enforcementMode: source.enforcement_mode === "enforce" || source.enforcementMode === "enforce"
+            ? "enforce"
+            : "audit",
+    };
+}
+/**
+ * Fetch ACL scope attached to the current Memvid API key.
+ *
+ * This reads `/api/ticket` from the dashboard control plane and returns
+ * the normalized ACL scope that can be reused for ingestion and retrieval.
+ */
+async function getAclScopeFromApiKey(options) {
+    const apiKey = (options?.apiKey || globalConfig.apiKey || process.env.MEMVID_API_KEY || "").trim();
+    if (!apiKey) {
+        throw new error_1.ApiKeyRequiredError("API key required for getAclScopeFromApiKey(). Set configure({ apiKey: 'mv2_...' }) or MEMVID_API_KEY.");
+    }
+    if (!isMemvidApiKey(apiKey)) {
+        throw new error_1.ApiKeyRequiredError("Invalid API key format (expected mv2_*).");
+    }
+    const dashboardUrl = resolveDashboardUrl(options?.dashboardUrl);
+    const cacheKey = `${dashboardUrl}|${apiKey}`;
+    if (!options?.forceRefresh && aclScopeCache.has(cacheKey)) {
+        return { ...aclScopeCache.get(cacheKey) };
+    }
+    const timeoutMs = options?.timeoutMs && options.timeoutMs > 0 ? options.timeoutMs : 5000;
+    const response = await fetch(`${dashboardUrl}/api/ticket`, {
+        method: "GET",
+        headers: { "x-api-key": apiKey },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        const message = response.status === 401
+            ? "Invalid API key. Get a valid key at https://memvid.com/dashboard/api-keys"
+            : `Failed to fetch ACL scope from ${dashboardUrl}/api/ticket (${response.status})`;
+        throw new error_1.MemvidError("MV022", message, body ? { body } : undefined);
+    }
+    const raw = await response.json().catch(() => ({}));
+    const ticket = parseTicketEnvelope(raw);
+    const scope = normalizeApiKeyAclScopePayload(ticket?.acl_scope);
+    aclScopeCache.set(cacheKey, scope);
+    return { ...scope };
+}
+/**
+ * Convert API-key ACL scope into query ACL context.
+ */
+function aclContextFromScope(scope) {
+    if (!scope?.tenantId) {
+        return undefined;
+    }
+    const context = { tenantId: scope.tenantId };
+    if (scope.subjectId)
+        context.subjectId = scope.subjectId;
+    if (scope.roles.length > 0)
+        context.roles = [...scope.roles];
+    if (scope.groupIds.length > 0)
+        context.groupIds = [...scope.groupIds];
+    return context;
+}
+/**
+ * Build ACL metadata for ingest from an API-key ACL scope.
+ */
+function aclMetadataFromScope(scope, options) {
+    if (!scope?.tenantId) {
+        throw new error_1.MemvidError("MV999", "ACL scope is missing tenantId. Create an ACL-scoped API key (tenant required) before ingesting restricted data.");
+    }
+    const mode = options?.visibility ?? "auto";
+    const hasReaders = !!scope.subjectId || scope.roles.length > 0 || scope.groupIds.length > 0;
+    const visibility = mode === "auto" ? (hasReaders ? "restricted" : "public") : mode;
+    const metadata = {
+        acl_tenant_id: scope.tenantId,
+        acl_visibility: visibility,
+        acl_policy_version: options?.policyVersion || "v1",
+    };
+    if (scope.subjectId)
+        metadata.acl_read_principals = [scope.subjectId];
+    if (scope.roles.length > 0)
+        metadata.acl_read_roles = [...scope.roles];
+    if (scope.groupIds.length > 0)
+        metadata.acl_read_groups = [...scope.groupIds];
+    return metadata;
 }
 /**
  * Validate the current configuration by testing API connectivity.
@@ -845,13 +1005,17 @@ function normaliseFindOptions(opts) {
         cursor: opts.cursor,
         asOfFrame: opts.asOfFrame,
         asOfTs: opts.asOfTs,
+        aclContext: opts.aclContext,
+        aclEnforcementMode: opts.aclEnforcementMode,
     };
     if (payload.k == null &&
         payload.snippetChars == null &&
         payload.scope == null &&
         payload.cursor == null &&
         payload.asOfFrame == null &&
-        payload.asOfTs == null) {
+        payload.asOfTs == null &&
+        payload.aclContext == null &&
+        payload.aclEnforcementMode == null) {
         return undefined;
     }
     return payload;
@@ -868,6 +1032,8 @@ function normaliseVecSearchOptions(opts) {
         minRelevancy: opts.minRelevancy,
         maxK: opts.maxK,
         adaptiveStrategy: opts.adaptiveStrategy,
+        aclContext: opts.aclContext,
+        aclEnforcementMode: opts.aclEnforcementMode,
     };
     if (payload.k == null &&
         payload.snippetChars == null &&
@@ -875,7 +1041,9 @@ function normaliseVecSearchOptions(opts) {
         payload.adaptive == null &&
         payload.minRelevancy == null &&
         payload.maxK == null &&
-        payload.adaptiveStrategy == null) {
+        payload.adaptiveStrategy == null &&
+        payload.aclContext == null &&
+        payload.aclEnforcementMode == null) {
         return undefined;
     }
     return payload;
@@ -903,6 +1071,8 @@ function normaliseAskOptions(opts) {
         maxK: opts.maxK,
         adaptiveStrategy: opts.adaptiveStrategy,
         showChunks: opts.showChunks,
+        aclContext: opts.aclContext,
+        aclEnforcementMode: opts.aclEnforcementMode,
     };
     if (payload.k == null &&
         payload.mode == null &&
@@ -921,7 +1091,9 @@ function normaliseAskOptions(opts) {
         payload.minRelevancy == null &&
         payload.maxK == null &&
         payload.adaptiveStrategy == null &&
-        payload.showChunks == null) {
+        payload.showChunks == null &&
+        payload.aclContext == null &&
+        payload.aclEnforcementMode == null) {
         return undefined;
     }
     return payload;

package/dist/ocr.d.ts

@@ -0,0 +1,302 @@
+/**
+ * OCR provider support for Memvid SDK (Node.js).
+ *
+ * This module provides classes for extracting text from images using OCR engines.
+ * Since docTR (best accuracy) is Python-native, Node.js has two options:
+ *   1. TesseractOCR - Built-in via tesseract.js, no external deps
+ *   2. DocTRSubprocess - Spawns Python for highest accuracy (85.3%)
+ *
+ * OCR Accuracy Comparison (tested on construction drawings):
+ *   - docTR (Python): 85.3% - BEST
+ *   - EasyOCR (Python): 79.4%
+ *   - Tesseract.js: ~50-60% (lower than Python Tesseract)
+ *
+ * @example
+ * ```typescript
+ * import { TesseractOCR, DocTRSubprocess, getOCRProvider } from 'memvid-sdk/ocr';
+ *
+ * // Built-in Tesseract.js (no external deps)
+ * const ocr = new TesseractOCR();
+ * const result = await ocr.extractText('drawing.png');
+ * console.log(result.text);
+ *
+ * // For highest accuracy, use docTR via Python subprocess
+ * const doctrOcr = new DocTRSubprocess();
+ * const result2 = await doctrOcr.extractText('drawing.png');
+ * ```
+*/
+/**
+ * Result from OCR text extraction.
+ */
+export interface OCRResult {
+    /** Full extracted text */
+    text: string;
+    /** Overall confidence score (0-1) */
+    confidence: number;
+    /** Word/region-level results with bounding boxes */
+    regions: OCRRegion[];
+    /** Provider-specific metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * A detected text region with bounding box.
+ */
+export interface OCRRegion {
+    /** Extracted text for this region */
+    text: string;
+    /** Confidence score for this region (0-1) */
+    confidence: number;
+    /** Bounding box coordinates */
+    bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Abstract interface for OCR providers.
+ */
+export interface OCRProvider {
+    /** Provider name (e.g., 'tesseract', 'doctr') */
+    readonly name: string;
+    /**
+     * Extract text from an image file.
+     * @param imagePath - Path to the image file
+     * @returns Promise resolving to OCR result
+     */
+    extractText(imagePath: string): Promise<OCRResult>;
+    /**
+     * Extract text from multiple images.
+     * Default implementation is sequential; override for batch processing.
+     * @param imagePaths - Array of image file paths
+     * @returns Promise resolving to array of OCR results
+     */
+    extractTextBatch?(imagePaths: string[]): Promise<OCRResult[]>;
+    /**
+     * Clean up resources (e.g., terminate workers).
+     */
+    terminate?(): Promise<void>;
+}
+/**
+ * Tesseract.js configuration options.
+ */
+export interface TesseractConfig {
+    /** Language code (default: 'eng') */
+    lang?: string;
+    /** Path to trained data (optional) */
+    dataPath?: string;
+    /** Number of worker threads (default: 1) */
+    workerCount?: number;
+}
+/**
+ * Tesseract.js OCR provider.
+ *
+ * Built-in OCR using tesseract.js - no external dependencies required.
+ * Lower accuracy than docTR (~50-60% vs 85.3%) but easy to set up.
+ *
+ * @example
+ * ```typescript
+ * const ocr = new TesseractOCR();
+ * const result = await ocr.extractText('construction_drawing.png');
+ * console.log(result.text);
+ * console.log(`Confidence: ${(result.confidence * 100).toFixed(1)}%`);
+ * await ocr.terminate(); // Clean up worker
+ * ```
+ */
+export declare class TesseractOCR implements OCRProvider {
+    private _lang;
+    private _dataPath?;
+    private _worker;
+    private _workerCount;
+    private _tesseract;
+    constructor(config?: TesseractConfig);
+    get name(): string;
+    private getTesseract;
+    private getWorker;
+    extractText(imagePath: string): Promise<OCRResult>;
+    extractTextBatch(imagePaths: string[]): Promise<OCRResult[]>;
+    terminate(): Promise<void>;
+}
+/**
+ * docTR via Python subprocess configuration.
+ */
+export interface DocTRConfig {
+    /** Path to Python executable (default: 'python3') */
+    pythonPath?: string;
+    /** Detection architecture (default: 'db_resnet50') */
+    detArch?: string;
+    /** Recognition architecture (default: 'crnn_vgg16_bn') */
+    recoArch?: string;
+    /** Timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/**
+ * docTR OCR via Python subprocess.
+ *
+ * Highest accuracy OCR (85.3% on construction drawings) using docTR.
+ * Requires Python with docTR installed: `pip install python-doctr[torch]`
+ *
+ * This spawns a Python subprocess for each extraction, which adds overhead
+ * but provides the best accuracy for technical documents.
+ *
+ * @example
+ * ```typescript
+ * const ocr = new DocTRSubprocess();
+ * const result = await ocr.extractText('construction_drawing.png');
+ * console.log(result.text);
+ * console.log(`Confidence: ${(result.confidence * 100).toFixed(1)}%`);
+ * ```
+ */
+export declare class DocTRSubprocess implements OCRProvider {
+    private _pythonPath;
+    private _detArch;
+    private _recoArch;
+    private _timeout;
+    constructor(config?: DocTRConfig);
+    get name(): string;
+    extractText(imagePath: string): Promise<OCRResult>;
+    extractTextBatch(imagePaths: string[]): Promise<OCRResult[]>;
+}
+/**
+ * EasyOCR via Python subprocess configuration.
+ */
+export interface EasyOCRConfig {
+    /** Path to Python executable (default: 'python3') */
+    pythonPath?: string;
+    /** Languages to recognize (default: ['en']) */
+    languages?: string[];
+    /** Use GPU if available (default: false) */
+    gpu?: boolean;
+    /** Timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/**
+ * EasyOCR via Python subprocess.
+ *
+ * Good fallback OCR (79.4% on construction drawings) using EasyOCR.
+ * Requires Python with EasyOCR installed: `pip install easyocr`
+ *
+ * @example
+ * ```typescript
+ * const ocr = new EasyOCRSubprocess();
+ * const result = await ocr.extractText('construction_drawing.png');
+ * console.log(result.text);
+ * ```
+ */
+export declare class EasyOCRSubprocess implements OCRProvider {
+    private _pythonPath;
+    private _languages;
+    private _gpu;
+    private _timeout;
+    constructor(config?: EasyOCRConfig);
+    get name(): string;
+    extractText(imagePath: string): Promise<OCRResult>;
+}
+/**
+ * PaddleOCR configuration options.
+ */
+export interface PaddleOCRConfig {
+    /** Apply high contrast preprocessing (default: true, improves accuracy by ~25%) */
+    preprocessing?: boolean;
+    /** Contrast multiplier for preprocessing (default: 1.5) */
+    contrast?: number;
+}
+/**
+ * PaddleOCR via @gutenye/ocr-node (ONNX runtime).
+ *
+ * Fast and accurate OCR using PaddleOCR PP-OCRv4 model.
+ * Runs natively in Node.js via ONNX - no Python required.
+ *
+ * Requires: npm install @gutenye/ocr-node
+ *
+ * Performance (on construction drawings):
+ *   - Speed: ~0.35s
+ *   - Accuracy: ~75% with preprocessing (vs 50% without)
+ *
+ * @example
+ * ```typescript
+ * const ocr = new PaddleOCR();
+ * const result = await ocr.extractText('drawing.png');
+ * console.log(result.text);
+ * ```
+ */
+export declare class PaddleOCR implements OCRProvider {
+    private _ocr;
+    private _sharp;
+    private _preprocessing;
+    private _contrast;
+    constructor(config?: PaddleOCRConfig);
+    get name(): string;
+    private getOcr;
+    private getSharp;
+    private preprocessImage;
+    extractText(imagePath: string): Promise<OCRResult>;
+    extractTextBatch(imagePaths: string[]): Promise<OCRResult[]>;
+}
+/**
+ * Ensemble OCR configuration options.
+ */
+export interface EnsembleOCRConfig {
+    /** Contrast multiplier for preprocessing (default: 1.5) */
+    contrast?: number;
+    /** Enable sharpening (default: true) */
+    sharpen?: boolean;
+}
+/**
+ * Ensemble OCR - combines PaddleOCR + Tesseract for maximum accuracy.
+ *
+ * Achieves ~100% accuracy by running multiple OCR engines in parallel
+ * with different preprocessing, then merging results.
+ *
+ * Performance:
+ *   - Accuracy: ~100% (vs 75% for PaddleOCR alone)
+ *   - Speed: ~900ms (parallel execution)
+ *
+ * Requires: npm install @gutenye/ocr-node tesseract.js
+ *
+ * @example
+ * ```typescript
+ * const ocr = new EnsembleOCR();
+ * const result = await ocr.extractText('drawing.png');
+ * console.log(result.text); // Maximum accuracy
+ * ```
+ */
+export declare class EnsembleOCR implements OCRProvider {
+    private _paddleOcr;
+    private _tessWorker;
+    private _sharp;
+    private _contrast;
+    private _sharpen;
+    constructor(config?: EnsembleOCRConfig);
+    get name(): string;
+    private getPaddleOcr;
+    private getTessWorker;
+    private getSharp;
+    extractText(imagePath: string): Promise<OCRResult>;
+    terminate(): Promise<void>;
+}
+/**
+ * OCR provider type for factory function.
+ */
+export type OCRProviderType = 'ensemble' | 'paddle' | 'tesseract' | 'doctr' | 'easyocr';
+/**
+ * Factory function to create an OCR provider.
+ *
+ * @param provider - Provider type: 'paddle', 'tesseract', 'doctr', or 'easyocr'
+ * @param config - Provider-specific configuration
+ * @returns OCR provider instance
+ *
+ * @example
+ * ```typescript
+ * // PaddleOCR via ONNX (fast, recommended for Node.js)
+ * const ocr1 = getOCRProvider('paddle');
+ *
+ * // Tesseract.js (fallback)
+ * const ocr2 = getOCRProvider('tesseract');
+ *
+ * // docTR via Python (best accuracy: 85%)
+ * const ocr3 = getOCRProvider('doctr');
+ * ```
+ */
+export declare function getOCRProvider(provider?: OCRProviderType, config?: TesseractConfig | DocTRConfig | EasyOCRConfig | PaddleOCRConfig | EnsembleOCRConfig): OCRProvider;