Project Documentation

Course Project Overview

Edited on 16/09: Proof-of-concept oral presentations moved to Week 9 (November 11).

Edited on 10/09: Added mandatory weekly decision-log and TA-update expectations.

The course project is a semester-long team project in which you will design, build, evaluate, and document an AI system for global health or humanitarian response.

The goal is not only to train a model or build an interface. We want to make you build a credible prototype of an AI system that could support decision making, communication, translation, risk analysis, or clinical work in a constrained and high-stakes setting.

See the Project Briefs page for the available project descriptions.

Project Philosophy

Your project will be evaluated through five recurring questions.

These questions should appear in your technical design, your proof of concept, and your final report.

Note on AI use

This course is happening in late 2026. LLMs are a thing. Nowadays they are rather good at coding.

You are allowed to use AI responsibly to help you in the project. It can be a powerful tool for brainstorming, debugging, coding boring parts of the code faster (including tests and documentation, there is no longer an excuse not to write them!).

Beware! As of September 2026, LLMs still hallucinate and can still bring a lot of mess, excessively verbose code, when tests do not pass they may prefer making tests easier to pass than fix the actual code logic.

If you do choose to generate code with LLMs, carefully check it all manually. You should understand everything, be critical, replace slop with proper content, be rude to your coding agent.

We will look for traces of detrimental AI slop in your submissions and penalize them. We think it is part of your engineering journey to learn how to make a smart use of AI in your work.

Project Timeline

Deadlines are set at 21:59 on Sundays.

Weekly Project Responsibilities

Every team must maintain the provided docs/decision-log.md file in its project repository. Populate it at least once per week, even if the entry is simply that the current plan still holds and why. Also update it whenever the team changes scope, datasets, baselines, evaluation strategy, interface contracts, risks, fallback plans, or features to cut.

Every week, each team must give a short project update to a TA during the exercise session.

If the team cannot give this update in person, it must post an update on the course forum on the Wednesday of that week, as a message visible only to staff.

Assessment

The project counts for 80% of the course grade; the remaining 20% covers in-class quizzes.

The project grade is split across two intermediate milestones, the final submission and oral presentations. See the Project Rubrics.

Repository

All project work and submissions happen inside your team GitHub repository in the course GitHub organization.

Your repository is both the place you will be working on during the semester and your submission record. Reports, milestone documents, presentation material, the weekly decision log, and final documentation should all be committed to the repository.

The course provides shared computing resources on EPFL's SCITAS cluster for project work that is too large, slow, or inconvenient to run locally. See the SCITAS Guide for how to connect and submit jobs.

See the Project Setup Guide.

Expected Final Output

By the end of the course, each team submits a reproducible and clean code repository (tests, linting, type checks, pre-commit, CI, working prototype), a final report (submitted as a PDF inside the repository), one individual contribution report per team member, and handover or maintenance documentation.

See the Final Submission tab for the complete submission checklist and report requirements.

What Counts As Success

A successful project does not need to solve the full real-world problem. It should instead make a well-scoped, technically credible, and well-evaluated contribution.

Strong projects usually have:

• a clear user and use case;
• a working vertical slice through the system;
• a realistic evaluation strategy;
• honest limitations and failure analysis;
• readable and reproducible code;
• evidence of collaboration through issues, pull requests, and reviews;
• a final demo that shows the system working, not just slides describing it.

Project Management 101

Edited on 10/09: Clarified that docs/decision-log.md is mandatory and must be updated weekly.

Working in teams can be challenging. Here is a guide we provide you to help you manage your teams and (hopefully) go through less drama over the course of the semester.

A lot of things are covered, we encourage you to regularly check this guide throughout the semester to check tips that may get useful as you progress on the project.

Good project management in this course means keeping the project scoped, runnable, evaluated, and honestly documented while several people work on it at the same time.

Start With The Brief

Find a time to meet, get to know each other and the project together before starting actual work. Read the project brief individually, make sure you understand it before meeting with your peers. This will make the following easier, better know what you will be talking about ;)

Agree on:

• the intended user;
• one core use case;
• the minimum convincing end-to-end proof of concept;
• what evidence will show that the system works;
• what is out of scope.

Do not turn the brief into a list of every possible feature. Choose the smallest useful system that addresses the central technical risk.

Have The Team Conversation Early

During the first project meeting, explicitly discuss each team member's strengths, weaknesses, constraints (think of things that may compromise the time you spend on this project throughout the semester), why not learning goals too.

Useful questions:

• What have you already done: courses, data work, ML, backend, frontend, evaluation, writing in English (prompting an LLM to ask it to write your report is not what we are talking about for this one), presentations?
• What do you want to learn in this project?
• What made you choose this project?
• What kinds of tasks are you slow at or uncomfortable with?
• When are you usually available to meet / work together?
• What deadlines or external constraints should the team know about?

Use this conversation to split roles. Do not assign roles only based on who speaks first or who seems most confident.

Cover The Core Responsibilities

Every team must cover these responsibilities. One person may cover several (there are more responsibilities than team members…), and roles can change during the semester.

Do ensure to split evaluation and reproducibility: That's the best way to ensure the documentation is solid and the environment is actually reproducible, if reproducing results requires coordination with the person who did the evaluation, that's a signal the documentation lacks something.

