Similarity API

A simple and efficient API for comparing and ranking items by their semantic similarity. Uses embeddings under the hood but provides a clean, easy-to-use interface.

Installation

# First, install the required dependency
npm install ai

# Then copy similarity.ts into your project

Quick Start

import { Similarity } from './similarity';
import { openai } from "@ai-sdk/openai";

// Initialize
const similarity = new Similarity(
  openai.embedding("text-embedding-3-small")
);

// Rank items by similarity
const rankings = await similarity.rank([
  "pizza",
  "hamburger",
  "hot dog"
]);
// => [{ item: "hamburger", similarityScore: 0.89 }, ...]

API Reference

Creating an Instance

const similarity = new Similarity(model, options?);

Options:

interface SimilarityOptions {
  enableCache?: boolean;    // Default: true
  maxCacheSize?: number;    // Default: 1000
  maxRetries?: number;      // Default: 0
}

Methods

rank(items: T[]): Promise<RankedItem[]>

Ranks items by their similarity to the group.

const rankings = await similarity.rank([
  "reading a book",
  "watching movies",
  "skydiving"
]);

// Returns:
[
  { item: "reading a book", similarityScore: 0.92 },
  { item: "watching movies", similarityScore: 0.85 },
  { item: "skydiving", similarityScore: 0.72 }
]

compare(item1: T, item2: T): Promise

Directly compares two items.

const score = await similarity.compare("pizza", "hamburger");
// => 0.82 (higher means more similar)

findSimilar(target: T, items: T[]): Promise<RankedItem[]>

Finds items most similar to a target.

const similar = await similarity.findSimilar(
  "pizza",
  ["hamburger", "sushi", "pasta"]
);
// Returns items ranked by similarity to "pizza"

clearCache(): void

Clears the embedding cache.

similarity.clearCache();

Return Types

interface RankedItem<T> {
  item: T;
  similarityScore: number;  // Range: -1 to 1
}

Examples

Ranking Similar Items

const similarity = new Similarity(openai.embedding("text-embedding-3-small"));

const foods = [
  "pepperoni pizza",
  "cheese pizza",
  "sushi roll",
  "hamburger"
];

const rankings = await similarity.rank(foods);
console.log(rankings);
// Items most similar to the group will be ranked first

Finding Similar Items to a Target

const target = "pizza";
const foods = ["hamburger", "hot dog", "pasta", "sushi"];

const similar = await similarity.findSimilar(target, foods);
console.log(similar);
// Items most similar to "pizza" will be ranked first

Using with Options

const similarity = new Similarity(
  openai.embedding("text-embedding-3-small"),
  {
    enableCache: true,
    maxCacheSize: 5000,
    maxRetries: 2
  }
);

Error Handling

try {
  const rankings = await similarity.rank(items);
} catch (error) {
  if (error instanceof SimilarityError) {
    console.error("Similarity error:", error.message);
    if (error.cause) console.error("Caused by:", error.cause);
  }
}

Performance Tips

1. Enable caching when working with repeated items:

const similarity = new Similarity(model, { enableCache: true });

2. Adjust cache size based on your needs:

const similarity = new Similarity(model, { maxCacheSize: 5000 });

3. Add retries for reliability:

const similarity = new Similarity(model, { maxRetries: 2 });

Error Types

The API throws SimilarityError for all error cases, with descriptive messages and optional cause chaining:

• Invalid inputs
• Model errors
• Processing errors
• Configuration errors

Limitations

• Requires at least 2 items for ranking
• All items in an array must be non-null/undefined
• Similarity scores are between -1 and 1