agentic-qe 1.7.0 → 1.8.0

package/dist/utils/prompt-cache.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Prompt Caching Infrastructure (CO-1)
+ *
+ * Implements Anthropic's prompt caching with proper cache key management and invalidation.
+ *
+ * IMPORTANT: Anthropic caching requirements:
+ * 1. Minimum 1024 tokens per cached block
+ * 2. Cache control on LAST 3 blocks only
+ * 3. 5-minute automatic TTL
+ *
+ * Cost model:
+ * - Cache write: 25% premium on input tokens
+ * - Cache hit: 90% discount on cached tokens
+ * - Regular tokens: Standard $3.00 per 1M input tokens
+ *
+ * @module utils/prompt-cache
+ */
+import Anthropic from '@anthropic-ai/sdk';
+/**
+ * Content that can be cached with TTL and priority
+ */
+export interface CacheableContent {
+    /** Text content to cache */
+    text: string;
+    /** Time-to-live in milliseconds (optional, defaults to 5 minutes) */
+    ttl?: number;
+    /** Priority hint for cache management */
+    priority?: 'high' | 'medium' | 'low';
+}
+/**
+ * Cache performance statistics
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of cache writes */
+    writes: number;
+    /** Hit rate as percentage (0-1) */
+    hitRate: number;
+    /** Total cost savings in dollars */
+    costSavings: number;
+    /** Total tokens written to cache */
+    tokensWritten: number;
+    /** Total tokens read from cache */
+    tokensRead: number;
+    /** Total regular input tokens */
+    tokensRegular: number;
+}
+/**
+ * PromptCacheManager
+ *
+ * Manages Anthropic prompt caching with content-addressable cache keys,
+ * TTL-based invalidation, and cost accounting.
+ *
+ * Features:
+ * - SHA-256 based cache keys for content addressability
+ * - 5-minute TTL with automatic pruning
+ * - Cost tracking for cache writes (25% premium) vs hits (90% discount)
+ * - Statistics for cache hit rate and cost savings
+ * - Support for up to 3 cached blocks per request
+ *
+ * @example
+ * ```typescript
+ * const cacheManager = new PromptCacheManager(process.env.ANTHROPIC_API_KEY!);
+ *
+ * const response = await cacheManager.createWithCache({
+ *   model: 'claude-sonnet-4',
+ *   systemPrompts: [
+ *     { text: AGENT_SYSTEM_PROMPT, priority: 'high' },
+ *   ],
+ *   projectContext: [
+ *     { text: JSON.stringify(projectStructure), priority: 'medium' },
+ *   ],
+ *   messages: [
+ *     { role: 'user', content: 'Generate tests for this code...' },
+ *   ],
+ * });
+ *
+ * const stats = cacheManager.getStats();
+ * console.log(`Cache hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+ * console.log(`Cost savings: $${stats.costSavings.toFixed(4)}`);
+ * ```
+ */
+export declare class PromptCacheManager {
+    private anthropic;
+    private cacheKeys;
+    private stats;
+    /** Cache TTL in milliseconds (5 minutes as per Anthropic specs) */
+    private readonly CACHE_TTL;
+    /** Minimum tokens required for caching */
+    private readonly MIN_CACHE_TOKENS;
+    /** Cost per million tokens */
+    private readonly COST_PER_MILLION;
+    /** Cache write premium (25%) */
+    private readonly CACHE_WRITE_PREMIUM;
+    /** Cache read discount (90%) */
+    private readonly CACHE_READ_DISCOUNT;
+    /**
+     * Create a new PromptCacheManager
+     *
+     * @param apiKey - Anthropic API key
+     */
+    constructor(apiKey: string);
+    /**
+     * Create message with cached content
+     *
+     * IMPORTANT: Anthropic caching requires:
+     * 1. Minimum 1024 tokens per cached block
+     * 2. Cache control on LAST 3 blocks only
+     * 3. 5-minute TTL (automatic)
+     *
+     * This method automatically:
+     * - Checks content size before caching (must be >= 1024 tokens)
+     * - Adds cache control to last 3 blocks
+     * - Tracks cache hits/misses via content hashing
+     * - Updates cost statistics
+     *
+     * @param params - Message parameters with cacheable content
+     * @returns Anthropic message response
+     *
+     * @example
+     * ```typescript
+     * const response = await cacheManager.createWithCache({
+     *   model: 'claude-sonnet-4',
+     *   systemPrompts: [
+     *     { text: SYSTEM_PROMPT, priority: 'high' },
+     *   ],
+     *   projectContext: [
+     *     { text: projectData, priority: 'medium' },
+     *   ],
+     *   messages: [{ role: 'user', content: userQuery }],
+     * });
+     * ```
+     */
+    createWithCache(params: {
+        model: string;
+        messages: Anthropic.MessageParam[];
+        systemPrompts: CacheableContent[];
+        projectContext?: CacheableContent[];
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<Anthropic.Message>;
+    /**
+     * Generate cache key from content using SHA-256
+     *
+     * Creates a content-addressable cache key by hashing all text blocks.
+     * Only cached blocks (those with cache_control) are included in the hash.
+     *
+     * @param content - Text blocks to hash
+     * @returns SHA-256 hash of content
+     *
+     * @example
+     * ```typescript
+     * const key = cacheManager.generateCacheKey([
+     *   { type: 'text', text: 'system prompt', cache_control: { type: 'ephemeral' } },
+     *   { type: 'text', text: 'project context', cache_control: { type: 'ephemeral' } },
+     * ]);
+     * // Returns: "a3f2c8b9..." (SHA-256 hash)
+     * ```
+     */
+    private generateCacheKey;
+    /**
+     * Check if cache key exists and is fresh (within 5 minutes)
+     *
+     * @param cacheKey - Cache key to check
+     * @returns true if cache hit, false if cache miss
+     *
+     * @example
+     * ```typescript
+     * const isHit = cacheManager.isCacheHit('a3f2c8b9...');
+     * if (isHit) {
+     *   console.log('Cache hit! Will save 90% on cached tokens');
+     * }
+     * ```
+     */
+    private isCacheHit;
+    /**
+     * Update cache statistics from API response
+     *
+     * Tracks:
+     * - Cache creation tokens (write with 25% premium)
+     * - Cache read tokens (hit with 90% discount)
+     * - Regular input tokens (standard cost)
+     * - Cost savings calculation
+     *
+     * @param response - Anthropic API response
+     * @param wasHit - Whether this was a cache hit
+     */
+    private updateStats;
+    /**
+     * Get cache statistics
+     *
+     * @returns Current cache statistics including hit rate and cost savings
+     *
+     * @example
+     * ```typescript
+     * const stats = cacheManager.getStats();
+     * console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+     * console.log(`Cost savings: $${stats.costSavings.toFixed(4)}`);
+     * console.log(`Total hits: ${stats.hits}, misses: ${stats.misses}`);
+     * ```
+     */
+    getStats(): CacheStats;
+    /**
+     * Clear cache keys older than TTL
+     *
+     * Automatically prunes expired cache entries to prevent memory bloat.
+     * Should be called periodically in long-running processes.
+     *
+     * @returns Number of entries pruned
+     *
+     * @example
+     * ```typescript
+     * // Run every 5 minutes
+     * setInterval(() => {
+     *   const pruned = cacheManager.pruneCache();
+     *   console.log(`Pruned ${pruned} expired cache entries`);
+     * }, 5 * 60 * 1000);
+     * ```
+     */
+    pruneCache(): number;
+    /**
+     * Reset statistics
+     *
+     * Clears all cache statistics. Useful for testing or when starting
+     * a new measurement period.
+     *
+     * @example
+     * ```typescript
+     * // Reset stats at start of each day
+     * cacheManager.resetStats();
+     * ```
+     */
+    resetStats(): void;
+    /**
+     * Clear all cache keys
+     *
+     * Removes all cache entries. Does not affect statistics.
+     *
+     * @example
+     * ```typescript
+     * // Clear cache when deploying new version
+     * cacheManager.clearCache();
+     * ```
+     */
+    clearCache(): void;
+    /**
+     * Check if content should be cached based on token count
+     *
+     * Anthropic requires minimum 1024 tokens for caching to be effective.
+     *
+     * @param text - Text content to check
+     * @returns true if content is large enough to cache
+     */
+    private shouldCache;
+    /**
+     * Estimate token count for content blocks
+     *
+     * Uses rough heuristic: 4 characters per token (conservative estimate)
+     *
+     * @param content - Text blocks to estimate
+     * @returns Estimated token count
+     */
+    private estimateTokens;
+    /**
+     * Get cache size (number of entries)
+     *
+     * @returns Number of cache entries
+     */
+    getCacheSize(): number;
+    /**
+     * Get expected hit rate target
+     *
+     * According to the MCP improvement plan, we should target
+     * 60-80% cache hit rate over 5-minute windows.
+     *
+     * @returns Target hit rate range
+     */
+    static getTargetHitRate(): {
+        min: number;
+        max: number;
+    };
+    /**
+     * Calculate break-even point
+     *
+     * Cache writes cost 25% more than regular calls.
+     * Cache hits save 90% on cached tokens.
+     *
+     * Break-even: 1 write + N hits where total cost equals regular cost
+     *
+     * @param cacheTokens - Number of tokens in cached content
+     * @returns Number of hits needed to break even
+     */
+    static calculateBreakEven(cacheTokens: number): {
+        hitsToBreakEven: number;
+        savings: {
+            atBreakEven: number;
+            at5Hits: number;
+            at10Hits: number;
+        };
+    };
+}
+//# sourceMappingURL=prompt-cache.d.ts.map

package/dist/utils/prompt-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-cache.d.ts","sourceRoot":"","sources":["../../src/utils/prompt-cache.ts"],"names":[],"mappings":"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"}