Slides

<span class="week-label">WEEK 07 · <time datetime="2026-11-03">Tuesday, 3 November 2026</time></span>

# Build a course-search agent

## Semantic spaces, hybrid retrieval, and source-based answers

---

# The question for today

## “In which courses do we use pandas?”

The answer may be spread across module descriptions, expressed in another
language, or absent from the published text.

Build a small application that finds evidence, follows up when necessary,
and shows where each answer came from.

Then give a coding agent the same folder and question. Does your application
justify its extra engineering?

---

# From course PDFs to cited answers

<video class="course-video" controls muted playsinline preload="metadata" width="1920" height="1080" poster="assets/videos/week-07-agentic-rag.jpg" aria-label="Silent demonstration of the module-description workflow: animated retrieval concepts, real downloader log replay, NiceGUI ingestion with cache reuse, and an agent answer with page-linked sources and an evidence trace.">
  <source src="assets/videos/week-07-agentic-rag.mp4" type="video/mp4">
  <p><a href="assets/videos/week-07-agentic-rag.mp4">Open the agentic RAG demonstration</a>.</p>
</video>

<p class="video-demo-link"><a href="assets/videos/week-07-agentic-rag.mp4">Open video separately</a> · 2 min 1 s · silent · recorded application · <a href="https://duerrsimon.github.io/hevs-lse-course-overview/463.pdf#page=2">Module 463 source</a></p>

<aside class="notes">
The downloader segment replays selected output from a real run. Ingestion is
recorded at 1.2×; the agent query is shown at normal speed, with operator pauses
removed. The frozen local demonstration uses 20 descriptions and 76 chunks.
Ask students to distinguish the generated answer, retrieved passages, and
deterministic citation checks. Distribute the tools and ID list; the PDFs and
extracted Markdown remain local.
</aside>

---

# Before we begin

## Prepare the tools and the local collection

Run from your course folder:

**Intel Mac:** run the updater, then use the alternative on the next slide
before installing dependencies.

```bash
uv run scripts/update.py
uv sync --locked --group rag
```

Read the updater summary; review incoming copies in `.course-updates/` if needed.
Open `src/aiforlifescience/exercises/07_module_rag.md`.

Download **all 118 module descriptions** from the
[ID and URL list](assets/week07/module-sources.json) into your own local folder.
Use the tested model settings.

<aside class="notes">
Before class, check the 118 URLs in docs/assets/week07/module-sources.json
and verify a known supporting passage. Students use the supplied tool to download
those descriptions before class or in staggered groups. The course supplies the
ID and URL list; PDFs and extracted Markdown remain local. Confirm the embedding
model is cached and test the course model
credentials. Do not ask every student to scan all 599 candidate URLs during the
lesson. Read the exercise brief for setup.
</aside>

---

# Intel Mac · alternative setup

## Python 3.13 · macOS 13 or later

Ask your coding assistant to create a **separate project** in
`artifacts/week07/app/`, with its own dependencies and lockfile.

| Component | Intel Mac alternative |
| --- | --- |
| Local database | `qdrant-client==1.20.0` · local mode, no server |
| Local embeddings | `fastembed==0.9.1` + `onnxruntime==1.23.2` |

Use a multilingual model and its own token limit. Keep keyword, semantic,
and hybrid search, with the same module/page citations and agent comparison.

Follow the **Intel Mac section of the exercise brief**. The course `rag` group
still installs LanceDB and PyTorch; this alternative uses a separate environment.

**Dependency resolution checked; native Intel execution still needs confirmation.**

<p class="source-note">References: <a href="https://github.com/qdrant/qdrant-client#local-mode">Qdrant local mode and FastEmbed</a> · <a href="https://pypi.org/project/onnxruntime/1.23.2/">ONNX Runtime 1.23.2 Intel macOS wheels</a>.</p>

<aside class="notes">
This is an alternative implementation of the same weekly lab, not an additional
assignment or a ready-made port of the teacher reference. Use Python 3.13 exactly;
the current FastEmbed dependencies for Python 3.14 lack Intel macOS wheels.
The existing Intel Mac cryptography source-build prerequisites still apply.
The brief specifies a small multilingual MiniLM model, 384 dimensions, and a
128-token input limit including special tokens. Do not reuse the E5 prefixes
or 430-token chunks. Use a keyword ranking alongside dense retrieval and combine
the two with reciprocal rank fusion. Rebuild embeddings for the chosen model.
Wheel-only dependency resolution passed except for the documented cryptography
source build; this does not establish native runtime behavior on a student's Mac.
</aside>

