Why RAG?

// demo-context-math.js: why "just paste everything" gets expensive
// EXAMPLE price only. Look up your provider's real price list.
const examplePricePerMillionInputTokens = 1.0; // US dollars, an example

const pages = 2000;            // a company wiki
const tokensPerPage = 700;     // rough guess for a page of text
const wholeWiki = pages * tokensPerPage;
const ragPrompt = 4 * 150 + 200; // 4 chunks of about 150 tokens + instructions + question

const cost = (tokens) => (tokens / 1_000_000) * examplePricePerMillionInputTokens;
console.log("paste the whole wiki:", wholeWiki.toLocaleString("en-US"), "tokens, $" + cost(wholeWiki).toFixed(4), "per question");
console.log("RAG prompt          :", ragPrompt.toLocaleString("en-US"), "tokens, $" + cost(ragPrompt).toFixed(4), "per question");
console.log("ratio:", Math.round(wholeWiki / ragPrompt) + "x");
// output
// paste the whole wiki: 1,400,000 tokens, $1.4000 per question
// RAG prompt          : 800 tokens, $0.0008 per question
// ratio: 1750x

INGEST  (offline, repeat when documents change)

  files ──► load ──► chunk ──► embed ──► store
  .md       read     cut into   text →    vector index
  .pdf      text     passages   numbers   (index.json)


QUERY   (online, for every question)

  question ──► embed ──► search ──► build prompt ──► generate ──► cite
               question  top-k      "Context: [1]…    the model    show
               → numbers chunks     Question: …"      writes       sources

mkdir raglab
cd raglab
npm init -y
npm pkg set type=module
mkdir src docs

raglab/
  mock-llm.js        the fake LLM server (section 6)
  package.json
  docs/              the sample documents (section 7)
  src/
    config.js        settings from environment variables
    client.js        chat() and ApiError         (from the chatbot series)
    stream.js        streaming reader            (from the chatbot series)
    conversation.js  conversation memory         (from the chatbot series)
    load.js          chapter 2
    chunk.js         chapter 2
    embed.js         chapter 3
    ...

