@claude-flow/embeddings
Version:
V3 Embedding Service - OpenAI, Transformers.js, Agentic-Flow (ONNX), Mock providers with hyperbolic embeddings, normalization, and chunking
267 lines • 8.13 kB
TypeScript
/**
* 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
*
* `ruvector-onnx` (ADR-121 Phase 1) uses `ruvector-onnx-embeddings-wasm` —
* a portable WASM+SIMD ONNX embedder. Drop-in replacement for the
* `transformers` provider for the Xenova/HF MiniLM/BGE/E5/GTE model
* family, with smaller install footprint and a path to running in
* browsers / Workers / Deno. The legacy `transformers` provider stays
* supported through ADR-121 Phase 4.
*/
export type EmbeddingProvider = 'openai' | 'transformers' | 'mock' | 'agentic-flow' | 'rvf' | 'ruvector-onnx';
/**
* 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;
}
/**
* RVF provider configuration
* Lightweight hash-based embeddings (no neural model, sub-ms latency)
*/
export interface RvfEmbeddingConfig extends EmbeddingBaseConfig {
provider: 'rvf';
/** Embedding dimensions (default: 384) */
dimensions?: number;
/** Path to binary cache file for persistent storage */
cachePath?: string;
/** Similarity metric preference (default: 'cosine') */
metric?: 'cosine' | 'l2' | 'dotproduct';
}
/**
* ruvector-onnx provider configuration (ADR-121 Phase 1).
*
* Uses `ruvector-onnx-embeddings-wasm` — portable WASM+SIMD ONNX
* embedding generation. Model catalog includes sentence-transformers,
* BGE, E5, GTE; default is all-MiniLM-L6-v2 (384-dim).
*/
export interface RuvectorOnnxEmbeddingConfig extends EmbeddingBaseConfig {
provider: 'ruvector-onnx';
/** Model name from the bundled catalog (default: 'all-MiniLM-L6-v2'). */
model?: 'all-MiniLM-L6-v2' | 'all-MiniLM-L12-v2' | 'bge-small-en-v1.5' | 'bge-base-en-v1.5' | 'e5-small-v2' | 'gte-small' | string;
/** Pooling strategy (default: 'mean' — matches sentence-transformers). */
pooling?: 'mean' | 'cls' | 'max' | 'mean-sqrt-len' | 'last-token';
/** L2-normalize the output (default: true). */
normalize?: boolean;
/**
* Override the model fetch URL pair. Useful for air-gapped envs or
* mirror caches. When set, the model is loaded from these URLs instead
* of the bundled HuggingFace defaults.
*/
modelUrl?: string;
tokenizerUrl?: string;
}
/**
* Union of all provider configs
*/
export type EmbeddingConfig = OpenAIEmbeddingConfig | TransformersEmbeddingConfig | MockEmbeddingConfig | AgenticFlowEmbeddingConfig | RvfEmbeddingConfig | RuvectorOnnxEmbeddingConfig;
/**
* 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