Build A Vertical Slice First

Your proof of concept should be a thin vertical slice: one meaningful path through the system that works end to end.

Examples:

• data sample -> baseline forecast -> simple dashboard;
• a few guideline documents -> retrieval -> grounded answer with sources;
• image input -> local model inference -> result screen;
• patient dialogue -> structured observations -> Bayesian update;
• speech input -> translation -> verification or correction workflow.

Avoid isolated work packages that only meet at the end. A weak integrated demo is more useful than five polished components that cannot run together.

Work In Small Tasks

Use GitHub issues or a project board from Week 3 onward.

A good task has:

• one owner (you may work with several members on a specific task, but one person has to be held accountable for the completion of the task to avoid diffusion of responsibility);
• a clear output;
• a deadline;
• a link to a milestone or risk;
• a definition of successfully completed.

Bad task: Work on model.

Better task: Add persistence baseline for DengAI weekly cases and report MAE on temporal split.

Use Pull Requests Early

Use pull requests throughout the semester, not only before deadlines.

A good pull request:

• solves one clear problem;
• explains what changed and why;
• includes tests or a reason why tests do not apply;
• passes formatting, linting, type checks, and tests;
• is small enough for a teammate to review seriously (absolute max 1,000 lines, aim for (way) less).

Assign PRs to a different team member for review, do not approve you own PRs.

Approving a PR means you read it and believe it is safe to merge. Do not approve because the deadline is close.

Keep The Project Runnable

At least once per week, someone should check that the project runs from a fresh clone or a clean environment. This takes max 10 minutes of human effort and avoids stress close to the deadline. Do not always make the same teammate do this.

Run the Fresh Clone Health Check from the Project Setup Guide to confirm the repository is healthy from a clean environment.

Make Evaluation A Week 1 Topic

Define evaluation early, this will change (in a good way) your implementation decisions and avoid last minute changes.

Decide early:

• the baseline(s), what should your project be compared to;
• the metric or review criterion;
• the data split or test cases;
• what counts as a failure;
• how you will show uncertainty, limitations, or unsafe cases.

Each project needs evidence. A demo without evaluation is not enough.

Plan Around Milestones

Use the course milestones as management checkpoints.

Control Scope Deliberately

Use three categories:

• Must have: needed for the minimum convincing proof of concept.
• Should have: useful if the core system works early.
• Stretch: only attempted after the demo, evaluation, and reproducibility are stable.

Cut scope early when needed, better do a smaller but neatly made project than having weak parts.

Keep A Decision Log

Every team must maintain the provided docs/decision-log.md file in its project repository. It is not a placeholder and not only a final-report aid: populate it at least once per week.

If no major decision changed during a week, still add a short entry explaining that the current plan remains valid and why. This is how staff can distinguish steady progress from undocumented drift.

Record decisions like:

• chosen core use case;
• datasets included or rejected;
• baseline model;
• evaluation split;
• API or UI contract;
• features cut from scope;
• known risks and fallbacks.

Each entry should include the date, the decision, the reason, the main alternatives rejected, the expected impact, and any owner or follow-up task.

This will make the final report easier to write and help staff understand your tradeoffs.

Define Interfaces Between People

Before working in parallel, agree on simple contracts.

Examples:

• data file schema;
• model input and output format;
• API endpoint request and response;
• UI fields expected from the backend;
• evaluation dataset format;
• configuration keys.

Write these contracts down. Most team delays come from hidden assumptions, not from hard algorithms.

Be open about your availability for communication, this can avoid unnecessary frustrations…

Use AI Tools Carefully

AI coding assistants can help with boilerplate, tests, documentation, debugging, and first drafts.

They can also produce incorrect, verbose, overcomplicated, or untested code (ok, LLMs tend to do this one less often than humans).

Rules for AI-generated work:

• understand the code before merging it;
• run the checks;
• require teammate review;
• remove hallucinated APIs, fake assumptions, and unnecessary abstractions;
• do not weaken tests just to make them pass (current LLMs love to do this).

You are responsible for the code in your repository.

Weekly Meeting Template

Keep weekly meetings short and concrete. The project coordinator should write an agenda and submit it to the rest of the team beforehand.

Suggested agenda:

1. What changed since last week?
2. What works now in the repository?
3. What is blocked?
4. Which tasks can/must be merged this week?
5. What evidence or evaluation did we add?
6. What should we cut, defer, or ask staff about?
7. New external constraints?

End every meeting with tasks for the upcoming week, with owners and deadlines.

Definition Of Done

A task is done when:

• the code or document is committed;
• the relevant checks pass;
• the README or docs are updated if needed;
• data, configuration, or assumptions are documented;
• a teammate has reviewed the change;
• the work can be reproduced by someone else.

If it only works on your laptop, it is not done.

Common Failure Modes

Avoid:

• building only a notebook;
• building only a UI mock-up;
• postponing integration to the final weeks;
• reporting model scores without a baseline or valid split;
• having no owner for evaluation;
• committing undocumented data or outputs;
• using direct pushes instead of PRs;
• letting one person silently do all integration;
• writing a final report that claims more than the repository shows;
• preparing no backup for the live demo.

