Slides

# Setup · your course workspace

## First exercise: get the files onto your computer

The course supports **Windows, macOS, and Linux**. We check setup and access
together with the instructor; you can prepare early if you wish.

1. Download the [course archive (.zip)](https://www.idiap.ch/~wdroz/lifescience_course/aiforlifescience.zip) and **extract it**.
2. Open the extracted course folder in your code editor.
3. Find `pyproject.toml`, `examples`, and `.env.example` inside that folder.

This is the **course folder**: the starting place for our commands.

**Checkpoint:** open `examples/01_pydanticai_chat.py` in the editor.

<aside class="notes">
Have the course archive link and individual PPQ keys ready for the first
exercise. Guide students through setup and check each checkpoint with them;
preparation before class is optional. Students should extract the archive before
opening files; working inside an archive preview will not provide a usable project folder.
If there is an extra outer folder, open the inner one that contains pyproject.toml.
On Windows, right-click the ZIP and choose Extract All; on macOS, double-click
it in Finder; on Linux, use the archive manager's Extract action. Keep a writable
local course folder and open it as a folder in the editor, not just one file.
</aside>

---

# Choose your terminal

## Use the shell for your operating system

| Computer | Open | Course shell |
| --- | --- | --- |
| Windows | Search Start for **PowerShell** | PowerShell |
| macOS | Search Spotlight for **Terminal** | zsh (the usual default) |
| Linux | Open **Terminal** from the applications menu | bash |

An editor's terminal also works: choose the matching shell profile.
On Windows, select **PowerShell** if the editor opens Command Prompt.

The course's `uv` and Python commands are the same in all three shells.
Only instructions marked with an operating system differ.

**New to the command line?** See the visual [Terminal basics for Windows and macOS](terminal_basics.html) reference.

<aside class="notes">
Windows students can use Windows PowerShell or PowerShell 7. Windows Terminal
is an application that can host PowerShell; check the tab's shell, not only the
application's name. Native Windows setup does not require WSL. Keep the editor,
course folder, and terminal in the same operating-system environment.
On Linux, select bash if the editor uses another shell. On macOS, the course's
shared commands also work in bash; no shell change is needed for those commands.
</aside>

---

# Find your place in the terminal

## A terminal runs commands in the current folder

| Command | What it does |
| --- | --- |
| `pwd` | Shows the current folder |
| `cd '...'` | Changes folder; replace `...` with your course folder's full path |
| `ls` | Lists the files and folders here |

Example paths: replace `student` and the folder location with your own.

| Computer | Example command |
| --- | --- |
| Windows | `cd 'C:\Users\student\Downloads\aiforlifescience'` |
| macOS | `cd '/Users/student/Downloads/aiforlifescience'` |
| Linux | `cd '/home/student/Downloads/aiforlifescience'` |

Keep the quotes for spaces. Press **Enter** after each command.

**Checkpoint:** `ls` shows `pyproject.toml` and `examples`.

<aside class="notes">
These commands work in PowerShell and the usual macOS/Linux shells. The prompt
is the text before the cursor, where the terminal waits for a command. Copy the
course folder's actual full path from the file manager, then place it between
the quotes after cd. In PowerShell, use cd -LiteralPath '...' if the folder name
contains brackets, so they are treated as part of the name.
Do not copy another student's path. These example paths
are not guaranteed download locations: use the actual extracted folder.
An editor terminal may already start there; use pwd and ls to check. Copy
commands without prompt symbols such as $, %, or PS>. If the prompt is Python's
>>>, enter exit() first. Use straight quotes. If a folder name contains an
apostrophe, ask the assistant to quote that actual path for your shell.
Match filenames and capital letters exactly; Linux and some macOS filesystems
are case-sensitive. Forward slashes in the supplied Python script paths also
work on Windows, so keep commands such as python examples/01_pydanticai_chat.py
as written.
</aside>

---

# Keyboard shortcuts for the lab

## Saving, pasting, and stopping are different actions

| Action | Windows | macOS | Linux |
| --- | --- | --- | --- |
| Save in the editor | Ctrl+S | Command+S | Ctrl+S |
| Paste in the terminal | Ctrl+V in Windows Terminal | Command+V | Ctrl+Shift+V in GNOME Terminal |
| Stop the running app | Ctrl+C | **Control+C** | Ctrl+C |

Use the application's **Paste** menu if a shortcut differs in your editor or terminal.
Paste one command at a time, inspect it, then press **Enter**.

**On a Mac:** stopping the app uses the Control key, even though saving uses Command.

<aside class="notes">
In Windows Terminal, clear any text selection before Ctrl+C so the shortcut
reaches the running program instead of copying the selection. Other terminal
applications can use different paste shortcuts; use their menu or right-click
paste action. Ctrl+C in a shell interrupts the active program. It is not the
same as closing the browser tab.

[Sources]

- https://learn.microsoft.com/en-us/windows/terminal/customize-settings/actions#clipboard-integration-commands
- https://support.apple.com/guide/terminal/keyboard-shortcuts-trmlshtcts/mac
- https://help.gnome.org/gnome-terminal/txt-copy-paste.html
</aside>

---

# Install uv once

## uv prepares Python and the libraries our app needs

**Windows · PowerShell**

```powershell
winget install --id=astral-sh.uv -e
```

**macOS · Terminal (zsh) / Linux · Terminal (bash)**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Installers download and run code. Review the source and instructions in the
[official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/)
before running them.

**Checkpoint:** reopen your terminal; `uv --version` prints `uv` and a version number.

**Mac installation or shell-file permission issue?** See [macOS uv troubleshooting](macos_uv.html).

<aside class="notes">
Run only the command for your operating system. If uv is already available,
skip installation and check its version. The macOS/Linux command downloads
Astral's installer script and passes it to the shell to execute; the official
guide explains how to inspect the script first. If winget is unavailable, the
guide also provides a Windows standalone installer and downloadable binaries;
choose an approved method with the instructor or IT on a managed computer.
If curl is missing on Linux and wget is already installed, the official
alternative is wget -qO- https://astral.sh/uv/install.sh | sh. On a Mac already
using Homebrew, brew install uv is another official option. Only one uv
installation method is needed. Do not change system security settings to bypass
a restriction. uv selects the platform's installer binary. Intel Macs need
additional preparation for a course dependency, covered on the next slide.
Reopening an editor's integrated terminal may require restarting the editor.
</aside>

---

# Intel Mac · prepare a dependency build

## Complete this before `uv sync`

The course's `cryptography` dependency needs a **source build on Intel Macs**.
In macOS Terminal, install Apple's command-line tools and wait for them to finish:

```bash
xcode-select --install
```

With [Homebrew](https://brew.sh/) installed, prepare the libraries and compiler:

```bash
brew install openssl@3 rust
```

Then continue with `uv sync --group examples`; allow extra time for compilation.
An Intel Mac build still needs verification on your machine with the instructor.

<aside class="notes">
Check Apple menu > About This Mac to distinguish an Intel processor from Apple
silicon. On Apple silicon, use a native ARM64 terminal and Python, rather than
an Intel environment under Rosetta, so compatible binary packages can be used.
If command-line tools are already installed, do not reinstall them. Homebrew
installation and source builds can need extra disk space, downloads, and IT
support on managed machines. If Homebrew is not available, review its official
installation instructions or use the MacPorts alternative in the cryptography
guide with the instructor. Keep the course's locked dependency versions.
cryptography 49 removed Intel macOS support and prebuilt wheels; the course
currently locks cryptography 50.0.1. Its documented macOS source-build
requirements include a C compiler, Rust, and a separately installed OpenSSL;
the base macOS SSL libraries are insufficient. uv sync can build this dependency
from source. This preparation is not a claim that native Intel execution has
been verified. If compilation fails, share the redacted error with the instructor.

[Sources]

- https://cryptography.io/en/stable/installation/#building-cryptography-on-macos
- https://cryptography.io/en/stable/changelog/
- https://brew.sh/
</aside>

---

# What uv manages for you

## Prepare the project, then run a program inside it

| Command | Purpose |
| --- | --- |
| `uv sync --group examples` | Prepares the environment and installs the example dependencies |
| `uv run --group examples python …` | Runs Python with those dependencies available |

| Item in the course folder | Meaning |
| --- | --- |
| `pyproject.toml` | Required Python version and libraries |
| `uv.lock` | Recorded dependency versions for reproducibility |
| `.venv` | Local environment created by uv; no manual activation needed |

**Coding assistant:** “Explain this command before I run it. What will it change?”

<aside class="notes">
The project requires Python 3.13 or newer. uv can download a compatible Python
if one is not available, subject to network access and the computer's setup.
The examples group includes the libraries needed by the supplied chat app.
uv run also checks the project environment before executing the command.
Keep pyproject.toml and uv.lock supplied with the course; students do not need
to edit either file or work inside .venv for Week 1.
The lockfile can be shared between operating systems; the .venv folder cannot.
When moving to another computer, copy the course files without .venv and run
uv sync --group examples there to create that computer's environment.

[Sources]

- https://docs.astral.sh/uv/guides/projects/
</aside>

---

# Check Python before the chat

## The same commands work on Windows, macOS, and Linux

From the course folder, prepare the dependencies; the first run may take several minutes:

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

When the terminal prompt returns, run a small Python instruction:

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

**Expected output:** `Python is ready`

This is Python executing your instruction. No model or API key is involved.

<aside class="notes">
Wait for each command to finish before entering the next. Installation output
varies between computers; success means the sync command finishes without an
error and the Python command prints the expected text. The -c option tells
Python to execute the instruction supplied inside the following quotes.
If setup fails, use the troubleshooting slides before continuing.
</aside>

---

# Connect with your course key

## `.env` holds this app's connection settings

In the editor, copy `.env.example` to a new file named exactly **`.env`**, beside
`pyproject.toml`. Keep an existing configured `.env`.

The template already contains the course 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 with your individual instructor-supplied key
and save. Check that the filename is not `.env.txt`.

**After any `.env` change:** save, stop with **Control+C** on all three systems,
and launch again.

<aside class="notes">
Use a plain-text code editor. If hidden files are not visible in the file
manager, the editor's file list can help find .env.example and create .env.
Retain the setting names and replace only the key value after the equals sign.
For an existing .env, compare the endpoint and model with .env.example before
changing settings. The app's helper loads .env from the course folder. A key
placeholder can let the app start but will not provide working API access;
a returned answer is the connection check. Prompts and conversation context go
through PPQ to the model provider, so use public practice questions.
</aside>

---

# Find files whose names start with a dot

## Keep the exact names `.env.example` and `.env`

The editor's file list can show these files even when the file manager hides them.
To find the course files from the terminal:

| Shell | Command |
| --- | --- |
| Windows PowerShell | `ls` |
| macOS zsh / Linux bash | `ls -a` |

These commands list names; they do not print your key.
Check that the saved file is **`.env`**, beside `pyproject.toml`, with no `.txt` suffix.

**Windows File Explorer:** enable **View → Show → File name extensions**.

<aside class="notes">
In Windows PowerShell, ls is an alias for Get-ChildItem. A leading dot does not
make a Windows file hidden, so ls normally shows .env and .env.example. If a
file has the Windows Hidden attribute, use ls -Force to include it.
On Windows 11, View > Show > Hidden items also reveals files with the hidden
attribute; on Windows 10 these controls are in the View tab/options. On macOS
and Linux, a leading dot normally hides a file from the file manager. Use the
editor's file list to open it, or the terminal listing above to check the name.
GNOME Files on Linux also provides Show Hidden Files (Ctrl+H). Do not remove the
leading dot to make the file visible: the app expects .env. If creating .env
with Save As, use the code editor's plain-text format, retain .env.example, and
keep an existing configured .env instead of replacing it. This also applies
to the updater's .course-update.json and .course-updates folder.

[Sources]

- https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-childitem
- https://support.microsoft.com/en-us/windows/experience/fileexplorer/file-explorer-in-windows
- https://help.gnome.org/gnome-help/files-hidden.html
</aside>

---

# What your course key provides

## Individual API access through PPQ

- You need no PPQ signup or payment to use the supplied key.
- The instructor communicates your key's spending allowance and expiration date.
- The default model is `deepseek/deepseek-v4.1-flash`; the optional alternative
  is `openai/gpt-5.6-luna`. Change `LLM_MODEL`, save, and restart to switch.
- Use your own subscription or free tier for the coding assistant.
  Reserve the supplied PPQ key for agents running inside your course code.

Keep the key in private settings. Never include it in prompts, screenshots,
shared logs, or submissions.

---

# Open your first chat

## The terminal runs the app; the browser displays it

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

Leave this terminal open. The app keeps running, so the prompt does not return.
Questions and conversation context go through PPQ to the model provider.

Open [http://127.0.0.1:7932](http://127.0.0.1:7932) in your browser and ask:

> Which canton is Martigny in?

**Checkpoint:** the chat displays an answer. You still need to check its claims.

To stop the app, return to its terminal and press **Control+C** on Windows, Mac, or Linux.

<aside class="notes">
127.0.0.1 refers to this computer. It is the local app address, not the model
provider address. The app sends the question and conversation context to the
provider configured in .env. The built-in browser interface needs internet on
first use. Opening a page successfully proves that the local server responds;
receiving an answer additionally checks the model connection.
</aside>

---

# If a setup command fails

## Read the message before trying another command

| What you see | First check |
| --- | --- |
| `uv` is not found or recognized | Reopen the terminal or editor after installation; retry `uv --version` |
| No `pyproject.toml`, or Python cannot open the script | Use `pwd` and `ls`; check the extracted folder, quoted path, and exact filename case |
| Download fails, or a library cannot be imported | Check internet access and the complete error; retry `uv sync --group examples`, then use the full `uv run --group examples …` command |

**Coding assistant:** “Here is my command and error, with secrets removed.
Explain the likely cause and suggest one reversible check.”

<aside class="notes">
Do not repeatedly reinstall tools without reading the error. Dependency
installation may require downloading both Python and packages. A blocked
network, certificate problem, or permission error needs instructor or IT help;
do not disable certificate checks or system protections. Share the command,
operating system, current folder, and relevant error text, after removing
credentials and any private path details.
If pwd or ls is unrecognized on Windows, open PowerShell instead of Command
Prompt. If an activation script is blocked, use the documented uv run command;
manual .venv activation is unnecessary. If uv works in one terminal but not
another, restart the second terminal's application and check its shell profile.
For macOS/Linux installer PATH issues, follow the installer message to reopen
the shell or load its environment; ask the instructor before editing profiles.
</aside>

---

# If the chat does not work

## Use the terminal output to locate the problem

| What you see | First check |
| --- | --- |
| Browser cannot connect, or the interface does not load | Check the app is still running and the address is `http://127.0.0.1:7932`; check internet access for the interface's first load |
| `Address already in use` | A previous app may still be running; stop your earlier instance with Ctrl+C in its terminal, then retry |

If the interface opens but PPQ rejects a question, check the terminal message
using the next slide.

<aside class="notes">
Closing a browser tab does not stop the Python server. If another program owns
the port, ask for help rather than stopping an unfamiliar process.
</aside>

---

# If PPQ rejects a request

## Check the cause before sending another question

| Terminal message | First check |
| --- | --- |
| Missing setting or authentication failure | Check the `.env` filename and location; replace the key placeholder with your supplied key, save, and restart |
| Model unknown or unavailable | Use the exact model ID from `.env.example` or the course alternative; save and restart |
| Spending limit reached or key expired | Stop retrying and contact the instructor, who manages your allowance and expiry |

Share the error with secrets removed. Never send the key itself.

**Checkpoint:** one public question returns an answer; review its claims.

<aside class="notes">
The instructor can check key status without displaying its value to the class.
Students do not need to open a PPQ account or purchase credits to resolve a
course-key problem. Local Python checks and deterministic offline exercises
remain available while model access is being resolved.
</aside>

---

# Come back next session

## Open the same course folder and launch again

1. Open the course folder in the editor and open its terminal.
2. Check `ls` shows `pyproject.toml` and `examples`.
3. From Day 02 / Week 02 onward, start every session by running `uv run scripts/update.py`.
4. Start the app and open its browser address:

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

After changing an instruction or `.env`: **save, Ctrl+C, run again, then start a new chat**.
Installed uv and a saved `.env` can be reused.

The updater shows progress and preserves your work. Review any incoming course
copies it saves in `.course-updates/`; keep `.course-update.json` in the folder.

Continue with [Week 1 · your first PydanticAI chat](week_01.html).

<aside class="notes">
The supplied script does not automatically reload when edited. Stop it in its
terminal and rerun the launch command after saving changes. Use a new chat to
avoid mixing a previous conversation with the changed instructions. From
Day 02 / Week 02 onward, run the updater in the existing course folder at the
start of every session. It reports when no newer course release is available.
The updater installs its own Rich dependency through uv and needs no Git. It compares
the deployment number, verifies the download, adds new files, and updates only
unchanged course files. Edited files and known local deletions are preserved;
incoming changes that need review are saved separately. Files removed upstream
are also retained. Keep the hidden .course-update.json baseline supplied in the
ZIP: without it, all differing existing files are preserved and missing files
are added conservatively. The recorded version advances after an update even
when incoming copies still need manual review. Use --check to compare versions
or --dry-run to preview verified changes without applying them. The optional
--directory PATH selects a course folder and --course-url URL selects an
instructor-provided course website. Run uv sync --group examples if course
dependencies changed, then check the environment again.
</aside>