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

Fast, type-safe utilities for vector embedding comparison and search.

/**
 * Calculates cosine similarity between two vectors.
 * Measures how similar their directions are, ignoring magnitude.
 * Use for comparing semantic or normalized vectors (e.g., text embeddings).
 *
 * @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.992...
 * 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;
/**
 * Calculates Euclidean distance between two vectors.
 * Measures straight-line distance considering both magnitude and direction.
 * Use for raw numeric data or spatial coordinates.
 *
 * @public
 * @param {number[]} vecA - First vector.
 * @param {number[]} vecB - Second vector.
 * @returns {number} - Euclidean distance between `vecA` and `vecB`.
 * @example
 * computeEuclideanDistance([1, 2], [4, 6]);
 * // => 5 (distance between (1,2) and (4,6))
 * computeEuclideanDistance([0, 0], [0, 0]);
 * // => 0 (identical vectors)
 * computeEuclideanDistance([1, 0], [0, 1]);
 * // => 1.414...
 * computeEuclideanDistance([1, 2, 3], [4, 5, 6]);
 * // => 5.196...
 */
export function computeEuclideanDistance(vecA: number[], vecB: number[]): number;
/**
 * Calculates Manhattan distance between two vectors.
 * Measures sum of absolute differences.
 * Use for grid-like data or when less sensitive to large differences.
 *
 * @public
 * @param {number[]} vecA - First vector.
 * @param {number[]} vecB - Second vector.
 * @returns {number} - Manhattan distance between `vecA` and `vecB`.
 * @example
 * computeManhattanDistance([1, 2, 3], [4, 5, 6]);
 * // => 9
 * computeManhattanDistance([1, 0], [0, 1]);
 * // => 2
 * computeManhattanDistance([1, 2], [1, 2]);
 * // => 0 (identical vectors)
 * computeManhattanDistance([1, -1], [-1, 1]);
 * // => 4
 */
export function computeManhattanDistance(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