@lov3kaizen/agentsea-embeddings 0.5.1

package/dist/caching/index.d.mts

@@ -0,0 +1,286 @@
+import { E as EmbeddingVector, a as EmbeddingResult } from '../embedding.types-CCgPVxt1.mjs';
+
+type CacheBackendType = 'memory' | 'redis' | 'sqlite' | 'file' | 'tiered';
+interface CachedEmbedding {
+    key: string;
+    vector: EmbeddingVector;
+    text: string;
+    model: string;
+    dimensions: number;
+    tokenCount: number;
+    createdAt: number;
+    accessedAt: number;
+    accessCount: number;
+    ttl: number;
+    version?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CacheEntryInfo {
+    key: string;
+    model: string;
+    dimensions: number;
+    tokenCount: number;
+    createdAt: number;
+    accessedAt: number;
+    accessCount: number;
+    sizeBytes: number;
+}
+interface CacheOptions {
+    defaultTTL?: number;
+    maxEntries?: number;
+    maxSizeBytes?: number;
+    keyPrefix?: string;
+    compression?: boolean;
+    compressionThreshold?: number;
+}
+interface MemoryCacheOptions extends CacheOptions {
+    maxAge?: number;
+    updateAgeOnGet?: boolean;
+    staleWhileRevalidate?: number;
+}
+interface RedisCacheOptions extends CacheOptions {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    url?: string;
+    connectTimeout?: number;
+    commandTimeout?: number;
+    cluster?: boolean;
+    clusterNodes?: Array<{
+        host: string;
+        port: number;
+    }>;
+    sentinel?: {
+        master: string;
+        sentinels: Array<{
+            host: string;
+            port: number;
+        }>;
+    };
+}
+interface SQLiteCacheOptions extends CacheOptions {
+    dbPath?: string;
+    inMemory?: boolean;
+    walMode?: boolean;
+    busyTimeout?: number;
+    autoVacuum?: boolean;
+    vacuumInterval?: number;
+}
+interface TieredCacheOptions extends CacheOptions {
+    tiers: TierConfig[];
+    writeThrough?: boolean;
+    promoteOnHit?: boolean;
+}
+interface TierConfig {
+    name: string;
+    type: CacheBackendType;
+    options: CacheOptions;
+    priority: number;
+}
+interface CacheLookupResult {
+    hit: boolean;
+    entry?: CachedEmbedding;
+    tier?: string;
+    latencyMs: number;
+}
+interface BatchCacheLookupResult {
+    hits: Map<string, CachedEmbedding>;
+    misses: string[];
+    hitRate: number;
+    latencyMs: number;
+}
+interface CacheStats {
+    entries: number;
+    sizeBytes: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    gets: number;
+    sets: number;
+    deletes: number;
+    evictions: number;
+    avgGetLatencyMs: number;
+    avgSetLatencyMs: number;
+    memoryUsageBytes?: number;
+    tierStats?: Record<string, CacheStats>;
+}
+type CacheEvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'ttl' | 'random';
+interface CacheKeyOptions {
+    includeModel?: boolean;
+    includeVersion?: boolean;
+    prefix?: string;
+    hashAlgorithm?: 'md5' | 'sha1' | 'sha256' | 'xxhash';
+}
+interface CacheWarmupOptions {
+    texts: string[];
+    concurrency?: number;
+    onProgress?: (progress: {
+        completed: number;
+        total: number;
+    }) => void;
+}
+interface CacheExportFormat {
+    version: string;
+    exportedAt: number;
+    totalEntries: number;
+    entries: CachedEmbedding[];
+    metadata?: Record<string, unknown>;
+}
+interface CacheImportOptions {
+    skipExisting?: boolean;
+    updateExisting?: boolean;
+    validate?: boolean;
+    onProgress?: (progress: {
+        imported: number;
+        total: number;
+    }) => void;
+}
+interface CacheCleanupOptions {
+    removeExpired?: boolean;
+    olderThan?: number;
+    notAccessedSince?: number;
+    model?: string;
+    version?: string;
+    dryRun?: boolean;
+}
+interface CacheCleanupResult {
+    removed: number;
+    freedBytes: number;
+    durationMs: number;
+    dryRun: boolean;
+}
+
+declare abstract class BaseCache {
+    abstract readonly backendType: CacheBackendType;
+    protected options: CacheOptions;
+    protected stats: CacheStats;
+    constructor(options?: CacheOptions);
+    private createInitialStats;
+    generateKey(text: string, model: string): string;
+    abstract get(key: string): Promise<CachedEmbedding | undefined>;
+    abstract set(key: string, entry: CachedEmbedding): Promise<void>;
+    abstract has(key: string): Promise<boolean>;
+    abstract delete(key: string): Promise<boolean>;
+    abstract clear(): Promise<void>;
+    abstract size(): Promise<number>;
+    abstract keys(): Promise<string[]>;
+    abstract close(): Promise<void>;
+    lookup(key: string): Promise<CacheLookupResult>;
+    lookupBatch(keys: string[]): Promise<BatchCacheLookupResult>;
+    store(key: string, result: EmbeddingResult, model: string, ttl?: number): Promise<void>;
+    storeBatch(entries: Array<{
+        key: string;
+        result: EmbeddingResult;
+        model: string;
+    }>, ttl?: number): Promise<void>;
+    getStats(): CacheStats;
+    resetStats(): void;
+    protected updateHitRate(): void;
+    cleanup(options?: CacheCleanupOptions): Promise<CacheCleanupResult>;
+    export(): Promise<CacheExportFormat>;
+    import(data: CacheExportFormat, options?: CacheImportOptions): Promise<{
+        imported: number;
+        skipped: number;
+    }>;
+    protected estimateEntrySize(entry: CachedEmbedding): number;
+}
+
+declare class MemoryCache extends BaseCache {
+    readonly backendType: CacheBackendType;
+    private cache;
+    constructor(options?: MemoryCacheOptions);
+    get(key: string): Promise<CachedEmbedding | undefined>;
+    set(key: string, entry: CachedEmbedding): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    close(): Promise<void>;
+    getMemoryInfo(): {
+        entries: number;
+        calculatedSize: number;
+        maxSize: number;
+    };
+    prune(): void;
+}
+declare function createMemoryCache(options?: MemoryCacheOptions): MemoryCache;
+
+declare class RedisCache extends BaseCache {
+    readonly backendType: CacheBackendType;
+    private client;
+    private config;
+    private connected;
+    constructor(options: RedisCacheOptions);
+    connect(): Promise<void>;
+    private ensureConnected;
+    get(key: string): Promise<CachedEmbedding | undefined>;
+    set(key: string, entry: CachedEmbedding): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    close(): Promise<void>;
+    private prefixKey;
+    isConnected(): boolean;
+}
+declare function createRedisCache(options: RedisCacheOptions): RedisCache;
+
+declare class SQLiteCache extends BaseCache {
+    readonly backendType: CacheBackendType;
+    private db;
+    private config;
+    private initialized;
+    private vacuumCounter;
+    constructor(options?: SQLiteCacheOptions);
+    init(): Promise<void>;
+    private ensureInitialized;
+    get(key: string): Promise<CachedEmbedding | undefined>;
+    set(key: string, entry: CachedEmbedding): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    close(): Promise<void>;
+    private maybeVacuum;
+    vacuum(): Promise<void>;
+    removeExpired(): Promise<number>;
+}
+declare function createSQLiteCache(options?: SQLiteCacheOptions): SQLiteCache;
+
+declare class TieredCache extends BaseCache {
+    readonly backendType: CacheBackendType;
+    private tiers;
+    private writeThrough;
+    private promoteOnHit;
+    constructor(options: TieredCacheOptions);
+    private initializeTiers;
+    init(): Promise<void>;
+    get(key: string): Promise<CachedEmbedding | undefined>;
+    set(key: string, entry: CachedEmbedding): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    close(): Promise<void>;
+    lookup(key: string): Promise<CacheLookupResult>;
+    getTierStats(): Record<string, CacheStats>;
+    getTier(name: string): BaseCache | undefined;
+    getTierNames(): string[];
+    getStats(): CacheStats;
+}
+declare function createTieredCache(options: TieredCacheOptions): TieredCache;
+declare function createStandardTieredCache(options?: {
+    memoryMaxEntries?: number;
+    persistentPath?: string;
+    useRedis?: boolean;
+    redisUrl?: string;
+}): TieredCache;
+
+declare function createCache(type: CacheBackendType, options?: CacheOptions): BaseCache;
+
+export { BaseCache, type BatchCacheLookupResult, type CacheBackendType, type CacheCleanupOptions, type CacheCleanupResult, type CacheEntryInfo, type CacheEvictionPolicy, type CacheExportFormat, type CacheImportOptions, type CacheKeyOptions, type CacheLookupResult, type CacheOptions, type CacheStats, type CacheWarmupOptions, type CachedEmbedding, MemoryCache, type MemoryCacheOptions, RedisCache, type RedisCacheOptions, SQLiteCache, type SQLiteCacheOptions, type TierConfig, TieredCache, type TieredCacheOptions, createCache, createMemoryCache, createRedisCache, createSQLiteCache, createStandardTieredCache, createTieredCache };

package/dist/caching/index.d.ts

@@ -0,0 +1,286 @@
+import { E as EmbeddingVector, a as EmbeddingResult } from '../embedding.types-CCgPVxt1.js';
+
+type CacheBackendType = 'memory' | 'redis' | 'sqlite' | 'file' | 'tiered';
+interface CachedEmbedding {
+    key: string;
+    vector: EmbeddingVector;
+    text: string;
+    model: string;
+    dimensions: number;
+    tokenCount: number;
+    createdAt: number;
+    accessedAt: number;
+    accessCount: number;
+    ttl: number;
+    version?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CacheEntryInfo {
+    key: string;
+    model: string;
+    dimensions: number;
+    tokenCount: number;
+    createdAt: number;
+    accessedAt: number;
+    accessCount: number;
+    sizeBytes: number;
+}
+interface CacheOptions {
+    defaultTTL?: number;
+    maxEntries?: number;
+    maxSizeBytes?: number;
+    keyPrefix?: string;
+    compression?: boolean;
+    compressionThreshold?: number;
+}
+interface MemoryCacheOptions extends CacheOptions {
+    maxAge?: number;
+    updateAgeOnGet?: boolean;
+    staleWhileRevalidate?: number;
+}
+interface RedisCacheOptions extends CacheOptions {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    url?: string;
+    connectTimeout?: number;
+    commandTimeout?: number;
+    cluster?: boolean;
+    clusterNodes?: Array<{
+        host: string;
+        port: number;
+    }>;
+    sentinel?: {
+        master: string;
+        sentinels: Array<{
+            host: string;
+            port: number;
+        }>;
+    };
+}
+interface SQLiteCacheOptions extends CacheOptions {
+    dbPath?: string;
+    inMemory?: boolean;
+    walMode?: boolean;
+    busyTimeout?: number;
+    autoVacuum?: boolean;
+    vacuumInterval?: number;
+}
+interface TieredCacheOptions extends CacheOptions {
+    tiers: TierConfig[];
+    writeThrough?: boolean;
+    promoteOnHit?: boolean;
+}
+interface TierConfig {
+    name: string;
+    type: CacheBackendType;
+    options: CacheOptions;
+    priority: number;
+}
+interface CacheLookupResult {
+    hit: boolean;
+    entry?: CachedEmbedding;
+    tier?: string;
+    latencyMs: number;
+}
+interface BatchCacheLookupResult {
+    hits: Map<string, CachedEmbedding>;
+    misses: string[];
+    hitRate: number;
+    latencyMs: number;
+}
+interface CacheStats {
+    entries: number;
+    sizeBytes: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    gets: number;
+    sets: number;
+    deletes: number;
+    evictions: number;
+    avgGetLatencyMs: number;
+    avgSetLatencyMs: number;
+    memoryUsageBytes?: number;
+    tierStats?: Record<string, CacheStats>;
+}
+type CacheEvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'ttl' | 'random';
+interface CacheKeyOptions {
+    includeModel?: boolean;
+    includeVersion?: boolean;
+    prefix?: string;
+    hashAlgorithm?: 'md5' | 'sha1' | 'sha256' | 'xxhash';
+}
+interface CacheWarmupOptions {
+    texts: string[];
+    concurrency?: number;
+    onProgress?: (progress: {
+        completed: number;
+        total: number;
+    }) => void;
+}
+interface CacheExportFormat {
+    version: string;
+    exportedAt: number;
+    totalEntries: number;
+    entries: CachedEmbedding[];
+    metadata?: Record<string, unknown>;
+}
+interface CacheImportOptions {
+    skipExisting?: boolean;
+    updateExisting?: boolean;
+    validate?: boolean;
+    onProgress?: (progress: {
+        imported: number;
+        total: number;
+    }) => void;
+}
+interface CacheCleanupOptions {
+    removeExpired?: boolean;
+    olderThan?: number;
+    notAccessedSince?: number;
+    model?: string;
+    version?: string;
+    dryRun?: boolean;
+}
+interface CacheCleanupResult {
+    removed: number;
+    freedBytes: number;
+    durationMs: number;
+    dryRun: boolean;
+}
+
+declare abstract class BaseCache {
+    abstract readonly backendType: CacheBackendType;
+    protected options: CacheOptions;
+    protected stats: CacheStats;
+    constructor(options?: CacheOptions);
+    private createInitialStats;
+    generateKey(text: string, model: string): string;
+    abstract get(key: string): Promise<CachedEmbedding | undefined>;
+    abstract set(key: string, entry: CachedEmbedding): Promise<void>;
+    abstract has(key: string): Promise<boolean>;
+    abstract delete(key: string): Promise<boolean>;
+    abstract clear(): Promise<void>;
+    abstract size(): Promise<number>;
+    abstract keys(): Promise<string[]>;
+    abstract close(): Promise<void>;
+    lookup(key: string): Promise<CacheLookupResult>;
+    lookupBatch(keys: string[]): Promise<BatchCacheLookupResult>;
+    store(key: string, result: EmbeddingResult, model: string, ttl?: number): Promise<void>;
+    storeBatch(entries: Array<{
+        key: string;
+        result: EmbeddingResult;
+        model: string;
+    }>, ttl?: number): Promise<void>;
+    getStats(): CacheStats;
+    resetStats(): void;
+    protected updateHitRate(): void;
+    cleanup(options?: CacheCleanupOptions): Promise<CacheCleanupResult>;
+    export(): Promise<CacheExportFormat>;
+    import(data: CacheExportFormat, options?: CacheImportOptions): Promise<{
+        imported: number;
+        skipped: number;
+    }>;
+    protected estimateEntrySize(entry: CachedEmbedding): number;
+}
+
+declare class MemoryCache extends BaseCache {
+    readonly backendType: CacheBackendType;
+    private cache;
+    constructor(options?: MemoryCacheOptions);
+    get(key: string): Promise<CachedEmbedding | undefined>;
+    set(key: string, entry: CachedEmbedding): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    close(): Promise<void>;
+    getMemoryInfo(): {
+        entries: number;
+        calculatedSize: number;
+        maxSize: number;
+    };
+    prune(): void;
+}
+declare function createMemoryCache(options?: MemoryCacheOptions): MemoryCache;
+
+declare class RedisCache extends BaseCache {
+    readonly backendType: CacheBackendType;
+    private client;
+    private config;
+    private connected;
+    constructor(options: RedisCacheOptions);
+    connect(): Promise<void>;
+    private ensureConnected;
+    get(key: string): Promise<CachedEmbedding | undefined>;
+    set(key: string, entry: CachedEmbedding): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    close(): Promise<void>;
+    private prefixKey;
+    isConnected(): boolean;
+}
+declare function createRedisCache(options: RedisCacheOptions): RedisCache;
+
+declare class SQLiteCache extends BaseCache {
+    readonly backendType: CacheBackendType;
+    private db;
+    private config;
+    private initialized;
+    private vacuumCounter;
+    constructor(options?: SQLiteCacheOptions);
+    init(): Promise<void>;
+    private ensureInitialized;
+    get(key: string): Promise<CachedEmbedding | undefined>;
+    set(key: string, entry: CachedEmbedding): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    close(): Promise<void>;
+    private maybeVacuum;
+    vacuum(): Promise<void>;
+    removeExpired(): Promise<number>;
+}
+declare function createSQLiteCache(options?: SQLiteCacheOptions): SQLiteCache;
+
+declare class TieredCache extends BaseCache {
+    readonly backendType: CacheBackendType;
+    private tiers;
+    private writeThrough;
+    private promoteOnHit;
+    constructor(options: TieredCacheOptions);
+    private initializeTiers;
+    init(): Promise<void>;
+    get(key: string): Promise<CachedEmbedding | undefined>;
+    set(key: string, entry: CachedEmbedding): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    close(): Promise<void>;
+    lookup(key: string): Promise<CacheLookupResult>;
+    getTierStats(): Record<string, CacheStats>;
+    getTier(name: string): BaseCache | undefined;
+    getTierNames(): string[];
+    getStats(): CacheStats;
+}
+declare function createTieredCache(options: TieredCacheOptions): TieredCache;
+declare function createStandardTieredCache(options?: {
+    memoryMaxEntries?: number;
+    persistentPath?: string;
+    useRedis?: boolean;
+    redisUrl?: string;
+}): TieredCache;
+
+declare function createCache(type: CacheBackendType, options?: CacheOptions): BaseCache;
+
+export { BaseCache, type BatchCacheLookupResult, type CacheBackendType, type CacheCleanupOptions, type CacheCleanupResult, type CacheEntryInfo, type CacheEvictionPolicy, type CacheExportFormat, type CacheImportOptions, type CacheKeyOptions, type CacheLookupResult, type CacheOptions, type CacheStats, type CacheWarmupOptions, type CachedEmbedding, MemoryCache, type MemoryCacheOptions, RedisCache, type RedisCacheOptions, SQLiteCache, type SQLiteCacheOptions, type TierConfig, TieredCache, type TieredCacheOptions, createCache, createMemoryCache, createRedisCache, createSQLiteCache, createStandardTieredCache, createTieredCache };