<p>We are going to walk through a small RAG chatbot you can run, line by line, in the order the code actually runs. In the last tip we named the eight stages. This time each stage is real Python.</p><p>The code is on GitHub, at <a href="https://github.com/mmmohajer/rag_step_by_step" target="_blank" rel="noopener noreferrer">https://github.com/mmmohajer/rag_step_by_step</a>. You do not need to write that down. The link is on the screen right now. If you are on the tip page, press copy on that box, or take it from the notes under the video. If you are watching on YouTube, it is in the description.</p><p>This is for you if you know those eight stages and you can read a Python function. By the end, you can point at the code that runs once when the program starts, and the code that runs on every question.</p><p>The example is a made-up company called Fieldnote. Its policy lives in two files. A web page covers billing and refunds. A voice recording covers passwords and locked accounts. Neither file has every answer, so the chatbot has to read both.</p><p>Everything starts in main.py, and we read it from the top. Each time a line calls a method, we open that method, read the lines that do the work, and then come back.</p><p>The first real line is rag = Rag(). That creates one object from the RAG class, in rag.py, which is the pipeline. Its init method has two lines. self.llm = Llm() creates a client from a second class, in llm.py. And self.stored equals an empty list. Hold on to that empty list. It comes back at stage four.</p><p>That Llm class is the only place that talks to OpenAI. Its own init stores the model names and sets the embedding size to 3072. Then it reads your OpenAI key from the .env file, raises an error if the key is missing, and creates the OpenAI client that every other method in that class uses.</p><p>Back in main.py, stage one is data equals rag.gather_info. Inside gather_info, a for loop walks every file in the sources folder. If the file is audio, like the MP3, it calls self.llm.stt, short for speech to text.</p><p>Over in the Llm class, stt opens the audio file, sends it to OpenAI's transcription endpoint with the Whisper model, and returns the text it gets back.</p><p>Back in gather_info, if the file is HTML instead, BeautifulSoup parses it, and get_text keeps only the words. Either way, the text is added to a list called texts, and that list is returned. For Fieldnote, it holds two texts, one per file.</p><p>Stage two in main.py is chunks equals rag.split(data). One embedding for a whole page blurs every topic on it together, so a narrow question matches it only weakly. That is why split cuts each text into smaller chunks. Its defaults are a size of one thousand characters and an overlap of two hundred. Step equals size minus overlap, so step is eight hundred. Then a while loop slices one thousand characters, adds that chunk, and moves the start forward by eight hundred. So two hundred characters repeat between neighbours. That overlap matters, because a short sentence cut at the edge of one chunk still shows up whole in the next. For Fieldnote, two texts became three chunks.</p><p>Stage three is embedded equals rag.embed_chunks. For each chunk, it adds a small dictionary with two keys, chunk_text and chunk_embedding. The embedding comes from self.llm.build_embedding.</p><p>In the Llm class, build_embedding sends the text to the embeddings endpoint, with dimensions set to that same 3072. It takes the first embedding from the response, checks its length, and returns it. So back in embed_chunks, each dictionary keeps the words and their numbers together, and later a match can turn back into words.</p><p>Stage four is rag.store, with embedded. Inside, it is one line. self.stored equals a list of embedded. That is the empty list from init, now filled. In a real app, this goes into a permanent store, such as a database, so the work survives a restart. Here, for simplicity, it is a variable on the one RAG object. When the program stops, the list is gone, and the next run gathers and embeds everything again.</p><p>That is the end of setup. Those four stages ran once. Next, main.py enters a while true loop. Question equals input reads what you type. Typing exit breaks out of the loop, and an empty line goes back to the top. Every real question runs the next four stages.</p><p>Stage five is query_embedding equals rag.embed_query. Inside, it is one line that calls the same build_embedding as stage three, this time on your question. That is the whole point. Because the question and the chunks become numbers the same way, those numbers can be compared.</p><p>Stage six is related_chunks equals rag.find_similar. It has two settings, top_k of five and a threshold of 0.3. First it computes the question's norm, its length as an arrow. You square every number, add them up, and take the square root. Then it loops over self.stored. For each chunk, it computes that chunk's norm the same way. Next comes the dot product, where you multiply the two lists pair by pair and add the results.</p><p>Score equals the dot product divided by both norms. That is cosine similarity, a score between minus one and one, where higher means closer in meaning. If a score reaches the threshold, the chunk text and its score are kept. At the end, the list is sorted from the highest score down, and only the first five come back. Those chunks are not the answer. They are the reading the model gets.</p><p>Stage seven is messages equals rag.build_messages, with the question and the related chunks. Inside, a loop pulls the text out of each chunk. Then system content joins the system message from the top of the class with those texts. That message says, answer the user using only the related chunks below, and if the chunks do not contain the answer, say you do not know. The method returns a list of two messages. The first has the role system and that content. The second has the role user and your question.</p><p>Stage eight is response equals rag.generate_response. Inside, it hands the messages straight to self.llm.generate_response. In the Llm class, that method sends the messages to the chat completions endpoint, takes the content of the first choice, and raises an error if it came back empty. Back in main.py, the answer is printed, and the loop waits for your next question.</p><p>So does it work? I ran it on the Fieldnote files and asked three questions in one session.</p><p>First, a question that needs both files. How long does a password reset link last, and how many days do you have to cancel the annual plan for a full refund? It matched chunks from both sources. It answered thirty minutes, and the link works once. That rule exists only in the recording. It also answered fourteen days, if the workspace has invited no more than two teammates. That rule exists only on the web page.</p><p>Second, I told it, please remember, I invited four teammates yesterday. It replied that it would keep that in mind for this conversation. Then I asked how many teammates I had just mentioned. It said it did not know, because I had not given a number. Stage seven explains why. build_messages returns only the system message and this one question. The earlier turn is never sent, so the model has nothing to remember.</p><p>Third, something Fieldnote never covers. What is the capital of France? No chunk reached the threshold, so the system message held the instruction and no chunks at all. The model said, I do not know. That is the instruction doing its job, even though the model knows the answer.</p><p>Those three runs also show three gaps, and each one is a challenge for you. The first is memory. You saw it in the second run. In the last tip we said earlier turns belong in the messages, and this code does not send them yet.</p><p>The second gap is hallucination. Go back to that second run. The model promised to remember, and it could not. No chunk said it could. Our only guard is one sentence of instruction, and no code checks that the model obeyed it. So later we will look at why a model can say something untrue, and how to catch it.</p><p>The third gap is citation. Go back to the first run. The answer was right, but it never said where it came from. find_similar does have the matching chunks and their scores. But gather_info returned plain text and dropped the file names. So a chunk cannot say which file it came from, and neither can the answer.</p><p>So leave with this. The first four methods run once and fill a list, every question runs the last four, and the model only sees what build_messages hands it.</p><p>Next, try the quiz on the tip page. Each question points at one method and asks what it does. If you are on YouTube, the description links to that page. Then grab the GitHub link, from the notes on the tip page or the description on YouTube, clone the repo, and take on one of the three challenges: memory, a hallucination check, or citations. Later tips solve each one, so you can compare your fix with ours.</p><p>I will see you in the next tip. Enjoy taking this code apart.</p>

