tasq/node_modules/@claude-flow/embeddings/dist/embedding-service.d.ts

/**
 * V3 Embedding Service Implementation
 *
 * Production embedding service aligned with agentic-flow@alpha:
 * - OpenAI provider (text-embedding-3-small/large)
 * - Transformers.js provider (local ONNX models)
 * - Mock provider (development/testing)
 *
 * Performance Targets:
 * - Single embedding: <100ms (API), <50ms (local)
 * - Batch embedding: <500ms for 10 items
 * - Cache hit: <1ms
 */
import { EventEmitter } from 'events';
import type { EmbeddingProvider, EmbeddingConfig, OpenAIEmbeddingConfig, TransformersEmbeddingConfig, MockEmbeddingConfig, AgenticFlowEmbeddingConfig, EmbeddingResult, BatchEmbeddingResult, IEmbeddingService, EmbeddingEvent, EmbeddingEventListener, SimilarityMetric, SimilarityResult, NormalizationType } from './types.js';
import { PersistentEmbeddingCache } from './persistent-cache.js';
declare class LRUCache<K, V> {
    private readonly maxSize;
    private cache;
    private hits;
    private misses;
    constructor(maxSize: number);
    get(key: K): V | undefined;
    set(key: K, value: V): void;
    clear(): void;
    get size(): number;
    get hitRate(): number;
    getStats(): {
        size: number;
        maxSize: number;
        hits: number;
        misses: number;
        hitRate: number;
    };
}
declare abstract class BaseEmbeddingService extends EventEmitter implements IEmbeddingService {
    protected readonly config: EmbeddingConfig;
    abstract readonly provider: EmbeddingProvider;
    protected cache: LRUCache<string, Float32Array>;
    protected persistentCache: PersistentEmbeddingCache | null;
    protected embeddingListeners: Set<EmbeddingEventListener>;
    protected normalizationType: NormalizationType;
    constructor(config: EmbeddingConfig);
    abstract embed(text: string): Promise<EmbeddingResult>;
    abstract embedBatch(texts: string[]): Promise<BatchEmbeddingResult>;
    /**
     * Apply normalization to embedding if configured
     */
    protected applyNormalization(embedding: Float32Array): Float32Array;
    /**
     * Check persistent cache for embedding
     */
    protected checkPersistentCache(text: string): Promise<Float32Array | null>;
    /**
     * Store embedding in persistent cache
     */
    protected storePersistentCache(text: string, embedding: Float32Array): Promise<void>;
    protected emitEvent(event: EmbeddingEvent): void;
    addEventListener(listener: EmbeddingEventListener): void;
    removeEventListener(listener: EmbeddingEventListener): void;
    clearCache(): void;
    getCacheStats(): {
        size: number;
        maxSize: number;
        hitRate: number;
    };
    shutdown(): Promise<void>;
}
export declare class OpenAIEmbeddingService extends BaseEmbeddingService {
    readonly provider: EmbeddingProvider;
    private readonly apiKey;
    private readonly model;
    private readonly baseURL;
    private readonly timeout;
    private readonly maxRetries;
    constructor(config: OpenAIEmbeddingConfig);
    embed(text: string): Promise<EmbeddingResult>;
    embedBatch(texts: string[]): Promise<BatchEmbeddingResult>;
    private callOpenAI;
}
export declare class TransformersEmbeddingService extends BaseEmbeddingService {
    readonly provider: EmbeddingProvider;
    private pipeline;
    private readonly modelName;
    private initialized;
    constructor(config: TransformersEmbeddingConfig);
    private initialize;
    embed(text: string): Promise<EmbeddingResult>;
    embedBatch(texts: string[]): Promise<BatchEmbeddingResult>;
}
export declare class MockEmbeddingService extends BaseEmbeddingService {
    readonly provider: EmbeddingProvider;
    private readonly dimensions;
    private readonly simulatedLatency;
    constructor(config?: Partial<MockEmbeddingConfig>);
    embed(text: string): Promise<EmbeddingResult>;
    embedBatch(texts: string[]): Promise<BatchEmbeddingResult>;
    /**
     * Generate deterministic hash-based embedding
     */
    private hashEmbedding;
}
/**
 * Agentic-Flow embedding service using OptimizedEmbedder
 *
 * Features:
 * - ONNX-based embeddings with SIMD acceleration
 * - 256-entry LRU cache with FNV-1a hash
 * - 8x loop unrolling for cosine similarity
 * - Pre-allocated buffers (no GC pressure)
 * - 3-4x faster batch processing
 */
