nttp 1.0.0

package/dist/cache/exact-cache.js

@@ -0,0 +1,104 @@
+/**
+ * L1 Exact Match Cache
+ * Fast hash-based cache for identical queries
+ */
+import { createHash } from 'crypto';
+/**
+ * L1 exact match cache using Map with LRU eviction
+ */
+export class ExactCache {
+    cache = new Map();
+    accessOrder = new Map();
+    accessCounter = 0;
+    maxSize;
+    hits = 0;
+    misses = 0;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    /**
+     * Get cached result for a query
+     */
+    get(query) {
+        const key = this.normalizeQuery(query);
+        const result = this.cache.get(key);
+        if (result) {
+            // Update hit count and access time
+            result.hitCount++;
+            result.lastUsedAt = new Date();
+            this.accessOrder.set(key, ++this.accessCounter);
+            this.hits++;
+            return result;
+        }
+        this.misses++;
+        return null;
+    }
+    /**
+     * Set cached result for a query
+     */
+    set(query, result) {
+        const key = this.normalizeQuery(query);
+        // Evict if at max size
+        if (!this.cache.has(key) && this.cache.size >= this.maxSize) {
+            this.evictLRU();
+        }
+        this.cache.set(key, result);
+        this.accessOrder.set(key, ++this.accessCounter);
+    }
+    /**
+     * Clear all cached results
+     */
+    clear() {
+        this.cache.clear();
+        this.accessOrder.clear();
+        this.accessCounter = 0;
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            hits: this.hits,
+            misses: this.misses,
+        };
+    }
+    /**
+     * Normalize query string for consistent cache keys
+     * - Convert to lowercase
+     * - Trim whitespace
+     * - Collapse multiple spaces
+     * - Hash to fixed-length key
+     */
+    normalizeQuery(query) {
+        const normalized = query
+            .toLowerCase()
+            .trim()
+            .replace(/\s+/g, ' ');
+        // Use SHA-256 hash for cache key
+        return createHash('sha256')
+            .update(normalized)
+            .digest('hex')
+            .substring(0, 16);
+    }
+    /**
+     * Evict least recently used entry
+     */
+    evictLRU() {
+        let oldestKey = null;
+        let oldestAccess = Infinity;
+        for (const [key, accessTime] of this.accessOrder.entries()) {
+            if (accessTime < oldestAccess) {
+                oldestAccess = accessTime;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            this.accessOrder.delete(oldestKey);
+        }
+    }
+}
+//# sourceMappingURL=exact-cache.js.map

package/dist/cache/exact-cache.js.map

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

