Slides

# Your first PydanticAI chat

## Everyday questions and the limits of generated answers

---

# Week 1 · first application

## A chat running on your own computer

Use **Windows PowerShell, macOS Terminal (zsh), or Linux Terminal (bash)**.

Watch the instructor open the app and ask:

> “Which canton is Martigny in?”

Then you will launch it, send a question, and restart it yourself.
We check your setup and access together during this first exercise.

**First milestone:** make Python display a message you chose.
We will explain each command as we use it; no terminal experience is assumed.

[Computer setup and command reference](setup.html)

<aside class="notes">
Begin with a one-minute demonstration of the working browser chat. Point out
the terminal that keeps it running. Ask students what they expect to happen
when it stops. Keep the answer for the stop/restart activity.

Allow about 25–30 minutes for guided onboarding, adjusting to students' setup
needs. Have the course download link and individual PPQ keys ready. Communicate
each key's allowance and expiry without exposing its value to the class.
During the first exercise, help students choose or open a code editor and coding
assistant, check sign-in and available access, and install uv using setup.md as
needed. Students choose their assistant from the options presented in the guide.
A coding-assistant subscription does not supply the Python app's API access.
The instructor's PPQ key supplies application-agent access without student
signup or payment. Coding assistants use students' own subscriptions or free
tiers; do not configure them with the supplied course key.
Check dependency downloads, the first chat UI load, and an actual model answer
with each student. Pause at each checkpoint; students who finish early can
explain the result to a partner. If installation or access is blocked, pair
temporarily on a working machine and resolve the setup with the instructor.
</aside>

---

# Your workspace

## Where each action happens

| Place | What you do there | Today’s example |
| --- | --- | --- |
| **Code editor** | Read, change, and save files | The Python chat script |
| **Terminal** | Type commands and read program messages | Start and stop the app |
| **Browser** | Use the running app | Send a question |

The **command line** is the text interface inside the terminal.
Your **coding assistant** helps explain code and commands.
Choose the assistant that suits your access and preferences; the
[coding-assistant guide](coding_assistants.html) presents the options.

**Try it:** point to where you would change a file, run it, and use the chat.

<aside class="notes">
Show the three places on the instructor's screen, then let students find them.
An editor may contain both a terminal panel and an assistant panel. These have
different roles: shell commands go in the terminal, requests for help go to the
assistant. Ask the assistant to explain a command before authorizing it to run.
</aside>

---

# Your course folder

## The terminal needs a starting location

