embeddings.js

/**
 * WHAT THIS FILE DOES
 *
 * The only file that talks to outside AI services. Two functions, two vendors:
 *
 *   embedText(text)                -> Gemini  -> a 3072-number vector
 *   generateAnswer(context, q)     -> Groq    -> the final written answer
 *
 * Keeping both here means swapping providers is a one-file change: as long as
 * the replacements return the same shapes, nothing else in the project cares.
 *
 * One rule worth remembering: embedText() is used at BOTH ingest and query
 * time, and it must be the same model in both places. Vectors from different
 * models are not comparable, so mixing them silently breaks all search results.
 *
 * See docs/04-code-walkthrough.md for a line-by-line explanation.
 *
 * @author  Raqibul Hasan Moon <rhmoon21@gmail.com>
 * @created 2026-08-12
 */

const GEMINI_KEY = process.env.GEMINI_API_KEY;
const GEMINI_BASE = "https://generativelanguage.googleapis.com/v1/models";

/*
 * We're calling both APIs directly with Node.js's built-in fetch rather than the official SDKs. The reason is practical: Google's Node.js SDK routes requests through the v1beta endpoint by default, and gemini-embedding-001 isn't available there — only on v1. Direct fetch sidesteps that entirely and keeps the dependency count low.
*/

async function embedText(text) {
  const res = await fetch(
    `${GEMINI_BASE}/gemini-embedding-001:embedContent?key=${GEMINI_KEY}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ content: { parts: [{ text }] } }),
    },
  );
  const data = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(data));
  return data.embedding.values;
}

async function generateAnswer(context, question) {
  const res = await fetch("https://api.groq.com/openai/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.GROQ_API_KEY}`,
    },
    body: JSON.stringify({
      model: "llama-3.1-8b-instant",
      messages: [
        {
          role: "system",
          content:
            "You are a helpful assistant. Answer the question using only the context provided. If the context does not contain enough information, say so clearly.",
        },
        {
          role: "user",
          content: `Context:\n${context}\n\nQuestion: ${question}`,
        },
      ],
    }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(data));
  return data.choices[0].message.content;
}

module.exports = { embedText, generateAnswer };