@betterdb/semantic-cache 0.1.0 → 0.4.0

package/dist/discovery.d.ts

@@ -0,0 +1,67 @@
+import type { Valkey } from './types';
+export declare const PROTOCOL_VERSION = 1;
+export declare const REGISTRY_KEY = "__betterdb:caches";
+export declare const PROTOCOL_KEY = "__betterdb:protocol";
+export declare const HEARTBEAT_KEY_PREFIX = "__betterdb:heartbeat:";
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+export declare const HEARTBEAT_TTL_SECONDS = 60;
+export declare const CACHE_TYPE: "semantic_cache";
+export type CacheType = typeof CACHE_TYPE;
+export interface DiscoveryOptions {
+    enabled?: boolean;
+    heartbeatIntervalMs?: number;
+    includeCategories?: boolean;
+}
+export interface MarkerMetadata {
+    type: CacheType;
+    prefix: string;
+    version: string;
+    protocol_version: number;
+    capabilities: string[];
+    stats_key: string;
+    started_at: string;
+    pid?: number;
+    hostname?: string;
+    [extra: string]: unknown;
+}
+export interface BuildSemanticMetadataInput {
+    name: string;
+    version: string;
+    defaultThreshold: number;
+    categoryThresholds: Record<string, number>;
+    uncertaintyBand: number;
+    includeCategories: boolean;
+}
+export declare function buildSemanticMetadata(input: BuildSemanticMetadataInput): MarkerMetadata;
+export interface DiscoveryLogger {
+    warn: (msg: string) => void;
+    debug: (msg: string) => void;
+}
+export interface DiscoveryManagerDeps {
+    client: Valkey;
+    name: string;
+    metadata: MarkerMetadata;
+    heartbeatIntervalMs?: number;
+    logger?: DiscoveryLogger;
+    onWriteFailed?: () => void;
+}
+export declare class DiscoveryManager {
+    private readonly client;
+    private readonly name;
+    private readonly metadata;
+    private readonly heartbeatIntervalMs;
+    private readonly heartbeatKey;
+    private readonly logger;
+    private readonly onWriteFailed;
+    private heartbeatHandle;
+    constructor(deps: DiscoveryManagerDeps);
+    register(): Promise<void>;
+    stop(opts: {
+        deleteHeartbeat: boolean;
+    }): Promise<void>;
+    tickHeartbeat(): Promise<void>;
+    private startHeartbeat;
+    private safeHget;
+    private safeCall;
+    private checkCollision;
+}