---

# RAG has two paths

## Prepare the collection; retrieve evidence for each question

<div class="workflow-row">
  <div class="workflow-step">PDFs → text</div>
  <div class="workflow-arrow">→</div>
  <div class="workflow-step">Chunks +<br>source metadata</div>
  <div class="workflow-arrow">→</div>
  <div class="workflow-step">Searchable<br>collection</div>
</div>

<div class="workflow-row">
  <div class="workflow-step">Question</div>
  <div class="workflow-arrow">→</div>
  <div class="workflow-step">Retrieve +<br>read passages</div>
  <div class="workflow-arrow">→</div>
  <div class="workflow-step">Generate +<br>cite answer</div>
</div>

Retrieval supplies evidence at answer time. It does not retrain the language model.
A fluent answer can still misrepresent the retrieved passages.

<p class="source-note">Background: Lewis et al., <a href="https://arxiv.org/abs/2005.11401">Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks</a> (2020).</p>

---

# Keyword search

## Exact vocabulary can be a strong signal

A query for **pandas** should prioritize passages containing that library name.
Full-text search tokenizes text; BM25 ranks matches using term frequency,
term rarity, and document length.

- Useful for library names, module codes, and distinctive terms.
- Can miss a paraphrase or a translation without shared vocabulary.
- A matching word still needs context: taught, recommended, or merely mentioned?

Tokenization and language settings affect which words count as matches.

<p class="source-note">Implementation reference: <a href="https://docs.lancedb.com/search/full-text-search">LanceDB full-text search</a>.</p>

---

# What is a semantic space?

## An embedding represents text as a vector

A **vector** is an ordered list of numbers. An **embedding model** learns how to
map text to these coordinates from patterns in its training data.

Texts with related uses or meanings can receive similar vectors. The relationships
captured depend on the model's training objective and examples.

The coordinates work together: individual dimensions usually have no simple
human-readable labels. A two-dimensional drawing is only an illustration of a
space that may have hundreds of dimensions.

<p class="source-note">Background: Mikolov et al., <a href="https://arxiv.org/abs/1301.3781">Efficient Estimation of Word Representations in Vector Space</a> (2013) · Reimers and Gurevych, <a href="https://arxiv.org/abs/1908.10084">Sentence-BERT</a> (2019).</p>

---

# Relationships as vector directions

## King − man, then + woman: near queen

Start at **king**. Move backward along **man**'s arrow, then forward along
**woman**'s arrow from that new point. You land near **queen**.

This is an **approximate learned pattern**. It varies across relations and
embedding models.

<p class="source-note">Source: Mikolov et al., <a href="https://arxiv.org/abs/1301.3781">Efficient Estimation of Word Representations in Vector Space</a> (2013), §1.1. Original schematic; no model outputs are plotted.</p>

<aside class="notes">
Follow the numbered arrows: start at king, subtract the man vector by reversing
its arrow, then add the woman vector from that intermediate endpoint. The copied
arrows keep the reference vectors' lengths; subtraction reverses the direction.
In notation: v(king) − v(man) + v(woman) ≈ v(queen). The intermediate point
does not need to correspond to a word. The final open circle is distinct from
queen to emphasize the approximation.
The sketch uses illustrative 2D coordinates, not measured embeddings or a
projection. Its axes have no assigned semantic meanings. The historical example
uses individual word vectors; the lab retrieves passages using a different,
contextual embedding model.
</aside>

---

# How similar are two vectors?

## Cosine similarity compares their directions

For nonzero vectors **q** (question) and **p** (passage):

**cosine(q, p) = (q · p) / (‖q‖ × ‖p‖)**

The dot product multiplies matching coordinates and adds the products;
the denominator removes the effect of vector length.

| Geometric relationship | Cosine similarity |
| --- | --- |
| Same direction | 1 |
| Perpendicular directions | 0 |
| Opposite directions | −1 |

With unit-length embeddings, cosine similarity equals the dot product.
A score of **0.8 does not mean an 80% probability of a supported answer**.

