feat(lib): add Unlimiformer-style kNN attention retrieval helpers

[kayo09]

Implement the score-and-top-k pattern from Bertsch et al. (arXiv:2305.01625) for embedding vectors: dot-product attention scores with top-k key selection, plus multi-head and generic item ranking utilities. Add Bun tests and a test script for @repo/lib.

[entelligence-ai-pr-reviews]

EntelligenceAI PR Summary

Implements Unlimiformer-style kNN retrieval in packages/lib/unlimiformer.ts and adds full test coverage in packages/lib/unlimiformer.test.ts, with test runner configuration in packages/lib/package.json.

• attentionScore: dot-product/cosine similarity between a single query and key vector
• attentionScores: computes scores against all keys in a set
• topKAttentionKeys: returns top-k keys sorted by descending score with k-capping
• topKAttentionKeysMultiHead: independent per-head top-k selection across multiple query vectors
• rankItemsByAttentionTopK: generic top-k ranking over arbitrary typed items via an embedding accessor, skipping null/empty embeddings
• Test suite validates edge cases, ordering correctness, and original index preservation

---

Confidence Score: 5/5 - Safe to Merge

Safe to merge — this PR cleanly introduces isFiniteEmbeddingVector as a defensive guard in unlimiformer.ts, integrating it correctly into attentionScore, attentionScores, and rankItemsByAttentionTopK to prevent non-finite embedding vectors from causing downstream errors in cosineSimilarity. The implementation follows a consistent pattern: invalid inputs return NaN or are skipped/return empty arrays, which is a well-reasoned fail-safe contract. No review comments were generated and both changed files received coverage, indicating a focused, well-scoped change with accompanying test coverage.

Key Findings:

• isFiniteEmbeddingVector is integrated at all relevant entry points (attentionScore, attentionScores, rankItemsByAttentionTopK), ensuring consistent guard behavior without gaps in the validation surface.
• Returning NaN from attentionScore/attentionScores on invalid input is a predictable, documented contract that callers can reason about, avoiding silent corruption of ranking results.
• Test coverage was added alongside the feature, validating the non-finite vector edge cases that motivated the change — this reduces regression risk for the new guard logic.
• No critical, significant, or medium-severity issues were identified by automated review; all changed files were reviewed with zero unresolved comments.

Files requiring special attention

• unlimiformer.ts

[entelligence-ai-pr-reviews]

Walkthrough

This PR introduces a new unlimiformer.ts module implementing Unlimiformer-style kNN retrieval (Bertsch et al., 2023) with five exported functions for attention score computation and top-k key retrieval, including multi-head and generic typed-item ranking support. A corresponding test suite is added using Bun's test runner, and the library's package.json is updated to enable test execution via bun test.

Changes

File(s)	Summary
packages/lib/unlimiformer.ts	New module implementing Unlimiformer-style kNN retrieval with five exported functions: attentionScore, attentionScores, topKAttentionKeys, topKAttentionKeysMultiHead, and rankItemsByAttentionTopK.
packages/lib/unlimiformer.test.ts	New test file covering topKAttentionKeys (edge cases, cosine similarity ordering, k-capping), attentionScores (output length), topKAttentionKeysMultiHead (per-query independence), and rankItemsByAttentionTopK (index mapping, null embedding filtering).
packages/lib/package.json	Added scripts section with a test script running bun test.

---

🔗 Cross-Repository Impact Analysis

Enable automatic detection of breaking changes across your dependent repositories. → Set up now

Learn more about Cross-Repository Analysis

What It Does

• Automatically identifies repositories that depend on this code
• Analyzes potential breaking changes across your entire codebase
• Provides risk assessment before merging to prevent cross-repo issues

How to Enable

1. Visit Settings → Code Management
2. Configure repository dependencies
3. Future PRs will automatically include cross-repo impact analysis!

Benefits

• 🛡️ Prevent breaking changes across repositories
• 🔍 Catch integration issues before they reach production
• 📊 Better visibility into your multi-repo architecture

---