package/dist/discovery.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscoveryManager = exports.CACHE_TYPE = exports.HEARTBEAT_TTL_SECONDS = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.HEARTBEAT_KEY_PREFIX = exports.PROTOCOL_KEY = exports.REGISTRY_KEY = exports.PROTOCOL_VERSION = void 0;
+exports.buildSemanticMetadata = buildSemanticMetadata;
+const node_os_1 = require("node:os");
+const errors_1 = require("./errors");
+exports.PROTOCOL_VERSION = 1;
+exports.REGISTRY_KEY = '__betterdb:caches';
+exports.PROTOCOL_KEY = '__betterdb:protocol';
+exports.HEARTBEAT_KEY_PREFIX = '__betterdb:heartbeat:';
+exports.DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+exports.HEARTBEAT_TTL_SECONDS = 60;
+exports.CACHE_TYPE = 'semantic_cache';
+function buildSemanticMetadata(input) {
+    const metadata = {
+        type: exports.CACHE_TYPE,
+        prefix: input.name,
+        version: input.version,
+        protocol_version: exports.PROTOCOL_VERSION,
+        capabilities: ['invalidate', 'similarity_distribution', 'threshold_adjust'],
+        index_name: `${input.name}:idx`,
+        stats_key: `${input.name}:__stats`,
+        config_key: `${input.name}:__config`,
+        default_threshold: input.defaultThreshold,
+        uncertainty_band: input.uncertaintyBand,
+        started_at: new Date().toISOString(),
+        pid: process.pid,
+        hostname: (0, node_os_1.hostname)(),
+    };
+    if (input.includeCategories && Object.keys(input.categoryThresholds).length > 0) {
+        metadata.category_thresholds = { ...input.categoryThresholds };
+    }
+    return metadata;
+}
+const noopLogger = {
+    warn: () => { },
+    debug: () => { },
+};
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+class DiscoveryManager {
+    client;
+    name;
+    metadata;
+    heartbeatIntervalMs;
+    heartbeatKey;
+    logger;
+    onWriteFailed;
+    heartbeatHandle = null;
+    constructor(deps) {
+        this.client = deps.client;
+        this.name = deps.name;
+        this.metadata = deps.metadata;
+        this.heartbeatIntervalMs = deps.heartbeatIntervalMs ?? exports.DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.heartbeatKey = `${exports.HEARTBEAT_KEY_PREFIX}${deps.name}`;
+        this.logger = deps.logger ?? noopLogger;
+        this.onWriteFailed = deps.onWriteFailed ?? (() => { });
+    }
+    async register() {
+        const existingJson = await this.safeHget();
+        if (existingJson !== null) {
+            this.checkCollision(existingJson);
+        }
+        await this.safeCall(() => this.client.hset(exports.REGISTRY_KEY, this.name, JSON.stringify(this.metadata)), 'HSET registry');
+        await this.safeCall(() => this.client.set(exports.PROTOCOL_KEY, String(exports.PROTOCOL_VERSION), 'NX'), 'SET protocol');
+        await this.tickHeartbeat();
+        this.startHeartbeat();
+    }
+    async stop(opts) {
+        if (this.heartbeatHandle) {
+            clearInterval(this.heartbeatHandle);
+            this.heartbeatHandle = null;
+        }
+        if (!opts.deleteHeartbeat) {
+            return;
+        }
+        try {
+            await this.client.del(this.heartbeatKey);
+        }
+        catch (err) {
+            this.logger.debug(`discovery: DEL heartbeat failed: ${errMsg(err)}`);
+        }
+    }
+    async tickHeartbeat() {
+        const now = new Date().toISOString();
+        try {
+            await this.client.set(this.heartbeatKey, now, 'EX', exports.HEARTBEAT_TTL_SECONDS);
+        }
+        catch (err) {
+            this.logger.debug(`discovery: heartbeat SET failed: ${errMsg(err)}`);
+            this.onWriteFailed();
+        }
+    }
+    startHeartbeat() {
+        if (this.heartbeatHandle) {
+            clearInterval(this.heartbeatHandle);
+        }
+        const handle = setInterval(() => {
+            void this.tickHeartbeat();
+        }, this.heartbeatIntervalMs);
+        handle.unref?.();
+        this.heartbeatHandle = handle;
+    }
+    async safeHget() {
+        try {
+            return await this.client.hget(exports.REGISTRY_KEY, this.name);
+        }
+        catch (err) {
+            this.logger.warn(`discovery: HGET registry failed: ${errMsg(err)}`);
+            this.onWriteFailed();
+            return null;
+        }
+    }
+    async safeCall(fn, label) {
+        try {
+            await fn();
+        }
+        catch (err) {
+            this.logger.warn(`discovery: ${label} failed: ${errMsg(err)}`);
+            this.onWriteFailed();
+        }
+    }
+    checkCollision(existingJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(existingJson);
+        }
+        catch {
+            return;
+        }
+        if (parsed.type && parsed.type !== exports.CACHE_TYPE) {
+            throw new errors_1.SemanticCacheUsageError(`cache name collision: '${this.name}' is already registered as type '${String(parsed.type)}' on this Valkey instance`);
+        }
+        if (parsed.version && parsed.version !== this.metadata.version) {
+            this.logger.warn(`discovery: overwriting marker for '${this.name}' (existing version ${String(parsed.version)}, this version ${this.metadata.version})`);
+        }
+    }
+}
+exports.DiscoveryManager = DiscoveryManager;

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,10 @@
 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, ConfigRefreshOptions, } from './types';
 export { SemanticCacheUsageError, EmbeddingError, ValkeyCommandError, } from './errors';
+export type { ContentBlock, TextBlock, BinaryBlock, ToolCallBlock, ToolResultBlock, ReasoningBlock, BlockHints, } from './utils';
+export { escapeTag } from './utils';
+export type { BinaryRef, BinaryNormalizer, NormalizerConfig } from './normalizer';
+export { hashBase64, hashBytes, hashUrl, fetchAndHash, passthrough, composeNormalizer, defaultNormalizer, } from './normalizer';
+export type { DiscoveryOptions } from './discovery';