<p class="source-note">References: <a href="https://sbert.net/docs/sentence_transformer/usage/semantic_textual_similarity.html">Sentence Transformers: similarity measures</a> · <a href="https://huggingface.co/intfloat/multilingual-e5-small#faq">E5 model card: interpreting similarity scores</a>.</p>

---

# Semantic search

## From individual words to questions and passages

The analogy uses one vector per word. Our retrieval model encodes a whole text
with its context: “pandas for data analysis” and “pandas in a wildlife park”
can receive different vectors.

| Input to the lab's multilingual E5 model | Role |
| --- | --- |
| `query: Where can I learn to work with tables in Python?` | Represent the information need |
| `passage: Manipulation de tableaux de données avec Python.` | Represent a possible source passage |

These are **illustrative inputs**, not quotations from module descriptions.
Both become 384-dimensional vectors in the same space. The model uses different
prefixes for queries and passages, including non-English text.

Vector search ranks nearby passages. Cross-language matches depend on the
model's language coverage; the original passage still needs to be read.

<p class="source-note">References: <a href="https://sbert.net/examples/sentence_transformer/applications/semantic-search/README.html">Sentence Transformers: semantic search</a> · <a href="https://huggingface.co/intfloat/multilingual-e5-small">multilingual-e5-small model card</a>.</p>

---

# Similarity and support are different

## A relevant topic can still contradict the proposed answer

Claim: **“This course uses pandas.”**

| Invented passage for illustration | What it supports |
| --- | --- |
| “Students analyse tables using pandas.” | Supports the claim |
| “This course does not use pandas.” | Contradicts the claim |
| “Students manipulate tables in Python.” | Related, but the library is unspecified |

All three concern related vocabulary. Their retrieval order is model-dependent;
no similarity scores are assumed here.

Search identifies candidates. Reading establishes whether a passage supports,
contradicts, or leaves a claim unresolved. A valid citation alone does not decide this.

---

# Hybrid search

## Combine two ranked lists

<div class="workflow-row">
  <div class="workflow-step">Keyword<br>ranking</div>
  <div class="workflow-arrow">+</div>
  <div class="workflow-step">Semantic<br>ranking</div>
  <div class="workflow-arrow">→</div>
  <div class="workflow-step">Rank fusion<br>→ candidates</div>
</div>

**Reciprocal rank fusion (RRF)** combines positions in the two lists.
It avoids treating a keyword score and a vector distance as interchangeable.

Keyword and semantic search can contribute different relevant passages.
Their relative usefulness depends on the question and the collection.

<p class="source-note">Implementation reference: <a href="https://docs.lancedb.com/search/hybrid-search">LanceDB hybrid search and RRF</a>.</p>

---

# Why agentic RAG matters

## The next search can depend on what was found

| Fixed retrieval workflow | Agentic retrieval workflow |
| --- | --- |
| Search once, then answer | Search, inspect, decide what is missing |
| Same sequence for every question | Reformulate or read another source when useful |
| Simple, predictable cost | More flexible; requires budgets and a trace |

For our course question, the agent might search **pandas**, inspect a module,
then investigate a related description or translated term.

The value is adaptive evidence gathering. A straightforward question may need
only one search; extra calls must earn their cost.

---

# An agent needs a stopping rule

## Search → read → reconsider → answer or report a gap

A useful trace shows the queries, returned source IDs, passages read, and the
reason to stop. It should expose observable tool actions, not private reasoning.

Application code enforces bounds on model requests, tool calls, result sizes,
and runtime. The agent's instructions describe when enough evidence is available.

**Hybrid** describes how candidates are retrieved. **Agentic** describes who
chooses the next retrieval step. Our application uses both.

<p class="source-note">Implementation reference: <a href="https://ai.pydantic.dev/agents/#usage-limits">PydanticAI usage limits</a>. Request and tool limits are enforced in code.</p>

---

# Our source collection

## Public module descriptions, with provenance preserved

The source pattern is
`https://duerrsimon.github.io/hevs-lse-course-overview/{id}.pdf`.
The [ID and URL list](assets/week07/module-sources.json) contains **all 118 URLs
rechecked on 3 November 2026**. The downloader acquires every listed description.
These were successful IDs from the earlier 1–599 scan; this recheck does not
establish the complete current curriculum.

