Scoring Word Similarity

Welcome to the first lesson of our course, “Enhancing the Word Play Game with New Functionalities”. In this lesson, we will make our word prediction game more interactive and fair by adding a way to score player guesses. Instead of only rewarding exact matches, we want to give points for guesses that are close in meaning to the correct answer. This will make the game more fun and challenging, and it will feel more like how people actually use language.

By the end of this lesson, you’ll know how to compare two words for similarity and assign a score based on how close they are in meaning. This is a key step in building a smarter, more engaging game.

Semantic similarity is a way to measure how close two words are in meaning. For example, car and automobile mean almost the same thing, so they are semantically similar. On the other hand, car and banana are not similar at all.

Here’s a simple table to show some examples:

In our game, we want to reward players for making guesses that are close in meaning, not just exact matches. This makes the game fairer and more fun.

To compare word meanings, computers use something called word vectors or embeddings. You can think of a word vector as a list of numbers that represents the meaning of a word. Words with similar meanings have vectors that are close together.

For example, the word cat might be represented by a vector like [0.2, 0.5, 0.1, ...], and kitten might have a vector that is very close to it. The word banana would have a very different vector.

To get these vectors in JavaScript, we can use a service like the OpenAI API. This API can generate embeddings for words or phrases, which we can then use to compare their meanings.

We can measure how close two vectors are using a mathematical formula called cosine similarity:

$\text{cos}(\theta) = \frac{\mathbf{A} \cdot \mathbf{B}}{\|\mathbf{A}\| \|\mathbf{B}\|}$

Let’s break down the formula:

• $\mathbf{A}$ and $\mathbf{B}$ are the word vectors for the two words you want to compare. Each vector is a list of numbers that represents the meaning of a word.
• $\mathbf{A} \cdot \mathbf{B}$ is the dot product of the two vectors. This is a way to combine the two lists of numbers into a single value that reflects how much they point in the same direction.
• $\|\mathbf{A}\|$ and $\|\mathbf{B}\|$ are the lengths (also called the “norms” or “magnitudes”) of each vector. You can think of this as how long each arrow is if you drew it on a graph.
• $\frac{\mathbf{A} \cdot \mathbf{B}}{\|\mathbf{A}\| \|\mathbf{B}\|}$ divides the dot product by the lengths of the two vectors. This ensures the similarity score is always between -1 and 1, where 1 means the vectors point in exactly the same direction (very similar), 0 means they are completely unrelated, and -1 means they are opposite (which doesn’t usually happen with word vectors).

In simple terms, this formula measures how close the two word meanings are by looking at the angle between their vectors: the smaller the angle, the more similar the words.

Let’s build our guess scorer step by step in JavaScript.

First, we need to import the OpenAI library and create a client using your API key. This will let us request word embeddings from the OpenAI API.

const OpenAI = require('openai');
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

• require('openai') imports the OpenAI library.
• new OpenAI({ apiKey: ... }) creates a client that can talk to the OpenAI API.

Next, we need to prepare the user’s guess and the correct word as an array of lowercase strings. This array will be sent to the API to get their embeddings.

const input = [userGuess.toLowerCase(), correctWord.toLowerCase()];

• We use .toLowerCase() to make sure the comparison is case-insensitive.
• Both words are put into an array, which the API will process together.

Now, we can use the OpenAI API to get the embeddings for both words, and then calculate the cosine similarity between them.

const res = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input
});
const [v1, v2] = res.data.map(d => d.embedding);

• client.embeddings.create sends the words to the API and gets their embeddings.
• res.data.map(d => d.embedding) extracts the embedding vectors for each word.

To calculate the cosine similarity, we use a helper function:

function cosineSimilarity(a, b) {
  if (!a?.length || !b?.length || a.length !== b.length) return 0;
  let dot = 0, na = 0, 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];
  }
  if (!na || !nb) return 0;
  return dot / (Math.sqrt(na) * Math.sqrt(nb));
}

• This function takes two vectors and returns a similarity score between -1 and 1.

To make the score easier to understand, we multiply it by 100 to get a value between 0 and 100.

const sim = cosineSimilarity(v1, v2);
return sim * 100;

Here is the complete function:

const OpenAI = require('openai');
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

function cosineSimilarity(a, b) {
  if (!a?.length || !b?.length || a.length !== b.length) return 0;
  let dot = 0, na = 0, 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];
  }
  if (!na || !nb) return 0;
  return dot / (Math.sqrt(na) * Math.sqrt(nb));
}

async function scoreGuess(userGuess, correctWord) {
  try {
    const input = [userGuess.toLowerCase(), correctWord.toLowerCase()];
    const res = await client.embeddings.create({
      model: 'text-embedding-3-small',
      input
    });
    const [v1, v2] = res.data.map(d => d.embedding);
    const sim = cosineSimilarity(v1, v2);
    return sim * 100; // Scale to 0–100
  } catch (e) {
    console.error('❌ Embedding similarity failed:', e);
    return 0;
  }
}

Let’s see an example of how to use this function:

(async () => {
  console.log(await scoreGuess("cat", "kitten"));        // Output: e.g. 74.2
  console.log(await scoreGuess("car", "automobile"));    // Output: e.g. 87.5
  console.log(await scoreGuess("car", "banana"));        // Output: e.g. 12.3
})();

• The function gives a higher score for words that are close in meaning.
• The output values are just examples; your results may be slightly different depending on the API and model.

In this lesson, you learned how to make your word prediction game smarter by scoring guesses based on their meaning, not just their spelling. We talked about semantic similarity, word vectors (embeddings), and how to use the OpenAI API in JavaScript to compare words. You also saw how to build a function that gives a score from 0 to 100 for any two words.

This new scoring system will make your game more fun and fair, rewarding players for close guesses. In the next practice exercises, you’ll get hands-on experience using and testing this function. Get ready to see how your game can understand language just a little bit more like a human!