Set up the capstone repository

What you will be able to do

Get the capstone starter onto your computer, prove that the computer is ready, and choose your track. A known-good first run now saves you from “bugs” in Module 3 that are really a closed or missing tool.

Before you startWhat to know and to have readyAbout 60 minutes

What you need to know

This course puts together what earlier courses taught. You do not need to remember every detail: each lesson links to the exact earlier lesson for each piece that it uses.

• A terminal, a project folder and a virtual environment, from Isolate dependencies in Python for Practical AI Engineering.
• Git: a repository, git add and git commit, from Set up Git and Track a first change in Git and Team Development Essentials.
• Docker Desktop, installed and checked, from Install and verify in Docker and Cloud Essentials for AI Developers.
• What a design pack is, from Set up the design pack in AI System Design and Cost Engineering. This one is helpful, not required.

What you need on your computer

• Python 3.12 or newer, Git, Docker Desktop (or Docker Engine on Linux), VS Code and a terminal.
• About 50 MB of free disk space for this lesson. From Module 3, the project needs about 5 GB: the search models, the packages and the database image.
• No account, no key and no money.

Tested with Python 3.12 on macOS (Apple silicon) with Docker Desktop. The Windows (PowerShell) and Linux commands are written, not tested.

Before a long hike

Think of a group of friends who plan a five-day hike in the mountains. On the evening before, they do three things.

First, they check the equipment: boots, a map, water, a torch with working batteries. They check at home, because a dead torch is easy to fix at home and a real problem on the mountain at night.

Second, they choose a route. Most of them take the marked trail from the guide book, with its daily stages. One friend knows the area and wants her own route through the next valley. She still uses the same daily stages and the same equipment. Only the path is hers.

Third, they open a logbook with one page for each day and the same headings on each page. Every evening, they fill that day’s page. At the end, the logbook tells the whole story, and nobody has to remember it.

This lesson does the same three things for your capstone.

The problem: a missing tool looks like a bug

A capstone is the last, large project of a programme of study. It puts the earlier pieces together into one product. Your capstone has many moving parts: Python, PostgreSQL in Docker, the RAG course’s search models, a sign-in provider, tests and a page. Module 3 is the first time that they all run together.

Now imagine that you skip the checks and start to code. In Module 3, you start the database, and the command stops with an error about the Docker daemon. Is your code wrong? Is the database file wrong? Or is Docker Desktop only closed? The error appears weeks after its cause, in the middle of new code, and you lose an afternoon to a closed app.

There is a second problem. A capstone takes weeks and many decisions: who the user is, what “good enough” means, which questions you keep for the final test. Decisions kept in your head change without anyone noticing. At the end, a reviewer asks “why 75%?”, and nobody remembers.

The idea: a known-good first run and a design pack

The first idea is a known-good first run: one command with a known expected result, run before you change anything. “Known-good” means that you know exactly what good output looks like. If your output matches, every later problem is in your own work, not in your computer. It is the hikers’ equipment check, done at home.

The capstone starter has this command. python -m scripts.check_setup checks six things and prints one line for each: OK, or TODO with what to do. It changes nothing on your computer.

The second idea is the design pack: a folder of documents, one for each decision, written when you make the decision. The system design course teaches it in Set up the design pack. Here, the starter gives you nine templates: files with the headings already written and short hints in angle brackets. Each lesson tells you which template to copy and fill. It is the hikers’ logbook, with one page per stage.

A tiny example: six lines

Here is the output of the setup check on the course team’s computer:

OK    Python 3.12 or newer   3.12.13
OK    Git                    git version 2.54.0 (Apple Git-157)
OK    Docker is running      Docker Engine 29.6.1
OK    Docker Compose         5.2.0
OK    5 GB of free disk      33 GB free
OK    Design-pack templates  9 templates in docs/templates/
Ready for the capstone.

Each line has the result, the name of the check, and what the check found. Here is why each check exists:

Check	Why the capstone needs it	First used in
Python 3.12 or newer	The project’s code and its pinned packages need it.	This lesson
Git	Your commits are evidence. One of them will prove that you froze your test questions before any tuning.	This lesson
Docker is running	PostgreSQL with pgvector runs in a container.	Module 2
Docker Compose	One file starts the database, and later the whole demonstration.	Module 2
5 GB of free disk	The two search models (about 1 GB), the Python packages and the database image.	Module 3
Design-pack templates	Every lesson fills one of them.	The next lesson

Look at the third and fourth lines. “Docker is installed” and “Docker is running” are two different facts. The check asks Docker’s server for its version, so it fails when Docker Desktop is closed, even if Docker is installed. That is exactly the error that would cost you an afternoon in Module 3.

The worked capstone and your project

Every lesson of this course has two parts.