The downloader retains each PDF, its Markdown extraction, and `manifest.json`,
including the source URL, retrieval time, and content hash.
The converter marks pages with `## Page N` and ``.

Descriptions document what is stated in that snapshot. They do not establish
everything taught in practice or the current complete curriculum.

<p class="source-note">Source: HES-SO Valais-Wallis module descriptions hosted by Simon Duerr · <a href="https://duerrsimon.github.io/hevs-lse-course-overview/462.pdf">example PDF 462</a>. The course supplies download and processing tools; students retain their downloaded PDFs and extracted Markdown locally.</p>

---

# The downloader is supplied

## Acquire once, reuse the cache

```bash
uv run --locked --group rag python -m aiforlifescience.module_corpus --ids-file docs/assets/week07/module-sources.json
```

- Each downloaded PDF is converted to `.md`.
- Cached documents are reused; missing URLs and recoverable errors are recorded.
- Requests are paced, with backoff on temporary server failures.
- A repeated run reuses completed work and can retry failures.

The supplied list downloads **all 118 descriptions**. Download before class
or in staggered groups, then reuse the local cache.
The course does not distribute the PDFs or extracted Markdown.

<aside class="notes">
Demonstrate the supplied-list command twice and inspect its cache behavior. Explain
--retry-errors, --retry-missing, and --refresh as deliberate maintenance options;
students do not need a scan for the weekly lab. Do not interpret a network error
as a missing module. The downloader is provided infrastructure; students design
the prompts and implementation for their own ingestion and search application.
</aside>

---

# A chunk must remain traceable

## Source metadata connects a passage to its PDF

| Stored with each chunk | Purpose |
| --- | --- |
| Module ID, title, source URL | Identify the source |
| PDF page, text, stable chunk ID | Verify the cited passage |
| Content hash, extraction settings | Detect a changed document |
| Embedding model and configuration | Reproduce the vector representation |

Short chunks offer precise matches; longer chunks retain more context.
Page boundaries help locate the original passage.

A PDF and its Markdown extraction represent one source. Indexing both creates
duplicates; an empty extraction contributes no searchable evidence.

---

# An interface for retrieval

## NiceGUI makes the collection visible

| Collection panel | Question panel |
| --- | --- |
| Local folder path + Load | Question + Search |
| Stages: inspect, chunk, embed, index | Answer with clickable source references |
| Progress: completed / total files | Supporting excerpts and PDF pages |
| Indexed, skipped, failed counts | Expandable search/read trace |
| Per-file error + Retry | Clear running, stopped, and failed states |

Background work keeps the interface responsive during loading. Progress reflects
completed files, while per-file states distinguish skipped documents from failures.

<p class="source-note">Implementation references: <a href="https://github.com/zauberzeug/nicegui/blob/main/nicegui/llms.md">NiceGUI background work</a> · <a href="https://github.com/zauberzeug/nicegui/blob/main/examples/progress/main.py">progress example</a>.</p>

---

# Recovery is part of ingestion

## A failed file must not invalidate successful work

A file moves through visible states: pending, processing, indexed, skipped, or failed.
An indexed state means its chunks were stored successfully.

- A second load skips unchanged files without adding duplicate chunks.
- A changed file replaces its old chunks; an interrupted load can resume.
- A malformed file has an actionable error while other files finish.
- Retrying one failure preserves the successfully indexed documents.

These states let ingestion continue after a failure without restarting the collection.

---

# LanceDB search structure

## Store text, vectors, and source metadata together

A **full-text index** supports keyword search; stored embeddings support vector
search. Hybrid search combines both rankings over the same chunks.

For the small lab collection, exact vector search is sufficient. An approximate
vector index is a scaling extension, not a prerequisite for semantic retrieval.

The embedding configuration belongs to the collection. A different model
requires compatible new embeddings.

<p class="source-note">Implementation references: <a href="https://docs.lancedb.com/search/full-text-search">full-text indexing</a> · <a href="https://docs.lancedb.com/search/vector-search">vector search</a> · <a href="https://docs.lancedb.com/search/hybrid-search">hybrid queries</a>.</p>

---

# Weekly lab · your prompts

## Specify the system you want the coding assistant to build

| Prompt | Purpose |
| --- | --- |
| Development requests | Describe the ingestion, retrieval, and interface you want the coding assistant to build |
| Runtime instructions | Describe how the answering agent uses sources and when it stops |

