import type { EmbeddingCacheEntry, EmbeddingCacheStore, EmbeddingInputType } from '../types/embeddings.js';
import { type RedisRawClient } from '../utils/redis-command.js';
export { packVector, unpackVector } from '../utils/vector-bytes.js';
export type { EmbeddingCacheEntry, EmbeddingCacheStore } from '../types/embeddings.js';
/** What a cached vector depends on besides its input: the same text under another model is another vector. */
export interface EmbeddingCacheContext {
    /** The provider that embedded it. */
    provider: string;
    /** The concrete model. */
    model: string;
    /** The input type it was embedded as. */
    inputType?: EmbeddingInputType;
    /** The size it was shortened to. */
    dimensions?: number;
    /** Whether it was scaled to unit length. */
    normalize?: boolean;
    /** How a long input was cut. */
    truncate?: string;
}
/**
 * The cache key for an input embedded under a context: a SHA-256 in hex, so the text itself never
 * becomes a key in a shared store.
 */
export declare function embeddingCacheKey(context: EmbeddingCacheContext, input: string): string;
/** Limits for the in-process embedding cache. */
export interface MemoryEmbeddingCacheOptions {
    /** Most vectors held; the least recently used goes first. Defaults to 10,000. */
    maxEntries?: number;
    /** Replaces the system clock, for tests. */
    now?: () => number;
}
/**
 * Vectors in process memory, packed as float32, the least recently used evicted first. As the near
 * tier of `tieredEmbeddingCache()`, it answers repeated texts without a round trip.
 */
export declare class MemoryEmbeddingCache implements EmbeddingCacheStore {
    private readonly entries;
    private readonly maxEntries;
    private readonly now;
    constructor(options?: MemoryEmbeddingCacheOptions);
    /** Vectors held now. */
    get size(): number;
    /** The vectors under these keys, in order, with `undefined` for each miss or expired entry. */
    getMany(keys: readonly string[]): Promise<Array<number[] | undefined>>;
    /** Stores vectors, evicting the least recently used past `maxEntries`. */
    setMany(entries: readonly EmbeddingCacheEntry[], ttlSeconds?: number): Promise<void>;
    /** Removes every vector. */
    clear(): void;
}
/** A Redis client that sends raw commands: ioredis, with `call()`, or node-redis, with `sendCommand()`. */
export type RedisEmbeddingCacheClient = RedisRawClient;
/** Options for the Redis embedding cache. */
export interface RedisEmbeddingCacheOptions {
    /** Placed before every key, so the cache owns a part of the keyspace. Defaults to `nexus:embedding:`. */
    prefix?: string;
    /**
     * Reads and writes a batch as one `MGET` and one script, which is one round trip. Defaults to
     * `true`. Set `false` on Redis Cluster, whose multi-key commands need every key in one slot: each
     * key then travels as its own command, sent all at once.
     */
    multiKey?: boolean;
}
/**
 * Vectors in Redis, shared by every process that reaches it. A batch is one `MGET` and one write, and
 * a vector is packed float32 in base64: about 8 KB for 1,536 dimensions, against about 30 KB as JSON.
 */
export declare class RedisEmbeddingCache implements EmbeddingCacheStore {
    private readonly send;
    private readonly prefix;
    private readonly multiKey;
    constructor(client: RedisEmbeddingCacheClient, options?: RedisEmbeddingCacheOptions);
    /** The vectors under these keys, in order, with `undefined` for each miss. */
    getMany(keys: readonly string[]): Promise<Array<number[] | undefined>>;
    /** Stores vectors, each for `ttlSeconds` when given. */
    setMany(entries: readonly EmbeddingCacheEntry[], ttlSeconds?: number): Promise<void>;
}
/**
 * Two caches as one: the near one, usually `MemoryEmbeddingCache`, answers first, and the far one,
 * usually shared, answers the rest in one call. A far hit is copied near, and a write goes to both.
 */
export declare function tieredEmbeddingCache(near: EmbeddingCacheStore, far: EmbeddingCacheStore): EmbeddingCacheStore;