The first part is the worked capstone. Sam, a junior developer on the team, builds a complete product as their portfolio project, one lesson at a time. The product is a document support assistant for two shops. Larkfield is the home and garden shop of the RAG course; Bramble Books is the bookshop of the authentication course. Staff upload their shop’s policy documents, ask questions, and get short answers with citations, or a clear “the documents do not answer this”. One shop never sees the other shop’s documents. You see Sam’s real files, commands and outputs, mistakes included.

Sam does not work alone. Grace, Larkfield’s support lead, is the user, and she writes the acceptance criteria with Sam. Amira, a developer, reviews the code. Priya, a data scientist, reviews the evaluation. Kwame, the solution architect, reviews the design and the budget. Mei, a data engineer, reviews ingestion and deletion. Omar, the product manager, asks for the demo. Tomás, an AI engineer, has many ideas, and Sam must sometimes say no.

The second part is your project: the same step for your own product, the evidence that you keep, and a checklist. The diagram shows the whole route, and which design-pack files each module fills.

The capstone's route. The first two modules decide and design, the next two build, and the last three prove and present. Each module fills its design-pack files.

Text description of the diagram

The route starts with the starter: nine templates and the setup check. The first group, decide and design, has two modules. Module 1, Select and bound the project, fills the project brief, the acceptance criteria and the evidence plan, and locks the held-out questions. Module 2, Prepare data and architecture, fills the data card, the architecture and the threat and cost review. The second group, build, has Module 3, one complete user journey, and Module 4, reliability and access control. The third group, prove and present, has three modules. Module 5 fills the evaluation report. Module 6 makes a demonstration that anyone can run. Module 7 fills the demo script and the portfolio checklist.

Look at the order: two whole modules of decisions before the first line of product code. That is on purpose, and the next three lessons show why.

Choose a track

You build your own product in this course. You can do it in one of two ways, called tracks.

• The standard track. You build the same kind of product as Sam: a document assistant for two shops. You use the supplied synthetic data pack (documents written for the course, not by a real company) and the supplied questions. Your code, your decisions and your evidence are your own, but the domain is given. This is a good choice for a first portfolio project, and you can compare every step with Sam’s.
• The own-idea track. You follow the same steps in your own narrow domain, for example the procedures of a volunteer group. You use your own documents, but only documents that you may use. They are public with an open licence, permitted in writing by their owner, or synthetic ones that you write. You write your own test questions in the same format.

Two tracks, one method. Only the documents and the questions differ; the steps, the scripts, the checks and the rubric are the same.

Text description of the diagram

The flow starts at the starter and reaches a choice. The standard track uses the supplied two-shop data pack and the supplied bank of 103 questions. The own-idea track uses your own narrow domain, your own permissioned or synthetic documents, and your own questions. Both tracks then join in one box. The lessons, the templates, the scripts, the checks and the marking rubric are the same for both. The result of both is your portfolio project with its evidence.

How do you choose? Ask yourself: “Do I have a narrow set of documents that I may use, and a real person who needs answers from them?” If not, take the standard track. It is not a weaker choice. Reviewers judge a capstone by its evidence, its honesty and how well you explain it, not by its domain. If you have the documents and the person, the own-idea track gives a more personal portfolio piece. It costs more work: you write the data card and the test questions yourself.

Two warnings for the own-idea track. First, never use private documents in a public demo: no work documents without written permission, no personal data, no customer emails. Second, keep the domain narrow. You choose it in the next lesson, with a test for “narrow enough”.

Set up the starter

The starter is a snapshot: a copy of the project at one point of the course. The snapshot start has the templates, the setup check and its tests, and no product code. If your project breaks later, you can copy the snapshot of the last module that you finished, and continue.

1. Open a terminal and go to your projects folder, for example ~/projects. If you have Git, clone the labs repository once. If you have the clone already, run git -C nextia-learning-labs pull instead.

   cd ~/projects
   git clone https://github.com/Nextia-Intelligence/nextia-learning-labs.git

   Without Git, download the ZIP file of the repository and unzip it in ~/projects. Its folder is then nextia-learning-labs-main. Use that name in the next steps.

2. Copy the snapshot start into a new folder, doc-assistant, and go into it. On the own-idea track, you can give the folder another name.

   macOS / Linux

   cp -R nextia-learning-labs/C27/snapshots/start doc-assistant
   cd doc-assistant

   Windows (PowerShell)

   Copy-Item -Recurse nextia-learning-labs\C27\snapshots\start doc-assistant
   cd doc-assistant

3. Make the folder a Git repository of its own. Your capstone needs its own history, separate from the labs repository.

   git init

   Initialized empty Git repository in /Users/you/projects/doc-assistant/.git/

   The path is your own. If Git does not know your name yet, follow Set up Git, step 2.

4. Open the folder doc-assistant in VS Code. All the commands in this course run in this folder.

