@allemandi/embed-utils/dist/utils/similarity.d.ts

Fast, type-safe utilities for comparing and searching vector embeddings.

/**
 * Calculates the cosine similarity between two vectors.
 * Cosine similarity measures how similar two vectors are, ranging from -1 (opposite) to 1 (identical).
 * @public
 * @param {number[]} vecA - First vector.
 * @param {number[]} vecB - Second vector.
 * @returns {number} - Cosine similarity score between `vecA` and `vecB`.
 * @example
 * computeCosineSimilarity([1, 2, 3], [1, 2, 3]);
 * // => 1 (identical vectors)
 * computeCosineSimilarity([1, 0], [0, 1]);
 * // => 0 (orthogonal vectors)
 * computeCosineSimilarity([1, 2], [2, 3]);
 * // => 0.9922778767136677
 * computeCosineSimilarity([1, 0], [-1, 0]);
 * // => -1 (vectors diametrically opposed)
 * computeCosineSimilarity([0, 0], [1, 2]);
 * // => 0 (one vector has zero magnitude)
 */
export function computeCosineSimilarity(vecA: number[], vecB: number[]): number;
/**
 * Normalizes a vector to unit length. If the vector has zero magnitude, returns the original vector.
 * @public
 * @param {number[]} vec - Input vector.
 * @returns {number[]} - A new vector scaled to unit length.
 * @example
 * normalizeVector([3, 4]);
 * // => [0.6, 0.8] (vector normalized to length 1)
 * normalizeVector([0, 0]);
 * // => [0, 0] (zero vector remains unchanged)
 * normalizeVector([1, 1, 1]);
 * // => [0.5773502691896258, 0.5773502691896258, 0.5773502691896258]
 */
export function normalizeVector(vec: number[]): number[];
/**
 * Efficiently checks if a vector is L2-normalized (unit length).
 * @public
 * @param {number[]} vec - Input vector.
 * @param {number} [epsilon=1e-6] - Tolerance for floating-point comparison.
 * @returns {boolean} - True if the L2 norm is within epsilon of 1.
 * @example
 * isNormalized([1, 0]);
 * // => true (vector length is exactly 1)
 * isNormalized([0.6, 0.8]);
 * // => true (approximately unit length)
 * isNormalized([3, 4]);
 * // => false (length is 5)
 * isNormalized([0, 0]);
 * // => false (length is 0)
 */
export function isNormalized(vec: number[], epsilon?: number): boolean;
/**
 * Computes the mean (centroid) vector from an array of vectors.
 * Assumes all vectors are of equal length.
 * @public
 * @param {number[][]} vectors - Array of input vectors.
 * @returns {number[]} - The mean vector.
 * @example
 * meanVector([[1, 2], [3, 4], [5, 6]]);
 * // => [3, 4]
 * meanVector([]);
 * // => []
 */
export function meanVector(vectors: number[][]): number[];
//# sourceMappingURL=similarity.d.ts.map