The BrightCart Project
BrightCart is a made-up online store that sells home electronics: headphones, kettles, smart lights, robot vacuums. It is not a real company. Every example in this course is set there.
The problem
BrightCart's support team answers about 2,000 customer messages a day. Most are the same forty questions: where is my order, how do I return this, is it under warranty, why was I charged twice. Customers wait hours for answers that already exist in the help centre.
BrightCart wants an assistant that:
- Answers common questions correctly, using the company's real policies.
- Says "I don't know, let me get a person" when it does not know.
- Can look up an order and start a return, with a human approving anything that moves money.
- Costs less per conversation than it saves.
- Cannot be talked into doing things it should not do.
You are the engineer building it.
The people
| Name | Role | Why they appear in lessons |
|---|---|---|
| Priya | Head of Support | Brings you the problems customers actually have |
| Dev | Backend engineer | Owns the order system your assistant must talk to |
| Marta | Finance lead | Asks what everything costs |
| Sam | Security lead | Asks how it can be abused |
The facts the assistant works with
These policies are used throughout the course. They are short on purpose, so you can check the assistant's answers yourself.
| Policy | Rule |
|---|---|
| Returns | 30 days from delivery. Item must be unused and in its original box. |
| Refunds | Paid back to the original payment method within 5 to 7 working days of the return arriving. |
| Shipping | Standard delivery takes 3 to 5 working days. Free over $50. |
| Warranty | 1 year on all electronics. Covers faults, not accidental damage. |
| Order changes | An order can be changed or cancelled until it is marked "shipped". |
| Support hours | Human agents are available 8am to 8pm, Monday to Saturday. |
What you build, module by module
| Module | The piece you add |
|---|---|
| 0 | The assistant answers its first question |
| 1 | An API client that retries, times out, and keeps keys secret |
| 2 | The help-centre documents, cleaned and validated |
| 3 | A simple classifier that sorts tickets into categories, as a baseline |
| 4 | A small neural network, and a tool for exploring embeddings |
| 5 | Keyword search over the help-centre documents |
| 6 | A written decision: should BrightCart prompt, retrieve, or fine-tune? |
| 7 | The answer engine: structured replies, fallbacks, cost tracking, and defences against misuse |
| 8 | Answers grounded in the documents, with citations |
| 9 | Order lookup and returns, as tools, with human approval |
| 10 | A web service other systems can call |
| 11 | A database, a cache and background jobs |
| 12 | Tests that tell you whether a change made the assistant better or worse |
| 13 | A deployed service with a way to roll back |
| 14 | A write-up you can show an employer |
One repository: which module adds which file
Everything you keep goes in one repository, a single Python package called brightcart/. Lessons run in Colab, so their code sits in cells; the labs show where each piece lives in the repository. Labs that must run in a temporary folder for testing create brightcart/ there with the same layout.
| Module | Adds to the brightcart/ repository |
|---|---|
| 1 | The package itself: brightcart/llm.py, brightcart/answer.py, tests/, pyproject.toml, .gitignore (Lesson 3); brightcart/client.py and brightcart/log.py, tagged v0.1.0 (lab) |
| 2 to 9 | The pieces each module builds (cleaning, the classifier baseline, search, the answer engine, retrieval, tools), first in notebook cells |
| 10 | The web service, inside the package as brightcart/api/, with its tests |
| 11 | The database, cache and job code the service uses |
| 12 | The evaluation set, results files and gate.py under evals/ |
| 13 | A container and a CI pipeline for the same brightcart/ folder, deployed to Cloud Run |
| 14 | The capstone: the README and write-up for everything in brightcart/ |
The finished product
- Document ingestion pipeline
- Dense retrieval with a category filter (hybrid search and reranking measured in Module 8 and held back)
- Grounded answers with citations
- Tool calling with human approval
- FastAPI backend with auth
- PostgreSQL and vector storage
- Redis caching
- Background processing
- Tests with mocked providers
- Retrieval and LLM evaluation
- Traces, latency and cost monitoring
- Docker and cloud deployment