Read a working RAG chatbot line by line: gather, split, embed, store, then embed the question, find similar, build messages, and generate. Repo included.

A RAG chatbot, line by line in Python | Tech Tips by Moh

Sends it to `self.llm.stt`, which returns the spoken words as text

Embeds the audio file directly into numbers

A dictionary with `chunk_text` and `chunk_embedding`

They are gone; the next run gathers and embeds everything again

So the question and the chunks become numbers the same way and can be compared

So the question is saved next to the chunks

Because `build_embedding` is the only method that calls the chat model

It is kept, because every chunk goes to the model

It is dropped, because the score is under the 0.3 threshold

It is sent back to `split` to be cut smaller

`split`, because the message was too short to chunk

`find_similar`, because the threshold was too high

`build_messages`, because it sends only the system message and the current question

`generate_response`, because the model forgets after each call

A RAG chatbot, line by line in Python

<div class="course-slide cs-center">
  <p class="cs-kicker">Tip 9 · after the 8 stages</p>
  <h2 class="cs-title cs-at-3-3">RAG, <span class="cs-hl">line by line</span></h2>
  <p class="cs-pill cs-at-10-7">Each stage is real Python</p>
</div>

<div class="course-slide">
  <p class="cs-kicker">The code</p>
  <h2 class="cs-title">The <span class="cs-hl">repo</span> for this tip</h2>
  <div class="cs-code cs-at-0-6">
    <div class="cs-code-bar"><span class="cs-code-path">GitHub</span></div>
    <pre class="cs-code-body">https://github.com/mmmohajer/rag_step_by_step</pre>
  </div>
  <p class="cs-pill cs-at-14-1">Tip page: press Copy, or open the notes</p>
  <p class="cs-pill cs-at-18-8">YouTube: the link is in the description</p>
</div>

<div class="course-slide">
  <p class="cs-kicker">Before we start</p>
  <ul class="cs-checks">
    <li class="cs-at-1-1">You know the 8 stages</li>
    <li class="cs-at-2-7">You can read a Python function</li>
  </ul>
  <h2 class="cs-title cs-at-4-1">By the end, you can point at</h2>
  <div class="cs-grid cs-cols-2">
    <div class="cs-card cs-at-6-4"><p class="cs-card-label">Stages 1–4</p><p class="cs-card-title">Code that runs once, at startup</p></div>
    <div class="cs-card cs-card-accent cs-at-9-2"><p class="cs-card-label">Stages 5–8</p><p class="cs-card-title">Code that runs on every question</p></div>
  </div>
</div>

<div class="course-slide cs-center">
  <p class="cs-kicker">The example: Fieldnote</p>
  <h2 class="cs-title cs-at-4-1">One policy, <span class="cs-hl">two files</span></h2>
  <p class="cs-pill cs-at-5-4">Webpage: billing and refunds</p>
  <p class="cs-pill cs-at-7-7">Voice recording: passwords and lockouts</p>
</div>

<div class="course-slide">
  <p class="cs-kicker">How we read it</p>
  <h2 class="cs-title">Start at the top of <span class="cs-hl">main.py</span></h2>
  <ol class="cs-steps">
    <li>Read <span class="cs-mono">main.py</span> from the top</li>
    <li class="cs-at-3-7">A line calls a method: open it</li>
    <li class="cs-at-7">Read the lines that do the work</li>
    <li class="cs-at-8-7">Come back to <span class="cs-mono">main.py</span></li>
  </ol>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Setup · the pipeline object · main.py · line 5</span></div>
    <pre class="cs-code-body cs-lines cs-from-5"><span class="cs-ln cs-focus-at-0">rag = Rag()</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 10–19</span></div>
    <pre class="cs-code-body cs-lines cs-from-10"><span class="cs-ln cs-focus-at-4-7"><span class="cs-key">class</span> Rag:</span>
