@lov3kaizen/agentsea-cache 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 lovekaizen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# @lov3kaizen/agentsea-cache
+
+Semantic caching layer for LLM responses. Reduces LLM costs by 30-50% through intelligent caching using exact match and semantic similarity.
+
+## Features
+
+- **Exact Match Caching** - Hash-based caching for identical requests
+- **Semantic Matching** - Embedding-based similarity for semantically similar queries
+- **Multiple Backends** - Memory, Redis, SQLite, Pinecone support
+- **Cost Analytics** - Track tokens saved and cost reduction
+- **Streaming Support** - Cache and replay streaming LLM responses
+- **Multi-Tier Caching** - L1/L2/L3 cache hierarchy with promotion
+- **AgentSea Integration** - CachedProvider and CacheMiddleware for agents
+- **Gateway Integration** - Cache layer for LLM Gateway routing
+
+## Installation
+
+```bash
+pnpm add @lov3kaizen/agentsea-cache
+```
+
+For semantic matching, also install:
+
+```bash
+pnpm add @lov3kaizen/agentsea-embeddings
+```
+
+## Quick Start
+
+### Basic Exact Match Caching
+
+```typescript
+import {
+  SemanticCache,
+  MemoryCacheStore,
+  ExactMatchStrategy,
+} from '@lov3kaizen/agentsea-cache';
+
+// Create cache with memory store and exact matching
+const cache = new SemanticCache(
+  {
+    defaultTTL: 3600, // 1 hour
+    matchStrategy: 'exact',
+  },
+  new MemoryCacheStore({ type: 'memory', maxEntries: 10000 }),
+  new ExactMatchStrategy(),
+);
+
+// Wrap your LLM call
+const response = await cache.wrap(
+  {
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: 'What is the capital of France?' }],
+  },
+  async (request) => {
+    // Your LLM call here
+    return await openai.chat.completions.create(request);
+  },
+);
+
+console.log('Cached:', response._cache?.hit);
+```
+
+### Semantic Matching (with Embeddings Package)
+
+```typescript
+import {
+  SemanticCache,
+  MemoryCacheStore,
+  HybridMatchStrategy,
+  SimilarityEngine,
+} from '@lov3kaizen/agentsea-cache';
+import { OpenAIProvider } from '@lov3kaizen/agentsea-embeddings';
+
+// Create embedding provider
+const embeddingProvider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'text-embedding-3-small',
+});
+
+// Create similarity engine
+const similarity = new SimilarityEngine({
+  provider: embeddingProvider,
+  cacheEmbeddings: true,
+});
+
+// Create cache with semantic matching
+const cache = new SemanticCache(
+  {
+    defaultTTL: 3600,
+    similarityThreshold: 0.92, // 92% similarity required
+    matchStrategy: 'hybrid', // Try exact first, then semantic
+  },
+  new MemoryCacheStore({ type: 'memory' }),
+  new HybridMatchStrategy(),
+  similarity,
+);
+
+// Similar queries will hit cache
+const response1 = await cache.wrap(
+  {
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: 'What is the capital of France?' }],
+  },
+  llmCall,
+);
+
+// This will hit cache due to semantic similarity!
+const response2 = await cache.wrap(
+  {
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: "What's France's capital city?" }],
+  },
+  llmCall,
+);
+
+console.log('Second call cached:', response2._cache?.hit); // true
+console.log('Similarity:', response2._cache?.similarity); // ~0.95
+```
+
+## Configuration
+
+### SemanticCacheConfig
+
+| Option                | Type    | Default   | Description                                      |
+| --------------------- | ------- | --------- | ------------------------------------------------ |
+| `defaultTTL`          | number  | 3600      | Default TTL in seconds (0 = no expiry)           |
+| `similarityThreshold` | number  | 0.92      | Similarity threshold for semantic matching (0-1) |
+| `maxEntries`          | number  | 10000     | Maximum cache entries                            |
+| `matchStrategy`       | string  | 'hybrid'  | 'exact', 'semantic', or 'hybrid'                 |
+| `namespace`           | string  | 'default' | Namespace for multi-tenant isolation             |
+| `analyticsEnabled`    | boolean | true      | Enable analytics tracking                        |
+
+### Store Options
+
+#### MemoryStoreConfig
+
+```typescript
+{
+  type: 'memory',
+  maxEntries: 10000,
+  maxSizeBytes: 1024 * 1024 * 1024, // 1GB
+  evictionPolicy: 'lru'
+}
+```
+
+#### RedisStoreConfig
+
+```typescript
+{
+  type: 'redis',
+  url: 'redis://localhost:6379',
+  keyPrefix: 'llm-cache'
+}
+```
+
+#### PineconeStoreConfig
+
+```typescript
+{
+  type: 'pinecone',
+  apiKey: process.env.PINECONE_API_KEY,
+  index: 'llm-cache',
+  namespace: 'production'
+}
+```
+
+#### TieredStoreConfig
+
+```typescript
+{
+  type: 'tiered',
+  tiers: [
+    { name: 'l1-memory', priority: 1, store: memoryStore, ttl: 300 },
+    { name: 'l2-redis', priority: 2, store: redisStore, ttl: 3600 }
+  ],
+  writeThrough: true,
+  promoteOnHit: true
+}
+```
+
+## Analytics
+
+Track cache performance and cost savings:
+
+```typescript
+// Get statistics
+const stats = cache.getStats();
+console.log(`Hit Rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+console.log(`Tokens Saved: ${stats.tokensSaved.toLocaleString()}`);
+console.log(`Cost Savings: $${stats.costSavingsUSD.toFixed(2)}`);
+
+// Get detailed analytics
+const analytics = cache.getAnalytics();
+const report = analytics.getCostSavingsReport();
+console.log(`Reduction: ${report.reductionPercent.toFixed(1)}%`);
+```
+
+## API Reference
+
+### SemanticCache
+
+```typescript
+class SemanticCache {
+  // Wrap an LLM call with caching
+  wrap<T>(request, fn, options?): Promise<T>;
+
+  // Direct cache operations
+  get(request, options?): Promise<CacheLookupResult>;
+  set(request, response, options?): Promise<void>;
+  delete(key): Promise<boolean>;
+  clear(): Promise<void>;
+
+  // Invalidation
+  invalidateByPattern(pattern): Promise<number>;
+  invalidateByTags(tags): Promise<number>;
+
+  // Analytics
+  getStats(): CacheStats;
+  getAnalytics(): CacheAnalytics;
+
+  // Health
+  checkHealth(): Promise<StoreHealth>;
+  close(): Promise<void>;
+}
+```
+
+### WrapOptions
+
+```typescript
+interface WrapOptions {
+  ttl?: number; // Custom TTL
+  tags?: string[]; // Tags for grouping
+  namespace?: string; // Namespace override
+  skipCache?: boolean; // Bypass cache
+  forceRefresh?: boolean; // Force update
+}
+```
+
+## Streaming Cache
+
+Cache and replay streaming LLM responses:
+
+```typescript
+import { StreamCache, MemoryCacheStore } from '@lov3kaizen/agentsea-cache';
+
+const streamCache = new StreamCache(store, {
+  minLengthToCache: 50,
+  cacheIncomplete: false,
+  streamTtl: 3600,
+});
+
+// Wrap streaming calls
+const stream = streamCache.wrapStream('gpt-4o', messages, async function* () {
+  for await (const chunk of llm.stream(request)) {
+    yield chunk;
+  }
+});
+
+// Cached streams are replayed transparently
+for await (const chunk of stream) {
+  process.stdout.write(chunk.content);
+}
+```
+
+## AgentSea Integration
+
+### CachedProvider
+
+Wrap any LLM provider with caching:
+
+```typescript
+import { CachedProvider } from '@lov3kaizen/agentsea-cache';
+
+const cachedProvider = new CachedProvider({
+  provider: anthropicProvider,
+  cache: semanticCache,
+  skipModels: ['gpt-4-vision'], // Don't cache vision models
+});
+
+// Uses cache transparently
+const response = await cachedProvider.complete({
+  model: 'claude-sonnet-4-20250514',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+```
+
+### CacheMiddleware
+
+Add caching to agent pipelines:
+
+```typescript
+import { CacheMiddleware } from '@lov3kaizen/agentsea-cache';
+
+const middleware = new CacheMiddleware({
+  cache: semanticCache,
+  skipToolRequests: true, // Don't cache tool-using requests
+  defaultTTL: 1800,
+});
+
+const response = await middleware.handle(request, next);
+```
+
+## Examples
+
+See the `examples/` directory for complete examples:
+
+- `basic-cache.ts` - Exact match caching
+- `semantic-similarity.ts` - Semantic matching with embeddings
+- `streaming-cache.ts` - Caching streaming responses
+- `multi-tier.ts` - Multi-tier cache hierarchy
+- `agentsea-integration.ts` - AgentSea CachedProvider and Middleware
+
+## Roadmap
+
+- [x] Phase 1: Core cache with exact matching
+- [x] Phase 2: Semantic matching with embeddings
+- [x] Phase 3: Streaming cache, multi-tier, invalidation
+- [x] Phase 4: AgentSea and Gateway integrations
+
+## License
+
+MIT

package/dist/BaseMatchStrategy-1E1SHaUt.d.ts

@@ -0,0 +1,60 @@
+import { C as CacheMessage, a as CacheLookupResult, b as CacheEntry } from './cache.types-DMuyQseO.js';
+import { B as BaseCacheStore } from './store.types-BQy5Yyz9.js';
+import { S as SimilarityEngine } from './SimilarityEngine-Cwv_mF9a.js';
+
+type MatchStrategyType = 'exact' | 'semantic' | 'hybrid' | 'fuzzy';
+interface MatchOptions {
+    threshold?: number;
+    namespace?: string;
+    topK?: number;
+    matchModel?: boolean;
+}
+interface MatchRequest {
+    model: string;
+    messages: CacheMessage[];
+    temperature?: number;
+    systemPrompt?: string;
+}
+interface MatchResult extends CacheLookupResult {
+    strategy: MatchStrategyType;
+    candidates?: Array<{
+        entry: CacheEntry;
+        score: number;
+        reason: string;
+    }>;
+}
+interface ExactMatchConfig {
+    normalizeWhitespace?: boolean;
+    hashFields?: Array<'model' | 'messages' | 'temperature' | 'systemPrompt'>;
+}
+interface SemanticMatchConfig {
+    threshold?: number;
+    matchModel?: boolean;
+    topK?: number;
+}
+interface HybridMatchConfig {
+    exact?: ExactMatchConfig;
+    semantic?: SemanticMatchConfig;
+    semanticPatterns?: RegExp[];
+    exactOnlyPatterns?: RegExp[];
+}
+interface FuzzyMatchConfig {
+    minSimilarity?: number;
+    maxDistance?: number;
+}
+interface ThresholdConfig {
+    base: number;
+    contextThresholds?: Record<string, number>;
+    autoAdjust?: boolean;
+    min?: number;
+    max?: number;
+}
+type ContextType = 'code' | 'chat' | 'analysis' | 'creative' | 'default';
+type ContextDetector = (request: MatchRequest) => ContextType;
+
+declare abstract class BaseMatchStrategy {
+    abstract readonly name: MatchStrategyType;
+    abstract match(request: MatchRequest, store: BaseCacheStore, similarity?: SimilarityEngine, options?: MatchOptions): Promise<CacheLookupResult>;
+}
+
+export { BaseMatchStrategy as B, type ContextType as C, type ExactMatchConfig as E, type FuzzyMatchConfig as F, type HybridMatchConfig as H, type MatchStrategyType as M, type SemanticMatchConfig as S, type ThresholdConfig as T, type MatchOptions as a, type MatchRequest as b, type MatchResult as c, type ContextDetector as d };

package/dist/SemanticCache-vysguwUQ.d.ts

@@ -0,0 +1,65 @@
+import { EventEmitter } from 'eventemitter3';
+import { b as CacheEntry, S as SemanticCacheConfig, C as CacheMessage, W as WrapOptions, a as CacheLookupResult, c as CacheStats } from './cache.types-DMuyQseO.js';
+import { B as BaseCacheStore, S as StoreHealth } from './store.types-BQy5Yyz9.js';
+import { B as BaseMatchStrategy } from './BaseMatchStrategy-1E1SHaUt.js';
+import { S as SimilarityEngine } from './SimilarityEngine-Cwv_mF9a.js';
+import { CacheAnalytics } from './analytics/index.js';
+
+interface SemanticCacheEvents {
+    hit: (entry: CacheEntry, similarity: number) => void;
+    miss: (key: string, reason: string) => void;
+    set: (entry: CacheEntry) => void;
+    delete: (key: string) => void;
+    evict: (entry: CacheEntry, reason: string) => void;
+    error: (error: Error, context: string) => void;
+}
+interface CacheRequest {
+    model: string;
+    messages: CacheMessage[];
+    temperature?: number;
+    maxTokens?: number;
+    tools?: unknown[];
+}
+interface CacheResponseInput {
+    content: string;
+    model?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    finishReason?: string;
+    toolCalls?: unknown[];
+}
+declare class SemanticCache extends EventEmitter<SemanticCacheEvents> {
+    private readonly config;
+    private readonly store;
+    private readonly strategy;
+    private readonly similarity?;
+    private readonly analytics;
+    private stats;
+    constructor(config: Partial<SemanticCacheConfig>, store: BaseCacheStore, strategy: BaseMatchStrategy, similarity?: SimilarityEngine);
+    private createInitialStats;
+    wrap<T extends CacheResponseInput>(request: CacheRequest, fn: (req: CacheRequest) => Promise<T>, options?: WrapOptions): Promise<T & {
+        _cache?: {
+            hit: boolean;
+            similarity?: number;
+        };
+    }>;
+    get(request: CacheRequest, options?: WrapOptions): Promise<CacheLookupResult>;
+    set(request: CacheRequest, response: CacheResponseInput, options?: WrapOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    invalidateByPattern(pattern: RegExp): Promise<number>;
+    invalidateByTags(tags: string[]): Promise<number>;
+    getStats(): CacheStats;
+    getAnalytics(): CacheAnalytics;
+    getConfig(): Readonly<SemanticCacheConfig>;
+    checkHealth(): Promise<StoreHealth>;
+    close(): Promise<void>;
+    private updateStats;
+    private updateHitRate;
+}
+declare function createSemanticCache(config: Partial<SemanticCacheConfig>, store: BaseCacheStore, strategy: BaseMatchStrategy, similarity?: SimilarityEngine): SemanticCache;
+
+export { type CacheRequest as C, SemanticCache as S, type SemanticCacheEvents as a, type CacheResponseInput as b, createSemanticCache as c };

package/dist/SimilarityEngine-Cwv_mF9a.d.ts

@@ -0,0 +1,41 @@
+interface EmbeddingProvider {
+    embed(text: string): Promise<number[]>;
+    embedBatch?(texts: string[]): Promise<number[][]>;
+    readonly dimensions?: number;
+}
+type SimilarityMetric = 'cosine' | 'euclidean' | 'dot_product';
+interface SimilarityEngineConfig {
+    provider: EmbeddingProvider;
+    metric?: SimilarityMetric;
+    cacheEmbeddings?: boolean;
+    maxCacheSize?: number;
+}
+declare class SimilarityEngine {
+    private provider;
+    private metric;
+    private embeddingCache?;
+    private maxCacheSize;
+    constructor(config: SimilarityEngineConfig);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    computeSimilarity(a: number[], b: number[]): number;
+    findMostSimilar(query: number[], candidates: Array<{
+        id: string;
+        vector: number[];
+    }>, minSimilarity?: number): Array<{
+        id: string;
+        similarity: number;
+    }>;
+    get dimensions(): number;
+    clearCache(): void;
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    } | null;
+    private cosineSimilarity;
+    private euclideanDistance;
+    private dotProduct;
+}
+declare function createSimilarityEngine(config: SimilarityEngineConfig): SimilarityEngine;
+
+export { type EmbeddingProvider as E, SimilarityEngine as S, type SimilarityMetric as a, type SimilarityEngineConfig as b, createSimilarityEngine as c };

package/dist/analytics/index.d.ts

@@ -0,0 +1,123 @@
+import { b as CacheEntry } from '../cache.types-DMuyQseO.js';
+
+interface AnalyticsData {
+    totalHits: number;
+    totalMisses: number;
+    exactHits: number;
+    semanticHits: number;
+    hitRate: number;
+    avgLatencyMs: number;
+    p50LatencyMs: number;
+    p95LatencyMs: number;
+    p99LatencyMs: number;
+    totalTokensSaved: number;
+    estimatedCostSavingsUSD: number;
+    topModels: Array<{
+        model: string;
+        hits: number;
+    }>;
+    topNamespaces: Array<{
+        namespace: string;
+        hits: number;
+    }>;
+    hourlyStats: Array<{
+        hour: number;
+        hits: number;
+        misses: number;
+        avgLatencyMs: number;
+    }>;
+}
+interface CostSavingsReport {
+    period: string;
+    totalRequests: number;
+    cachedRequests: number;
+    hitRate: number;
+    inputTokensSaved: number;
+    outputTokensSaved: number;
+    totalTokensSaved: number;
+    estimatedCostWithoutCache: number;
+    actualCostWithCache: number;
+    costSaved: number;
+    reductionPercent: number;
+}
+interface ModelPricing {
+    inputPer1K: number;
+    outputPer1K: number;
+}
+interface PerformanceMetrics {
+    avgLookupMs: number;
+    avgEmbeddingMs: number;
+    avgStoreReadMs: number;
+    avgStoreWriteMs: number;
+    p50LatencyMs: number;
+    p95LatencyMs: number;
+    p99LatencyMs: number;
+    totalOperations: number;
+    failedOperations: number;
+    errorRate: number;
+}
+interface HitEvent {
+    timestamp: number;
+    type: 'exact' | 'semantic';
+    model: string;
+    namespace?: string;
+    similarity?: number;
+    latencyMs: number;
+    tokensSaved: number;
+}
+interface MissEvent {
+    timestamp: number;
+    model: string;
+    namespace?: string;
+    latencyMs: number;
+    reason: 'not_found' | 'below_threshold' | 'expired' | 'error';
+}
+interface AnalyticsQueryOptions {
+    startTime?: number;
+    endTime?: number;
+    model?: string;
+    namespace?: string;
+    groupBy?: 'model' | 'namespace' | 'hour' | 'day';
+}
+type AnalyticsExportFormat = 'json' | 'csv' | 'prometheus';
+interface AnalyticsConfig {
+    enabled?: boolean;
+    sampleRate?: number;
+    retentionSeconds?: number;
+    flushIntervalMs?: number;
+    modelPricing?: Record<string, ModelPricing>;
+}
+
+declare class CacheAnalytics {
+    private config;
+    private hits;
+    private misses;
+    private exactHits;
+    private semanticHits;
+    private tokensSaved;
+    private inputTokensSaved;
+    private outputTokensSaved;
+    private latencies;
+    private modelHits;
+    private namespaceHits;
+    private hitEvents;
+    private missEvents;
+    private setCount;
+    constructor(config?: Partial<AnalyticsConfig>);
+    recordHit(entry: CacheEntry, type: 'exact' | 'semantic', latencyMs: number): void;
+    recordMiss(latencyMs: number, reason?: MissEvent['reason']): void;
+    recordSet(_entry: CacheEntry): void;
+    getSummary(): AnalyticsData;
+    getCostSavingsReport(periodLabel?: string): CostSavingsReport;
+    getPerformanceMetrics(): PerformanceMetrics;
+    reset(): void;
+    export(format?: 'json' | 'csv'): string;
+    private calculateCostSavings;
+    private getTopModels;
+    private getTopNamespaces;
+    private getHourlyStats;
+    private trimEvents;
+}
+declare function createCacheAnalytics(config?: Partial<AnalyticsConfig>): CacheAnalytics;
+
+export { type AnalyticsConfig, type AnalyticsData, type AnalyticsExportFormat, type AnalyticsQueryOptions, CacheAnalytics, type CostSavingsReport, type HitEvent, type MissEvent, type ModelPricing, type PerformanceMetrics, createCacheAnalytics };