@betterdb/semantic-cache 0.1.0 → 0.2.0

package/dist/embed/bedrock.d.ts

@@ -0,0 +1,32 @@
+/**
+ * AWS Bedrock embedding helper for @betterdb/semantic-cache.
+ *
+ * Supports Titan Text Embeddings v2 (1024-dim) and Cohere Embed v3 (1024-dim).
+ * Requires @aws-sdk/client-bedrock-runtime as a peer dependency.
+ *
+ * Usage:
+ *   import { createBedrockEmbed } from '@betterdb/semantic-cache/embed/bedrock';
+ *   const embed = createBedrockEmbed({ modelId: 'amazon.titan-embed-text-v2:0' });
+ *   const cache = new SemanticCache({ client, embedFn: embed });
+ */
+import type { EmbedFn } from '../types';
+export type BedrockEmbedModelId = 'amazon.titan-embed-text-v2:0' | 'amazon.titan-embed-text-v1' | 'cohere.embed-english-v3' | 'cohere.embed-multilingual-v3' | (string & {});
+export interface BedrockEmbedOptions {
+    /**
+     * Pre-configured BedrockRuntimeClient instance.
+     * If not provided, a new client is created from environment credentials.
+     */
+    client?: any;
+    /**
+     * Model ID to use for embeddings.
+     * Default: 'amazon.titan-embed-text-v2:0'
+     */
+    modelId?: BedrockEmbedModelId;
+    /** AWS region. Used only when client is not provided. Default: AWS_DEFAULT_REGION env var. */
+    region?: string;
+}
+/**
+ * Create an EmbedFn backed by the AWS Bedrock embedding models.
+ * Requires @aws-sdk/client-bedrock-runtime to be installed.
+ */
+export declare function createBedrockEmbed(opts?: BedrockEmbedOptions): EmbedFn;

package/dist/embed/bedrock.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBedrockEmbed = createBedrockEmbed;
+/**
+ * Create an EmbedFn backed by the AWS Bedrock embedding models.
+ * Requires @aws-sdk/client-bedrock-runtime to be installed.
+ */
+function createBedrockEmbed(opts) {
+    const modelId = opts?.modelId ?? 'amazon.titan-embed-text-v2:0';
+    let clientPromise = null;
+    let CommandClass = null;
+    function getClient() {
+        if (!clientPromise) {
+            clientPromise = (async () => {
+                if (opts?.client) {
+                    // Load InvokeModelCommand separately
+                    try {
+                        // @ts-ignore - optional peer dep
+                        const mod = await Promise.resolve(`${'@aws-sdk/client-bedrock-runtime'}`).then(s => __importStar(require(s)));
+                        CommandClass = mod.InvokeModelCommand;
+                    }
+                    catch {
+                        throw new Error('@betterdb/semantic-cache embed/bedrock requires "@aws-sdk/client-bedrock-runtime". Install it.');
+                    }
+                    return opts.client;
+                }
+                try {
+                    // @ts-ignore - optional peer dep
+                    const mod = await Promise.resolve(`${'@aws-sdk/client-bedrock-runtime'}`).then(s => __importStar(require(s)));
+                    const { BedrockRuntimeClient, InvokeModelCommand } = mod;
+                    CommandClass = InvokeModelCommand;
+                    return new BedrockRuntimeClient({
+                        region: opts?.region ?? process.env.AWS_DEFAULT_REGION ?? 'us-east-1',
+                    });
+                }
+                catch {
+                    throw new Error('@betterdb/semantic-cache embed/bedrock requires "@aws-sdk/client-bedrock-runtime". Install it.');
+                }
+            })();
+        }
+        return clientPromise;
+    }
+    return async (text) => {
+        const client = await getClient();
+        const isTitan = modelId.startsWith('amazon.titan');
+        const isCohere = modelId.startsWith('cohere.embed');
+        let body;
+        if (isTitan) {
+            body = { inputText: text };
+        }
+        else if (isCohere) {
+            body = { texts: [text], input_type: 'search_document', truncate: 'END' };
+        }
+        else {
+            body = { inputText: text };
+        }
+        const command = new CommandClass({
+            modelId,
+            body: JSON.stringify(body),
+            contentType: 'application/json',
+            accept: 'application/json',
+        });
+        const response = await client.send(command);
+        const decoded = new TextDecoder().decode(response.body);
+        const parsed = JSON.parse(decoded);
+        if (isTitan) {
+            return parsed.embedding ?? [];
+        }
+        else if (isCohere) {
+            const embeddings = parsed.embeddings;
+            return embeddings[0] ?? [];
+        }
+        // Generic fallback
+        return parsed.embedding ?? parsed.embeddings?.[0] ?? [];
+    };
+}