<span class="cs-ln cs-gap">  # 6 lines</span>
<span class="cs-ln cs-from-17 cs-focus-at-8-2">    <span class="cs-key">def</span> __init__(self):</span>
<span class="cs-ln cs-focus-at-8-2 cs-focus-at-10-7">        self.llm = Llm()</span>
<span class="cs-ln cs-focus-at-8-2 cs-focus-at-16-8">        self.stored = []</span></pre>
  </div>
  <p class="cs-pill cs-at-13-8">Llm lives in <span class="cs-mono">services/llm.py</span></p>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Setup · Llm, the OpenAI client · services/rag.py · line 18</span></div>
    <pre class="cs-code-body cs-lines cs-from-18"><span class="cs-ln cs-focus-at-0">self.llm = Llm()</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/llm.py · lines 10–24</span></div>
    <pre class="cs-code-body cs-lines cs-from-10"><span class="cs-ln cs-focus-at-0-1"><span class="cs-key">class</span> Llm:</span>
<span class="cs-ln">    <span class="cs-key">def</span> __init__(</span>
<span class="cs-ln">        self,</span>
<span class="cs-ln cs-focus-at-4-5">        embedding_model: str = "text-embedding-3-large",</span>
<span class="cs-ln cs-focus-at-4-5">        chat_model: str = "gpt-6-astra",</span>
<span class="cs-ln cs-focus-at-4-5">        stt_model: str = "whisper-1",</span>
<span class="cs-ln">    ) -&gt; None:</span>
<span class="cs-ln cs-focus-at-6">        self.embedding_dimension = 3072</span>
<span class="cs-ln cs-focus-at-4-5">        self.embedding_model = embedding_model</span>
<span class="cs-ln cs-focus-at-4-5">        self.chat_model = chat_model</span>
<span class="cs-ln cs-focus-at-4-5">        self.stt_model = stt_model</span>
<span class="cs-ln cs-focus-at-9-9">        api_key = os.getenv("OPEN_AI_API_KEY", "").strip()</span>
<span class="cs-ln cs-focus-at-12-9">        <span class="cs-key">if</span> not api_key:</span>
<span class="cs-ln cs-focus-at-12-9">            raise ValueError("OPEN_AI_API_KEY is not set")</span>
<span class="cs-ln cs-focus-at-15-1">        self._client = OpenAI(api_key=api_key)</span></pre>
  </div>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 1 · Gather · main.py · line 10</span></div>
    <pre class="cs-code-body cs-lines cs-from-10"><span class="cs-ln cs-focus-at-0">data = rag.gather_info()</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 21–35</span></div>
    <pre class="cs-code-body cs-lines cs-from-21"><span class="cs-ln cs-focus-at-5-3">    <span class="cs-key">def</span> gather_info(self):</span>
<span class="cs-ln">        texts = []</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-6-8">        <span class="cs-key">for</span> path in sorted(SOURCES_DIR.iterdir()):</span>
<span class="cs-ln">            <span class="cs-key">if</span> not path.is_file():</span>
<span class="cs-ln">                continue</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-9-7">            suffix = path.suffix.lower()</span>
<span class="cs-ln cs-focus-at-9-7">            <span class="cs-key">if</span> suffix in VOICE_SUFFIXES:</span>
<span class="cs-ln cs-focus-at-9-7 cs-focus-at-12-5">                texts.append(self.llm.stt(str(path)))</span>
<span class="cs-ln">            <span class="cs-key">elif</span> suffix in {".html", ".htm"}:</span>
<span class="cs-ln">                soup = BeautifulSoup(path.read_text(encoding="utf-8"), "html.parser")</span>
<span class="cs-ln">                texts.append(soup.get_text(separator="\n", strip=True))</span>
<span class="cs-ln"></span>
<span class="cs-ln">        <span class="cs-key">return</span> texts</span></pre>
  </div>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 1 · speech to text · services/rag.py · line 30</span></div>
    <pre class="cs-code-body cs-lines cs-from-30"><span class="cs-ln cs-focus-at-0">texts.append(self.llm.stt(str(path)))</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/llm.py · lines 56–69</span></div>
    <pre class="cs-code-body cs-lines cs-from-56"><span class="cs-ln cs-focus-at-2-2">    <span class="cs-key">def</span> stt(self, audio_path: str) -&gt; str:</span>
<span class="cs-ln">        <span class="cs-key">if</span> not audio_path.strip():</span>
<span class="cs-ln">            raise ValueError("audio path is empty")</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-2-6">        <span class="cs-key">with</span> open(audio_path, "rb") as audio_file:</span>
<span class="cs-ln cs-focus-at-4-4">            response = self._client.audio.transcriptions.create(</span>
<span class="cs-ln cs-focus-at-4-4">                model=self.stt_model,</span>
<span class="cs-ln cs-focus-at-4-4">                file=audio_file,</span>
<span class="cs-ln cs-focus-at-4-4">            )</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-7-9">        transcript = response.text.strip()</span>
<span class="cs-ln">        <span class="cs-key">if</span> not transcript:</span>
<span class="cs-ln">            raise ValueError("model returned an empty transcript")</span>
<span class="cs-ln cs-focus-at-7-9">        <span class="cs-key">return</span> transcript</span></pre>
  </div>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 1 · Gather, the HTML file · main.py · line 10</span></div>
    <pre class="cs-code-body cs-lines cs-from-10"><span class="cs-ln cs-focus-at-0">data = rag.gather_info()</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 21–35</span></div>
    <pre class="cs-code-body cs-lines cs-from-21 cs-focus-at-12-1"><span class="cs-ln">    <span class="cs-key">def</span> gather_info(self):</span>
