The Project: Kestrel

Every lesson in this course is set at one company, on one project. Kestrel is made up. The company, its people, its depots, every parcel, message and number in the project are fictional and simulated. The real cases that open each lesson are separate, cited and clearly marked as real.

The company

Kestrel is a UK parcel-delivery company. Its hub is in Leicester, and it runs nine depots from Dartford to Inverness, 1,150 vans, and about 210,000 parcels a day (September 2026). Businesses hand parcels to Kestrel with a promise: next day, two days (standard) or three days (economy). Kestrel delivers Monday to Saturday.

The problem

About one parcel in twelve misses its promised day. When that happens with no warning, the customer calls, writes or complains publicly, and Kestrel pays for it in contact-centre time and lost business. If Kestrel knew in the morning which parcels were at risk, it could warn those customers at 06:00 and send its few spare vans to the routes that need them most.

A data scientist built a prototype in a notebook last spring. It scored well. Nobody could rerun it, it was trained on a column that is only known after delivery, and it has never seen a parcel from Doncaster, the depot that opened in August. Adaeze, the head of data and ML, wants the real thing: a model that is right, that runs every day without anyone touching it, and that tells someone when it stops being right.

You are the ML engineer Kestrel hired in October 2026 to build it.

The model

What this course uses the project for

This course teaches the AI / ML engineer's job: training models and keeping them correct in production. Kestrel is the instrument. Each module adds one piece and its proof to one repository, so by the capstone the model lives in production, keeps working without anyone watching it, and you can answer the roadmap's five questions from your own measurements.

It is not Northdesk (AI System Design), BrightCart (AI Engineering), Harbourline Freight (Forward Deployed Engineer), the returns desk (Agentic AI Engineer), the Quillpath support desk (Large Language Models), Hollin Answers (RAG), the notes assistant (MCP), the TinyFormer lab (Transformers), Booknook (Python) or the Tidewell Cycles inbox (NLP). Kestrel is a different company, with a different cast, data and problem.

The people

Do not add named Kestrel staff. Customers appear only as message senders in the shared data, never by name.

The depots

Shares are of the parcels in the sample (guide 06, block 3). The late rates by depot are measured in guide 06, block 10.

Fixed numbers (simulated)

These are the facts every lesson uses. They do not change; lessons that need another number add it, say "added in this lesson", and label it.

Kestrel's money is in pounds sterling. Cloud and model providers publish prices in US dollars; lessons quote those in dollars and convert only with a dated exchange rate and its source.

Dates

• The shared data covers parcels shipped Monday 6 July to Sunday 27 September 2026 (12 weeks). The snapshot was taken on Monday 28 September 2026 (DATA_AS_OF). Code counts days to DATA_AS_OF, never to date.today(), so lessons give the same answers whenever you run them.
• A parcel's label is ready the day after it is delivered. Labels not ready by DATA_AS_OF are missing (late is None); the first ship date with missing labels is 22 September.
• Dates in prose are written day first ("7 September 2026"); dates in data are ISO (2026-09-07).

Key events in the data

Weather and the gales are simulated. The two bank holidays are real dates, read from gov.uk/bank-holidays.json on 24 October 2026.

The project weeks

Gemini 3.8 Flash's price doubles on 1 January 2027, in week 9: course-guide/02 says so, and Module 12 lesson 2 uses it as the example of a dated price.

Fixed names

So that modules fit together, these names do not change:

• The repository is kestrel/; the package inside it is kestrel/ (imported as import kestrel); tests live in tests/; pipelines in pipelines/; the service in service/; evaluation of the message models in evals/; documents in docs/; reports generated by code in reports/; model files in artifacts/. Paths below are relative to the repository root.
• kestrel/data.py holds blocks 1 to 8 of the shared data, copied exactly.
• FEATURES (in kestrel/features.py, Module 3) is the list of the 18 columns known at collection; FORBIDDEN = ["attempts", "delivered_date", "late", "label_ready_date"] never reach training.
• Every model, whatever its library, is wrapped to predict_proba(df) -> numpy array of late probabilities, so baselines, trees, networks and the ONNX runtime are interchangeable in the gates and the service.
• The time-based split: train on ship dates before Monday 24 August 2026, validate on 24 August to 6 September, and keep 7 to 21 September as the locked test set (Module 6 lesson 2). Labels after 21 September are incomplete. The test set starts on the day weight_kg turns into grams: Modules 3 and 4 train and test on dates before 7 September only, and from Module 5 on the data contract converts September's grams back to kilograms before anything trains or scores (kestrel/contracts.py). Monitoring lessons replay the raw feed, grams included, on purpose.
• The service's request carries the 18 columns of FEATURES (parcel_id included); the response carries late_probability, model_version and fallback (true when the baseline answered).
• Every run record holds the Git commit, the data fingerprint from guide 06 block 8, the parameters, the metrics and the model file's hash.
• Reports in reports/ are generated by code and never edited by hand.

One repository: which module adds which file

In Colab each lesson writes the files it needs with %%writefile (one small file per component, never more than about 40 lines) and imports them; on a laptop the same files form the repository. Tests run with !python -m pytest -q in Colab and pytest -q locally. Every lab from Module 2 on starts by checking that the earlier modules' files are present and writing back any that are missing, so you can start at any module. This table is the plan; it will be regenerated from the published lessons' %%writefile cells when the course is built.

Decision records

Decisions are written as architecture decision records (ADRs) in docs/adr/, numbered in the order above (ADR-001 in Module 3 to ADR-010 in Module 14). Every ADR uses this template:

# ADR-NNN: <decision in a few words>

Status: proposed | accepted | superseded by ADR-MMM
Date: <ISO date>
Deciders: <names from the cast>

## Context
<the problem, with the measured numbers that force a decision>

## Options considered
<two or three, each with quality (PR-AUC, Brier), latency, cost and what it locks in>

## Decision
<the choice, in one or two sentences>

## Consequences
<what gets easier, what gets harder, what we now have to operate or monitor>

## Revisit when
<the measurable condition that would change the decision, for example "Doncaster's PR-AUC falls 0.02 below the fleet's">

The artifacts you end with

The finished system

• A pipeline from raw depot scans to a registered model, run by one command and versioned (data with DVC, code with Git, models in the registry)
• A data contract that fails loudly on the 7 September grams
• Model v1 and v2 with tracked experiments, honest baselines and a significance test
• An ONNX model in a FastAPI service with a 06:00 batch path and an online path, a fallback to the baseline, and a benchmark against the 50 ms p99 SLO
• Promotion gates, shadow and canary rollout simulated, and a rehearsed rollback
• Drift, null-rate, prediction and segment monitoring that works before labels arrive, with alerts tuned on September and a postmortem
• An automated retraining trigger inside a cost ceiling
• A small foundation model adapted for customer messages and evaluated against a hosted one
• A model card, a fairness report and an explanation a customer could read

The five questions

The capstone answers the roadmap's five questions from measured numbers:

1. What does one prediction cost, and one training run? (Imran; Modules 7 and 8)
2. What is p99, and where does it go? (Rhys; Modules 8 and 9)
3. How would you know the model degraded, and how fast? (Adaeze; Module 11)
4. What happens if the feature pipeline silently changes a column? (Tomasz; Modules 5 and 11, the 7 September grams)
5. Can you reproduce last month's model exactly? (Adaeze; Modules 6 and 10)

The one idea

Training is the bounded part; keeping a model correct in production is the job. Every component in this course has to earn its place with a number: a leak it removes, a drift it catches, a millisecond it saves, a pound it saves, or a rollback it makes possible.