package/dist/embed/cohere.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cohere embedding helper for @betterdb/semantic-cache.
+ *
+ * Supports Cohere Embed v3 models via the Cohere REST API.
+ * Uses native fetch - no SDK required.
+ *
+ * Usage:
+ *   import { createCohereEmbed } from '@betterdb/semantic-cache/embed/cohere';
+ *   const embed = createCohereEmbed({ model: 'embed-english-v3.0' });
+ *   const cache = new SemanticCache({ client, embedFn: embed });
+ */
+import type { EmbedFn } from '../types';
+export interface CohereEmbedOptions {
+    /**
+     * Cohere embedding model.
+     * Default: 'embed-english-v3.0' (1024 dimensions).
+     * Other options: 'embed-multilingual-v3.0', 'embed-english-light-v3.0'.
+     */
+    model?: string;
+    /** Cohere API key. Default: COHERE_API_KEY env var. */
+    apiKey?: string;
+    /** API base URL. Default: 'https://api.cohere.com/v2'. */
+    baseUrl?: string;
+    /**
+     * Input type for embedding.
+     * Default: 'search_query'. Use 'search_document' when storing.
+     */
+    inputType?: 'search_query' | 'search_document' | 'classification' | 'clustering';
+}
+/**
+ * Create an EmbedFn backed by the Cohere Embed API.
+ * Uses native fetch - no SDK required.
+ */
+export declare function createCohereEmbed(opts?: CohereEmbedOptions): EmbedFn;

package/dist/embed/cohere.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCohereEmbed = createCohereEmbed;
+/**
+ * Create an EmbedFn backed by the Cohere Embed API.
+ * Uses native fetch - no SDK required.
+ */
+function createCohereEmbed(opts) {
+    const model = opts?.model ?? 'embed-english-v3.0';
+    const baseUrl = opts?.baseUrl ?? 'https://api.cohere.com/v2';
+    const inputType = opts?.inputType ?? 'search_query';
+    return async (text) => {
+        const apiKey = opts?.apiKey ?? process.env.COHERE_API_KEY;
+        if (!apiKey) {
+            throw new Error('Cohere API key is required. Set COHERE_API_KEY env var or pass apiKey in options.');
+        }
+        const res = await fetch(`${baseUrl}/embed`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                texts: [text],
+                input_type: inputType,
+                embedding_types: ['float'],
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`Cohere API error: ${res.status} ${body}`);
+        }
+        const json = (await res.json());
+        return json.embeddings.float[0] ?? [];
+    };
+}

package/dist/embed/ollama.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ollama embedding helper for @betterdb/semantic-cache.
+ *
+ * Supports local Ollama embedding models (nomic-embed-text, mxbai-embed-large, etc.).
+ * Uses the Ollama REST API directly - no SDK required.
+ *
+ * Usage:
+ *   import { createOllamaEmbed } from '@betterdb/semantic-cache/embed/ollama';
+ *   const embed = createOllamaEmbed({ model: 'nomic-embed-text' });
+ *   const cache = new SemanticCache({ client, embedFn: embed });
+ */
+import type { EmbedFn } from '../types';
+export interface OllamaEmbedOptions {
+    /**
+     * Ollama embedding model name.
+     * Default: 'nomic-embed-text' (768 dimensions).
+     * Other options: 'mxbai-embed-large' (1024-dim), 'all-minilm' (384-dim).
+     */
+    model?: string;
+    /**
+     * Ollama API base URL.
+     * Default: 'http://localhost:11434'
+     */
+    baseUrl?: string;
+}
+/**
+ * Create an EmbedFn backed by a local Ollama instance.
+ * Uses native fetch - no SDK required.
+ */
+export declare function createOllamaEmbed(opts?: OllamaEmbedOptions): EmbedFn;