<span class="cs-ln cs-focus-at-9-3">        texts = []</span>
<span class="cs-ln"></span>
<span class="cs-ln">        <span class="cs-key">for</span> path in sorted(SOURCES_DIR.iterdir()):</span>
<span class="cs-ln">            <span class="cs-key">if</span> not path.is_file():</span>
<span class="cs-ln">                continue</span>
<span class="cs-ln"></span>
<span class="cs-ln">            suffix = path.suffix.lower()</span>
<span class="cs-ln">            <span class="cs-key">if</span> suffix in VOICE_SUFFIXES:</span>
<span class="cs-ln cs-focus-at-8-4">                texts.append(self.llm.stt(str(path)))</span>
<span class="cs-ln cs-focus-at-1-2">            <span class="cs-key">elif</span> suffix in {".html", ".htm"}:</span>
<span class="cs-ln cs-focus-at-3-5">                soup = BeautifulSoup(path.read_text(encoding="utf-8"), "html.parser")</span>
<span class="cs-ln cs-focus-at-5-1 cs-focus-at-8-4">                texts.append(soup.get_text(separator="\n", strip=True))</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-11">        <span class="cs-key">return</span> texts</span></pre>
  </div>
</div>

<div class="course-slide cs-center">
  <p class="cs-kicker">Stage 2 · Split</p>
  <p class="cs-pill cs-at-2-6"><span class="cs-mono">chunks = rag.split(data)</span></p>
  <h2 class="cs-title cs-at-6-9">One page, one <span class="cs-bad">blurry</span> match</h2>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 2 · Split · main.py · line 14</span></div>
    <pre class="cs-code-body cs-lines cs-from-14"><span class="cs-ln cs-focus-at-0">chunks = rag.split(data)</span></pre>
  </div>
  <div class="cs-split cs-split-code">
    <div class="cs-code">
      <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 37–55</span></div>
      <pre class="cs-code-body cs-lines cs-from-37"><span class="cs-ln cs-focus-at-0-5">    <span class="cs-key">def</span> split(self, texts, size=1000, overlap=200):</span>
<span class="cs-ln cs-gap">  # 6 lines</span>
<span class="cs-ln cs-from-44 cs-focus-at-8-1">        step = size - overlap</span>
<span class="cs-ln">        <span class="cs-key">for</span> text in texts:</span>
<span class="cs-ln cs-gap">  # 4 lines</span>
<span class="cs-ln cs-from-50">            start = 0</span>
<span class="cs-ln cs-focus-at-13-1">            <span class="cs-key">while</span> start &lt; len(cleaned):</span>
<span class="cs-ln cs-focus-at-13-1">                chunk = cleaned[start : start + size].strip()</span>
<span class="cs-ln cs-focus-at-13-1">                <span class="cs-key">if</span> chunk:</span>
<span class="cs-ln cs-focus-at-13-1 cs-focus-at-15-8">                    chunks.append(chunk)</span>
<span class="cs-ln cs-focus-at-13-1 cs-focus-at-16-8">                start += step</span></pre>
    </div>
    <div class="cs-stack">
      <div class="cs-card cs-at-0-5 cs-until-3-4"><p class="cs-card-label">Why</p><p class="cs-card-title">One topic per chunk, a sharper match</p></div>
      <div class="cs-card cs-at-3-4 cs-until-8-1"><p class="cs-card-label">Defaults</p><p class="cs-card-title">size 1000 characters, overlap 200</p></div>
      <div class="cs-card cs-card-accent cs-at-8-1 cs-until-13-1"><p class="cs-card-label">Step</p><p class="cs-card-title">1000 − 200 = 800</p></div>
      <div class="cs-card cs-at-13-1"><p class="cs-card-label">Loop</p><p class="cs-card-title">Slice 1000, add it, move 800</p></div>
    </div>
  </div>
</div>

<div class="course-slide cs-center">
  <p class="cs-kicker">Why overlap</p>
  <h2 class="cs-title cs-at-0-2">200 characters <span class="cs-hl">repeat</span></h2>
  <p class="cs-pill cs-at-4-5">A sentence cut at one edge is whole in the next</p>
  <p class="cs-pill cs-at-8-9">Fieldnote: 2 texts became 3 chunks</p>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 3 · Embed · main.py · line 18</span></div>
    <pre class="cs-code-body cs-lines cs-from-18"><span class="cs-ln cs-focus-at-0">embedded = rag.embed_chunks(chunks)</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 59–70</span></div>
    <pre class="cs-code-body cs-lines cs-from-59"><span class="cs-ln">    <span class="cs-key">def</span> embed_chunks(self, chunks):</span>
