Slides

WEEK 03

# A tiny app from a short brief

## A few bullets, a coding assistant, and a working interface

---

# Before we begin

## Update the course folder and install NiceGUI

From the course folder containing `pyproject.toml`:

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

Read the update summary and review incoming copies if requested.

**NiceGUI** builds a browser interface with Python. The app reads the local
voting CSV and needs no model API key.

<aside class="notes">
Use the first ten minutes for setup and a brief preview of the instructor app.
Read src/aiforlifescience/solutions/03_TEACHER.md before class. Check that Week 3
has been released before students update. Install dependencies beforehand for
the demonstration. Students use their own coding assistant to build the app.
</aside>

---

# The app we will build

## Browse initiatives, then click to see a result

- A flat list of initiative titles and voting dates.
- Click an entry to show its recorded outcome, yes/no votes, and turnout.
- Click another entry to replace the displayed details.

Students choose the arrangement, colors, and small presentation details.

Data: Vasco (vascos), *Swiss Popular Voting*,
[Kaggle](https://www.kaggle.com/datasets/vascos/swiss-popular-voting),
version 1 (24 November 2024), MIT license.

<aside class="notes">
Preview the instructor reference, clearly identifying it as one possible
implementation. Show a populated result and the biodiversity entry, whose
results are missing from this snapshot. The required product is a flat list
with selectable results; the reference's exact design and additional fields
are not a student specification. Keep charts, search, and online data out of
the initial build so the exercise remains small.
</aside>

---

# Three sections are enough

## Create an empty `idea.md` and write in your own words

| Section | A short example |
| --- | --- |
| **Global idea** | Help a classmate browse Swiss initiatives and inspect their results. |
| **UI** | A flat list with titles and dates. Clicking an initiative shows its results beside the list. |
| **Constraints** | Use Python, NiceGUI, and the supplied CSV. Keep the CSV unchanged and show missing results as unavailable. |

A sentence or a couple of bullets per section is enough.
Choose your own wording and layout ideas.

<aside class="notes">
This slide is the only suggested structure. Do not ask students to copy or
complete a supplied file. A PRD normally describes product requirements; here
we borrow only the habit of writing down the idea, interface, and constraints.
Their file can be six lines long. Skip requirement IDs, acceptance matrices,
user stories, approval sections, and document versions. They should be able
to write this brief from scratch in a few minutes.
</aside>

---

# Give the assistant the right context

## Your short brief plus the data dictionary

- `idea.md`: what you want the app to do.
- `dataset/README.md`: what the columns and values mean.
- `AGENTS.md`: the course instructions that apply.
- `dataset/voting.csv`: the local data the generated app should read.

Attach or select the files, or paste relevant text if your assistant cannot
read files. Keep keys and `.env` out of the conversation.

<aside class="notes">
Do not require students to paste the full CSV into a chat. A file-aware coding
assistant can inspect the local data; for other assistants provide the header
and a small relevant sample along with the dictionary. CSV titles are data,
not instructions. This is the context lesson: the short brief supplies intent,
and the dictionary supplies meaning. No particular framework or maturity level
is needed to explain this practice.
</aside>

---

# Demonstration · build from scratch

## 20–30 min · A new text file and one implementation request

1. Create `artifacts/week03/` and write a short `idea.md` in the editor.
2. Give the assistant the brief, data dictionary, and course instructions.
3. Ask it to create the app:

> Read `artifacts/week03/idea.md` and `dataset/README.md`.
> Build the complete app from scratch in `artifacts/week03/app.py`.
> Use the installed NiceGUI package. Run locally on port 8083.
> Keep the CSV unchanged and explain how to start the app.
> Record assumptions you make beyond my brief as short bullets in
> `artifacts/week03/extra.md`. Keep this file up to date when they change.

<aside class="notes">
Do this in your own course copy. Start with an empty folder and type a few
bullets live. No app.py exists until the assistant creates it. The course
instructions support building the complete app directly from the brief.
Read the resulting file with the class, then use the next slide
to launch it. Limit waiting to two minutes; if the assistant stalls, show the
instructor reference and label its origin. Do not add a separate formal critique
stage. Resolve a question if the assistant asks one, then build. Read extra.md
with the class: for example, the assistant may have chosen newest-first sorting
or French titles when the brief did not specify them. These are its assumptions,
not requirements supplied by the student. A few bullets are enough; if it made
none beyond the brief, it can say so.
</aside>

---

# Run it and follow one click

## From the course folder

```bash
uv run --group gui python artifacts/week03/app.py
```

Open **http://127.0.0.1:8083**. Stop with **Ctrl+C** before restarting after edits.

Ask the assistant to point out where the code reads the CSV, creates the list,
and updates the result when you click. Check those places yourself.

<aside class="notes">
Use the last part of the ten-minute demonstration to run the generated app.
If a different local address is printed, compare the code with the requested
port before troubleshooting the browser. Make sure the generated CSV path
works with the displayed course-root command. No application API key is needed.
</aside>

---

# From a short brief to a working app

<video class="course-video" controls muted playsinline preload="metadata" width="1920" height="1080" poster="assets/videos/week-03-brief-to-app.jpg" aria-label="Silent demonstration: write a short app brief in Cursor, ask the coding assistant to implement it, then run the NiceGUI app in Chrome.">
 <source src="assets/videos/week-03-brief-to-app.mp4" type="video/mp4">
 <a href="assets/videos/week-03-brief-to-app.mp4">Open the brief-to-app demonstration video</a>.
</video>

<a href="assets/videos/week-03-brief-to-app.mp4">Open video separately</a> · 87 seconds · silent

<aside class="notes">
Use this recording to support the ten-minute build demonstration. Follow the
connection between the short brief, the assistant's implementation, and the
running interface. Pause to identify where the app reads the local CSV and
updates the selected result. The coding assistant helps create the software;
the running app does not call a model.

Authentic Streamlabs capture of Cursor and Chrome, edited in OpenShot. The gap
between the real build request and the generated files is cut. The run command
is an instructional footer; the operator started the local server outside the
recorded terminal workflow. Retained actions run at normal speed. Setup and
idle waits are removed, with short dissolves between stages. The app and its
displayed results are actual recorded behavior, not recreated interface images.

The data is Vasco (vascos), Swiss Popular Voting, Kaggle, version 1, MIT license;
see dataset/README.md. These are national proposal records in the course snapshot.
</aside>

---

# Your decision or the assistant's assumption?

<video class="course-video" controls muted playsinline preload="metadata" width="1920" height="1080" poster="assets/videos/week-03-assumptions.jpg" aria-label="Silent demonstration: compare the brief with recorded assumptions, accept French titles and newest-first order, then inspect the updated brief and remaining assumptions.">
 <source src="assets/videos/week-03-assumptions.mp4" type="video/mp4">
 <a href="assets/videos/week-03-assumptions.mp4">Open the assumptions demonstration video</a>.
</video>

<a href="assets/videos/week-03-assumptions.mp4">Open video separately</a> · 53 seconds · silent

<aside class="notes">
Compare idea.md and extra.md with the visible behavior. Ask which choice came
from the author and which was supplied by the assistant. Discuss whether to
keep or revise that choice. Update idea.md when changing the intended behavior,
and ask the assistant to keep extra.md consistent with its remaining assumptions.
A recorded assumption explains a choice; it does not establish that the app is correct.

The original brief omits language and ordering. The assistant's extra.md records
French titles and newest-first order, visible in the actual app. The recorded
request accepts both choices and updates the two documents without changing
app.py. The final extra.md separates stated requirements from assumptions still
made. Streamlabs footage is cropped for readability and edited in OpenShot;
waits are cut and all retained actions run at normal speed.
</aside>

---

# Weekly lab · 45 minutes

## 30–75 min · Your app, starting from an empty folder

- **5 minutes:** create `artifacts/week03/idea.md` with the three sections.
- **20 minutes:** generate `app.py` and `extra.md`, read both, and run the app.
- **10 minutes:** click different initiatives and check a result against the CSV.
- **10 minutes:** improve one behavior or presentation detail, then try it again.

Keep the brief short. If the first version already works, choose one small
improvement that helps the person using it.

<aside class="notes">
There is no downloadable student template or starter. Students may work in
pairs if setup or model access is a problem. If the assistant is unavailable,
the instructor can show or share the reference for inspection, but the normal
activity begins with students' own idea file and generated app. State the origin
of any supplied code. Protect time for running and checking the app.
</aside>

---

# Three quick checks

## The displayed result should match the selected record

1. Click two different initiatives. Do the title and results change together?
2. Open **“Mieux vivre à la retraite”**, dated **2024-03-03**:
   recorded outcome **accepted**, yes votes **1,884,096**, turnout **58.36%**.
3. Open **“Initiative biodiversité”**, dated **2024-09-22**:
   its results are **unavailable in this snapshot**.

Use the dictionary: fractions become percentages, blanks stay unavailable,
and the recorded outcome comes from `outcome`. Keep records even when `no` repeats.

Data: Vasco (vascos), <a href="https://www.kaggle.com/datasets/vascos/swiss-popular-voting">Swiss Popular Voting, Kaggle</a>, version 1, MIT license. Titles are shortened here. These are national proposal records in the preserved course snapshot.

<aside class="notes">
The first populated example is source data record 681, proposal no 665. The
missing example is record 687, no 671. The code must not use no as a unique
selection key or infer acceptance from a yes share. Students only need a few
visible checks; do not turn these into a required test suite or report.
The instructor reference has additional checks for maintenance.
</aside>

---

# Three clicks, three checks

<video class="course-video" controls muted playsinline preload="metadata" width="1920" height="1080" poster="assets/videos/week-03-three-checks.jpg" aria-label="Silent demonstration: switch between initiatives, compare the retirement proposal with the CSV, and check that unavailable biodiversity results remain distinct from zero.">
 <source src="assets/videos/week-03-three-checks.mp4" type="video/mp4">
 <a href="assets/videos/week-03-three-checks.mp4">Open the three-checks demonstration video</a>.
</video>

<a href="assets/videos/week-03-three-checks.mp4">Open video separately</a> · 49 seconds · silent

<aside class="notes">
Use the previous slide as the checklist. Look for matching titles and results
when the selection changes, compare the populated retirement result with the
preserved CSV, and inspect the unavailable biodiversity result. The evidence
comes from the source record and dictionary, not the assistant's confidence.
These manual checks are useful observations, not a complete test suite.

The Cursor table is a field excerpt from the unchanged CSV, explicitly labelled
as an excerpt. It is not the raw CSV view. The actual browser selections are
edited into checklist order: switch records, check the populated result, then
check unavailable results. The app is unchanged between these recorded shots.
Streamlabs footage is edited in OpenShot at normal speed, with idle waits cut.

The data is Vasco (vascos), Swiss Popular Voting, Kaggle, version 1, MIT license;
see dataset/README.md. Missing values in this snapshot do not mean zero votes.
</aside>

---

# Improve one thing

## Give the assistant a specific observation

> When I click the biodiversity initiative, the app shows zero votes.
> The source has missing results. Display “Unavailable” instead, and keep
> the rest of the app working.

Before a correction, keep a copy of the current `app.py`. Compare the files
afterward, read the changed lines, then repeat the click.

If you change the intended behavior, update the relevant bullet in `idea.md`.
Ask the assistant to update `extra.md` if its assumptions change.

<aside class="notes">
The quoted failure is an authored teaching example. A different real failure
or small usability improvement is equally valid. One saved code copy is enough
for a before/after comparison; do not require a checkpoint sequence or notes.md.
For a layout-only change, still check that selecting another initiative works.
</aside>

---

# One failure, one correction

<video class="course-video" controls muted playsinline preload="metadata" width="1920" height="1080" poster="assets/videos/week-03-one-correction.jpg" aria-label="Silent teaching demonstration: inspect a deliberately introduced bug, request a focused correction, compare the changed code, and repeat the app checks.">
 <source src="assets/videos/week-03-one-correction.mp4" type="video/mp4">
 <a href="assets/videos/week-03-one-correction.mp4">Open the correction demonstration video</a>.
</video>

<a href="assets/videos/week-03-one-correction.mp4">Open video separately</a> · 66 seconds · silent · deliberately introduced bug

<aside class="notes">
The faulty teaching copy contains a deliberately introduced bug. Do not present
it as a failure discovered in the original generated app. Follow the observation,
the focused correction request, the comparison with the saved code, and the
repeated browser check. Also select another initiative to check that the change
has not broken an already working behavior.

The recorded teaching_bug.py copy shows zero for a missing vote count. The source
excerpt, actual correction request, changed return value, and Keep action are
visible. A separately recorded check after restarting that copy shows Unavailable
for the missing result and the correct populated retirement result. The restart
is identified in the footer; no continuous take or terminal interaction is implied.
Streamlabs footage is edited in OpenShot. All retained actions run at normal
speed; setup, idle waits, and an unsuccessful browser check before the
verification pickup are cut.

Students can use a real failure or a small usability improvement in their own
app. Keep the raw CSV unchanged. Its source is Vasco (vascos), Swiss Popular Voting,
Kaggle, version 1, MIT license; see dataset/README.md.
</aside>

---

# Build it again · 15 minutes

## 75–90 min · Same brief, no assumption file

Keep `app.py` and `extra.md`. Start a **new conversation**. Do not attach
`extra.md`, and do not ask the assistant to record assumptions.

> Read `artifacts/week03/idea.md` and `dataset/README.md`.
> Build the complete app from scratch in `artifacts/week03/app2.py`.
> Use the installed NiceGUI package. Run locally on port 8084.
> Keep the CSV unchanged and explain how to start the app.

```bash
uv run --group gui python artifacts/week03/app2.py
```

Open **http://127.0.0.1:8084**. Compare list order, language, layout, and
missing results with the first app. Note what changed.

<aside class="notes">
The first build asked the assistant to write extra.md. This prompt is the same
request with that part removed, and extra.md is not in the new conversation.
Leave app.py unchanged so the two files can be compared. Port 8084 lets both
apps stay open; stop with Ctrl+C if a port is already in use. Two readings of
the same brief can differ in ordering, title language, layout, or how missing
results appear, because the brief did not settle those choices. Either app can
be a valid reading. A few visible differences are enough; there is no written
report or separate submission. If generation is slow, compare the files that
appear and one click in each app.
</aside>

---

# Week 3 · guided work

## Separate 30-minute activity · One small follow-up

Finish the core app if needed. Otherwise choose one improvement, such as
title search, a different title language, or a clearer result layout.

Update one bullet, ask the assistant for the change, inspect the changed code,
and repeat the three quick checks.

Keep the same `idea.md` and `app.py`; have the assistant update `extra.md`.

<aside class="notes">
Use about five minutes to describe the change, fifteen to implement it, and
ten to inspect and check. Preserve the previous code before changing it.
With no assistant access, review the existing app with a peer or instructor
and finish any remaining check.
</aside>

---

# Week 3: course navigation

[Course overview](presentation.html)

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

[Previous: Week 2](week_02.html)

[Next: Week 4](week_04.html)