export declare class AgenticFlowEmbeddingService extends BaseEmbeddingService {
    readonly provider: EmbeddingProvider;
    private embedder;
    private initialized;
    private readonly modelId;
    private readonly dimensions;
    private readonly embedderCacheSize;
    private readonly modelDir;
    private readonly autoDownload;
    constructor(config: AgenticFlowEmbeddingConfig);
    private initialize;
    embed(text: string): Promise<EmbeddingResult>;
    embedBatch(texts: string[]): Promise<BatchEmbeddingResult>;
    /**
     * Get combined cache statistics from both our LRU cache and embedder's internal cache
     */
    getCacheStats(): {
        size: number;
        maxSize: number;
        hitRate: number;
    } | {
        size: any;
        maxSize: any;
        hitRate: number;
        embedderCache: any;
    };
    shutdown(): Promise<void>;
}
/**
 * Create embedding service based on configuration (sync version)
 * Note: For 'auto' provider or smart fallback, use createEmbeddingServiceAsync
 */
export declare function createEmbeddingService(config: EmbeddingConfig): IEmbeddingService;
/**
 * Extended config with auto provider option
 */
export interface AutoEmbeddingConfig {
    /** Provider: 'auto' will pick best available (agentic-flow > transformers > mock) */
    provider: EmbeddingProvider | 'auto';
    /** Fallback provider if primary fails */
    fallback?: EmbeddingProvider;
    /** Auto-install agentic-flow if not available (default: true for 'auto' provider) */
    autoInstall?: boolean;
    /** Model ID for agentic-flow */
    modelId?: string;
    /** Model name for transformers */
    model?: string;
    /** Dimensions */
    dimensions?: number;
    /** Cache size */
    cacheSize?: number;
    /** OpenAI API key (required for openai provider) */
    apiKey?: string;
}
/**
 * Create embedding service with automatic provider detection and fallback
 *
 * Features:
 * - 'auto' provider picks best available: agentic-flow > transformers > mock
 * - Automatic fallback if primary provider fails to initialize
 * - Pre-validates provider availability before returning
 *
 * @example
 * // Auto-select best provider
 * const service = await createEmbeddingServiceAsync({ provider: 'auto' });
 *
 * // Try agentic-flow, fallback to transformers
 * const service = await createEmbeddingServiceAsync({
 *   provider: 'agentic-flow',
 *   fallback: 'transformers'
 * });
 */
export declare function createEmbeddingServiceAsync(config: AutoEmbeddingConfig): Promise<IEmbeddingService>;
/**
 * Convenience function for quick embeddings
 */
export declare function getEmbedding(text: string, config?: Partial<EmbeddingConfig>): Promise<Float32Array | number[]>;
/**
 * Compute cosine similarity between two embeddings
 */
export declare function cosineSimilarity(a: Float32Array | number[], b: Float32Array | number[]): number;
/**
 * Compute Euclidean distance between two embeddings
 */
export declare function euclideanDistance(a: Float32Array | number[], b: Float32Array | number[]): number;
/**
 * Compute dot product between two embeddings
 */
export declare function dotProduct(a: Float32Array | number[], b: Float32Array | number[]): number;
/**
 * Compute similarity using specified metric
 */
export declare function computeSimilarity(a: Float32Array | number[], b: Float32Array | number[], metric?: SimilarityMetric): SimilarityResult;
export {};
//# sourceMappingURL=embedding-service.d.ts.map