@sparkleideas/embeddings 3.0.0-alpha.29 → 3.0.0-alpha.36

package/dist/types.d.ts

@@ -0,0 +1,224 @@
+/**
+ * V3 Embedding Service Types
+ *
+ * Type definitions for embedding service aligned with agentic-flow@alpha:
+ * - OpenAI provider
+ * - Transformers.js provider
+ * - Mock provider
+ *
+ * Performance Targets:
+ * - Single embedding: <100ms (API), <50ms (local)
+ * - Batch embedding: <500ms for 10 items
+ * - Cache hit: <1ms
+ */
+/**
+ * Supported embedding providers
+ */
+export type EmbeddingProvider = 'openai' | 'transformers' | 'mock' | 'agentic-flow';
+/**
+ * Normalization type for embeddings
+ */
+export type NormalizationType = 'l2' | 'l1' | 'minmax' | 'zscore' | 'none';
+/**
+ * Persistent cache configuration
+ */
+export interface PersistentCacheConfig {
+    /** Enable persistent disk cache (requires better-sqlite3) */
+    enabled: boolean;
+    /** Path to SQLite database file (default: .cache/embeddings.db) */
+    dbPath?: string;
+    /** Maximum entries in persistent cache (default: 10000) */
+    maxSize?: number;
+    /** TTL in milliseconds (default: 7 days) */
+    ttlMs?: number;
+}
+/**
+ * Base configuration for all providers
+ */
+export interface EmbeddingBaseConfig {
+    /** Provider identifier */
+    provider: EmbeddingProvider;
+    /** Embedding dimensions */
+    dimensions?: number;
+    /** Cache size (number of embeddings) */
+    cacheSize?: number;
+    /** Enable caching */
+    enableCache?: boolean;
+    /** Normalization type (default: 'none' - most providers pre-normalize) */
+    normalization?: NormalizationType;
+    /** Persistent disk cache configuration */
+    persistentCache?: PersistentCacheConfig;
+}
+/**
+ * OpenAI provider configuration
+ */
+export interface OpenAIEmbeddingConfig extends EmbeddingBaseConfig {
+    provider: 'openai';
+    /** OpenAI API key */
+    apiKey: string;
+    /** Model to use */
+    model?: 'text-embedding-3-small' | 'text-embedding-3-large' | 'text-embedding-ada-002';
+    /** Target dimensions (for text-embedding-3-* models) */
+    dimensions?: number;
+    /** Base URL override */
+    baseURL?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Max retries */
+    maxRetries?: number;
+}
+/**
+ * Transformers.js provider configuration
+ */
+export interface TransformersEmbeddingConfig extends EmbeddingBaseConfig {
+    provider: 'transformers';
+    /** Model name from Hugging Face */
+    model?: string;
+    /** Quantization level */
+    quantized?: boolean;
+    /** Use web worker */
+    useWorker?: boolean;
+}
+/**
+ * Mock provider configuration
+ */
+export interface MockEmbeddingConfig extends EmbeddingBaseConfig {
+    provider: 'mock';
+    /** Output dimensions */
+    dimensions?: number;
+    /** Simulated latency in ms */
+    simulatedLatency?: number;
+}
+/**
+ * Agentic-flow provider configuration
+ * Uses optimized ONNX embeddings with:
+ * - Float32Array with flattened matrices
+ * - 256-entry LRU cache with FNV-1a hash
+ * - SIMD-friendly loop unrolling (4x)
+ * - Pre-allocated buffers (no GC pressure)
+ */
+export interface AgenticFlowEmbeddingConfig extends EmbeddingBaseConfig {
+    provider: 'agentic-flow';
+    /** Model ID (default: all-MiniLM-L6-v2) */
+    modelId?: string;
+    /** Embedding dimensions (default: 384) */
+    dimensions?: number;
+    /** Internal cache size for embedder (default: 256) */
+    embedderCacheSize?: number;
+    /** Model directory path */
+    modelDir?: string;
+    /** Auto-download model if not present */
+    autoDownload?: boolean;
+}
+/**
+ * Union of all provider configs
+ */
+export type EmbeddingConfig = OpenAIEmbeddingConfig | TransformersEmbeddingConfig | MockEmbeddingConfig | AgenticFlowEmbeddingConfig;
+/**
+ * Single embedding result
+ */
+export interface EmbeddingResult {
+    /** The embedding vector */
+    embedding: Float32Array | number[];
+    /** Latency in milliseconds */
+    latencyMs: number;
+    /** Token usage (for API providers) */
+    usage?: {
+        promptTokens: number;
+        totalTokens: number;
+    };
+    /** Whether result was from cache */
+    cached?: boolean;
+    /** Whether result was from persistent cache */
+    persistentCached?: boolean;
+    /** Whether embedding was normalized */
+    normalized?: boolean;
+}
+/**
+ * Batch embedding result
+ */
+export interface BatchEmbeddingResult {
+    /** Array of embeddings */
+    embeddings: Array<Float32Array | number[]>;
+    /** Total latency in milliseconds */
+    totalLatencyMs: number;
+    /** Average latency per embedding */
+    avgLatencyMs: number;
+    /** Token usage (for API providers) */
+    usage?: {
+        promptTokens: number;
+        totalTokens: number;
+    };
+    /** Cache statistics */
+    cacheStats?: {
+        hits: number;
+        misses: number;
+    };
+}
+/**
+ * Embedding service interface
+ */
+export interface IEmbeddingService {
+    /** Provider identifier */
+    readonly provider: EmbeddingProvider;
+    /** Get embedding for single text */
+    embed(text: string): Promise<EmbeddingResult>;
+    /** Get embeddings for multiple texts */
+    embedBatch(texts: string[]): Promise<BatchEmbeddingResult>;
+    /** Clear cache */
+    clearCache(): void;
+    /** Get cache statistics */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+    };
+    /** Shutdown service */
+    shutdown(): Promise<void>;
+}
+/**
+ * Embedding service events
+ */
+export type EmbeddingEvent = {
+    type: 'embed_start';
+    text: string;
+} | {
+    type: 'embed_complete';
+    text: string;
+    latencyMs: number;
+} | {
+    type: 'embed_error';
+    text: string;
+    error: string;
+} | {
+    type: 'batch_start';
+    count: number;
+} | {
+    type: 'batch_complete';
+    count: number;
+    latencyMs: number;
+} | {
+    type: 'cache_hit';
+    text: string;
+} | {
+    type: 'cache_eviction';
+    size: number;
+};
+/**
+ * Event listener type
+ */
+export type EmbeddingEventListener = (event: EmbeddingEvent) => void | Promise<void>;
+/**
+ * Similarity metric type
+ */
+export type SimilarityMetric = 'cosine' | 'euclidean' | 'dot';
+/**
+ * Similarity result
+ */
+export interface SimilarityResult {
+    /** Similarity score (0-1 for cosine, unbounded for others) */
+    score: number;
+    /** Metric used */
+    metric: SimilarityMetric;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * V3 Embedding Service Types
+ *
+ * Type definitions for embedding service aligned with agentic-flow@alpha:
+ * - OpenAI provider
+ * - Transformers.js provider
+ * - Mock provider
+ *
+ * Performance Targets:
+ * - Single embedding: <100ms (API), <50ms (local)
+ * - Batch embedding: <500ms for 10 items
+ * - Cache hit: <1ms
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkleideas/embeddings",
-  "version": "3.0.0-alpha.29",
+  "version": "3.0.0-alpha.36",
   "description": "V3 Embedding Service - OpenAI, Transformers.js, Agentic-Flow (ONNX), Mock providers with hyperbolic embeddings, normalization, and chunking",
   "type": "module",
   "main": "./dist/index.js",