Write your own prompts using `src/aiforlifescience/exercises/07_module_rag.md`
in the course package.
The coding assistant can implement the complete application.

---

# Weekly lab · build the course-search app

## 30–65 min · NiceGUI, LanceDB, and an answering agent

Work with the coding assistant to create the app in `artifacts/week07/app/`.
Use all 118 descriptions in the supplied JSON list and the supplied downloader.

The app loads the collection with visible progress and supports keyword,
semantic, and hybrid search. Its agent searches and reads passages before
answering with source links.

Try “In which courses do we use pandas?” The answer links to supporting passages
or reports that none were found.

<aside class="notes">
Contact-session timing: 0–20 min concepts, 20–30 min downloader and app acceptance
criteria demonstration, 30–65 min implementation, 65–80 min comparison, 80–90 min
class discussion. The lab uses all 118 listed descriptions. Guided work continues the same
app and comparison if class time is insufficient. Students author their own prompts.
Within the concept block, allow about five minutes for semantic spaces, the
analogy, cosine similarity, and passage embeddings. Treat the formula as an
explanation of ranking; no hand calculation or separate embedding exercise is required.
</aside>

---

# Weekly lab · answers with sources

## Search and read tools connect the agent to the collection

The app exposes bounded tools to **search passages** and **read source context**.

The agent should inspect evidence, reformulate when useful, preserve the
question's meaning, and report an evidence gap when it cannot support an answer.

Answers include source IDs, PDF pages, links, and supporting excerpts.
The interface shows the searches and passages read. Application code enforces
budgets and validates source IDs.

---

# Example questions

## Exact terms, paraphrases, and missing evidence

| Question | What it tests |
| --- | --- |
| “In which courses do we use pandas?” | Exact library mentions and their context |
| “Where can I learn to manipulate tables of data with Python?” | Related concepts and paraphrases |
| “Which course guarantees that I will get a job?” | An unsupported conclusion and stopping behavior |

The available descriptions determine which questions have supporting passages.
An evidence gap is a valid answer.

---

# A top-k list is not a curriculum audit

## Retrieval gaps and absence are different claims

“No relevant passage was retrieved” may mean poor extraction, an unsuitable
query, limited candidates, or missing documents.

An explicit mention of **pandas** differs from an inference based on “Python”
or “data analysis”. A library omitted from a description might still be used in teaching.

An exhaustive list depends on coverage of the full collection, including
failed extractions. A top-five search alone cannot establish every matching course.

---

# Compare with the coding agent

## 65–80 min · Same folder, same questions, fresh session

Open a new coding-agent session with access to the same local source folder.
Write your own request to answer from its PDFs or Markdown and provide sources.
Let it choose how to search and read the files.

Give it the source folder without the app's previous answers or LanceDB index.
Compare the answers and the passages they cite.

Different models can affect the comparison as well as the retrieval workflow.

---

# Class discussion

## 80–90 min · When is a dedicated RAG app useful?

- How did the two approaches find their source passages?
- Did either answer go beyond what those passages support?
- When would repeated questions justify building a dedicated application?

Retrieved text, computed search results, and generated interpretations play
different roles in both workflows.

---

# Documents cross a trust boundary

## Source text is evidence, not instructions to the agent

A retrieved passage might contain instruction-like text. PDF extraction and
Markdown rendering can also fail independently of the language model.

Read-only source tools and validated IDs limit the answering agent's access.
Retrieved text is displayed as content; it has no authority to change the
task, execute code, or request credentials.

Prompt instructions describe the intended behavior. Application permissions
determine which operations are possible.

---

# Week 7 · guided work

## Continue the same app and comparison

Use the 30 minutes to finish the course-search app or explore your own course
questions with the two approaches.

---

# Keep the working app

## The course folder contains your implementation

Keep the app and its launch command in `artifacts/week07/`.
The downloader's manifest records where the source documents came from.

API keys stay in `.env`. Downloaded PDFs and extracted Markdown remain local.

---

# Week 7: course navigation

[Course overview](presentation.html)

[14-week course map](course_map.html)

[Optional reference: workflow patterns](workflow_patterns.html)

[Previous: Week 6](week_06.html)

Next: Week 8 (not yet released)