Avoid overflow and underflow in cosine similarity for finite vectors

[pralav-25]

Cosine similarity of identical vectors such as [1e200, 2e200] returns NaN, while [1e-200, 2e-200] raises ZeroDivisionError. Scale each vector independently by its largest absolute component before computing products and norms, and use math.fsum for accumulation. Generator expressions retain constant auxiliary space.

Tests independent positive scale factors for same, opposite, perpendicular and general directions, the largest finite float and smallest subnormal, and the existing zero-vector and dimension-mismatch exceptions.

Validation on Python 3.12.14:

• The new test file reproduced 10 failing cases on unmodified main.
• python -m pytest -q: 615 passed.
• python -m pytest --doctest-modules algorithms/ -q: 480 passed, 1 skipped.
• ruff check algorithms/ tests/ and git diff --check: passed.

Prepared with AI assistance; the failures and fixes above were reproduced locally.

Summary by CodeRabbit

• Bug Fixes
  • Cosine similarity now handles vectors with very large or very small component values more reliably, including values near the limits of floating-point representation.
  • Results remain consistent when vectors are independently scaled, and zero vectors and mismatched vector lengths continue to raise errors.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 0fbacc71-7f6c-4abd-ad12-4069698a525f

📥 Commits

Reviewing files that changed from the base of the PR and between bd1d152 and fdbf4a3.

📒 Files selected for processing (2)

• algorithms/math/cosine_similarity.py
• tests/test_cosine_scaling.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Cosine similarity now scales vectors before computing norms and the dot product, and uses math.fsum for numerical accumulation. New tests cover scaled and extreme values, zero vectors, and mismatched vector lengths.

Changes

Cosine similarity stability

Layer / File(s)	Summary
Scaled calculation and validation algorithms/math/cosine_similarity.py, tests/test_cosine_scaling.py	_l2_distance accepts iterables and uses math.fsum. cosine_similarity scales each vector by its largest absolute component before calculating norms and the dot product. Tests cover independent scaling, extreme values, zero vectors, and mismatched lengths.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: keon

Merge Risk: ⚪ Minimal · up to fdbf4

The changed calculation preserves the checked error behavior, with no identified issue requiring a fix before merge.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preventing overflow and underflow in cosine similarity calculations for finite vectors.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 2 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}