<span class="cs-ln">        embedded = []</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-3-1">        <span class="cs-key">for</span> chunk in chunks:</span>
<span class="cs-ln cs-focus-at-4-6">            embedded.append(</span>
<span class="cs-ln cs-focus-at-4-6">                {</span>
<span class="cs-ln cs-focus-at-4-6 cs-focus-at-7-2">                    "chunk_text": chunk,</span>
<span class="cs-ln cs-focus-at-4-6 cs-focus-at-7-2 cs-focus-at-9-3">                    "chunk_embedding": self.llm.build_embedding(chunk),</span>
<span class="cs-ln cs-focus-at-4-6">                }</span>
<span class="cs-ln cs-focus-at-4-6">            )</span>
<span class="cs-ln"></span>
<span class="cs-ln">        <span class="cs-key">return</span> embedded</span></pre>
  </div>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 3 · one call per chunk · services/rag.py · line 66</span></div>
    <pre class="cs-code-body cs-lines cs-from-66"><span class="cs-ln cs-focus-at-0">"chunk_embedding": self.llm.build_embedding(chunk),</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/llm.py · lines 26–41</span></div>
    <pre class="cs-code-body cs-lines cs-from-26"><span class="cs-ln cs-focus-at-1-2">    <span class="cs-key">def</span> build_embedding(self, text: str) -&gt; list[float]:</span>
<span class="cs-ln">        cleaned = text.strip()</span>
<span class="cs-ln">        <span class="cs-key">if</span> not cleaned:</span>
<span class="cs-ln">            raise ValueError("text is empty")</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-1-8">        response = self._client.embeddings.create(</span>
<span class="cs-ln cs-focus-at-1-8">            model=self.embedding_model,</span>
<span class="cs-ln cs-focus-at-1-8">            input=cleaned,</span>
<span class="cs-ln cs-focus-at-1-8 cs-focus-at-4-3">            dimensions=self.embedding_dimension,</span>
<span class="cs-ln cs-focus-at-1-8">        )</span>
<span class="cs-ln cs-focus-at-7-6">        embedding = response.data[0].embedding</span>
<span class="cs-ln cs-focus-at-10-1">        <span class="cs-key">if</span> len(embedding) != self.embedding_dimension:</span>
<span class="cs-ln cs-focus-at-10-1">            raise ValueError(</span>
<span class="cs-ln cs-focus-at-10-1">                f"expected {self.embedding_dimension} dimensions, got {len(embedding)}"</span>
<span class="cs-ln cs-focus-at-10-1">            )</span>
<span class="cs-ln cs-focus-at-11">        <span class="cs-key">return</span> embedding</span></pre>
  </div>
</div>

<div class="course-slide">
  <p class="cs-kicker">Stage 3 · back in embed_chunks</p>
  <h2 class="cs-title">Words and numbers, <span class="cs-hl">together</span></h2>
  <div class="cs-grid cs-cols-2">
    <div class="cs-card cs-at-3-1"><p class="cs-card-label">chunk_text</p><p class="cs-card-title">The words, to hand to the model</p></div>
    <div class="cs-card cs-at-3-9"><p class="cs-card-label">chunk_embedding</p><p class="cs-card-title">3072 numbers, to compare</p></div>
  </div>
  <p class="cs-pill cs-at-4-8">A match turns back into words</p>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 4 · Store · main.py · line 22</span></div>
    <pre class="cs-code-body cs-lines cs-from-22"><span class="cs-ln cs-focus-at-0">rag.store(embedded)</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 17–73</span></div>
    <pre class="cs-code-body cs-lines cs-from-17"><span class="cs-ln">    <span class="cs-key">def</span> __init__(self):</span>
<span class="cs-ln">        self.llm = Llm()</span>
<span class="cs-ln cs-focus-at-8-8 cs-focus-at-10-7">        self.stored = []</span>
<span class="cs-ln cs-gap">  # 52 lines</span>
<span class="cs-ln cs-from-72 cs-focus-at-3-4">    <span class="cs-key">def</span> store(self, embedded):</span>
<span class="cs-ln cs-focus-at-3-4 cs-focus-at-5-7 cs-focus-at-10-7">        self.stored = list(embedded)</span></pre>
  </div>
</div>

<div class="course-slide cs-center">
  <p class="cs-kicker">Stage 4 · in a real app</p>
  <h2 class="cs-title cs-at-3-2">A list here, a <span class="cs-hl">database</span> later</h2>
  <p class="cs-pill cs-at-5-6">Here: <span class="cs-mono">self.stored</span> on one Rag object</p>
  <p class="cs-pill cs-at-9-8">Program stops, the list is gone</p>
</div>

<div class="course-slide">
  <p class="cs-kicker">Setup ran once. Now the loop.</p>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">main.py · lines 27–33</span></div>
    <pre class="cs-code-body cs-lines cs-from-27"><span class="cs-ln cs-focus-at-6-2"><span class="cs-key">while</span> True:</span>
<span class="cs-ln cs-focus-at-7-6">    question = input(f"{BOLD}You{RESET}  ").strip()</span>
<span class="cs-ln cs-focus-at-10-4">    <span class="cs-key">if</span> question == "exit()":</span>
<span class="cs-ln cs-focus-at-10-4">        print("\nGoodbye.\n")</span>
<span class="cs-ln cs-focus-at-10-4">        break</span>
<span class="cs-ln cs-focus-at-12-6">    <span class="cs-key">if</span> not question:</span>
<span class="cs-ln cs-focus-at-12-6">        continue</span></pre>
  </div>
  <p class="cs-pill cs-at-1-9">Stages 1–4 ran once</p>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 5 · Embed the question · main.py · line 36</span></div>
    <pre class="cs-code-body cs-lines cs-from-36"><span class="cs-ln cs-focus-at-0">query_embedding = rag.embed_query(question)</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 66–76</span></div>
    <pre class="cs-code-body cs-lines cs-from-66"><span class="cs-ln cs-focus-at-9-5">                    "chunk_embedding": self.llm.build_embedding(chunk),</span>
