Foundations

cosine.py# Cosine similarity from scratch — the heart of semantic search.
import math

def dot(a, b):
    return sum(x * y for x, y in zip(a, b))

def norm(a):
    return math.sqrt(sum(x * x for x in a))

def cosine(a, b):
    return dot(a, b) / (norm(a) * norm(b) + 1e-9)   # +tiny to avoid /0

# Pretend these are 4-number embeddings of three sentences.
car_wont_start   = [0.9, 0.1, 0.0, 0.2]
vehicle_no_crank = [0.8, 0.2, 0.1, 0.1]   # same meaning, different words
banana_bread     = [0.0, 0.1, 0.9, 0.8]   # unrelated topic

print('car vs vehicle :', round(cosine(car_wont_start, vehicle_no_crank), 3))
print('car vs banana  :', round(cosine(car_wont_start, banana_bread), 3))

chunk.pydef chunk_words(text, size=60, overlap=15):
    """Split text into ~size-word chunks that overlap by `overlap` words.
    Overlap keeps a fact whole even if it straddles a boundary."""
    words = text.split()
    chunks, i = [], 0
    step = size - overlap
    while i < len(words):
        chunks.append(' '.join(words[i:i + size]))
        i += step
    return chunks

doc = ('The checkout service reads orders from the queue. '
       'If the queue backs up, latency climbs and the pod restarts. '
       'To recover, drain the queue and scale the consumer group. '
       'Never restart the database to fix a queue problem.') * 1

for i, c in enumerate(chunk_words(doc, size=12, overlap=3)):
    print(f'chunk {i}: {c}')

mini_rag.pyimport math, re
from collections import Counter

# ---- 1. a FAKE embedder (deterministic bag-of-words). Swap for a real model later. ----
VOCAB = {}
def embed(text):
    counts = Counter(re.findall(r'[a-z]+', text.lower()))
    for w in counts:
        VOCAB.setdefault(w, len(VOCAB))
    vec = [0.0] * len(VOCAB)
    for w, c in counts.items():
        vec[VOCAB[w]] = float(c)
    return vec

def cosine(a, b):
    n = max(len(a), len(b)); a = a + [0.0]*(n-len(a)); b = b + [0.0]*(n-len(b))
    dot = sum(x*y for x, y in zip(a, b))
    na = math.sqrt(sum(x*x for x in a)); nb = math.sqrt(sum(x*x for x in b))
    return dot / (na*nb + 1e-9)

# ---- 2. index the documents (embed once, keep the vectors) ----
docs = [
    'To restart the checkout service, drain the queue then scale the consumer group.',
    'The billing service stores invoices in Postgres and retries failed charges.',
    'Never restart the database to fix a queue backlog; it makes recovery slower.',
]
index = [(d, embed(d)) for d in docs]

# ---- 3. retrieve: top-k chunks by cosine similarity to the question ----
def retrieve(question, k=2):
    q = embed(question)
    scored = sorted(index, key=lambda di: cosine(q, di[1]), reverse=True)
    return [d for d, _ in scored[:k]]

# ---- 4. augment: build a grounded prompt ----
def build_prompt(question, chunks):
    context = '\n'.join(f'[{i+1}] {c}' for i, c in enumerate(chunks))
    return (f'Answer ONLY from the context. Cite sources like [1].\n\n'
            f'Context:\n{context}\n\nQuestion: {question}\nAnswer:')

q = 'how do I restart checkout?'
chunks = retrieve(q)
print('RETRIEVED:')
for c in chunks: print('  -', c)
print('\nPROMPT SENT TO THE LLM:\n' + build_prompt(q, chunks))

generate.py# The generation step. Complete and correct; needs YOUR API key to actually run.
# pip install anthropic ; export ANTHROPIC_API_KEY=sk-...
from anthropic import Anthropic          # runs in your own environment, not the sandbox

client = Anthropic()
def generate(prompt):
    msg = client.messages.create(
        model='claude-opus-4-8',           # any current model id
        max_tokens=300,
        messages=[{'role': 'user', 'content': prompt}],
    )
    return msg.content[0].text

# answer = generate(build_prompt(q, retrieve(q)))
# print(answer)  ->  'Drain the queue, then scale the consumer group. [1]'