@memvid/sdk 2.0.113

package/dist/entities.js

@@ -0,0 +1,489 @@
+"use strict";
+/**
+ * Entity extraction (NER) provider support for Memvid SDK (Node.js).
+ *
+ * Providers:
+ *   - LocalNER: DistilBERT-NER (ONNX, offline)
+ *   - OpenAIEntities: OpenAI GPT-4 (cloud, custom entity types)
+ *   - ClaudeEntities: Anthropic Claude (cloud, custom entity types)
+ *   - GeminiEntities: Google Gemini (cloud, custom entity types)
+ *
+ * @example
+ * ```typescript
+ * import { create } from 'memvid-sdk';
+ * import { getEntityExtractor, LocalNER, OpenAIEntities } from 'memvid-sdk/entities';
+ *
+ * // Local NER (default)
+ * const ner = getEntityExtractor('local');
+ *
+ * // Or with cloud provider for custom entity types
+ * const ner = getEntityExtractor('openai', {
+ *   entityTypes: ['COMPANY', 'PRODUCT', 'EXECUTIVE'],
+ * });
+ *
+ * // Extract entities
+ * const text = "Microsoft CEO Satya Nadella announced the new Surface Pro in Seattle.";
+ * const entities = await ner.extract(text);
+ * // [
+ * //   { name: "Microsoft", type: "ORG", confidence: 0.99 },
+ * //   { name: "Satya Nadella", type: "PERSON", confidence: 0.97 },
+ * //   { name: "Seattle", type: "LOCATION", confidence: 0.98 },
+ * // ]
+ *
+ * // Store with entities
+ * const mem = await create('knowledge.mv2', 'basic');
+ * await mem.put({ title: 'Tech News', text, entities });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiEntities = exports.ClaudeEntities = exports.OpenAIEntities = exports.LocalNER = exports.DEFAULT_ENTITY_TYPES = void 0;
+exports.getEntityExtractor = getEntityExtractor;
+/**
+ * Default entity types for cloud providers.
+ */
+exports.DEFAULT_ENTITY_TYPES = [
+    'PERSON',
+    'ORG',
+    'LOCATION',
+    'DATE',
+    'PRODUCT',
+    'EVENT',
+    'OTHER',
+];
+/**
+ * Local NER provider using DistilBERT-NER (ONNX).
+ *
+ * Supported entity types (fixed):
+ *   - PERSON: People's names
+ *   - ORG: Organizations
+ *   - LOCATION: Places
+ *   - MISC: Miscellaneous
+ */
+class LocalNER {
+    constructor(config = {}) {
+        this._nativeModel = null;
+        this._model = config.model || 'distilbert-ner';
+    }
+    get name() {
+        return `local:${this._model}`;
+    }
+    get entityTypes() {
+        return ['PERSON', 'ORG', 'LOCATION', 'MISC'];
+    }
+    async _getModel() {
+        if (this._nativeModel === null) {
+            try {
+                // Import native bindings - use relative path for development
+                const native = require('../index.node');
+                if (!native.NerModel) {
+                    throw new Error('NerModel not exported from native module');
+                }
+                this._nativeModel = new native.NerModel();
+            }
+            catch (e) {
+                throw new Error(`Local NER support requires memvid-sdk with NER feature. ` +
+                    `The model will auto-download on first use (~261 MB). Error: ${e}`);
+            }
+        }
+        return this._nativeModel;
+    }
+    async extract(text, minConfidence = 0.5) {
+        const model = await this._getModel();
+        const rawEntities = await model.extract(text);
+        return rawEntities
+            .filter((e) => e.confidence >= minConfidence)
+            .map((e) => ({
+            name: e.name,
+            type: e.type,
+            confidence: e.confidence,
+        }));
+    }
+    async extractBatch(texts, minConfidence = 0.5) {
+        const results = [];
+        for (const text of texts) {
+            results.push(await this.extract(text, minConfidence));
+        }
+        return results;
+    }
+}
+exports.LocalNER = LocalNER;
+/**
+ * OpenAI GPT-4 entity extraction provider.
+ *
+ * Supports custom entity types and relationship extraction.
+ */
+class OpenAIEntities {
+    constructor(config = {}) {
+        this._apiKey = config.apiKey || process.env.OPENAI_API_KEY || '';
+        if (!this._apiKey) {
+            throw new Error('OpenAI API key required. Pass apiKey or set OPENAI_API_KEY environment variable.');
+        }
+        this._model = config.model || 'gpt-4o-mini';
+        this._entityTypes = config.entityTypes || exports.DEFAULT_ENTITY_TYPES;
+        this._prompt = config.prompt || OpenAIEntities.DEFAULT_PROMPT;
+    }
+    get name() {
+        return `openai:${this._model}`;
+    }
+    get entityTypes() {
+        return this._entityTypes;
+    }
+    async extract(text, minConfidence = 0.5) {
+        const prompt = this._prompt
+            .replace('{entity_types}', this._entityTypes.join(', '))
+            .replace('{text}', text);
+        const response = await fetch('https://api.openai.com/v1/chat/completions', {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this._apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: this._model,
+                messages: [
+                    {
+                        role: 'system',
+                        content: 'You are an expert at extracting named entities from text. Always return valid JSON.',
+                    },
+                    { role: 'user', content: prompt },
+                ],
+                temperature: 0.1,
+                max_tokens: 1000,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`OpenAI API error: ${response.status} ${error}`);
+        }
+        const data = await response.json();
+        let content = data.choices?.[0]?.message?.content || '{}';
+        // Parse JSON response
+        try {
+            // Handle markdown code blocks
+            if (content.includes('```json')) {
+                content = content.split('```json')[1].split('```')[0];
+            }
+            else if (content.includes('```')) {
+                content = content.split('```')[1].split('```')[0];
+            }
+            const parsed = JSON.parse(content);
+            const rawEntities = parsed.entities || [];
+            return rawEntities
+                .filter((e) => (e.confidence || 0.8) >= minConfidence)
+                .map((e) => ({
+                name: e.name || '',
+                type: e.type || 'OTHER',
+                confidence: e.confidence || 0.8,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    async extractBatch(texts, minConfidence = 0.5) {
+        const results = [];
+        for (const text of texts) {
+            results.push(await this.extract(text, minConfidence));
+        }
+        return results;
+    }
+    /**
+     * Extract entities AND relationships from text.
+     */
+    async extractWithRelationships(text, minConfidence = 0.5) {
+        const prompt = `Extract named entities AND their relationships from the text.
+
+Return a JSON object with:
+1. "entities": array of {"name": "...", "type": "...", "confidence": 0.9}
+2. "relationships": array of {"source": "entity name", "target": "entity name", "type": "RELATIONSHIP_TYPE", "confidence": 0.9}
+
+Entity types: ${this._entityTypes.join(', ')}
+Relationship types: WORKS_FOR, LOCATED_IN, OWNS, PRODUCES, PARTNER_OF, SUBSIDIARY_OF, CEO_OF, FOUNDED, ACQUIRED, OTHER
+
+Return ONLY valid JSON.
+
+Text: ${text}`;
+        const response = await fetch('https://api.openai.com/v1/chat/completions', {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this._apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: this._model,
+                messages: [
+                    {
+                        role: 'system',
+                        content: 'You are an expert at extracting entities and relationships. Always return valid JSON.',
+                    },
+                    { role: 'user', content: prompt },
+                ],
+                temperature: 0.1,
+                max_tokens: 2000,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`OpenAI API error: ${response.status} ${error}`);
+        }
+        const data = await response.json();
+        let content = data.choices?.[0]?.message?.content || '{}';
+        try {
+            if (content.includes('```json')) {
+                content = content.split('```json')[1].split('```')[0];
+            }
+            else if (content.includes('```')) {
+                content = content.split('```')[1].split('```')[0];
+            }
+            const parsed = JSON.parse(content);
+            const entities = (parsed.entities || [])
+                .filter((e) => (e.confidence || 0.8) >= minConfidence)
+                .map((e) => ({
+                name: e.name || '',
+                type: e.type || 'OTHER',
+                confidence: e.confidence || 0.8,
+            }));
+            const relationships = (parsed.relationships || [])
+                .filter((r) => (r.confidence || 0.8) >= minConfidence);
+            return { entities, relationships };
+        }
+        catch {
+            return { entities: [], relationships: [] };
+        }
+    }
+}
+exports.OpenAIEntities = OpenAIEntities;
+OpenAIEntities.DEFAULT_PROMPT = `Extract named entities from the provided text. Return a JSON object with an "entities" array.
+
+Each entity should have:
+- "name": The entity name as it appears in the text
+- "type": The entity type from the allowed types
+- "confidence": A number between 0.0 and 1.0 indicating your confidence
+
+Return ONLY valid JSON, no explanations or markdown.
+
+Allowed entity types: {entity_types}
+
+Text to analyze:
+{text}`;
+/**
+ * Anthropic Claude entity extraction provider.
+ */
+class ClaudeEntities {
+    constructor(config = {}) {
+        this._apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY || '';
+        if (!this._apiKey) {
+            throw new Error('Anthropic API key required. Pass apiKey or set ANTHROPIC_API_KEY environment variable.');
+        }
+        this._model = config.model || 'claude-3-5-sonnet-20241022';
+        this._entityTypes = config.entityTypes || exports.DEFAULT_ENTITY_TYPES;
+    }
+    get name() {
+        return `claude:${this._model}`;
+    }
+    get entityTypes() {
+        return this._entityTypes;
+    }
+    async extract(text, minConfidence = 0.5) {
+        const prompt = `Extract named entities from this text. Return ONLY a JSON object with an "entities" array.
+
+Each entity: {"name": "exact text", "type": "TYPE", "confidence": 0.9}
+Types: ${this._entityTypes.join(', ')}
+
+Text: ${text}`;
+        const response = await fetch('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'x-api-key': this._apiKey,
+                'anthropic-version': '2023-06-01',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: this._model,
+                max_tokens: 1000,
+                messages: [{ role: 'user', content: prompt }],
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Claude API error: ${response.status} ${error}`);
+        }
+        const data = await response.json();
+        let content = data.content?.[0]?.text || '{}';
+        try {
+            if (content.includes('```json')) {
+                content = content.split('```json')[1].split('```')[0];
+            }
+            else if (content.includes('```')) {
+                content = content.split('```')[1].split('```')[0];
+            }
+            const parsed = JSON.parse(content);
+            const rawEntities = parsed.entities || [];
+            return rawEntities
+                .filter((e) => (e.confidence || 0.8) >= minConfidence)
+                .map((e) => ({
+                name: e.name || '',
+                type: e.type || 'OTHER',
+                confidence: e.confidence || 0.8,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    async extractBatch(texts, minConfidence = 0.5) {
+        const results = [];
+        for (const text of texts) {
+            results.push(await this.extract(text, minConfidence));
+        }
+        return results;
+    }
+}
+exports.ClaudeEntities = ClaudeEntities;
+/**
+ * Google Gemini entity extraction provider.
+ */
+class GeminiEntities {
+    constructor(config = {}) {
+        this._apiKey = config.apiKey || process.env.GEMINI_API_KEY || '';
+        if (!this._apiKey) {
+            throw new Error('Gemini API key required. Pass apiKey or set GEMINI_API_KEY environment variable.');
+        }
+        this._model = config.model || 'gemini-2.0-flash';
+        this._entityTypes = config.entityTypes || exports.DEFAULT_ENTITY_TYPES;
+    }
+    get name() {
+        return `gemini:${this._model}`;
+    }
+    get entityTypes() {
+        return this._entityTypes;
+    }
+    async extract(text, minConfidence = 0.5) {
+        const prompt = `Extract named entities from this text. Return ONLY a JSON object with an "entities" array.
+
+Each entity: {"name": "exact text", "type": "TYPE", "confidence": 0.9}
+Types: ${this._entityTypes.join(', ')}
+
+Text: ${text}`;
+        const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${this._model}:generateContent?key=${this._apiKey}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                contents: [{ parts: [{ text: prompt }] }],
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Gemini API error: ${response.status} ${error}`);
+        }
+        const data = await response.json();
+        let content = data.candidates?.[0]?.content?.parts?.[0]?.text || '{}';
+        try {
+            if (content.includes('```json')) {
+                content = content.split('```json')[1].split('```')[0];
+            }
+            else if (content.includes('```')) {
+                content = content.split('```')[1].split('```')[0];
+            }
+            const parsed = JSON.parse(content);
+            const rawEntities = parsed.entities || [];
+            return rawEntities
+                .filter((e) => (e.confidence || 0.8) >= minConfidence)
+                .map((e) => ({
+                name: e.name || '',
+                type: e.type || 'OTHER',
+                confidence: e.confidence || 0.8,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    async extractBatch(texts, minConfidence = 0.5) {
+        const results = [];
+        for (const text of texts) {
+            results.push(await this.extract(text, minConfidence));
+        }
+        return results;
+    }
+}
+exports.GeminiEntities = GeminiEntities;
+/**
+ * Parse provider:model specification.
+ * Examples:
+ *   "openai" -> ["openai", undefined]
+ *   "openai:gpt-4o-mini" -> ["openai", "gpt-4o-mini"]
+ *   "claude:claude-3-5-sonnet-20241022" -> ["claude", "claude-3-5-sonnet-20241022"]
+ *   "gemini:gemini-2.0-flash" -> ["gemini", "gemini-2.0-flash"]
+ */
+function parseProviderModel(spec) {
+    if (spec.includes(':')) {
+        const idx = spec.indexOf(':');
+        return [spec.substring(0, idx).toLowerCase(), spec.substring(idx + 1)];
+    }
+    return [spec.toLowerCase(), undefined];
+}
+/**
+ * Factory function to create an entity extraction provider.
+ *
+ * @param provider - Provider specification. Can be:
+ *   - Simple: 'local', 'openai', 'claude', 'gemini'
+ *   - With model: 'openai:gpt-4o-mini', 'claude:claude-3-5-sonnet-20241022'
+ * @param config - Provider-specific configuration
+ * @returns EntityExtractor instance
+ *
+ * @example
+ * ```typescript
+ * // Simple provider
+ * const ner = getEntityExtractor('local');
+ * const ner = getEntityExtractor('openai');
+ *
+ * // Provider with model specification
+ * const ner = getEntityExtractor('openai:gpt-4o-mini');
+ * const ner = getEntityExtractor('claude:claude-3-5-sonnet-20241022');
+ * const ner = getEntityExtractor('gemini:gemini-2.0-flash');
+ *
+ * // With config for custom entity types
+ * const ner = getEntityExtractor('openai', { entityTypes: ['COMPANY', 'PRODUCT'] });
+ * ```
+ */
+function getEntityExtractor(provider = 'local', config = {}) {
+    // Parse provider:model format
+    const [parsedProvider, parsedModel] = parseProviderModel(provider);
+    // Use parsed model if config.model is not explicitly set
+    const effectiveModel = config.model ?? parsedModel;
+    switch (parsedProvider) {
+        case 'local':
+            return new LocalNER({ model: effectiveModel });
+        case 'openai':
+            return new OpenAIEntities({
+                apiKey: config.apiKey,
+                model: effectiveModel,
+                entityTypes: config.entityTypes,
+                prompt: config.prompt,
+            });
+        case 'claude':
+        case 'anthropic':
+            return new ClaudeEntities({
+                apiKey: config.apiKey,
+                model: effectiveModel,
+                entityTypes: config.entityTypes,
+            });
+        case 'gemini':
+            return new GeminiEntities({
+                apiKey: config.apiKey,
+                model: effectiveModel,
+                entityTypes: config.entityTypes,
+            });
+        default:
+            throw new Error(`Unknown provider: ${parsedProvider}. Supported: local, openai, claude, gemini`);
+    }
+}
+exports.default = {
+    LocalNER,
+    OpenAIEntities,
+    ClaudeEntities,
+    GeminiEntities,
+    getEntityExtractor,
+    DEFAULT_ENTITY_TYPES: exports.DEFAULT_ENTITY_TYPES,
+};

package/dist/error.d.ts

@@ -0,0 +1,91 @@
+import type { MemvidErrorCode, MemvidErrorDetails } from "./types";
+/**
+ * Structured error class for Memvid SDK operations.
+ *
+ * All errors from the Memvid SDK are instances of this class,
+ * providing consistent error handling with:
+ * - `.code`: Machine-readable error code (e.g., "MV001")
+ * - `.message`: Human-readable error message
+ * - `.details`: Optional structured details object
+ *
+ * @example
+ * ```typescript
+ * import { use, MemvidError } from "@memvid/sdk";
+ *
+ * try {
+ *   const mem = await use("basic", "file.mv2");
+ *   await mem.put({ title: "Doc", label: "test", text: "..." });
+ * } catch (err) {
+ *   if (err instanceof MemvidError) {
+ *     switch (err.code) {
+ *       case "MV001":
+ *         console.error("Capacity exceeded:", err.message);
+ *         break;
+ *       case "MV007":
+ *         console.error("File locked:", err.details?.owner);
+ *         break;
+ *       default:
+ *         console.error(`Error ${err.code}: ${err.message}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class MemvidError extends Error implements MemvidErrorDetails {
+    readonly code: MemvidErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: MemvidErrorCode, message: string, details?: Record<string, unknown>);
+    /**
+     * Create a MemvidError from a native error string.
+     * Parses the "MV001: message" format from the Rust binding.
+     */
+    static fromNative(err: Error): MemvidError;
+    /**
+     * Check if an error is a MemvidError.
+     */
+    static isMemvidError(err: unknown): err is MemvidError;
+    /**
+     * Convert to JSON for logging/serialization.
+     */
+    toJSON(): MemvidErrorDetails;
+}
+export declare class CapacityExceededError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class TicketInvalidError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class TicketReplayError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class LexIndexDisabledError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class TimeIndexMissingError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class VerificationFailedError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class LockedError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class ApiKeyRequiredError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class MemoryAlreadyBoundError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class FrameNotFoundError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class VecIndexDisabledError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class CorruptFileError extends MemvidError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Wrap a native error into the appropriate MemvidError subclass.
+ */
+export declare function wrapNativeError(err: Error): MemvidError;