M05 — RAG / Retrieval Grounding

// acmeKb.mjs — the help-doc KB + pure-JS retrieval (no AI here).
export const DOCS = [
  "Returns: unworn items with tags can be returned within 30 days of delivery for a full refund.",
  "Shipping: standard shipping takes 3-5 business days; express is 1-2 days for $12.",
  "Warranty: all footwear carries a 1-year warranty against manufacturing defects.",
  "Refunds: refunds go to the original payment method within 5-7 business days of receiving the return.",
  "Order changes: you can change or cancel an order within 1 hour of placing it, before it ships.",
];

function cosine(a, b) {
  const dot = a.reduce((s, x, i) => s + x * b[i], 0);
  return dot / (Math.hypot(...a) * Math.hypot(...b));
}

export function topK(queryVec, docVecs, k = 2) {
  return docVecs
    .map((v, i) => [i, cosine(queryVec, v)])
    .sort((x, y) => y[1] - x[1])
    .slice(0, k)
    .map(([i]) => i);          // indices of the best-matching docs
}

// embed_voyage.mjs — Anthropic has NO embeddings model; use Voyage AI.
//   npm i voyageai   |   VOYAGE_API_KEY
import { VoyageAIClient } from "voyageai";

const vo = new VoyageAIClient({ apiKey: process.env.VOYAGE_API_KEY });

export async function embed(texts, inputType) {   // "document" | "query"
  const resp = await vo.embed({ input: texts, model: "voyage-4", inputType });
  return resp.data.map(d => d.embedding);          // list of 1024-d vectors
}

# embed_gemini.py — Gemini has a native embeddings model.
from google import genai
from google.genai import types

client = genai.Client()   # reads GEMINI_API_KEY

def embed(texts, input_type):   # "document" | "query"
    task = "RETRIEVAL_QUERY" if input_type == "query" else "RETRIEVAL_DOCUMENT"
    result = client.models.embed_content(
        model="gemini-embedding-001", contents=texts,
        config=types.EmbedContentConfig(task_type=task),
    )
    return [e.values for e in result.embeddings]

// embed_gemini.mjs — Gemini has a native embeddings model.
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});   // reads GEMINI_API_KEY

export async function embed(texts, inputType) {   // "document" | "query"
  const taskType = inputType === "query" ? "RETRIEVAL_QUERY" : "RETRIEVAL_DOCUMENT";
  const resp = await ai.models.embedContent({
    model: "gemini-embedding-001", contents: texts, config: { taskType },
  });
  return resp.embeddings.map(e => e.values);
}

# embed_openai.py — OpenAI has a native embeddings model.
from openai import OpenAI

client = OpenAI()   # reads OPENAI_API_KEY

def embed(texts, input_type=None):   # OpenAI has no document/query distinction
    result = client.embeddings.create(model="text-embedding-3-small", input=texts)
    return [d.embedding for d in result.data]   # list of 1536-d vectors

// embed_openai.mjs — OpenAI has a native embeddings model.
import OpenAI from "openai";

const client = new OpenAI();   // reads OPENAI_API_KEY

export async function embed(texts, _inputType) {   // no document/query distinction
  const resp = await client.embeddings.create({
    model: "text-embedding-3-small", input: texts,
  });
  return resp.data.map(d => d.embedding);          // list of 1536-d vectors
}

// rag.mjs — ties Steps 1+2 together. Works with ANY provider's embed()/generate().
import { DOCS, topK } from "./acmeKb.mjs";
import { embed } from "./embed_voyage.mjs";   // swap for embed_gemini / embed_openai

const DOC_VECS = await embed(DOCS, "document");  // index the KB once, at startup

export async function answer(question, generate) {
  const qVec = (await embed([question], "query"))[0];   // embed the question
  const hits = topK(qVec, DOC_VECS, 2);                 // nearest chunks (indices)
  const context = hits.map(i => DOCS[i]).join("\n");    // retrieved passages
  const prompt =
    "Answer the customer using ONLY the policy context below. " +
    "If the answer isn't in it, say you'll check with a colleague.\n\n" +
    `Context:\n${context}\n\nQuestion: ${question}`;
  return generate(prompt);            // generate() = a one-shot call to ANY chat model (M00)
}

// `generate` is literally M00: a one-shot Claude / Gemini / GPT call.
console.log(await answer("Can I return shoes I wore once?", generate));