5. Make the virtual environment, activate it, and install the two tools of Module 1: pytest and ruff.

   macOS / Linux

   python3 -m venv .venv
   source .venv/bin/activate
   python -m pip install -r requirements.txt

   Windows (PowerShell)

   py -3.12 -m venv .venv
   .venv\Scripts\Activate.ps1
   python -m pip install -r requirements.txt

   The last line of the output is:

   Successfully installed iniconfig-2.3.1 packaging-26.3 pluggy-1.6.0 pygments-2.21.0 pytest-9.1.1 ruff-0.17.0

   If pip also prints a notice about a newer pip, you can ignore it. The prompt now starts with (.venv). The other packages come later, in Modules 2 and 3.

6. Start Docker Desktop, if it is not running. Then run the setup check:

   python -m scripts.check_setup

   OK    Python 3.12 or newer   3.12.13
   OK    Git                    git version 2.54.0 (Apple Git-157)
   OK    Docker is running      Docker Engine 29.6.1
   OK    Docker Compose         5.2.0
   OK    5 GB of free disk      33 GB free
   OK    Design-pack templates  9 templates in docs/templates/
   Ready for the capstone.

   Your versions and your free disk will differ. What matters is six OK lines and the last line. If a line says TODO, do what it says, and run the check again.

7. Run the tests:

   python -m pytest

   ..........                                                               [100%]
   10 passed in 0.10s

   One test runs the setup check; nine check that each template has its required headings. Your time can differ.

8. Save the starter as your first commit:

   git add .
   git commit -m "Start the capstone from the starter"
   git log --oneline

   8f3a391 Start the capstone from the starter

   Your commit has another hash. The file .gitignore keeps .venv and other local files out of the repository.

You now have a known-good first run: six OK lines, 10 passing tests and a first commit.

Read the templates

The design pack lives in docs/. The file docs/README.md lists the nine templates and the lesson that fills each one:

Template	Lesson that fills it	What it decides
project-brief.md	Problem and audience	one user, one decision, the documents, the non-goals, the track
acceptance-criteria.md	Acceptance criteria	testable behaviour, quality thresholds, access rules, budget
evidence-plan.md	Plan the evidence	the proof for every claim, and the held-out questions
data-card.md	Synthetic data pack	where the documents come from, and their deliberate difficulties
architecture.md	Architecture and contracts	components, API, database, ingestion states, search metadata
threat-and-cost.md	Threat and cost review	trust boundaries, threats, isolation rules, the budget
evaluation-report.md	Module 5	results, error categories, baseline against candidate
demo-script.md	Module 7	the five-minute story, with a failure case and a trade-off
portfolio-checklist.md	Module 7	every claim and its evidence

Open docs/templates/project-brief.md in VS Code. Every line in angle brackets is a hint, for example <one kind of person, for example "help-desk staff of a small shop">. When a lesson starts, you copy its template into docs/, next to README.md, and you replace every hint with your own decision. Three files go elsewhere: the architecture and the threat and cost review go into docs/design-pack/, and the data card becomes data/dataset.md. Each lesson gives the exact command. You never edit the files in templates/: they stay as the blank pages.

Why templates, and not a blank page? Because the headings are the questions that reviewers ask. A brief without a “Non-goals” heading tends to have no non-goals. The tests check that every template keeps its headings, so a template cannot lose a question by accident.

Common mistakes

Common mistake

Docker is installed, but not running

Symptom: the setup check prints a TODO line and does not say “Ready”:

OK    Python 3.12 or newer   3.12.13
OK    Git                    git version 2.54.0 (Apple Git-157)
TODO  Docker is running      start Docker Desktop (or the Docker service), then run this again
OK    Docker Compose         5.2.0
OK    5 GB of free disk      33 GB free
OK    Design-pack templates  9 templates in docs/templates/
1 thing(s) to do before you start.

The command also ends with exit code 1 instead of 0, so a script can see the failure too.

Cause: the docker command exists, but Docker’s server does not answer. Docker Desktop is closed, or on Linux the Docker service is stopped. The Docker Compose line can still say OK, because it asks only the docker command for its version.

Fix: start Docker Desktop and wait until it says that it is running. On Linux, run sudo systemctl start docker. Then run python -m scripts.check_setup again.

Common mistake

No module named scripts

Symptom: the check stops at once, with a line such as this one (the path is your own):

…/doc-assistant/.venv/bin/python: Error while finding module specification for 'scripts.check_setup' (ModuleNotFoundError: No module named 'scripts')

Cause: the terminal is not in the project folder. python -m scripts.check_setup looks for the folder scripts in the current folder. If the error says No module named pytest instead, the virtual environment is not active.