<span class="cs-ln cs-gap">  # 8 lines</span>
<span class="cs-ln cs-from-75 cs-focus-at-7-5">    <span class="cs-key">def</span> embed_query(self, query):</span>
<span class="cs-ln cs-focus-at-7-5 cs-focus-at-9-5">        <span class="cs-key">return</span> self.llm.build_embedding(query)</span></pre>
  </div>
  <p class="cs-pill cs-at-13-8">Same method, so the numbers compare</p>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 6 · Find similar · main.py · line 40</span></div>
    <pre class="cs-code-body cs-lines cs-from-40"><span class="cs-ln cs-focus-at-0">related_chunks = rag.find_similar(query_embedding)</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · line 78</span></div>
    <pre class="cs-code-body cs-lines cs-from-78"><span class="cs-ln cs-focus-at-4-4">    <span class="cs-key">def</span> find_similar(self, query_embedding, top_k=5, threshold=0.3):</span></pre>
  </div>
  <div class="cs-row">
    <span class="cs-chip cs-at-5-4">top_k = 5</span>
    <span class="cs-chip cs-at-6-8">threshold = 0.3</span>
  </div>
</div>

<div class="course-slide">
  <p class="cs-kicker">Stage 6 · Find similar</p>
  <div class="cs-split cs-split-code">
    <div class="cs-code">
      <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 78–96</span></div>
      <pre class="cs-code-body cs-lines cs-from-78 cs-focus-at-38-2"><span class="cs-ln">    <span class="cs-key">def</span> find_similar(self, query_embedding, top_k=5, threshold=0.3):</span>
<span class="cs-ln cs-focus-at-0">        query_norm = sum(x * x for x in query_embedding) ** 0.5</span>
<span class="cs-ln">        <span class="cs-key">if</span> query_norm == 0:</span>
<span class="cs-ln">            <span class="cs-key">return</span> []</span>
<span class="cs-ln"></span>
<span class="cs-ln">        scored = []</span>
<span class="cs-ln cs-focus-at-8">        <span class="cs-key">for</span> item in self.stored:</span>
<span class="cs-ln cs-focus-at-8">            chunk_embedding = item["chunk_embedding"]</span>
<span class="cs-ln cs-focus-at-8 cs-focus-at-10-9">            chunk_norm = sum(x * x for x in chunk_embedding) ** 0.5</span>
<span class="cs-ln">            <span class="cs-key">if</span> chunk_norm == 0:</span>
<span class="cs-ln">                continue</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-14-5">            dot = sum(q * c for q, c in zip(query_embedding, chunk_embedding))</span>
<span class="cs-ln cs-focus-at-19-1">            score = dot / (query_norm * chunk_norm)</span>
<span class="cs-ln cs-focus-at-29-2">            <span class="cs-key">if</span> score &gt;= threshold:</span>
<span class="cs-ln cs-focus-at-29-2">                scored.append({"chunk_text": item["chunk_text"], "score": score})</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-33-4">        scored.sort(key=lambda item: item["score"], reverse=True)</span>
<span class="cs-ln cs-focus-at-33-4">        <span class="cs-key">return</span> scored[:top_k]</span></pre>
    </div>
    <div class="cs-stack">
      <div class="cs-card cs-at-0-1 cs-until-8"><p class="cs-card-label">Norm</p><p class="cs-card-title">The length of the question's arrow</p></div>
      <div class="cs-card cs-at-8 cs-until-14-5"><p class="cs-card-label">Loop</p><p class="cs-card-title">Every stored chunk, its own norm</p></div>
      <div class="cs-card cs-at-14-5 cs-until-19-1"><p class="cs-card-label">Dot product</p><p class="cs-card-title">Multiply pairs, add them up</p></div>
      <div class="cs-card cs-at-19-1 cs-until-29-2"><p class="cs-card-label">Score</p><p class="cs-card-title">Cosine: −1 to 1, higher is closer</p></div>
      <div class="cs-card cs-at-29-2 cs-until-33-4"><p class="cs-card-label">Threshold</p><p class="cs-card-title">Keep it if the score is 0.3 or more</p></div>
      <div class="cs-card cs-at-33-4 cs-until-38-2"><p class="cs-card-label">Top 5</p><p class="cs-card-title">Sort high to low, keep 5</p></div>
      <div class="cs-card cs-card-accent cs-at-38-2"><p class="cs-card-label">Remember</p><p class="cs-card-title">Not the answer. The reading.</p></div>
    </div>
  </div>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 7 · Messages · main.py · line 44</span></div>
    <pre class="cs-code-body cs-lines cs-from-44"><span class="cs-ln cs-focus-at-0">messages = rag.build_messages(question, related_chunks)</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 98–105</span></div>
    <pre class="cs-code-body cs-lines cs-from-98"><span class="cs-ln">    <span class="cs-key">def</span> build_messages(self, user_question, related_chunks):</span>
<span class="cs-ln cs-focus-at-5-8">        chunk_texts = []</span>
<span class="cs-ln cs-focus-at-5-8">        <span class="cs-key">for</span> chunk in related_chunks:</span>
<span class="cs-ln cs-focus-at-5-8">            <span class="cs-key">if</span> isinstance(chunk, dict):</span>
<span class="cs-ln cs-focus-at-5-8">                chunk_texts.append(chunk["chunk_text"])</span>
<span class="cs-ln cs-focus-at-5-8">            else:</span>
<span class="cs-ln cs-focus-at-5-8">                chunk_texts.append(chunk)</span>
<span class="cs-ln"></span></pre>
  </div>