Context:
[1] (source: membership.md#Membership fee) text...

[2] (source: ...) text...

Question: <the question>

PORT=8840 node mock-llm.js
# output
# mock LLM listening on http://localhost:8840  (api key: test-key)

curl -s http://localhost:8840/health
# output
# {"ok":true}

# Membership and Fees

## Membership fee

Membership costs 10 US dollars per term. A term lasts about four months.
The fee pays for snacks, printing, and the Wi-Fi bill. There is no fee
for the first month, so new students can try the club before paying.

## Scholarships

No student is turned away because of money. Students who cannot pay can
apply for a free scholarship membership by talking to the club treasurer,
Dara, after any Saturday session. Scholarship students have exactly the
same rights as paying members.

## How to pay

Pay the treasurer in cash, or send the fee by bank transfer. The club
does not accept payment through social media messages. Always ask for a
receipt.

## Refunds

If you leave in the first two months of a term, you can ask for half of
your fee back. After two months there are no refunds.

// demo-corpus-size.js
import fs from "node:fs";

let chars = 0;
for (const f of fs.readdirSync("docs")) chars += fs.readFileSync(`docs/${f}`, "utf8").length;
console.log(chars, "characters, about", Math.ceil(chars / 4), "tokens");
// output
// 7059 characters, about 1765 tokens

// demo-baseline.js: ask without giving the model any documents
import { chat } from "./src/client.js";

const question = "How much is the membership fee at Mekong Code Club?";
const { text, usage } = await chat({ messages: [{ role: "user", content: question }] });
console.log(text);
console.log(usage);

LLM_BASE_URL=http://localhost:8840 node demo-baseline.js
# output
# You said: How much is the membership fee at Mekong Code Club?
# { prompt_tokens: 13, completion_tokens: 16, total_tokens: 29 }

// naive-rag.js: the whole RAG loop in about 30 lines, with keyword matching
import fs from "node:fs";
import { chat } from "./src/client.js";

// 1. Load: one passage per paragraph, remembering file and heading.
const passages = [];
for (const file of fs.readdirSync("docs").filter((f) => f.endsWith(".md"))) {
  let heading = "";
  for (const para of fs.readFileSync(`docs/${file}`, "utf8").split(/\n\s*\n/)) {
    if (para.startsWith("#")) { heading = para.replace(/^#+\s*/, "").trim(); continue; }
    passages.push({ source: file, heading, text: para.replace(/\s+/g, " ").trim() });
  }
}

// 2. Search: count the words the question and the passage share.
const words = (s) => new Set(s.toLowerCase().match(/\p{L}{3,}/gu) ?? []);
function search(question, k = 2) {
  const q = words(question);
  return passages
    .map((p) => ({ p, score: [...words(p.text)].filter((w) => q.has(w)).length }))
    .filter((r) => r.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, k);
}

// 3. Build the prompt and 4. generate.
export async function ask(question) {
  const hits = search(question);
  const context = hits
    .map((h, i) => `[${i + 1}] (source: ${h.p.source}#${h.p.heading}) ${h.p.text}`)
    .join("\n\n");
  const prompt = `Context:\n${context}\n\nQuestion: ${question}`;
  const { text } = await chat({ messages: [{ role: "user", content: prompt }] });
  return { text, hits };
}

for (const q of process.argv.slice(2)) {
  const { text, hits } = await ask(q);
  console.log(`Q: ${q}`);
  console.log(`A: ${text}`);
  console.log("   found:", hits.map((h) => `${h.p.source}#${h.p.heading} (${h.score})`).join(", ") || "nothing");
}

LLM_BASE_URL=http://localhost:8840 node naive-rag.js \
  "How much is the membership fee per term?" \
  "How long can I borrow a laptop?" \
  "Who is the treasurer?" \
  "What is the Wi-Fi password?" \
  "Does the club teach Rust?" \
  "What time does the Saturday workshop start?"
# output
# Q: How much is the membership fee per term?
# A: Membership costs 10 US dollars per term. [1]
#    found: membership.md#Membership fee (5), membership.md#Refunds (3)
# Q: How long can I borrow a laptop?
# A: You can bring your own, or borrow one of the club laptops if you are eligible. [1]
#    found: faq.md#Do I need my own laptop? (3), laptops.md#Who can borrow (3)
# Q: Who is the treasurer?
# A: I don't know based on the provided documents.
#    found: membership.md#Scholarships (3), about.md#About Mekong Code Club (2)
# Q: What is the Wi-Fi password?
# A: I don't know based on the provided documents.
#    found: laptops.md#Rules (2), about.md#About Mekong Code Club (1)
# Q: Does the club teach Rust?
# A: I don't know based on the provided documents.
#    found: membership.md#How to pay (3), projects.md#Prizes (3)
# Q: What time does the Saturday workshop start?
# A: The main workshop runs every Saturday from 9:00 to 12:00. [1]
#    found: schedule.md#Saturday workshops (4), laptops.md#How long (3)

// Settings come from environment variables, with safe local defaults.
export const baseUrl = process.env.LLM_BASE_URL ?? "http://localhost:8787";
export const apiKey = process.env.LLM_API_KEY ?? "test-key";
export const defaultModel = process.env.LLM_MODEL ?? "mock-1";
export const embedModel = process.env.LLM_EMBED_MODEL ?? "mock-embed";

// mock-llm.js — a tiny fake LLM server with a chat-completions-style API.
// Zero dependencies. Run: node mock-llm.js   (default port 8787)
import http from "node:http";

const KEY = "test-key";
let requestCount = 0;

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const estimateTokens = (text) => Math.max(1, Math.ceil(text.length / 4));


const STOP = new Set("a an the is are was were be to of in on at for and or but with by from as it its this that these those i you we they he she what when where who which how do does did can could should would will my your our their me us about into than then there here not no yes if so also any all some more most".split(" "));
const DIM = 256;
export const contentWords = (text) =>
  text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/)
    .filter((w) => w && !STOP.has(w)).map((w) => (w.length > 3 && w.endsWith("s") ? w.slice(0, -1) : w));

function hash(word) { // FNV-1a
  let h = 2166136261;
  for (const ch of word) { h ^= ch.codePointAt(0); h = Math.imul(h, 16777619) >>> 0; }
  return h;
}

// A toy embedding: hash each word into one of 256 slots, then normalise.
export function embedText(text) {
  const v = new Array(DIM).fill(0);
  for (const w of contentWords(text)) v[hash(w) % DIM] += 1;
  const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1;
  return v.map((x) => Number((x / norm).toFixed(6)));
}

// If the last user message has a "Context:" block of [n] passages, answer from it.
function ragReply(content, say) {
  const [ctx, ...rest] = content.split(/\n\s*Question:/);
  const question = rest.join(" ").trim();
  const passages = [...ctx.matchAll(/^\[(\d+)\][^\n]*\n?([\s\S]*?)(?=^\[\d+\]|$(?![\s\S]))/gm)]
    .map((m) => ({ n: m[1], text: m[0].replace(/^\[\d+\]\s*(\(source:[^)]*\))?\s*/, "").trim() }));
  const q = new Set(contentWords(question));
  let best = null;
  for (const p of passages) {
    for (const sentence of p.text.split(/(?<=[.!?])\s+/)) {
      const score = contentWords(sentence).filter((w) => q.has(w)).length;
      if (!best || score > best.score) best = { score, sentence: sentence.trim(), n: p.n };
    }
  }
  if (!best || best.score < 2) return say("I don't know based on the provided documents.");
  return say(`${best.sentence} [${best.n}]`);
}

function makeReply(messages) {
  const users = messages.filter((m) => m.role === "user");
  const last = (users.at(-1)?.content ?? "").toLowerCase();
  const system = messages.find((m) => m.role === "system")?.content ?? "";
  const pirate = system.toLowerCase().includes("pirate");
  const say = (t) => (pirate ? `Arr! ${t}` : t);

  if (/^\s*Context:/.test(users.at(-1)?.content ?? "")) return ragReply(users.at(-1).content, say);
  if (/\bjson\b/.test(last)) return '{"answer": "mock json", "confidence": 0.9}';
  if (/what('| i)s my name|who am i/.test(last)) {
    for (const m of [...users].reverse()) {
      const hit = m.content.match(/my name is (\w+)/i);
      if (hit) return say(`Your name is ${hit[1]}.`);
    }
    return say("I do not know your name yet. You have not told me.");
  }
  if (/\b(hello|hi|hey)\b/.test(last)) return say("Hello! How can I help you today?");
  if (/phnom penh/.test(last)) return say("Phnom Penh is the capital of Cambodia.");
  return say(`You said: ${users.at(-1)?.content ?? ""}`);
}

export function startMock(port = 8787) {
  const server = http.createServer(async (req, res) => {
    const send = (status, obj, headers = {}) => {
      res.writeHead(status, { "content-type": "application/json", ...headers });
      res.end(JSON.stringify(obj));
    };
    if (req.method === "GET" && req.url === "/health") return send(200, { ok: true });
    if (req.method === "POST" && req.url === "/v1/embeddings") {
      if (req.headers.authorization !== `Bearer ${KEY}`)
        return send(401, { error: { message: "invalid api key" } });
      let raw = "";
      for await (const chunk of req) raw += chunk;
      let body;
      try { body = JSON.parse(raw); } catch { return send(400, { error: { message: "body must be valid JSON" } }); }
      const inputs = Array.isArray(body.input) ? body.input : [body.input];
      if (!body.model || inputs.length === 0 || inputs.some((x) => typeof x !== "string" || x === ""))
        return send(400, { error: { message: "model and a non-empty string (or array of strings) input are required" } });
      const tokens = inputs.reduce((n, t) => n + estimateTokens(t), 0);
      return send(200, {
        model: body.model,
        data: inputs.map((t, index) => ({ index, embedding: embedText(t) })),
        usage: { prompt_tokens: tokens, total_tokens: tokens },
      });
    }
    if (req.method !== "POST" || req.url !== "/v1/chat/completions")
      return send(404, { error: { message: "not found" } });

    if (req.headers.authorization !== `Bearer ${KEY}`)
      return send(401, { error: { message: "invalid api key" } });

    let raw = "";
    for await (const chunk of req) raw += chunk;
    let body;
    try { body = JSON.parse(raw); } catch {
      return send(400, { error: { message: "body must be valid JSON" } });
    }
    const { model, messages, stream } = body;
    if (!model || !Array.isArray(messages) || messages.length === 0)
      return send(400, { error: { message: "model and messages are required" } });

    requestCount += 1;
    if (model === "mock-flaky" && requestCount % 3 !== 0)
      return send(429, { error: { message: "rate limit, slow down" } }, { "retry-after": "0" });
    if (model === "mock-error") return send(500, { error: { message: "server exploded" } });
    if (model === "mock-slow") await sleep(3000);

    const text = makeReply(messages);
    const promptTokens = estimateTokens(messages.map((m) => m.content).join(" "));
    const completionTokens = estimateTokens(text);
    const usage = {
      prompt_tokens: promptTokens,
      completion_tokens: completionTokens,
      total_tokens: promptTokens + completionTokens,
    };

    if (!stream) {
      return send(200, {
        id: `mock-${requestCount}`,
        model,
        choices: [{ index: 0, message: { role: "assistant", content: text }, finish_reason: "stop" }],
        usage,
      });
    }

    res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
    const event = (obj) => res.write(`data: ${JSON.stringify(obj)}\n\n`);
    event({ id: `mock-${requestCount}`, choices: [{ index: 0, delta: { role: "assistant" } }] });
    for (const piece of text.match(/\S+\s*/g) ?? []) {
      await sleep(40);
      event({ id: `mock-${requestCount}`, choices: [{ index: 0, delta: { content: piece } }] });
    }
    event({ id: `mock-${requestCount}`, choices: [{ index: 0, delta: {}, finish_reason: "stop" }], usage });
    res.write("data: [DONE]\n\n");
    res.end();
  });
  return new Promise((resolve) => server.listen(port, () => resolve(server)));
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const port = Number(process.env.PORT ?? 8787);
  await startMock(port);
  console.log(`mock LLM listening on http://localhost:${port}  (api key: ${KEY})`);
}

# About Mekong Code Club

Mekong Code Club is a student coding club in Phnom Penh. It was started in
2021 by a group of university students who wanted a friendly place to
learn programming together. The club is fictional and is used only as
sample data for this tutorial.

## Our mission

We help students from grade 9 up to university learn to build real
software. We believe that everyone can learn to code if they have a
patient mentor, a working laptop, and a project they care about.

## Where we meet

The club meets in Room 204 of the Riverside Learning Center, near the
Tonle Sap river. The room has 24 seats, a projector, and fast Wi-Fi. The
building has a lift, so the room is accessible for wheelchair users.

## Who can join

Any student aged 14 to 25 can join. You do not need any experience. Many
of our members wrote their first line of code at the club.

# Weekly Schedule

## Saturday workshops

The main workshop runs every Saturday from 9:00 to 12:00. A mentor
teaches one topic, such as HTML, Python, or Git, and then members practice
with exercises. Doors open at 8:30 and close at 9:15, so please arrive on
time.

## Wednesday help desk

On Wednesday evenings from 18:00 to 20:00 the room is open for homework
help. Bring your own project or question. A mentor is always present, but
there is no formal lesson.

## Holidays

The club is closed during Khmer New Year, Pchum Ben, and the Water
Festival. We also close for two weeks at the end of each term. Closing
dates are announced on the notice board and in the members' chat group at
least two weeks ahead.

## Cancelled sessions

If a session is cancelled, for example because of heavy rain or a power
cut, the mentors post a message in the members' chat group before 7:00 on
the same day.

# Laptop Loan Policy

## Who can borrow

Some students do not own a laptop. The club owns eight laptops that paid
members and scholarship members can borrow. You must have been a member
for at least two weeks.

## How long

A laptop can be borrowed for up to 7 days. You can renew it once if nobody
is waiting. Laptops must be returned on a Saturday before the workshop
begins, so the mentors can check them.

## Rules

Do not install games or pirated software on a club laptop. Do not change
the administrator password. Keep food and drinks away from the laptop. If
the laptop is lost or broken because of carelessness, the borrower and a
parent or guardian will discuss a fair repair plan with the club
treasurer.

## Late returns

A laptop returned late loses its borrowing rights for one month. We use
this rule so that everyone gets a fair turn.

# Code of Conduct

## Be kind

Treat every member with respect. We do not allow insults, bullying, or
making fun of someone's questions. Everyone was a beginner once.

## Academic honesty

You may ask mentors and friends for help, but do not copy someone else's
project and present it as your own. When you use code from the internet
or from an AI assistant, say so in your project's README.

## Safety online

Never share passwords or API keys in the members' chat group. Do not run
code from strangers on the club network. If you find a security problem
in a club system, tell a mentor privately.

## What happens if rules are broken

First we talk with the member. A second serious problem leads to a
one-month pause. Repeated or very serious problems can end the
membership. Members can always appeal to the club president, Sophea.

# Projects and Showcase Day

## Term projects

Each term, members form teams of three or four and build one project. Past
projects include a bus timetable website, a chatbot that answers school
questions, and a small game about the history of Angkor. Teams choose
their own idea, with advice from a mentor.

## Showcase Day

At the end of each term the club holds Showcase Day. Teams present their
projects to parents, teachers, and local developers. Each team has 7
minutes to present and 3 minutes for questions. A panel of three guest
judges gives feedback, and the audience votes for the Favourite Project.

## Prizes

The winning team receives a small prize, such as a book voucher. The club
does not give cash prizes. Every participating member receives a
certificate.

## Sharing your work

Projects are published on the club's GitHub organization with an open
source licence, unless the team decides to keep it private. Never publish
personal data of other people in a project.

# Mentors

## Who our mentors are

Our mentors are volunteers: university students and working developers.
In the current term there are six mentors. They teach Python, web
development, mobile apps, and the basics of computers.

## Becoming a mentor

Members who have completed two terms can apply to become a junior mentor.
Junior mentors help during Saturday workshops and receive a mentor
certificate and a reference letter. Experienced developers who want to
volunteer can contact the club president, Sophea, to arrange a trial
session.

## What mentors do not do

Mentors do not do homework for you, and they do not take payment for
private lessons from members. If anyone asks you to pay a mentor
privately, please tell the club president.

## Mentor meeting

Mentors meet on the first Wednesday of every month at 19:00 to plan the
next topics. Members may suggest topics by writing on the notice board.

# Frequently Asked Questions

## How do I contact the club?

Send an email to hello@mekongcodeclub.example or message the club on its
public page. Emails are answered within three working days. This address
is fictional and used as sample data only.

## Do I need my own laptop?

No. You can bring your own, or borrow one of the club laptops if you are
eligible. See the laptop loan policy.

## Can my parents visit?

Parents are welcome on Showcase Day. For normal workshops, parents may
wait in the lobby on the ground floor, because the room has only 24 seats.

## Is the club connected to a school?

No. The club is independent and not part of any school or company. It is
run by volunteers and paid for by membership fees and small donations.

## What programming languages do you teach?

We mostly teach Python and JavaScript. Other languages appear only in
special workshops.