package/dist/cache/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * nttp cache system
+ * Exports for 3-layer caching architecture
+ */
+export { ExactCache } from './exact-cache.js';
+export { SemanticCache } from './semantic-cache.js';
+export type { CachedResult, SemanticMatch, SemanticCacheConfig, LayerStats, CacheStats, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EACV,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,7 @@
+/**
+ * nttp cache system
+ * Exports for 3-layer caching architecture
+ */
+export { ExactCache } from './exact-cache.js';
+export { SemanticCache } from './semantic-cache.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,82 @@
+/**
+ * L2 Semantic Cache
+ * Embedding-based similarity matching using AI SDK
+ *
+ * PERFORMANCE NOTE: This implementation uses O(N) linear scan for similarity search.
+ * For large caches (>10,000 entries), consider using a vector database like:
+ * - Pinecone
+ * - Weaviate
+ * - FAISS (via Node.js bindings)
+ * - Qdrant
+ *
+ * These provide approximate nearest neighbor (ANN) search in O(log N) time.
+ */
+import type { CachedResult, SemanticMatch, SemanticCacheConfig, LayerStats } from './types.js';
+/**
+ * L2 semantic similarity cache using embeddings
+ */
+export declare class SemanticCache {
+    private entries;
+    private threshold;
+    private maxSize;
+    private model;
+    private modelPromise;
+    private config;
+    private hits;
+    private misses;
+    constructor(config: SemanticCacheConfig);
+    /**
+     * Lazy initialization of embedding model
+     * Supports multiple providers with dynamic imports
+     */
+    private initializeModel;
+    /**
+     * Load the embedding model based on provider configuration
+     * Passes API keys directly to avoid process.env race conditions
+     */
+    private loadEmbeddingModel;
+    /**
+     * Find semantically similar cached query
+     * ALWAYS returns the embedding to prevent double API billing on cache miss
+     *
+     * Usage pattern:
+     * const { match, embedding } = await cache.find(query);
+     * if (match) {
+     *   // Cache hit - use match.result
+     * } else {
+     *   // Cache miss - generate result and use addWithEmbedding(query, embedding, result)
+     * }
+     */
+    find(query: string): Promise<{
+        match: SemanticMatch | null;
+        embedding: number[];
+    }>;
+    /**
+     * Add new entry to cache with embedding generation
+     */
+    add(query: string, result: CachedResult): Promise<void>;
+    /**
+     * Add new entry with pre-computed embedding
+     * Used when embedding was already computed during find()
+     */
+    addWithEmbedding(query: string, embedding: number[], result: CachedResult): void;
+    /**
+     * Clear all cached results
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): LayerStats;
+    /**
+     * Evict least recently used entry
+     *
+     * NOTE: Minor race condition possible with concurrent adds in async code.
+     * Multiple parallel add() calls might all pass the size check before any
+     * eviction completes, temporarily exceeding maxSize by a few entries.
+     * This is acceptable for most use cases. For strict size limits, consider
+     * using a mutex/semaphore around the add operation.
+     */
+    private evictLRU;
+}
+//# sourceMappingURL=semantic-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-cache.d.ts","sourceRoot":"","sources":["../../src/cache/semantic-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,UAAU,EACX,MAAM,YAAY,CAAC;AAWpB;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,MAAM,EAAE,mBAAmB;IAMvC;;;OAGG;YACW,eAAe;IAa7B;;;OAGG;YACW,kBAAkB;IAmFhC;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA8CxF;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7D;;;OAGG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAahF;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,QAAQ,IAAI,UAAU;IAQtB;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ;CAkBjB"}

package/dist/cache/semantic-cache.js

@@ -0,0 +1,243 @@
+/**
+ * L2 Semantic Cache
+ * Embedding-based similarity matching using AI SDK
+ *
+ * PERFORMANCE NOTE: This implementation uses O(N) linear scan for similarity search.
+ * For large caches (>10,000 entries), consider using a vector database like:
+ * - Pinecone
+ * - Weaviate
+ * - FAISS (via Node.js bindings)
+ * - Qdrant
+ *
+ * These provide approximate nearest neighbor (ANN) search in O(log N) time.
+ */
+import { embed, cosineSimilarity } from 'ai';
+/**
+ * L2 semantic similarity cache using embeddings
+ */
+export class SemanticCache {
+    entries = [];
+    threshold;
+    maxSize;
+    model;
+    modelPromise = null;
+    config;
+    hits = 0;
+    misses = 0;
+    constructor(config) {
+        this.threshold = config.threshold ?? 0.85;
+        this.maxSize = config.maxSize ?? 500;
+        this.config = config;
+    }
+    /**
+     * Lazy initialization of embedding model
+     * Supports multiple providers with dynamic imports
+     */
+    async initializeModel() {
+        if (this.model) {
+            return this.model;
+        }
+        if (this.modelPromise) {
+            return this.modelPromise;
+        }
+        this.modelPromise = this.loadEmbeddingModel();
+        return this.modelPromise;
+    }
+    /**
+     * Load the embedding model based on provider configuration
+     * Passes API keys directly to avoid process.env race conditions
+     */
+    async loadEmbeddingModel() {
+        switch (this.config.provider) {
+            case 'openai': {
+                try {
+                    const { createOpenAI } = await import('@ai-sdk/openai');
+                    const openai = createOpenAI({
+                        apiKey: this.config.apiKey || process.env.OPENAI_API_KEY,
+                    });
+                    this.model = openai.textEmbeddingModel(this.config.model);
+                    return this.model;
+                }
+                catch (error) {
+                    throw new Error(`Failed to load @ai-sdk/openai. Install it with: npm install @ai-sdk/openai\nOriginal error: ${error}`);
+                }
+            }
+            case 'cohere': {
+                try {
+                    // @ts-expect-error - Optional peer dependency
+                    const { createCohere } = await import('@ai-sdk/cohere');
+                    const cohere = createCohere({
+                        apiKey: this.config.apiKey || process.env.COHERE_API_KEY,
+                    });
+                    this.model = cohere.embedding(this.config.model);
+                    return this.model;
+                }
+                catch (error) {
+                    throw new Error(`Failed to load @ai-sdk/cohere. Install it with: npm install @ai-sdk/cohere\nOriginal error: ${error}`);
+                }
+            }
+            case 'mistral': {
+                try {
+                    // @ts-expect-error - Optional peer dependency
+                    const { createMistral } = await import('@ai-sdk/mistral');
+                    const mistral = createMistral({
+                        apiKey: this.config.apiKey || process.env.MISTRAL_API_KEY,
+                    });
+                    this.model = mistral.embedding(this.config.model);
+                    return this.model;
+                }
+                catch (error) {
+                    throw new Error(`Failed to load @ai-sdk/mistral. Install it with: npm install @ai-sdk/mistral\nOriginal error: ${error}`);
+                }
+            }
+            case 'google': {
+                try {
+                    // @ts-expect-error - Optional peer dependency
+                    const { createGoogleGenerativeAI } = await import('@ai-sdk/google');
+                    const google = createGoogleGenerativeAI({
+                        apiKey: this.config.apiKey || process.env.GOOGLE_GENERATIVE_AI_API_KEY,
+                    });
+                    this.model = google.textEmbeddingModel(this.config.model);
+                    return this.model;
+                }
+                catch (error) {
+                    throw new Error(`Failed to load @ai-sdk/google. Install it with: npm install @ai-sdk/google\nOriginal error: ${error}`);
+                }
+            }
+            default: {
+                // Default to OpenAI for backward compatibility
+                try {
+                    const { createOpenAI } = await import('@ai-sdk/openai');
+                    const openai = createOpenAI({
+                        apiKey: this.config.apiKey || process.env.OPENAI_API_KEY,
+                    });
+                    this.model = openai.textEmbeddingModel(this.config.model);
+                    return this.model;
+                }
+                catch (error) {
+                    throw new Error(`Failed to load @ai-sdk/openai. Install it with: npm install @ai-sdk/openai\nOriginal error: ${error}`);
+                }
+            }
+        }
+    }
+    /**
+     * Find semantically similar cached query
+     * ALWAYS returns the embedding to prevent double API billing on cache miss
+     *
+     * Usage pattern:
+     * const { match, embedding } = await cache.find(query);
+     * if (match) {
+     *   // Cache hit - use match.result
+     * } else {
+     *   // Cache miss - generate result and use addWithEmbedding(query, embedding, result)
+     * }
+     */
+    async find(query) {
+        // Initialize model if needed
+        const model = await this.initializeModel();
+        // Generate embedding for the query (COST: 1 API call)
+        const { embedding } = await embed({
+            model,
+            value: query,
+        });
+        // Search for best match above threshold (O(N) linear scan)
+        let bestMatch = null;
+        let bestScore = 0;
+        for (const entry of this.entries) {
+            const score = cosineSimilarity(embedding, entry.embedding);
+            if (score >= this.threshold && score > bestScore) {
+                bestScore = score;
+                bestMatch = entry;
+            }
+        }
+        if (bestMatch) {
+            // Update hit count and access time
+            bestMatch.result.hitCount++;
+            bestMatch.result.lastUsedAt = new Date();
+            this.hits++;
+            return {
+                match: {
+                    result: bestMatch.result,
+                    similarity: bestScore,
+                    originalQuery: bestMatch.query,
+                },
+                embedding, // Return embedding for potential reuse
+            };
+        }
+        this.misses++;
+        return {
+            match: null,
+            embedding, // CRITICAL: Return embedding so caller can use addWithEmbedding()
+        };
+    }
+    /**
+     * Add new entry to cache with embedding generation
+     */
+    async add(query, result) {
+        // Initialize model if needed
+        const model = await this.initializeModel();
+        const { embedding } = await embed({
+            model,
+            value: query,
+        });
+        this.addWithEmbedding(query, embedding, result);
+    }
+    /**
+     * Add new entry with pre-computed embedding
+     * Used when embedding was already computed during find()
+     */
+    addWithEmbedding(query, embedding, result) {
+        // Evict if at max size
+        if (this.entries.length >= this.maxSize) {
+            this.evictLRU();
+        }
+        this.entries.push({
+            query,
+            embedding,
+            result,
+        });
+    }
+    /**
+     * Clear all cached results
+     */
+    clear() {
+        this.entries = [];
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            size: this.entries.length,
+            hits: this.hits,
+            misses: this.misses,
+        };
+    }
+    /**
+     * Evict least recently used entry
+     *
+     * NOTE: Minor race condition possible with concurrent adds in async code.
+     * Multiple parallel add() calls might all pass the size check before any
+     * eviction completes, temporarily exceeding maxSize by a few entries.
+     * This is acceptable for most use cases. For strict size limits, consider
+     * using a mutex/semaphore around the add operation.
+     */
+    evictLRU() {
+        if (this.entries.length === 0) {
+            return;
+        }
+        let oldestIndex = 0;
+        let oldestTime = this.entries[0].result.lastUsedAt;
+        for (let i = 1; i < this.entries.length; i++) {
+            const entryTime = this.entries[i].result.lastUsedAt;
+            if (entryTime < oldestTime) {
+                oldestTime = entryTime;
+                oldestIndex = i;
+            }
+        }
+        this.entries.splice(oldestIndex, 1);
+    }
+}
+//# sourceMappingURL=semantic-cache.js.map