package/dist/embed/ollama.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOllamaEmbed = createOllamaEmbed;
+/**
+ * Create an EmbedFn backed by a local Ollama instance.
+ * Uses native fetch - no SDK required.
+ */
+function createOllamaEmbed(opts) {
+    const model = opts?.model ?? 'nomic-embed-text';
+    const baseUrl = opts?.baseUrl ?? (process.env.OLLAMA_HOST ?? 'http://localhost:11434');
+    return async (text) => {
+        const res = await fetch(`${baseUrl}/api/embed`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ model, input: text }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`Ollama API error: ${res.status} ${body}`);
+        }
+        const json = (await res.json());
+        return json.embeddings[0] ?? [];
+    };
+}

package/dist/embed/openai.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenAI embedding helper for @betterdb/semantic-cache.
+ *
+ * Creates an EmbedFn backed by the OpenAI Embeddings API.
+ * Requires the 'openai' peer dependency to be installed.
+ *
+ * Usage:
+ *   import { createOpenAIEmbed } from '@betterdb/semantic-cache/embed/openai';
+ *   const embed = createOpenAIEmbed({ model: 'text-embedding-3-small' });
+ *   const cache = new SemanticCache({ client, embedFn: embed });
+ */
+import type { EmbedFn } from '../types';
+export interface OpenAIEmbedOptions {
+    /**
+     * Pre-configured OpenAI client instance.
+     * If not provided, a new client is created using the OPENAI_API_KEY env var.
+     */
+    client?: any;
+    /**
+     * Embedding model ID.
+     * Default: 'text-embedding-3-small' (1536 dimensions, best cost/quality tradeoff).
+     */
+    model?: string;
+    /** OpenAI API key. Used only when client is not provided. Default: OPENAI_API_KEY env var. */
+    apiKey?: string;
+}
+/**
+ * Create an EmbedFn backed by the OpenAI Embeddings API.
+ * Requires the 'openai' package to be installed as a peer dependency.
+ */
+export declare function createOpenAIEmbed(opts?: OpenAIEmbedOptions): EmbedFn;

package/dist/embed/openai.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOpenAIEmbed = createOpenAIEmbed;
+/**
+ * Create an EmbedFn backed by the OpenAI Embeddings API.
+ * Requires the 'openai' package to be installed as a peer dependency.
+ */
+function createOpenAIEmbed(opts) {
+    const model = opts?.model ?? 'text-embedding-3-small';
+    let clientPromise = null;
+    function getClient() {
+        if (!clientPromise) {
+            clientPromise = (async () => {
+                if (opts?.client)
+                    return opts.client;
+                try {
+                    // @ts-ignore - openai is an optional peer dep
+                    const { OpenAI } = await Promise.resolve().then(() => __importStar(require('openai')));
+                    return new OpenAI({ apiKey: opts?.apiKey ?? process.env.OPENAI_API_KEY });
+                }
+                catch {
+                    throw new Error('@betterdb/semantic-cache embed/openai requires the "openai" package. Install it: npm install openai');
+                }
+            })();
+        }
+        return clientPromise;
+    }
+    return async (text) => {
+        const client = (await getClient());
+        const response = await client.embeddings.create({ input: text, model });
+        return response.data[0].embedding;
+    };
+}

