C · Embedding

/**
 * What it does: scores how close two vectors are by their angle, ignoring length.
 *
 * Cosine similarity: the angle between two vectors, ignoring their length.
 * 1 = same direction (same meaning), 0 = no relation in theory (real texts rarely go that low), −1 = opposite.
 * @example cosine([1, 0], [2, 0]) // 1 — same direction, different length
 */
export function cosine(a: number[], b: number[]): number {
  let dot = 0;
  let na = 0;
  let nb = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i]! * b[i]!;
    na += a[i]! * a[i]!;
    nb += b[i]! * b[i]!;
  }
  return dot / (Math.sqrt(na) * Math.sqrt(nb));
}

/**
 * What it does: measures the straight-line distance between two vectors, so smaller is closer.
 *
 * Euclidean (L2) distance: the straight-line distance between the two points.
 * 0 = the same point; bigger = further apart. Note the direction: SMALLER is closer.
 * @example l2([0, 0], [3, 4]) // 5
 */
export function l2(a: number[], b: number[]): number {
  let sum = 0;
  for (let i = 0; i < a.length; i++) sum += (a[i]! - b[i]!) ** 2;
  return Math.sqrt(sum);
}

// ── YOUR TURN ───────────────────────────────────────────────────────────────────────────────────
// Write the sibling of cosine(): the dot product. Multiply the vectors element by element and sum.
// Unlike cosine it does NOT divide by the lengths. Check: npm run similar -- --metric dot → a score for each pair.
// Question to answer afterwards: step 4 printed "norm 1.000" for every vector — so for OUR vectors,
// how does dot() compare to cosine()?

/**
 * What it does: multiplies two vectors item by item and adds up the results.
 *
 * Dot product: sum of a[i] × b[i].
 * @example dot([1, 2, 3], [4, 5, 6]) // 32
 */
export function dot(a: number[], b: number[]): number {
  throw new Error("dot() is not written yet — see the YOUR TURN note above it in src/lib/similarity.ts");
}