Before Each Deadline

Ask:

• Can staff run the project from the repository?
• Is the current scope clear?
• Is the central technical risk addressed?
• Do we have evidence, even if imperfect?
• Are limitations and simulated parts explicit?
• Is every teammate's contribution visible through issues, PRs, reviews, commits, or documents?

If the answer is no, fix that before adding new features. The earlier this happens, the better.

Project Setup Guide

Edited on 10/09: Added docs/decision-log.md as a mandatory weekly-maintained project file.

This guide explains how your project repository should be set up and maintained.

Repository Access

Each team receives one repository from the staff.

Your repository starts as a minimal scaffold with documentation placeholders only. The Python setup, tooling, CI, tests, and minimal pipeline are built by your team during Milestone 1.

The main branch is not automatically protected. The course team enforces a pull-request workflow: do not push directly to main; all changes should go through pull requests.

Recommended branch names:

• feature/add-data-loader
• feature/baseline-model
• fix/ci-type-check
• docs/update-design
• experiment/geospatial-query-demo

Local Setup With uv

Clone your repository.

git clone <your-team-repository-url>
cd <your-team-repository>

Create the virtual environment and synchronize dependencies.

uv venv .venv
source .venv/bin/activate
uv sync

Install pre-commit hooks.

uv run pre-commit install

Run the quality checks locally.

uv run pre-commit run --all-files
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest

If formatting fails, format the code.

uv run ruff format .

Fresh Clone Health Check

The full set of checks that prove your repository is healthy from a clean environment:

uv sync
uv run pre-commit run --all-files
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest

Document these commands in your README. They double as the weekly freshness check described in the Project Management tab.

Required Repository Structure

Your exact structure may differ by project, but it should be clear and consistent.

Recommended structure:

.
|-- .env.example
|-- .gitignore
|-- .pre-commit-config.yaml
|-- README.md
|-- pyproject.toml
|-- uv.lock
|-- .github/
|   `-- workflows/
|       `-- ci.yml
|-- configs/
|   `-- example.yaml
|-- data/
|   |-- README.md
|   |-- DATASET_LICENSE.md
|   `-- data-provenance.md
|-- docs/
|   |-- final-report.pdf
|   |-- contribution-statement.md
|   |-- decision-log.md
|   |-- milestone-1-technical-design-and-repository.md
|   `-- milestone-2-proof-of-concept.md
|-- outputs/
|   `-- README.md
|-- scripts/
|   `-- run_smoke_pipeline.py
|-- src/
|   `-- <project_package>/
|       `-- __init__.py
`-- tests/
    `-- test_smoke.py

The root README should explain how to obtain or generate any data needed to run the project. Do not commit large datasets unless staff explicitly approves it.

The provided docs/decision-log.md file is mandatory to maintain. It must be populated at least once per week and after any important scope, data, model, evaluation, interface, risk, or fallback decision.

Python Project Requirements

Your repository must include a pyproject.toml.

The project must be installable and runnable from a fresh clone using documented commands. A staff member should be able to clone the repository, run uv venv and uv sync, and execute your minimal pipeline or demo instructions.

Dependencies should be pinned or locked. Commit uv.lock unless staff gives different instructions.

Running On SCITAS

Work that is too large, slow, or inconvenient to run on your own computer can be run on the course's shared EPFL computing resources. The SCITAS Guide explains how to connect, submit Slurm jobs, and manage data on the cluster.

CI Requirements

Your repository must include continuous integration that runs on pull requests and pushes to main.

CI must run at least:

• formatting check with ruff;
• linting with ruff;
• type checking with pyright;
• tests.

This will ensure every change can be checked automatically.

Pre-Commit Requirements

All teams must use pre-commit.

Pre-commit should run the same basic checks that developers should not skip locally, such as formatting, linting, and simple file hygiene checks.

Install pre-commit before your first contribution.

uv run pre-commit install

Run all hooks manually when needed.

uv run pre-commit run --all-files

Data And Secrets

Do not commit:

• API keys;
• passwords;
• private credentials;
• personal data;
• protected health information;
• large datasets;
• generated model checkpoints unless staff approves them.

If your project needs a secret, document the required environment variable and provide a placeholder example.

Use .env.example for examples. Do not commit .env.

If your project needs data, include a data/README.md explaining:

• what data is needed;
• where it comes from;
• whether it is public or restricted;
• how to download or generate a small sample;
• what should not be committed.

Also document dataset licensing and provenance:

• data/DATASET_LICENSE.md should describe usage rights, redistribution terms, attribution requirements, and anonymization or de-identification status;
• data/data-provenance.md should describe where each dataset came from, when it was obtained, how it was processed, and known limitations or biases.

Configuration

Separate configuration from code.

Examples of configuration:

• model name;
• dataset path;
• language pair;
• geospatial region;
• threshold;
• prompt template path;
• output directory.

Configuration can be stored in configs/, environment variables, or command-line arguments. Avoid hard-coded absolute paths such as /home/<name>/....

README Requirements

Your README.md should include:

• project title;
• short description;
• team members and their contact information;
• setup instructions;
• how to run tests and checks;
• how to run the current pipeline or demo;
• data instructions;
• current limitations.

Keep the README current. A stale README is a reproducibility problem.

SCITAS Guide

SCITAS provides EPFL computing resources for work that is too large, too slow, or simply more convenient to run on a shared computing cluster. The main difference from using your own computer is that you do not start a long computation directly after connecting. You first connect to a login node, prepare your files, and then ask Slurm to run the computation on one or more compute nodes.

This separation is the central idea behind using SCITAS. The login node is the place from which you organize and submit work. Slurm is the process, named scheduler, that decides when and where that work runs. Note that, because the cluster is shared, a submitted job may wait in a queue before resources become available.

For this course, the usual resources are:

• Jed for CPU computations. Student jobs run through the academic partition.
• Izar for GPU computations and courses that require GPUs.

Kuma is the research GPU cluster and is not available to student or course accounts.

This guide deliberately covers only the workflow needed for typical course analyses. The full SCITAS documentation remains the reference for advanced usage.

Connecting to SCITAS

Before connecting, you need a valid GASPAR account and access to SCITAS for the course. Access should normally have been granted before the first class. If your SCITAS access does not work, contact fabrice.nemo@epfl.ch. Your computer must also be on the EPFL network, or connected to the EPFL VPN.

On macOS and Linux, SSH is already available from a terminal. For Windows users, SCITAS recommends Git Bash or Windows Subsystem for Linux (WSL). Open a terminal and connect with:

ssh username@cluster.hpc.epfl.ch

Replace username with your GASPAR username and cluster with the cluster you want. For example:

ssh alice@jed.hpc.epfl.ch

or

ssh bob@izar.hpc.epfl.ch

The first login may ask you to confirm the identity of the remote host, do confirm it. Once logged in, your terminal is running commands on a SCITAS login node rather than on your laptop. See the SCITAS connection documentation if you need more details.

A few shell commands are enough for most sessions:

pwd                              # show the current directory
ls                               # list files
cd path/to/folder                # move to another directory
mkdir new_folder                 # create a directory
nohup command > output.log 2>&1 & # keep a non-compute command running after logout

nohup is useful when a non-compute command should continue after an SSH session disconnects. Long computations should still be submitted through Slurm.

Use the login node to inspect files, edit small scripts, organize your project, and submit jobs. Computation itself should be sent through Slurm rather than run as a long process on the login node.

From a command to a Slurm job

On your own computer, running an analysis may be as simple as typing a command such as python analysis.py. On SCITAS, the same command is normally placed inside a small job script. The script tells Slurm both what to run and how many resources the calculation needs.

For a simple CPU job on Jed, a minimal script can look like this:

#!/bin/bash -l

#SBATCH --job-name=homework
#SBATCH --partition=academic
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --time=00:30:00
#SBATCH --mem=4G

source .venv/bin/activate
python analysis.py

Save it as, for example, job.sh. The final two lines are only an example. Adjust the virtual-environment path if needed, and replace the Python command with the command required for your homework.

The #SBATCH lines describe the resources reserved for the job. --nodes sets the number of compute nodes, --ntasks the number of processes, --cpus-per-task the CPU cores available to each process, --time the maximum wall time, and --mem the requested memory. Here, the job uses one node, one task, one CPU core, at most 30 minutes of computation time, and 4 GB of memory. These values should be realistic. Requesting much more time or memory than necessary can make a job harder to schedule and may increase the time spent waiting in the queue. See the SCITAS Slurm documentation for more options.

The academic partition is required for student CPU jobs on Jed. Its current limits allow up to 7 days and 8 nodes per job. On Izar, request GPUs with, for example, #SBATCH --gres=gpu:1. One GPU is normally sufficient for course work. Most Izar compute nodes have 2 GPUs; the gpu-xl nodes have 4 GPUs each. Standard Izar jobs can run for up to 3 days and use up to 8 nodes, while the long QoS allows up to 7 days. See the SCITAS QoS and partition documentation for the current limits.

Use GPU resources sparingly. Prefer Jed for development, preprocessing, testing, and any work that does not require a GPU. Use Izar when the computation actually benefits from GPU acceleration.

Submitting and following a job

Once the script is ready, submit it from the directory containing the files needed by the analysis:

sbatch job.sh

Slurm replies with a job identifier:

Submitted batch job 1234567

It identifies the job while it is queued or running. Check the job shortly after submission, since many configuration or runtime errors appear as soon as the job starts.

To see your jobs, use:

squeue

You can also inspect a specific job with:

squeue -j 1234567

A job marked PD is pending and waiting for resources. A job marked R is running. Waiting after submission is expected on a shared cluster. If you submitted the wrong script or no longer need a job, cancel it with:

scancel 1234567

Unless you configure another output file or working directory, Slurm normally writes the program output in the directory from which you ran sbatch, using a file named after the job ID, for example:

slurm-1234567.out

You can inspect it with commands such as:

less slurm-1234567.out

or

cat slurm-1234567.out

When a job does not behave as expected, this output file is usually the first place to look. It is often useful to check in the first minute after the job submission, to verify that everything is running smoothly and not waste computation time.

Managing project files and transferring data

For source code and scripts, use Git when possible. Make changes either on your own computer or from the SSH terminal, then use commits and push or pull as needed to keep the project synchronized. This gives you a clear history of changes and avoids using file-transfer commands as the main way to manage source code. You can also directly connect to the cluster using VSCode and the SSH extension (see the SCITAS VSCode documentation for more info.).

For public datasets, prefer keeping a script in Git that downloads and preprocesses the data. Run this script wherever the dataset is needed, so that the data can be rebuilt from its public sources and reproduced by others. For results or other files that do not belong in Git, transfer them directly between your computer and the cluster over SSH. rsync is useful because it can resume interrupted transfers and avoids copying unchanged data again. See the SCITAS data-transfer documentation for more options.

Run transfer commands from your own computer, not from the SCITAS login node. To send a project folder to Jed:

rsync -azP ./project/ <username>@jed.hpc.epfl.ch:/home/<username>/project/

To retrieve results from SCITAS:

rsync -azP <username>@jed.hpc.epfl.ch:/scratch/<username>/project/results/ ./results/

Replace jed with the cluster used by the course when necessary. As with SSH, direct transfers require access to the EPFL network or VPN.

For a simple copy, scp is also available:

scp file.txt <username>@jed.hpc.epfl.ch:/home/<username>/

Use scp -r when copying a directory. A graphical file-transfer application such as FileZilla or WinSCP can also be used when appropriate.

Choosing where data should be stored

The cluster exposes several file systems, but most course work only needs two of them. See the SCITAS file-system documentation for the full details.

Your home directory, /home/<username>, is the safe place for source code, scripts, small input files, and material that should persist. It has a default quota of 100 GB and is backed up.

Your scratch directory, /scratch/<username>, is designed for data that a running computation reads and writes intensively. You can refer to it through the environment variable $SCRATCH. Scratch is faster for this type of work, but it is temporary storage. It is not backed up, files older than 30 days are automatically removed, and additional cleanup may occur when the file system becomes too full.

There is one more detail that matters when moving between clusters: scratch storage is cluster-specific. A file placed in scratch on Jed is not automatically available in scratch on Izar. Course access is temporary and is revoked when the course period ends, so download the final work you want to keep before your access ends.

A practical default is therefore to keep the durable copy of your project in home, use scratch for larger temporary inputs and outputs while the job runs, then move the results you want to keep back to home or to your own computer.

For example, you can prepare a scratch directory with:

mkdir -p $SCRATCH/homework1

and copy a project into it with:

rsync -a ~/homework1/ $SCRATCH/homework1/

From there, move into the directory and submit the job as usual:

cd $SCRATCH/homework1
sbatch job.sh

Once the computation is complete, copy important results out of scratch rather than leaving the only copy there.

Minimal command reference

Pull Requests And Reviews

Use pull requests for all the project work. This is part of the project requirements, as a good habit that you will need in professional settings.

This will make your work easier to review, easier to reproduce, and less likely to break your teammates' work.

Basic Workflow

Create a branch.

git switch -c feature/my-change

Make your changes and run the standard checks from the Project Setup Guide.

Commit and push.

git add .
git commit -m "Add baseline data loader"
git push -u origin feature/my-change

Open a pull request on GitHub.

Request review from at least one teammate.

Merge only after CI passes and the required review is complete.

Good Pull Requests

A good pull request should:

• solve one clear problem;
• have a descriptive title;
• explain what changed and why;
• link to the relevant issue or milestone task when possible;
• include tests or explain why tests are not applicable;
• include screenshots, logs, or demo notes when user-facing behavior changes;
• avoid unrelated formatting or refactoring (pre-commit and a clean technical plan at the beginning of the semester will help you avoid them);
• avoid committing output files unless really needed;
• pass CI before review;
• be small enough for a teammate to review seriously (absolute max 1,000 lines, aim for (way) less).

Good PR title examples:

• Add baseline temporal split for risk model
• Implement trusted-source retrieval for messenger prototype
• Add CI workflow for ruff, pyright, and pytest
• Document data download for Freetown geospatial layers

Weak PR title examples:

• updates
• fix stuff
• final version
• code

Pull Request Description Template

Use a short, useful description.

## What changed

Describe the change in 2-5 bullets.

## Why

Explain the reason for the change.

## How to test

List the commands or manual steps used to check the change.

## Notes for reviewer

Mention risks, shortcuts, known limitations, or questions.

Good Reviews

A good review should check correctness, reproducibility, and clarity.

Reviewers should ask:

• Does this change do what it claims?
• Can I understand the code or documentation?
• Does it introduce hard-coded paths or hidden assumptions?
• Does it handle errors clearly?
• Does it keep configuration separate from code?
• Does it avoid committing secrets, large data, or generated artifacts?
• Does it include tests or a reasonable explanation for missing tests?
• Does it preserve the ability to run the project from a fresh clone?

Review Comment Style

Use clear labels when possible.

Examples:

• Blocking: This will fail on a fresh clone because the path is absolute.
• Question: Should this threshold be configurable?
• Suggestion: This function name could be more specific.
• Nitpick: Typo in the README.

Approving a PR means you believe the change is understandable, appropriate, and safe to merge. Do not approve a PR you have not read.

What Not To Do

Avoid:

• giant PRs that combine many unrelated changes;
• direct pushes to main;
• approving PRs only because CI is green;
• merging broken tests because the deadline is close;
• committing credentials or private data;
• using PRs only at the end of the project after all work is already done.

Generally, ensure your PR does not fall under the Common Failure Modes list from the Project Management 101.

Evidence Of Collaboration

The teaching team may inspect your repository history.

Healthy collaboration usually includes:

• issues or tasks assigned to team members;
• multiple contributors making meaningful commits;
• pull requests opened throughout the project;
• reviews by teammates;
• discussions about design, tests, and trade-offs;
• no single student doing almost all technical work without explanation.

Milestone 1: Technical Design and Reproducible Repository

Edited on 10/09: Added initial decision-log requirements and fixed the Project Briefs overview link.

Deadline: Sunday of Week 3, September 27, 21:59.

Weight: 12.5% of the project grade.

Purpose

This milestone has two main goals:

• Prepare the technical design for your project, based on the problem statement;
• Prepare the repository skeleton according to your technical design.

We'll check whether your project is well-scoped, technically feasible, and evaluable, and whether your repository already has the right form for your technical design. We may give you feedback on things to change for the rest of the semester.

The main goal is to make your assumptions explicit and validated by the course team, before you invest heavily in implementation, and to establish a healthy and reproducible development process from the start. Staff feedback will focus on scope, feasibility, evaluation validity, team organization, and repository hygiene.

Your technical design should also address the five recurring project questions from the course overview: constraints, trust, evidence, scale, and uncertainty.

Assigned Project

Your team is assigned one of the proposed course projects. Read the brief for your project on the Project Briefs overview page before writing the design.

Your technical design must be consistent with your assigned project brief.

It should:

• commit to one well-defined core use case from the brief;
• answer the brief's design questions in the relevant sections;
• target the brief's minimum convincing proof of concept;
• use the brief's evaluation ideas when defining your evaluation strategy.

Submission

Submit inside your team repository.

Required design file:

docs/milestone-1-technical-design-and-repository.md

The repository itself is also part of the submission. By the deadline, the repository should be in a reproducible state as described below and should contain an initial task breakdown, for example through GitHub issues or a project board.

Required Design Content

Your technical design should include:

• an exact problem statement, broader than the project brief;
• intended users and usage context;
• core use cases and the one you will be focusing on during the semester;
• connection to the assigned project brief's proof-of-concept expectation;
• non-goals;
• proposed system architecture;
• initial idea of datasets, models, APIs, and external dependencies and justification of their selection (we know that you will likely find more resources later on in the project);
• evaluation strategy and success criteria;
• major risks and fallback plans;
• division of responsibilities (we recommend that you take the time to identify the strengths and weaknesses of each team member to split the work efficiently);
• provisional semester-level work plan.

Your docs/decision-log.md must already contain initial entries for the core use case, non-goals, main data/model/evaluation assumptions, division of responsibilities, and any important scope decisions.

All course projects are full-stack: dataset curation, ML tasks, evaluation, user interface. Ensure all of those aspects are covered in your Technical Design Document.

Regarding ML tasks, define provisional:

• prediction target or model objective;
• available data and data assumptions;
• train, validation, and test split strategy;
• baseline method;
• evaluation metric;
• expected failure modes;
• validity risks.

Required Repository State

Your repository should include:

• documented environment installation with uv;
• pinned or locked dependencies;
• a clear source-code structure, folders and empty scripts that follow your Technical Design;
• a minimal executable pipeline (check the section below);
• automated formatting and linting with ruff;
• mandatory pre-commit configuration;
• a CI that runs formatting checks, linting, type checks with pyright, and tests (see the Project Setup CI requirements);
• configuration separated from code;
• instructions for obtaining or generating a small sample of the data;
• data licensing and provenance documented in data/DATASET_LICENSE.md and data/data-provenance.md when data is used, following the Data and Secrets section in the Project Setup Guide;
• no credentials committed to Git and no unapproved large files (same);
• the provided docs/decision-log.md file, already populated with initial project decisions;
• evidence of pull-request-based collaboration (even for those first few steps).

Minimal Executable Pipeline

Your pipeline can be deliberately simple, but it must run.

Example structure:

load sample data -> run dummy model or simple operation -> save or display output

This can use fake, small, or public sample data. The point is that reproducibility can be tested now, before the project becomes complex.

Required Commands

Your README should document the setup and the standard quality-check commands from the Fresh Clone Health Check in the Project Setup Guide, and explain how to run the minimal pipeline.

Collaboration Evidence

The teaching team may inspect:

• branches;
• pull requests;
• review comments;
• issue assignments;
• commit history;
• CI results.

By the end of Week 3 there should already be evidence that the team is using this workflow.

Recommended Structure

Check the provided docs/milestone-1-technical-design-and-repository.md in your repository, you can just populate it.

Common Problems

Avoid:

• defining the project only as a list of features;
• attempting every feature in the project brief instead of committing to the core use case;
• proposing an architecture without an evaluation plan;
• assuming unavailable data will appear later;
• describing users too vaguely;
• ignoring privacy, safety, or deployment constraints;
• missing uv.lock or unpinned dependencies;
• hard-coded absolute paths to resources in your personal folders;
• uncommitted local configuration required for execution;
• CI that is present but not actually checking the project;
• tests that do not run;
• pre-commit not installed or by only one team member.

Generally, ensure your project does not fall under the Common Failure Modes list from the Project Management 101.

Milestone 2: Proof Of Concept

Edited on 10/09: Added decision-log update requirements for Milestone 2.

Deadline: Sunday of Week 8, November 8, 21:59.

Weight: 37.5% of the project grade (25% for the repo state and 12.5% for the midterm oral presentation).

Purpose

Your proof of concept should show a thin vertical slice through the system.

A vertical slice means that one meaningful path through the system works end to end, even if the dataset, scale, model quality, or interface is simplified.

The proof of concept should not be only a collection of isolated components. It should not be only a polished UI mock-up. It should demonstrate that the central technical idea has been attempted.

Submission

Submit inside your team repository.

Required file:

docs/milestone-2-proof-of-concept.md

Also include:

• demo instructions;
• midterm presentation slides for the separate oral assessment, in the docs/ folder;
• current evaluation results.

Required Content

Your milestone document should include:

• what works now;
• how to run the proof of concept;
• what is simulated, mocked, or simplified;
• current evaluation results, even if weak;
• unresolved technical risks;
• updated project scope;
• concrete plan for the remaining six weeks before the final presentation.

Your docs/decision-log.md must be up to date through the proof of concept. Staff may compare the milestone document, repository state, and decision log to understand why the project changed.

Ensure that your milestone document addresses the five recurring questions:

• Constraints: What constraints shape the setting?
• Trust: Why should users trust the system?
• Evidence: What evidence shows that it works?
• Larger Scale: What changes at larger scale?
• Uncertain: What remains uncertain?

Project-Specific Expectations

Each project has its own proof-of-concept expectations. See your assigned project brief on the Project Briefs overview page.

Midterm Presentation

Your midterm presentation should be concise and demo-centered. You will have 15 minutes for the presentation and about 5 to 10 minutes of questions.

Suggested structure:

• problem statement and intended user(s);
• live or recorded demonstration;
• one slide for the architecture of your system;
• current evidence or sanity checks;
• main risks;
• scope decision for the rest of the semester.

The course team will provide in due time a link for a Google Slides template.

The presentation should make it possible for staff to decide whether the project should continue as planned or require a reframing.

Recommended Structure

Check the provided docs/milestone-2-proof-of-concept.md in your repository, you can just populate it.

Common Problems

Avoid:

• showing only slides when a system should run;
• showing only a UI mock-up without the core pipeline;
• hiding that data is fake or simulated;
• presenting a model score without explaining the split or metric;
• postponing the central technical risk to the final weeks.

Generally, ensure your project does not fall under the Common Failure Modes list from the Project Management 101.

Week 11 Checkpoint

Edited on 10/09: Added decision-log and weekly TA-update expectations to the checkpoint preparation.

Timing: November 23-27, schedule agreed with TAs.

Weight: Not graded.

Format: 30-minute conversation with a TA.

Purpose

The checkpoint is a short intervention to help your team finish well. It is not a presentation and it is not graded.

The goal is to identify whether your team should continue as planned or reframe the project for the remaining time.

Preparation

Before the checkpoint, prepare concise answers to these questions:

• What currently works?
• What changed since the proof of concept?
• What is blocked?
• What will definitely be in the final submission?
• What is now a stretch goal?
• What evidence or evaluation do you currently have?
• What is the biggest remaining risk?
• What is one concrete question for staff?

Also make sure docs/decision-log.md is up to date before the checkpoint. Be ready to discuss the final scope decisions, stretch goals, risks, and fallback plans recorded there.

Suggested Structure

• Team status summary
• Current artifact or demo
• Risks, blockers, and evidence gaps

What Staff Will Look For

Staff will mainly look for:

• whether the final demo is feasible;
• whether the central technical risk has been addressed;
• whether evaluation is realistic;
• whether the team is working effectively;
• whether the team has kept the weekly decision log and TA updates up to date;
• whether the final report can be written from existing evidence;
• whether the remaining scope is credible.

Final Submission

Edited on 10/09: Added the completed decision log as a final repository requirement.

Deadline: Final Presentation: Wednesday December 16, 13:15. Code and final report: Sunday January 10, 2027, 21:59.

Weight: 50% of the project grade (37.5% for the repo state and final report, 12.5% for the final oral presentation).

The final submission includes code, report, documentation, and final oral presentation with a live demo in front of the class.

Submission Location

Submit everything inside your team GitHub repository.

Required final artifacts:

• final code;
• final report as PDF;
• reproducibility instructions;
• demo instructions;
• final presentation material;
• the completed docs/decision-log.md file;
• the contribution statement signed by each team member;
• handover or maintenance documentation.

Final Report

The final report must be submitted as a PDF inside the repository.

Strict page limit: 10 pages, excluding references and appendices.

The report should include:

• problem statement and intended user(s);
• system architecture;
• data sources and preprocessing;
• models, prompts, algorithms, or external tools used;
• evaluation and error analysis;
• UX and design decisions;
• limitations and failure modes;
• ethical, safety, privacy, and deployment considerations;
• reproducibility summary.

Use docs/decision-log.md as evidence for the design decisions, scope cuts, alternatives rejected, limitations, and fallback plans described in the report.

Ensure that your final report addresses the five recurring questions:

• Constraints: What constraints shape the setting?
• Trust: Why should users trust the system?
• Evidence: What evidence shows that it works?
• Larger Scale: What changes at larger scale?
• Uncertain: What remains uncertain?

References and appendices do not count toward the 10-page limit.

Individual Contribution Reports

Your repository must include the completed docs/contribution-statement.md document provided in the repo at the beginning of the semester, signed by each team member.

It should include for each student:

• main technical, design, evaluation, documentation, and presentation contributions;
• links or references to relevant pull requests, issues, commits, experiments, or report sections;
• decisions the student influenced and tradeoffs they handled;
• parts of the project they reviewed, tested, debugged, or helped integrate;
• any major blockers, handovers, or unfinished work relevant to their contribution.

Final Presentation And Live Demo

The final oral presentation should feature a live demo in front of the class.

Recommended presentation structure:

• problem statement and intended user(s);
• live demo;
• one slide for the architecture of your system;
• evaluation results;
• main limitations;
• what the team would do next if it had more one more semester.

It is strongly recommended to reuse the slides of your midterm oral presentation.

Have a backup plan for the live demo, such as a short recorded demo, screenshots, or a deterministic local example. The backup does not replace the live demo requirement, but it protects you from network or hardware issues. The midterm presentation allows you to have a recorded demo, for the final presentation you have to produce a demo that can work live.

Reproducibility Requirements

The final repository should be reproducible from a fresh clone.

At minimum, the README should explain:

• how to install the environment with uv;
• how to run tests;
• how to run linting, formatting checks, and type checks;
• how to obtain or generate sample data;
• how to run the demo or main pipeline;
• which features require credentials, network access, or external APIs;
• known limitations.

Code Quality Requirements

The final repository should include:

• passing CI;
• passing pre-commit hooks with proper linting;
• meaningful tests for representative project logic;
• a clear package structure;
• configuration separated from code;
• no committed secrets;
• no unapproved large files;
• readable documentation;
• clear instructions on how to run the demo or the main pipeline.

Common Problems

Avoid:

• relying on an API key without documenting it;
• showing a demo that cannot be reproduced;
• having a documentation that cannot be trusted for running the demo or the main pipeline;
• reporting only successful examples;
• hiding limitations;
• making the report longer by moving core content to appendices;
• submitting individual contribution descriptions that are vague or disconnected from repository evidence.

For general project-wide failure modes, see the Common Failure Modes in the Project Management 101 Guide.

Project Rubrics

Edited on 10/09: Added maintained decision logs to the general grading expectations.

This document collects the provisional rubrics for all graded project milestones.

The teaching team may adjust the final grading details before the project starts.

Course Assessment

Course-grade weights have priority. The project-related components account for 80% of the course grade; the project-grade equivalents below normalize those components to 100% of the project grade. The detailed rubrics in this document cover the repository-based project components and the midterm oral presentation. In-class tests, quizzes, and ethics certification are assessed separately.

Milestone 1: Technical Design and Reproducible Repository

To be announced after the submission

Milestone 2: Proof Of Concept

To be announced after the submission

Midterm Oral Presentation With Live Demo

To be announced after the submission

Final Oral Presentation With Live Demo

To be announced after the submission

Final Submission

To be announced after the submission

General Grading Expectations

Strong work is:

• scoped realistically;
• reproducible from a fresh clone;
• honest about limitations;
• supported by evidence or evaluation;
• clear about users and context;
• developed collaboratively;
• technically integrated rather than only described;
• supported by a maintained weekly decision log that explains major tradeoffs and scope changes.

Report Template

Use this template for the team final report.

The final report must be submitted as a PDF inside the repository.

Strict page limit: 10 pages, excluding references and appendices.

This page focuses on how to structure and write the report.

Suggested Final Report Structure

# Project Title

## 1. Problem Statement

State the problem, intended users, setting, and why the problem matters.

## 2. System Overview

Describe the system architecture and main components.

## 3. Data And Methods

Describe data sources, preprocessing, models, prompts, algorithms, external tools, and assumptions.

## 4. Evaluation And Results

Describe the evaluation setup, metrics, baselines, error analysis, and main results.

## 5. UX, Trust, Safety, And Limitations

Discuss user-facing design choices, trustworthiness, uncertainty, safety, privacy, ethical issues, and limitations.

## 6. Reproducibility And Handover

Summarize how to run the project and where to find documentation in the repository.

## References

## Appendices

Writing Advice

Prioritize evidence over claims.

Instead of writing that the system is trustworthy, explain what evidence supports trust and what limitations remain.

Instead of writing that the model performs well, report the baseline, metric, split, and failure cases.

Instead of writing that the interface is user-friendly, explain the user assumption, design choice, and remaining usability risk.

Appendix Use

Appendices may include:

• additional examples;
• extended tables;
• screenshots;
• prompt templates;
• data dictionaries;
• extra evaluation details.

Core arguments should remain in the 10-page report body.