package/dist/embed/voyage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Voyage AI embedding helper for @betterdb/semantic-cache.
+ *
+ * Supports all Voyage AI embedding models (voyage-3, voyage-3-lite, etc.).
+ * Uses the Voyage AI REST API directly - no SDK required.
+ *
+ * Usage:
+ *   import { createVoyageEmbed } from '@betterdb/semantic-cache/embed/voyage';
+ *   const embed = createVoyageEmbed({ model: 'voyage-3-lite' });
+ *   const cache = new SemanticCache({ client, embedFn: embed });
+ */
+import type { EmbedFn } from '../types';
+export interface VoyageEmbedOptions {
+    /**
+     * Voyage AI embedding model.
+     * Default: 'voyage-3-lite' (512 dimensions, fastest and cheapest).
+     * Other options: 'voyage-3' (1024-dim), 'voyage-3-large' (1024-dim).
+     */
+    model?: string;
+    /** Voyage AI API key. Default: VOYAGE_API_KEY env var. */
+    apiKey?: string;
+    /** API base URL. Default: 'https://api.voyageai.com/v1'. */
+    baseUrl?: string;
+    /** Input type hint for retrieval tasks ('query' or 'document'). Default: 'query'. */
+    inputType?: 'query' | 'document';
+}
+/**
+ * Create an EmbedFn backed by the Voyage AI Embeddings API.
+ * Uses native fetch - no SDK required.
+ */
+export declare function createVoyageEmbed(opts?: VoyageEmbedOptions): EmbedFn;

package/dist/embed/voyage.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVoyageEmbed = createVoyageEmbed;
+/**
+ * Create an EmbedFn backed by the Voyage AI Embeddings API.
+ * Uses native fetch - no SDK required.
+ */
+function createVoyageEmbed(opts) {
+    const model = opts?.model ?? 'voyage-3-lite';
+    const baseUrl = opts?.baseUrl ?? 'https://api.voyageai.com/v1';
+    const inputType = opts?.inputType ?? 'query';
+    return async (text) => {
+        const apiKey = opts?.apiKey ?? process.env.VOYAGE_API_KEY;
+        if (!apiKey) {
+            throw new Error('Voyage AI API key is required. Set VOYAGE_API_KEY env var or pass apiKey in options.');
+        }
+        const res = await fetch(`${baseUrl}/embeddings`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ model, input: [text], input_type: inputType }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`Voyage AI API error: ${res.status} ${body}`);
+        }
+        const json = (await res.json());
+        return json.data[0].embedding;
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,8 @@
 export { SemanticCache } from './SemanticCache';
-export type { SemanticCacheOptions, CacheCheckOptions, CacheStoreOptions, CacheCheckResult, CacheStats, IndexInfo, InvalidateResult, CacheConfidence, EmbedFn, } from './types';
+export type { ThresholdEffectivenessResult } from './SemanticCache';
+export { DEFAULT_COST_TABLE } from './defaultCostTable';
+export type { SemanticCacheOptions, CacheCheckOptions, CacheStoreOptions, CacheCheckResult, CacheStats, IndexInfo, InvalidateResult, CacheConfidence, EmbedFn, ModelCost, RerankOptions, } from './types';
 export { SemanticCacheUsageError, EmbeddingError, ValkeyCommandError, } from './errors';
+export type { ContentBlock, TextBlock, BinaryBlock, ToolCallBlock, ToolResultBlock, ReasoningBlock, BlockHints, } from './utils';
+export type { BinaryRef, BinaryNormalizer, NormalizerConfig } from './normalizer';
+export { hashBase64, hashBytes, hashUrl, fetchAndHash, passthrough, composeNormalizer, defaultNormalizer, } from './normalizer';

package/dist/index.js

@@ -1,9 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValkeyCommandError = exports.EmbeddingError = exports.SemanticCacheUsageError = exports.SemanticCache = void 0;
+exports.defaultNormalizer = exports.composeNormalizer = exports.passthrough = exports.fetchAndHash = exports.hashUrl = exports.hashBytes = exports.hashBase64 = exports.ValkeyCommandError = exports.EmbeddingError = exports.SemanticCacheUsageError = exports.DEFAULT_COST_TABLE = exports.SemanticCache = void 0;
 var SemanticCache_1 = require("./SemanticCache");
 Object.defineProperty(exports, "SemanticCache", { enumerable: true, get: function () { return SemanticCache_1.SemanticCache; } });
