Project Documentation

Course Project Overview

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 August 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's 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. Students will choose on the first lecture whether to have deadlines on Fridays or Sundays.

Assessment

The project counts for 80% of the course grade.

Repository-Based Submission

All project submissions happen inside your team GitHub repository.

Staff will grant you the access for the one repository for your project in the course GitHub organization. The main branch will be protected. You will have to work through branches, pull requests, and peer review.

Your repository is both your software artifact and your submission record. Reports, milestone documents, presentation material, and final documentation should be committed to the repository.

Required Technical Stack

All teams use the same baseline engineering stack.

Expected Final Output

By the end of the course, each team should submit:

• a working prototype;
• a reproducible code repository;
• tests, linting, type checks, pre-commit hooks, and CI;
• a final report submitted as a PDF inside the repository;
• one individual contribution report per team member;
• handover or maintenance documentation.

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 Setup Guide

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 ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest

If formatting fails, format the code.

uv run ruff format .

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
|   |-- individual-reports/
|   |   `-- <student-name>.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.

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.

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.

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 checks.

uv run ruff format .
uv run ruff check .
uv run pyright
uv run pytest

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.

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.

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

Deadline: Friday of Week 3, September 25, 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 rather than attempting all possible features;
• 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.

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;
• 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;
• no credentials committed to Git;
• no large files committed to Git (you may need to have some later, ask staff for approval);
• 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 commands equivalent to:

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

Your README should also 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;
• planning to build everything before testing anything;
• assigning all technical risk to the final weeks;
• describing users too vaguely;
• ignoring privacy, safety, or deployment constraints;
• code that only runs on one student's machine;
• 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;
• committing notebooks or outputs as the only working artifact.

Milestone 2: Proof Of Concept

Deadline: Friday of Week 8, November 6, 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.

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?

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.

Week 11 Checkpoint

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?

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 final report can be written from existing evidence;
• whether the remaining scope is credible.

Final Submission

Deadline: Final Presentation: Wednesday December 16, 13:15. Code and final report: Friday January 8 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 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.

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:

• submitting code that only runs on one machine;
• 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.

Project Rubrics

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.

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.

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.