Fix: go to the project folder with cd ~/projects/doc-assistant. Activate the environment again: source .venv/bin/activate on macOS and Linux, .venv\Scripts\Activate.ps1 on Windows.

Common mistake

An old Python

Symptom: the first line says TODO Python 3.12 or newer 3.9: install Python 3.12 or newer. On a Mac, python3 can be the old Python 3.9 of Apple’s command-line tools.

Fix: install Python 3.12 or newer, as in Install and verify Python. Delete .venv and make it again with the new Python: python3.12 -m venv .venv on macOS and Linux, py -3.12 -m venv .venv on Windows.

Reset. If your project breaks, rename its folder, copy the snapshot start again, and repeat the steps. The snapshots README shows how to use every later snapshot.

Your turn: break one check on purpose

Change one condition: close Docker Desktop (on Linux, stop the Docker service). Before you run anything, predict: how many lines say OK, which line says TODO, and what is the last line? Then run python -m scripts.check_setup, and start Docker again.

Show the answer

Five lines say OK and one says TODO: “Docker is running”. The last line is 1 thing(s) to do before you start., and the command ends with exit code 1. On macOS and Linux, echo $? right after the command prints 1; on Windows, $LASTEXITCODE prints it.

The Docker Compose line stays OK, because it asks only the docker command for its version. This is why the check asks for both: “installed” is not “running”. When you start Docker again, the check prints six OK lines and Ready for the capstone.

Your project

This lesson’s part for your own product is short, and it matters: the track, decided and written down.

1. Run the setup check until it prints Ready for the capstone. Keep the output, for example in a file docs/setup-check.txt.
2. Choose your track. On the own-idea track, write one sentence about the domain and where your documents come from. You test it in the next lesson.
3. Commit.

Evidence you keep: the first commit, the output of the setup check, and the track you chose.

Checklist

• python -m scripts.check_setup prints six OK lines and Ready for the capstone.
• python -m pytest prints 10 passed.
• The project is a Git repository with a first commit.
• You know which track you take, and why.
• On the own-idea track: every document that you plan to use is public with an open licence, permitted in writing, or synthetic.

Knowledge check

Check your understanding

What is a known-good first run, and why do you do it before you write any product code?

Show the answer

A known-good first run is one command with a known expected result, run before you change anything. Here it is python -m scripts.check_setup, which must print six OK lines and Ready for the capstone., and the tests, which must print 10 passed. If the output matches, the computer is ready, and every later failure is in your own work, not in a missing or stopped tool. Without it, a closed Docker Desktop shows up in Module 3, as an error in new code, far from its cause.

Check your understanding

A friend takes the own-idea track. She wants to use her employer's internal staff handbook and show the demo on her public portfolio. What do you tell her, and what are her options?

Show the answer

She may not use the handbook without written permission from its owner. Even with permission, a public demo must not show private documents or personal data. She has four options:

• Ask for written permission, and keep the demo private.
• Use public documents with an open licence on a similar topic.
• Write synthetic documents with the same kinds of difficulty.
• Take the standard track. A reviewer judges the evidence and the honesty, not whether the documents are real.

Check your understanding

Practical check: show that your starter is ready. What do the setup check, the tests and `git log --oneline` print, and which track did you choose?

Show the answer

The setup check prints six OK lines and Ready for the capstone. The lines are Python 3.12 or newer, Git, Docker is running, Docker Compose, 5 GB of free disk, and 9 templates in docs/templates/. The tests print 10 passed. git log --oneline shows one commit, for example “Start the capstone from the starter”, with your own hash. The track is the standard track, with the supplied data pack and questions, or the own-idea track, with your own permissioned or synthetic documents.

Case studies in this course

At the end of the course, you use what you learn on a realistic project, from the data to the recommendation. Complete at least one for the certificate; the others are optional.

• Capstone on a public document collectionApply the same method to an openly licensed document collection: scope, data card, held-out questions, isolation and an evaluation report.
• Review a weak capstoneMark a constructed weak capstone against the rubric, find the missing evidence, and write the feedback that would make it pass.

Recap

• A capstone puts many tools together, so a missing or stopped tool looks like a bug weeks later. A known-good first run removes that doubt before you write code.
• python -m scripts.check_setup checks Python, Git, a running Docker, Compose, the free disk and the templates. It prints six OK lines and Ready for the capstone., and it changes nothing. The tests print 10 passed.
• The design pack in docs/ keeps every decision in a file. The starter has nine templates, and each lesson fills one.
• Every lesson has two parts: Sam’s worked capstone, a document assistant for Larkfield and Bramble Books, and your project.
• Two tracks: the standard track uses the supplied data pack and questions; the own-idea track uses your own permissioned or synthetic documents. The steps, the checks and the rubric are the same.

Next, you decide who your product is for, what decision it helps with, and what it will not do.

Next: Problem and audience