package/dist/cache/semantic-cache.js.map

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

package/dist/cache/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Types for nttp caching system
+ */
+import type { JsonValue } from '../utils.js';
+/**
+ * Cached query result with metadata
+ */
+export interface CachedResult {
+    /**
+     * Schema ID for this query pattern
+     */
+    readonly schemaId: string;
+    /**
+     * Generated SQL query
+     */
+    readonly sql: string;
+    /**
+     * SQL query parameters
+     */
+    readonly params: JsonValue[];
+    /**
+     * Number of times this cache entry was hit (mutable)
+     */
+    hitCount: number;
+    /**
+     * When this cache entry was created
+     */
+    readonly createdAt: Date;
+    /**
+     * When this cache entry was last used (mutable)
+     */
+    lastUsedAt: Date;
+}
+/**
+ * Semantic match result from L2 cache
+ * Note: Embedding is returned separately from find() to prevent double API billing
+ */
+export interface SemanticMatch {
+    /**
+     * The cached result
+     */
+    result: CachedResult;
+    /**
+     * Cosine similarity score (0-1)
+     */
+    similarity: number;
+    /**
+     * Original query that was cached
+     */
+    originalQuery: string;
+}
+/**
+ * Statistics for a single cache layer
+ */
+export interface LayerStats {
+    /**
+     * Current size of the cache
+     */
+    size: number;
+    /**
+     * Number of cache hits
+     */
+    hits: number;
+    /**
+     * Number of cache misses
+     */
+    misses: number;
+}
+/**
+ * Aggregate cache statistics
+ */
+export interface CacheStats {
+    /**
+     * L1 exact match cache stats
+     */
+    l1: LayerStats;
+    /**
+     * L2 semantic cache stats
+     */
+    l2: LayerStats;
+    /**
+     * L3 LLM fallback stats
+     */
+    l3: {
+        /**
+         * Number of LLM calls made
+         */
+        calls: number;
+    };
+    /**
+     * Total queries processed
+     */
+    totalQueries: number;
+    /**
+     * Hit rates for each layer
+     */
+    hitRates: {
+        l1: number;
+        l2: number;
+        l3: number;
+    };
+    /**
+     * Estimated cost saved (USD)
+     */
+    estimatedCostSaved: number;
+}
+/**
+ * Configuration for L2 semantic cache
+ */
+export interface SemanticCacheConfig {
+    /**
+     * Embedding provider
+     */
+    provider: 'openai' | 'cohere' | 'mistral' | 'google';
+    /**
+     * Embedding model name
+     */
+    model: string;
+    /**
+     * Similarity threshold for matches (0-1)
+     * Recommended: 0.80-0.85 for natural language queries
+     * @default 0.85
+     */
+    threshold?: number;
+    /**
+     * Maximum cache size
+     * @default 500
+     */
+    maxSize?: number;
+    /**
+     * API key for embedding provider (if needed)
+     */
+    apiKey?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAE7B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IAEzB;;OAEG;IACH,UAAU,EAAE,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IAErB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,EAAE,EAAE,UAAU,CAAC;IAEf;;OAEG;IACH,EAAE,EAAE,UAAU,CAAC;IAEf;;OAEG;IACH,EAAE,EAAE;QACF;;WAEG;QACH,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IAEF;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;IAEF;;OAEG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAErD;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/cache/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types for nttp caching system
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}