/**
 * Optional embedding-based semantic search for Hippo.
 * Uses @xenova/transformers (local, zero API keys, ~22MB model).
 * Falls back silently if the library is not installed.
 */
import { MemoryEntry } from './memory.js';
/**
 * Per-model pooling dispatch for `@xenova/transformers`'s feature-extraction
 * pipeline. BGE family models were trained with CLS pooling (per BAAI's
 * official inference code in `FlagEmbedding`); MiniLM and most sentence-
 * transformers models use mean pooling. Unknown model ids default to mean
 * — that is the safe choice because most third-party models adopt the
 * sentence-transformers convention, and the alternative ('cls') silently
 * degrades vector quality for mean-pooling models.
 */
export declare function poolingFor(model: string): 'cls' | 'mean';
/**
 * Per-model input-prefix dispatch. The intfloat/e5 family was trained with
 * asymmetric "query: " / "passage: " prefixes — the model only matches the
 * two halves correctly when each side carries its prefix at inference. BGE
 * also has prefix conventions for some downstream tasks, but symmetric use
 * without prefixes is the documented default for `bge-*-en-v1.5`, so we leave
 * BGE alone here. Symmetric models (MiniLM, BGE) and unknown models return
 * an empty prefix.
 *
 * `role` semantics:
 *   - 'query'   — the text is the user's question / search input.
 *   - 'passage' — the text is a document being indexed.
 *   - undefined or absent — symmetric path; no prefix is applied even for
 *     asymmetric models (preserves backwards compatibility with the legacy
 *     two-argument `getEmbedding(text, model)` API).
 */
export type EmbeddingRole = 'query' | 'passage';
export declare function prefixFor(model: string, role?: EmbeddingRole): string;
/**
 * Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed.
 */
export declare function isEmbeddingAvailable(): boolean;
export declare function resolveEmbeddingModel(hippoRoot: string, explicitModel?: string): string;
export declare function resolveIndexedEmbeddingModel(hippoRoot: string, index?: Record<string, number[]>): string | null;
export declare function embeddingModelRequiresReindex(hippoRoot: string, model: string, index?: Record<string, number[]>): boolean;
/**
 * Get an embedding vector for a piece of text.
 * Returns an empty array if transformers is not available or fails.
 *
 * Pass `role: 'query'` / `'passage'` to engage asymmetric prefixing for
 * model families that require it (currently intfloat/e5-*). Omitting `role`
 * keeps the legacy symmetric behavior (no prefix), so BGE / MiniLM callers
 * don't need to change.
 */
export declare function getEmbedding(text: string, model?: string, role?: EmbeddingRole): Promise<number[]>;
/**
 * Cosine similarity between two vectors. Handles unnormalized vectors.
 * Returns 0 for empty or mismatched vectors.
 */
export declare function cosineSimilarity(a: number[], b: number[]): number;
/**
 * Load the cached embedding index from disk.
 * Returns an empty object if the file doesn't exist or is corrupt.
 */
export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
/**
 * Save the embedding index to disk.
 */
export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>): void;
/**
 * Embed a single memory entry and cache the result in the embedding index.
 */
export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string): Promise<void>;
/**
 * Embed all entries in hippoRoot that don't already have cached vectors.
 * Prunes orphaned embeddings for memories that no longer exist.
 * Returns the count of newly embedded entries.
 */
export declare function embedAll(hippoRoot: string, model?: string): Promise<number>;
//# sourceMappingURL=embeddings.d.ts.map