</div>

<div class="course-slide">
  <p class="cs-kicker">Stage 7 · Messages</p>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 11–110</span></div>
    <pre class="cs-code-body cs-lines cs-from-11"><span class="cs-ln cs-focus-at-1-7">    system_message = (</span>
<span class="cs-ln cs-focus-at-1-7 cs-focus-at-4-7">        "Answer the user using only the related chunks below. "</span>
<span class="cs-ln cs-focus-at-1-7 cs-focus-at-4-7">        "If the chunks do not contain the answer, say you do not know.\n\n"</span>
<span class="cs-ln cs-focus-at-1-7">        "Related chunks:\n"</span>
<span class="cs-ln cs-focus-at-1-7">    )</span>
<span class="cs-ln cs-gap">  # 90 lines</span>
<span class="cs-ln cs-from-106 cs-focus-at-0-3">        system_content = self.system_message + "\n\n".join(chunk_texts)</span>
<span class="cs-ln cs-focus-at-12-8">        <span class="cs-key">return</span> [</span>
<span class="cs-ln cs-focus-at-12-8 cs-focus-at-15-2">            {"role": "system", "content": system_content},</span>
<span class="cs-ln cs-focus-at-12-8 cs-focus-at-18">            {"role": "user", "content": user_question},</span>
<span class="cs-ln cs-focus-at-12-8">        ]</span></pre>
  </div>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 8 · Raw answer · main.py · line 48</span></div>
    <pre class="cs-code-body cs-lines cs-from-48"><span class="cs-ln cs-focus-at-0">response = rag.generate_response(messages)</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 112–113</span></div>
    <pre class="cs-code-body cs-lines cs-from-112"><span class="cs-ln cs-focus-at-3-8">    <span class="cs-key">def</span> generate_response(self, messages):</span>
<span class="cs-ln cs-focus-at-4-5">        <span class="cs-key">return</span> self.llm.generate_response(messages)</span></pre>
  </div>
</div>

<div class="course-slide">
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">Stage 8 · the chat call · services/rag.py · line 113</span></div>
    <pre class="cs-code-body cs-lines cs-from-113"><span class="cs-ln cs-focus-at-0"><span class="cs-key">return</span> self.llm.generate_response(messages)</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/llm.py · lines 43–54</span></div>
    <pre class="cs-code-body cs-lines cs-from-43"><span class="cs-ln">    <span class="cs-key">def</span> generate_response(self, messages: list[dict]) -&gt; str:</span>
<span class="cs-ln">        <span class="cs-key">if</span> not messages:</span>
<span class="cs-ln">            raise ValueError("messages are empty")</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-1-7">        response = self._client.chat.completions.create(</span>
<span class="cs-ln cs-focus-at-1-7">            model=self.chat_model,</span>
<span class="cs-ln cs-focus-at-1-7">            messages=messages,</span>
<span class="cs-ln cs-focus-at-1-7">        )</span>
<span class="cs-ln cs-focus-at-4-6">        content = response.choices[0].message.content</span>
<span class="cs-ln cs-focus-at-6-5">        <span class="cs-key">if</span> not content:</span>
<span class="cs-ln cs-focus-at-6-5">            raise ValueError("model returned an empty response")</span>
<span class="cs-ln">        <span class="cs-key">return</span> content</span></pre>
  </div>
</div>

<div class="course-slide">
  <p class="cs-kicker">Stage 8 · back in main.py</p>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">main.py · lines 27–49</span></div>
    <pre class="cs-code-body cs-lines cs-from-27"><span class="cs-ln cs-focus-at-3-4"><span class="cs-key">while</span> True:</span>
<span class="cs-ln cs-focus-at-3-4">    question = input(f"{BOLD}You{RESET}  ").strip()</span>
<span class="cs-ln cs-gap">  # 19 lines</span>
<span class="cs-ln cs-from-48 cs-focus-at-0">    response = rag.generate_response(messages)</span>
<span class="cs-ln cs-focus-at-0 cs-focus-at-2-7">    print(f"\n{BOLD}Answer{RESET}\n{response}\n")</span></pre>
  </div>
  <p class="cs-pill cs-at-5-3">Does it work? 3 questions, one session</p>
</div>

<div class="course-slide cs-center">
  <p class="cs-kicker">The live run · question 1</p>
  <h2 class="cs-title cs-at-0-9">It needs <span class="cs-hl">both files</span></h2>
  <p class="cs-pill cs-at-2-4">Reset link life + annual refund window</p>
</div>

<div class="course-slide">
  <p class="cs-kicker">Run 1 · from the files</p>
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">terminal · python main.py</span></div>
    <pre class="cs-code-body cs-lines"><span class="cs-ln">You  How long does a password reset link stay valid, and how many days does a workspace owner have to cancel Studio Annual for a full refund?</span>
<span class="cs-ln"></span>
<span class="cs-ln">Answer</span>
<span class="cs-ln cs-focus-at-2-6">A password reset link stays valid for 30 minutes and can be used only once.</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-7-9">A workspace owner has 14 days after the charge to cancel Studio Annual for a full refund, provided the workspace has invited no more than two teammates. Promotional pricing has a shorter refund window of 48 hours.</span></pre>
  </div>
  <div class="cs-row">
    <span class="cs-chip cs-at-4-9">30 minutes, once: the recording (.mp3)</span>
    <span class="cs-chip cs-at-12-9">14 days, two teammates: the webpage (.html)</span>
  </div>