+var defaultCostTable_1 = require("./defaultCostTable");
+Object.defineProperty(exports, "DEFAULT_COST_TABLE", { enumerable: true, get: function () { return defaultCostTable_1.DEFAULT_COST_TABLE; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "SemanticCacheUsageError", { enumerable: true, get: function () { return errors_1.SemanticCacheUsageError; } });
 Object.defineProperty(exports, "EmbeddingError", { enumerable: true, get: function () { return errors_1.EmbeddingError; } });
 Object.defineProperty(exports, "ValkeyCommandError", { enumerable: true, get: function () { return errors_1.ValkeyCommandError; } });
+var normalizer_1 = require("./normalizer");
+Object.defineProperty(exports, "hashBase64", { enumerable: true, get: function () { return normalizer_1.hashBase64; } });
+Object.defineProperty(exports, "hashBytes", { enumerable: true, get: function () { return normalizer_1.hashBytes; } });
+Object.defineProperty(exports, "hashUrl", { enumerable: true, get: function () { return normalizer_1.hashUrl; } });
+Object.defineProperty(exports, "fetchAndHash", { enumerable: true, get: function () { return normalizer_1.fetchAndHash; } });
+Object.defineProperty(exports, "passthrough", { enumerable: true, get: function () { return normalizer_1.passthrough; } });
+Object.defineProperty(exports, "composeNormalizer", { enumerable: true, get: function () { return normalizer_1.composeNormalizer; } });
+Object.defineProperty(exports, "defaultNormalizer", { enumerable: true, get: function () { return normalizer_1.defaultNormalizer; } });

package/dist/normalizer.d.ts

@@ -0,0 +1,68 @@
+export interface BinaryRef {
+    kind: "image" | "audio" | "document";
+    source: {
+        type: "base64";
+        data: string;
+        mediaType?: string;
+    } | {
+        type: "url";
+        url: string;
+    } | {
+        type: "fileId";
+        fileId: string;
+        provider: string;
+    } | {
+        type: "bytes";
+        data: Uint8Array | Buffer;
+    };
+    context?: Record<string, unknown>;
+}
+export type BinaryNormalizer = (ref: BinaryRef) => Promise<string>;
+export interface NormalizerConfig {
+    base64?: (data: string) => string | Promise<string>;
+    url?: (urlStr: string) => string | Promise<string>;
+    fileId?: (fileId: string, provider: string) => string | Promise<string>;
+    bytes?: (data: Uint8Array | Buffer) => string | Promise<string>;
+    byKind?: {
+        image?: BinaryNormalizer;
+        audio?: BinaryNormalizer;
+        document?: BinaryNormalizer;
+    };
+}
+/**
+ * Strip any "data:<mime>;base64," prefix, decode the base64 bytes,
+ * and return "sha256:<hex>" of the decoded bytes.
+ */
+export declare function hashBase64(data: string): string;
+/**
+ * Return "sha256:<hex>" of the raw bytes.
+ */
+export declare function hashBytes(data: Uint8Array | Buffer): string;
+/**
+ * Normalize a URL: lowercase scheme+host, drop default ports (80/443),
+ * sort query params, return "url:<normalized>".
+ */
+export declare function hashUrl(urlStr: string): string;
+/**
+ * Fetch a URL, throw if response is not ok, and return "sha256:<hex>"
+ * of the response body bytes.
+ */
+export declare function fetchAndHash(url: string): Promise<string>;
+/**
+ * Return a scheme-prefixed reference without any normalization:
+ * - base64 source  -> "base64:<data>"
+ * - url source     -> "url:<url>"
+ * - fileId source  -> "fileid:<provider>:<fileId>"
+ * - bytes source   -> "sha256:<hex>" (hashes the bytes)
+ */
+export declare function passthrough(ref: BinaryRef): string;
+/**
+ * Build a BinaryNormalizer from a config.
+ *
+ * Dispatch order:
+ * 1. If cfg.byKind[ref.kind] is defined, call it with the full BinaryRef.
+ * 2. Otherwise dispatch on ref.source.type using the per-source handlers.
+ * 3. Fall back to passthrough for any unhandled source types.
+ */
+export declare function composeNormalizer(cfg?: NormalizerConfig): BinaryNormalizer;
+export declare const defaultNormalizer: BinaryNormalizer;

package/dist/normalizer.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultNormalizer = void 0;
+exports.hashBase64 = hashBase64;
+exports.hashBytes = hashBytes;
+exports.hashUrl = hashUrl;
+exports.fetchAndHash = fetchAndHash;
+exports.passthrough = passthrough;
+exports.composeNormalizer = composeNormalizer;
+const node_crypto_1 = require("node:crypto");
+// --- Normalizer functions ---
+/**
+ * Strip any "data:<mime>;base64," prefix, decode the base64 bytes,
+ * and return "sha256:<hex>" of the decoded bytes.
+ */
+function hashBase64(data) {
+    const raw = data.includes(";base64,") ? data.split(";base64,")[1] : data;
+    const bytes = Buffer.from(raw, "base64");
+    return "sha256:" + (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex");
+}
+/**
+ * Return "sha256:<hex>" of the raw bytes.
+ */
+function hashBytes(data) {
+    return "sha256:" + (0, node_crypto_1.createHash)("sha256").update(data).digest("hex");
+}
+/**
+ * Normalize a URL: lowercase scheme+host, drop default ports (80/443),
+ * sort query params, return "url:<normalized>".
+ */
+function hashUrl(urlStr) {
+    const url = new URL(urlStr);
+    // URL constructor lowercases scheme and hostname; also drops default ports
+    url.searchParams.sort();
+    return "url:" + url.toString();
+}
+/**
+ * Fetch a URL, throw if response is not ok, and return "sha256:<hex>"
+ * of the response body bytes.
+ */
+async function fetchAndHash(url) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`fetchAndHash: HTTP ${res.status} for ${url}`);
+    }
+    const buf = await res.arrayBuffer();
+    return "sha256:" + (0, node_crypto_1.createHash)("sha256").update(Buffer.from(buf)).digest("hex");
+}
+/**
+ * Return a scheme-prefixed reference without any normalization:
+ * - base64 source  -> "base64:<data>"
+ * - url source     -> "url:<url>"
+ * - fileId source  -> "fileid:<provider>:<fileId>"
+ * - bytes source   -> "sha256:<hex>" (hashes the bytes)
+ */
+function passthrough(ref) {
+    const { source } = ref;
+    switch (source.type) {
+        case "base64":
+            return "base64:" + source.data;
+        case "url":
+            return "url:" + source.url;
+        case "fileId":
+            return "fileid:" + source.provider + ":" + source.fileId;
+        case "bytes":
+            return hashBytes(source.data);
+    }
+}
+// --- Factory ---
+/**
+ * Build a BinaryNormalizer from a config.
+ *
+ * Dispatch order:
+ * 1. If cfg.byKind[ref.kind] is defined, call it with the full BinaryRef.
+ * 2. Otherwise dispatch on ref.source.type using the per-source handlers.
+ * 3. Fall back to passthrough for any unhandled source types.
+ */
+function composeNormalizer(cfg = {}) {
+    return async (ref) => {
+        // byKind takes priority
+        const kindFn = cfg.byKind?.[ref.kind];
+        if (kindFn)
+            return kindFn(ref);
+        const { source } = ref;
+        switch (source.type) {
+            case "base64":
+                return cfg.base64 ? cfg.base64(source.data) : passthrough(ref);
+            case "url":
+                return cfg.url ? cfg.url(source.url) : passthrough(ref);
+            case "fileId":
+                return cfg.fileId
+                    ? cfg.fileId(source.fileId, source.provider)
+                    : passthrough(ref);
+            case "bytes":
+                return cfg.bytes ? cfg.bytes(source.data) : passthrough(ref);
+        }
+    };
+}
+exports.defaultNormalizer = composeNormalizer({
+    base64: hashBase64,
+    bytes: hashBytes,
+});

package/dist/telemetry.d.ts

@@ -10,6 +10,9 @@ interface CacheMetrics {
     similarityScore: Histogram;
     operationDuration: Histogram;
     embeddingDuration: Histogram;
+    costSavedTotal: Counter;
+    embeddingCacheTotal: Counter;
+    staleModelEvictions: Counter;
 }
 export interface Telemetry {
     tracer: Tracer;