Download and extract the [course archive (.zip)](https://www.idiap.ch/~wdroz/lifescience_course/aiforlifescience.zip).
Open the extracted course folder in your editor, then open its terminal.
The **course folder** contains `pyproject.toml` and `examples`.

Use **PowerShell on Windows**, **zsh on macOS**, or **bash on Linux**.
At the terminal prompt (the text before the cursor), type each command and press
**Enter**. Copy only the commands below:

```bash
pwd
ls
```

`pwd` shows your current folder. `ls` lists what is inside it.

**Checkpoint:** the listing includes `pyproject.toml`, `uv.lock`, and `examples`.
If it does not, use the folder instructions in the [setup reference](setup.html).

<aside class="notes">
pwd and ls work in the three course shells. On Windows, choose a PowerShell
profile if the editor opens Command Prompt. Demonstrate opening the folder and
a new terminal in the student's chosen editor. The setup reference gives paths
for all three systems; use the student's actual extracted folder, retain quotes
around spaces, and match filename case exactly.
Explain that the terminal prompt (often ending in $, %, or >) means it is ready
for a command. Copy only the commands, not prompt symbols or expected output.
If students see Python's >>> prompt, enter exit() to return to the shell.
</aside>

---

# A short folder visit

## Commands act in the current folder

| Type, then press Enter | What to observe |
| --- | --- |
| `cd examples` | Move into the examples folder; `cd` means “change directory” |
| `ls` | Find `01_pydanticai_chat.py`, a file containing Python code |
| `cd ..` | Move back to the parent folder; `..` means one level up |
| `pwd` | Confirm that you are back in the course root |

**Predict first:** does `cd` move the files, or change where the terminal works?

**Coding assistant:** “Explain `cd ..` using these two folders. Do not run anything.”

<aside class="notes">
Give students a moment to predict, then take the short trip together. cd changes
the shell's working directory; it does not move or modify files. Ask students
to run ls again at the end and find pyproject.toml before continuing. A terminal
remembers its own current folder; opening another terminal may start elsewhere.
</aside>

---

# Python with uv

## One tool prepares the project and runs its programs

First, check that `uv` is available:

```bash
uv --version
```

**Expect:** `uv` followed by a version number. If it is missing, follow the
[installation reference](setup.html).

**Intel Mac:** complete the dependency-build preparation in the [setup reference](setup.html) first.

Then prepare the libraries used by the examples:

```bash
uv sync --group examples
```

**Dependencies** are libraries our code uses. `--group examples` includes the
course’s example libraries. Wait for installation to finish and the prompt to return.

</div>
<picture class="teaching-cue-character" aria-hidden="true">
  <source media="(prefers-reduced-motion: reduce), print" srcset="assets/william-chibi/poses/waiting.png">
  <img src="assets/william-chibi/poses/waiting.png" data-src="assets/william-chibi/animations/waiting.gif" alt="" width="512" height="512">
</picture>
<img class="teaching-cue-print" src="assets/william-chibi/poses/waiting.png" alt="" width="512" height="512" aria-hidden="true">
</div>

<aside class="notes">
uv creates the project's .venv environment and can download a compatible Python
if needed; this course requires Python 3.13 or newer. pyproject.toml describes
the requirements; uv.lock records resolved versions. Explain that .venv keeps
this project's installed libraries together. uv run uses that environment, so
students do not need to activate it manually. Download progress is normal on
first use; later runs may only report that packages were audited. An error needs
attention even if the prompt returns. The next slide checks the actual result.
All uv commands shown here work unchanged in PowerShell, zsh, and bash. Recreate
.venv with uv sync when moving the course files to another operating system;
the environment itself should not be copied between computers.

[Sources]

- https://docs.astral.sh/uv/guides/projects/
- https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups
- https://docs.astral.sh/uv/guides/install-python/
</aside>

---

# Your first Python result

## A message you can predict

In the terminal:

```bash
uv run --group examples python -c "print('Python is ready')"
```

Expected output:

```text
Python is ready
```

`uv run` uses the project environment. `python -c` runs the code in quotes;
`print(...)` displays the text inside its quotes.

**Try it:** press **Up** to recall the command. Change only `Python is ready`
to a greeting using letters and spaces; keep the quotes, and press **Enter**.

<aside class="notes">
This check uses no LLM or API key. The result comes from deterministic Python
execution. The student's short greeting should appear exactly as written.
Use plain text without apostrophes for the first change, so the existing quotes
remain valid. Commands must go in the shell, not inside Python's >>> prompt.
Explain that later we will save Python instructions in .py files instead of
putting a small instruction after -c.

Coding-assistant prompt if needed: “Explain the quotes in this command. Help me
change only the printed message and predict its output.” The student inspects
the suggestion and decides whether to run it.
</aside>

---

# The chat’s connection settings

## The instructor supplies your individual PPQ key

In your editor, duplicate `.env.example` as **`.env`** beside `pyproject.toml`.
If `.env` already exists, check it with the instructor before changing it.

The template already contains the endpoint and default model:

```dotenv
LLM_BASE_URL=https://api.ppq.ai
LLM_MODEL=deepseek/deepseek-v4.1-flash
LLM_API_KEY=replace-with-your-instructor-provided-key
```

Replace only the `LLM_API_KEY` value and save. Restart the app after any `.env` change.
Keep the key out of prompts, screenshots, shared logs, and submissions.

**Cannot see `.env.example`?** Follow the hidden-file steps in the [setup reference](setup.html).

<aside class="notes">
Demonstrate with placeholders only. Ensure the filename is exactly .env, not
.env.txt, and preserve the setting names to the left of each equals sign.
The supplied helper reads this file automatically. A saved key placeholder can
still let the app start; receiving a model answer is the real connection check.
For an existing .env, compare its endpoint and model with .env.example first.
Use ls in Windows PowerShell or ls -a in macOS/Linux Terminal to find .env.example.
On Windows, use ls -Force only if the file has the Hidden attribute.
File Explorer can hide the .txt extension; enable File
name extensions to check it. Save in the editor with Ctrl+S on Windows/Linux
or Command+S on macOS. Preserve the original .env.example template.
</aside>

---

# Your course API access

## Check the allowance and expiry supplied by the instructor

You need no PPQ signup or payment to use your key. The instructor tells you
its spending allowance and expiration date.

Keep the default model, or optionally set `LLM_MODEL=openai/gpt-5.6-luna`.
Save `.env` and restart the app when changing models.

Use your own subscription or free tier for the coding assistant.
The supplied PPQ key is only for agents running inside your course code.

If a key expires, its allowance is exhausted, or a model is rejected, use the
[setup troubleshooting](setup.html) and contact the instructor with a redacted error.

---

# Starting the chat

## A command we can read in parts

```bash
uv run --group examples python examples/01_pydanticai_chat.py
```

| Part | Meaning |
| --- | --- |
| `uv run --group examples` | Use the project environment with the example libraries |
| `python` | Run Python |
| `examples/01_pydanticai_chat.py` | Run this file, inside `examples` |

Keep the `/` in this path on all three systems; match the filename exactly.

**Checkpoint:** the terminal reports `Uvicorn running on http://127.0.0.1:7932`.
Uvicorn serves the browser app. Keep this terminal open while you use it.

<aside class="notes">
Run from the course folder and wait for Uvicorn's running message. The script
also prints an Open message before the server starts; that line alone does not
prove startup succeeded. Compare the command with the previous Python command:
here a file path replaces -c and its short instruction. The absence of a new
shell prompt is expected: the app is running and waiting for browser requests.
</aside>

---

# Your first chat answer

## The browser connects to the running Python app

Open [http://127.0.0.1:7932](http://127.0.0.1:7932) in your **browser’s address bar**.
`127.0.0.1` means this computer; `7932` identifies the app’s listening port.

The interface runs locally. Your questions and conversation context go through
PPQ to the model provider, so use a public question:

> “Which canton is Martigny in?”

**Checkpoint:** you receive an answer. This confirms the connection works;
you still need to review what the model says.

<aside class="notes">
Have students explicitly review where the question will go before sending it.
Opening the interface alone does not verify API access. The built-in UI needs
an internet connection on first use. If the page opens but a message fails,
check the terminal error and the endpoint/model/key settings with the instructor.
</aside>

---

# Stopping and restarting

## You control when the app runs

1. Click the **terminal** running the app and press **Control+C** on all three systems.
2. Wait for the shell prompt to return. The browser tab may still show the old page.
3. Press **Up**, then **Enter** to run the same launch command again.
4. Refresh the browser and start a new chat.

**Predict first:** can the chat get a new answer while its Python app is stopped?

When you change the Python file or `.env`: **save it, stop the app, restart it,
and begin a new chat**.

<aside class="notes">
Ctrl+C means hold Control and press C, including on macOS; use it in the app's
terminal. On Windows Terminal, clear any text selection first so Ctrl+C reaches
the app. Save in the editor with Ctrl+S on Windows/Linux or Command+S on macOS.
Allow time for shutdown to complete. Up recalls the last shell command,
so students should inspect the recalled command before pressing Enter.
The script does not automatically reload saved changes. This small exercise
revisits the opening demonstration and gives students a reusable run/edit loop.
</aside>

---

# When a command fails

## The error is a clue for the next step

Read the last error line and check your current folder before changing anything.

**Ask your coding assistant:**

> “I use [Windows PowerShell / macOS zsh / Linux bash]. I ran [command] from [folder]
> and got [error, with secrets removed]. Explain it and suggest one small
> check. Wait for my result before suggesting another change.”

Inspect the proposed command and what it changes before running it.
Compare the new result with the expected checkpoint, or ask the instructor.

[Setup and common errors](setup.html)

<aside class="notes">
Demonstrate a harmless misspelling such as uv --versoin, then read the error and
correct it together. Avoid a broad automated environment repair. Students should
share only the relevant command and error after removing credentials and private
information; the assistant does not need their .env file. Close the onboarding
by asking students to explain one command in their own words.
</aside>

---

# The first app · read the code

## An agent, an instruction, and `to_web()`

Core of `examples/01_pydanticai_chat.py`:

```python
from _llm import make_pydantic_model
from pydantic_ai import Agent

agent = Agent(
    make_pydantic_model(),
    instructions=(
        "Answer general questions clearly and concisely. "
        "You have no data or tools; say when a question needs external evidence."
    ),
)
app = agent.to_web()
```

The supplied helper reads `.env`; the script uses Uvicorn to serve the chat.

**Coding assistant:** “Explain this script line by line, including where my question goes.”

<aside class="notes">
[Sources]

- https://pydantic.dev/docs/ai/guides/web/

Keep the focus on launching and understanding the small app. Provider internals,
structured outputs, and tools come in later weeks.
</aside>

---

# Inside our first agent

<aside class="notes">
Follow one question from the browser to the local Python app, then to the model
provider and back. The helper reads the connection settings from .env; the API
key authenticates the connection and is not part of the conversation. Instructions
guide the answer, while the question and conversation supply its context.
agent.to_web() supplies the chat interface. This first app has no tools, dataset,
or live web search. The student still checks the generated answer.
</aside>

---

# Week 1 · chat practice

## Ask about Martigny, Switzerland

- “How many people live in Martigny, Switzerland?”
- “Which year is that population figure from?”
- “Which canton is Martigny in?”
- Follow up: “Summarize your answer in one sentence.”

Then ask about the evidence:

> “What source supports your population figure?”

`to_web()` adds a chat interface, not web search. This app cannot look up the
current population; a source named in its answer has not been retrieved.

**Observe:** does the model give a date, acknowledge uncertainty, or supply an
exact number without supporting evidence?

---

# Ask for the year and source

<video class="course-video" controls muted playsinline preload="metadata" width="1920" height="1080" poster="assets/videos/week-01-chat-provenance.jpg" aria-label="Silent demonstration: ask the PydanticAI chat for Martigny's population, then ask for the year and source of its estimate.">
  <source src="assets/videos/week-01-chat-provenance.mp4" type="video/mp4">
  <a href="assets/videos/week-01-chat-provenance.mp4">Open the chat demonstration video</a>.
</video>

<p class="video-demo-link"><a href="assets/videos/week-01-chat-provenance.mp4">Open video separately</a> · 44 seconds · silent</p>

<aside class="notes">
Play the clip, then ask which claim needs checking. The model gives a population
estimate and subsequently acknowledges that it cannot substantiate the number
with a specific year or source. These are actual generated responses; no official
population source was retrieved or verified in this demonstration.

Waiting before actions runs at 5× speed. Typing, submission and response generation
remain at normal speed, with time to read the final reply. There is no audio or
caption track. The visible model controls reflect the recording environment;
students should follow the model settings in the course setup instructions.
</aside>

---

# How an answer is generated

## The model continues from the context it receives

- **Tokens** are pieces of text: a word, part of a word, or punctuation.
- **Context** is the material supplied for this answer: instructions, your question,
  and the conversation history the app includes. It has a size limit.
- **Probabilistic generation** builds a reply token by token using learned patterns.
  Depending on the settings, the same question can produce different replies.

**Example:** after a population question, “Which year?” depends on the previous
messages. In a new chat, that reference is missing.

**A likely continuation is not a verified fact.**

<aside class="notes">
Use the population conversation students just tried to make context visible.
Ask what “Which year?” refers to, then imagine asking it in an empty conversation.
An app chooses which earlier messages to send; a model does not automatically
remember every previous chat or see files on the computer. The context size limit
means an application may need to shorten long conversations.

Do not teach a fixed number of letters per token: token boundaries depend on the
model's tokenizer and the language. For generation, explain that the model assigns
likelihoods to possible next tokens. Sampling can introduce variation; repeated
answers can also be identical. Likelihood is not a confidence score for factual
correctness. Instructions influence the output but do not guarantee compliance.
</aside>

---

# Four ways an answer can mislead

## Check the answer and your reaction to it

| Risk | Example in our population chat |
| --- | --- |
| **Hallucination:** an invented or unsupported claim | A precise figure with a source that does not exist |
| **Omission:** important information is missing | A figure without its year or geographic area |
| **Anchoring:** an initial suggestion shapes later judgment | We keep using the first estimate after finding a conflicting source |
| **Automation bias:** we trust the automated answer too readily | We accept a fluent reply without opening its claimed source |

**Try it:** identify one risk in your reply, or explain what you checked to rule it out.

<aside class="notes">
These are possible failure modes, not claims that every generated answer is wrong.
Keep any demonstration figure hypothetical. An outdated figure can have been true
for its stated year; the problem is presenting it as current without evidence.
Likewise, an omitted year does not prove the number itself was invented.

Separate the text from the reviewer's behavior. Hallucination and omission describe
problems to look for in the answer. Anchoring can affect how we interpret later
evidence; automation bias can make us skip checking because a system supplied the
answer. Ask students to compare the same municipality and year before deciding
that two figures disagree. If no risk is visible, they should describe their
checking process rather than manufacture an error.
</aside>

---

# Where does the evidence come from?

## Generated, retrieved, and computed have different origins

| Origin | What happened |
| --- | --- |
| **Generated** | The model produced text |
| **Retrieved** | A person or tool opened an existing source |
| **Computed** | Code calculated a result from inputs |

Our chat generates answers. **Naming a source does not show that it was opened.**

<aside class="notes">
These labels describe how information was obtained, not whether it is correct.
A retrieved source can be unreliable, and a calculation depends on its inputs
and logic. This chat has no retrieval or calculation tools.
</aside>

---

# Week 1: data boundaries

## What goes into the conversation

- The model receives the conversation and the app's instructions
- This chat has no tools to browse the web, read local files, or run code
- Course prompts use public information and exclude passwords and private data

</div>
<picture class="teaching-cue-character" aria-hidden="true">
  <source media="(prefers-reduced-motion: reduce), print" srcset="assets/william-chibi/poses/caution.png">
  <img src="assets/william-chibi/poses/caution.png" data-src="assets/william-chibi/animations/caution.gif" alt="" width="512" height="512">
</picture>
<img class="teaching-cue-print" src="assets/william-chibi/poses/caution.png" alt="" width="512" height="512" aria-hidden="true">
</div>

---

# Human review remains essential

## The assistant implements, the student validates

- **Coding assistant:** writes code, explains changes, and helps create tests
- **Student review:** compares files before and after edits, checks assumptions,
  and evaluates test results
- **Human approval:** remains required before consequential actions and final exports

<aside class="notes">
Known examples and independent evidence help establish correctness. Passing
tests written by the assistant alone does not establish scientific validity.
</aside>

---

# Week 1: course navigation

[Computer setup and command reference](setup.html)

[Course overview](presentation.html)

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

[Next: Week 2](week_02.html)