</div>

<div class="course-slide">
  <p class="cs-kicker">Run 2 · no memory</p>
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">terminal · python main.py</span></div>
    <pre class="cs-code-body cs-lines"><span class="cs-ln cs-focus-at-1-1">You  Please remember this. I invited four teammates to my Fieldnote workspace yesterday.</span>
<span class="cs-ln">Answer</span>
<span class="cs-ln cs-focus-at-3-9">Got it—I’ll keep in mind for this conversation that you invited four teammates to your Fieldnote workspace yesterday.</span>
<span class="cs-ln"></span>
<span class="cs-ln cs-focus-at-7-1">You  How many teammates did I just tell you I invited?</span>
<span class="cs-ln">Answer</span>
<span class="cs-ln cs-focus-at-10-2">I don’t know—you haven’t provided a number in this conversation.</span></pre>
  </div>
  <p class="cs-pill cs-at-15-4"><span class="cs-mono">build_messages</span>: system message + this one question</p>
  <p class="cs-pill cs-at-19-4">The earlier turn is <span class="cs-bad">never sent</span></p>
</div>

<div class="course-slide">
  <p class="cs-kicker">Run 3 · not in the files</p>
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">terminal · python main.py</span></div>
    <pre class="cs-code-body cs-lines"><span class="cs-ln cs-focus-at-2-4">You  What is the capital of France?</span>
<span class="cs-ln">Answer</span>
<span class="cs-ln cs-focus-at-9-3">I don’t know.</span></pre>
  </div>
  <p class="cs-pill cs-at-4-3">No chunk reached the 0.3 threshold</p>
  <p class="cs-pill cs-at-11-2">The instruction doing its <span class="cs-hl">job</span></p>
</div>

<div class="course-slide cs-center">
  <p class="cs-kicker">Three gaps · three challenges</p>
  <h2 class="cs-title cs-at-6-2">Gap 1: <span class="cs-hl">memory</span></h2>
  <p class="cs-pill cs-at-8-3">Earlier turns belong in the messages</p>
  <p class="cs-pill cs-at-12-5">This code does not send them yet</p>
</div>

<div class="course-slide">
  <p class="cs-kicker">Gap 2 · hallucination</p>
  <div class="cs-code cs-no-copy">
    <div class="cs-code-bar"><span class="cs-code-path">terminal · python main.py</span></div>
    <pre class="cs-code-body cs-lines"><span class="cs-ln cs-focus-at-4-2">Got it—I’ll keep in mind for this conversation that you invited four teammates to your Fieldnote workspace yesterday.</span></pre>
  </div>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 11–15</span></div>
    <pre class="cs-code-body cs-lines cs-from-11"><span class="cs-ln">    system_message = (</span>
<span class="cs-ln cs-focus-at-8-7">        "Answer the user using only the related chunks below. "</span>
<span class="cs-ln cs-focus-at-8-7">        "If the chunks do not contain the answer, say you do not know.\n\n"</span>
<span class="cs-ln">        "Related chunks:\n"</span>
<span class="cs-ln">    )</span></pre>
  </div>
  <p class="cs-pill cs-at-11-8">No code checks that the model <span class="cs-bad">obeyed</span></p>
</div>

<div class="course-slide">
  <p class="cs-kicker">Gap 3 · citation</p>
  <div class="cs-code">
    <div class="cs-code-bar"><span class="cs-code-path">services/rag.py · lines 24–93</span></div>
    <pre class="cs-code-body cs-lines cs-from-24"><span class="cs-ln cs-focus-at-13-5">        <span class="cs-key">for</span> path in sorted(SOURCES_DIR.iterdir()):</span>
<span class="cs-ln cs-gap">  # 5 lines</span>
<span class="cs-ln cs-from-30 cs-focus-at-11-1">                texts.append(self.llm.stt(str(path)))</span>
<span class="cs-ln cs-gap">  # 2 lines</span>
<span class="cs-ln cs-from-33 cs-focus-at-11-1">                texts.append(soup.get_text(separator="\n", strip=True))</span>
<span class="cs-ln cs-gap">  # 59 lines</span>
<span class="cs-ln cs-from-93 cs-focus-at-7-7">                scored.append({"chunk_text": item["chunk_text"], "score": score})</span></pre>
  </div>
  <p class="cs-pill cs-at-4-1">Run 1: right answer, no source</p>
  <p class="cs-pill cs-at-14-7">A chunk cannot say which file it came from</p>
</div>

<div class="course-slide cs-center">
  <p class="cs-kicker">Leave with this</p>
  <ul class="cs-checks">
    <li class="cs-at-1-6">The first four methods run once and fill a list</li>
    <li class="cs-at-4-6">Every question runs the last four</li>
    <li class="cs-at-6-9">The model sees only what <span class="cs-mono">build_messages</span> hands it</li>
  </ul>
</div>

<div class="course-slide cs-center">
  <p class="cs-kicker">Next</p>
  <h2 class="cs-title cs-at-0-5">Quiz, then a <span class="cs-hl">challenge</span></h2>
  <p class="cs-pill cs-at-1 cs-until-9">Quiz: on the tip page. YouTube: link in the description.</p>
  <p class="cs-pill cs-at-9 cs-until-16-9">Repo link: notes or description</p>
  <p class="cs-pill cs-at-16-9">Memory · hallucination check · citations</p>
</div>