@directive-run/ai 0.1.1 → 0.3.0

package/dist/semantic-cache-F0psCRuz.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Semantic Caching Guardrail
+ *
+ * Caches agent responses based on semantic similarity to reduce redundant LLM calls.
+ * Uses vector embeddings to find semantically similar previous queries.
+ *
+ * @example
+ * ```typescript
+ * import { createSemanticCacheGuardrail } from '@directive-run/ai';
+ *
+ * const cacheGuardrail = createSemanticCacheGuardrail({
+ *   embedder: async (text) => {
+ *     // Use your embedding model (OpenAI, local model, etc.)
+ *     return await getEmbedding(text);
+ *   },
+ *   similarityThreshold: 0.95,
+ *   maxCacheSize: 1000,
+ *   ttlMs: 3600000, // 1 hour
+ * });
+ *
+ * const orchestrator = createAgentOrchestrator({
+ *   guardrails: {
+ *     input: [cacheGuardrail],
+ *   },
+ *   runner: run,
+ * });
+ * ```
+ */
+/** Vector embedding (array of numbers) */
+type Embedding = number[];
+/** Function to generate embeddings for text */
+type EmbedderFn = (text: string) => Promise<Embedding>;
+/** Cached response entry */
+interface CacheEntry {
+    id: string;
+    query: string;
+    queryEmbedding: Embedding;
+    response: string;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    accessedAt: number;
+    accessCount: number;
+    agentName?: string;
+}
+/** Cache lookup result */
+interface CacheLookupResult {
+    hit: boolean;
+    entry?: CacheEntry;
+    similarity?: number;
+    latencyMs: number;
+}
+/** Semantic cache configuration */
+interface SemanticCacheConfig {
+    /** Function to generate embeddings */
+    embedder: EmbedderFn;
+    /** Similarity threshold (0.0 to 1.0) for cache hits */
+    similarityThreshold?: number;
+    /** Maximum number of entries to cache */
+    maxCacheSize?: number;
+    /** Time-to-live in milliseconds for cache entries */
+    ttlMs?: number;
+    /** Cache namespace for multi-tenant scenarios */
+    namespace?: string;
+    /** Custom storage backend (defaults to in-memory) */
+    storage?: SemanticCacheStorage;
+    /** Callback when cache hit occurs */
+    onHit?: (entry: CacheEntry, similarity: number) => void;
+    /** Callback when cache miss occurs */
+    onMiss?: (query: string) => void;
+    /** Callback when cache lookup encounters an error */
+    onError?: (error: Error) => void;
+    /** Whether to include agent name in cache key */
+    perAgent?: boolean;
+}
+/** Storage interface for cache backends */
+interface SemanticCacheStorage {
+    /** Get all entries for a namespace */
+    getEntries(namespace: string): Promise<CacheEntry[]>;
+    /** Add an entry to the cache */
+    addEntry(namespace: string, entry: CacheEntry): Promise<void>;
+    /** Update an entry (e.g., access count) */
+    updateEntry(namespace: string, id: string, updates: Partial<CacheEntry>): Promise<void>;
+    /** Remove an entry */
+    removeEntry(namespace: string, id: string): Promise<void>;
+    /** Clear all entries in a namespace */
+    clear(namespace: string): Promise<void>;
+}
+/** Semantic cache instance */
+interface SemanticCache {
+    /** Look up a query in the cache */
+    lookup(query: string, agentName?: string): Promise<CacheLookupResult>;
+    /** Store a response in the cache */
+    store(query: string, response: string, agentName?: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Invalidate cache entries matching a predicate */
+    invalidate(predicate: (entry: CacheEntry) => boolean): Promise<number>;
+    /** Clear all cache entries */
+    clear(): Promise<void>;
+    /** Get cache statistics */
+    getStats(): CacheStats;
+    /** Export cache entries (for persistence) */
+    export(): Promise<CacheEntry[]>;
+    /** Import cache entries (from persistence) */
+    import(entries: CacheEntry[]): Promise<void>;
+}
+/** Cache statistics */
+interface CacheStats {
+    totalEntries: number;
+    totalHits: number;
+    totalMisses: number;
+    hitRate: number;
+    avgSimilarityOnHit: number;
+    oldestEntry: number | null;
+    newestEntry: number | null;
+}
+/**
+ * Create an in-memory cache storage backend.
+ */
+declare function createInMemoryStorage(): SemanticCacheStorage;
+/**
+ * Create a semantic cache instance.
+ *
+ * @example
+ * ```typescript
+ * const cache = createSemanticCache({
+ *   embedder: async (text) => {
+ *     const response = await openai.embeddings.create({
+ *       model: 'text-embedding-3-small',
+ *       input: text,
+ *     });
+ *     return response.data[0].embedding;
+ *   },
+ *   similarityThreshold: 0.92,
+ *   maxCacheSize: 500,
+ *   ttlMs: 3600000, // 1 hour
+ * });
+ *
+ * // Check cache before calling agent
+ * const result = await cache.lookup(userQuery);
+ * if (result.hit) {
+ *   return result.entry!.response;
+ * }
+ *
+ * // Call agent and cache response
+ * const response = await runAgent(userQuery);
+ * await cache.store(userQuery, response);
+ * ```
+ */
+declare function createSemanticCache(config: SemanticCacheConfig): SemanticCache;
+/** Input guardrail data for semantic cache */
+interface SemanticCacheGuardrailData {
+    input: string;
+    agentName?: string;
+}
+/**
+ * Result of semantic cache guardrail.
+ *
+ * **Important semantics:**
+ * - `passed: false` + `cacheHit: true` = Short-circuit with cached response (not an error!)
+ * - `passed: true` + `cacheHit: false` = No cache hit, proceed with agent call
+ *
+ * The `passed: false` follows guardrail convention where "not passing" stops the flow,
+ * but in this case stopping is desirable (returning cached data is good).
+ */
+interface SemanticCacheGuardrailResult {
+    /**
+     * Whether to proceed with the agent call.
+     * `false` means short-circuit with cached response (this is good, not an error).
+     * `true` means no cache hit, proceed with agent.
+     */
+    passed: boolean;
+    /** Indicates whether this was a cache hit */
+    cacheHit: boolean;
+    /** Reason for the result */
+    reason?: string;
+    /** The cached response (only present on cache hit) */
+    cachedResponse?: string;
+    /** Similarity score (0-1) of the cache hit */
+    similarity?: number;
+}
+/**
+ * Create a semantic caching input guardrail.
+ *
+ * **How it works:**
+ * - On cache HIT: Returns `{ passed: false, cacheHit: true, cachedResponse: "..." }`
+ *   The orchestrator should detect `cacheHit: true` and return the cached response.
+ * - On cache MISS: Returns `{ passed: true, cacheHit: false }`
+ *   Proceed with normal agent execution.
+ *
+ * **Important:** `passed: false` with `cacheHit: true` is SUCCESS, not failure.
+ * The guardrail "short-circuits" the flow to return cached data efficiently.
+ *
+ * @example
+ * ```typescript
+ * const cacheGuardrail = createSemanticCacheGuardrail({
+ *   cache: mySemanticCache,
+ * });
+ *
+ * const orchestrator = createAgentOrchestrator({
+ *   guardrails: {
+ *     input: [
+ *       {
+ *         name: 'semantic-cache',
+ *         fn: cacheGuardrail,
+ *       },
+ *     ],
+ *   },
+ *   runner: run,
+ * });
+ *
+ * // In your orchestrator wrapper, check for cache hits:
+ * const guardrailResult = await cacheGuardrail({ input: userQuery });
+ * if (guardrailResult.cacheHit) {
+ *   return guardrailResult.cachedResponse; // Fast path!
+ * }
+ * // Otherwise proceed with agent call...
+ * ```
+ */
+declare function createSemanticCacheGuardrail(config: {
+    cache: SemanticCache;
+}): (data: SemanticCacheGuardrailData) => Promise<SemanticCacheGuardrailResult>;
+/**
+ * Create a simple hash-based "embedder" for testing.
+ * NOT suitable for production - use a real embedding model.
+ */
+declare function createTestEmbedder(dimensions?: number): EmbedderFn;
+/** Batched embedder instance with dispose capability */
+interface BatchedEmbedder {
+    /** Embed a single text (batched internally) */
+    embed: EmbedderFn;
+    /** Flush any pending batch immediately */
+    flush(): Promise<void>;
+    /** Dispose of the embedder, clearing timers and rejecting pending requests */
+    dispose(): void;
+}
+/**
+ * Create a batched embedder that groups multiple texts into single API calls.
+ *
+ * **BREAKING CHANGE:** Previously returned `EmbedderFn` directly. Now returns
+ * a `BatchedEmbedder` object with `embed`, `flush`, and `dispose` methods.
+ *
+ * To migrate: `const embed = createBatchedEmbedder(...)` becomes
+ * `const { embed } = createBatchedEmbedder(...)`.
+ *
+ * @example
+ * ```typescript
+ * const batchedEmbedder = createBatchedEmbedder({
+ *   batchSize: 20,
+ *   embedBatch: async (texts) => {
+ *     const response = await openai.embeddings.create({
+ *       model: 'text-embedding-3-small',
+ *       input: texts,
+ *     });
+ *     return response.data.map(d => d.embedding);
+ *   },
+ *   maxWaitMs: 50,
+ * });
+ *
+ * // Use the embedder
+ * const embedding = await batchedEmbedder.embed("Hello world");
+ *
+ * // Clean up when done
+ * batchedEmbedder.dispose();
+ * ```
+ */
+declare function createBatchedEmbedder(config: {
+    batchSize?: number;
+    embedBatch: (texts: string[]) => Promise<Embedding[]>;
+    maxWaitMs?: number;
+}): BatchedEmbedder;
+
+export { type BatchedEmbedder as B, type CacheEntry as C, type Embedding as E, type SemanticCache as S, type EmbedderFn as a, type CacheLookupResult as b, type CacheStats as c, type SemanticCacheConfig as d, type SemanticCacheStorage as e, createBatchedEmbedder as f, createInMemoryStorage as g, createSemanticCache as h, createSemanticCacheGuardrail as i, createTestEmbedder as j };