DEV Community: Navas Herbert

We Built a Real API Live in Class - Here's How the Grade Tracker Session Went

Navas Herbert — Thu, 25 Jun 2026 21:11:08 +0000

I told the class before we typed a single line: "By the end of today, you will have a fully working API that adds, reads, updates, and deletes student records. We will test it live in the browser. No shortcuts, no copy-paste from a finished repo. We're building this together, file by file."

Five files. One database. A real REST API by the end of the session.

This is how it went - including the moment that made the whole class lean forward at once.

The Plan: Five Files, One Job Each

Before any code, I wrote five filenames on the board:

database.py   models.py   schemas.py   crud.py   main.py

I pointed at each one as we built it, so nobody lost track of where we were in the journey. That board stayed up the entire session - every time someone looked confused, I'd point back at it. "We're in file 3. Schemas. We just finished models."

Five files, five distinct jobs:

database.py - connects Python to the database
models.py - defines what the database table looks like
schemas.py - defines what the API accepts and returns
crud.py - does the actual database work
main.py - wires everything together into endpoints

File 1: database.py - The Foundation

"This file does one thing," I told them. "It sets up the connection between our Python code and the database. Everything else depends on this, so we write it first."

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./grades.db"

engine = create_engine(DATABASE_URL,
    connect_args={"check_same_thread": False})

SessionLocal = sessionmaker(autocommit=False,
    autoflush=False, bind=engine)

Base = declarative_base()

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

The analogy that did the most work in this file: SQLAlchemy is a translator. Our database speaks SQL. We speak Python. SQLAlchemy translates between the two so we never write raw SQL ourselves.

SessionLocal got its own analogy - a coffee machine. The machine itself isn't a cup of coffee, but you press a button and get a fresh cup. SessionLocal is the machine. Every request gets its own fresh session and throws it away when done.

The line that needed the most unpacking was yield db. I told them: normally a function returns and ends. yield gives something back but the function stays alive, waiting. The endpoint runs using that session. When the endpoint finishes, Python comes back here and runs the finally block - closing the session.

One student asked the question I wait for every cohort: "Why not just open and close the session inside each endpoint?"

You could. But you'd repeat the same five lines in every single function. get_db() writes it once, and every endpoint reuses it through dependency injection. Write the pattern once, never again.

File 2: models.py - The Database Table

"We're not writing SQL. We're writing Python. SQLAlchemy generates the SQL for us."

from sqlalchemy import Column, Integer, String, Float
from database import Base

class Student(Base):
    __tablename__ = "students"

    id     = Column(Integer, primary_key=True, index=True)
    name   = Column(String, nullable=False)
    course = Column(String, nullable=False)
    grade  = Column(Float, default=0.0)
    email  = Column(String, unique=True)

I drew this table on the board as we went - column name on the left, what it does on the right. The visual learners in the room followed noticeably better once they could see the table taking shape rather than just reading code.

The id column got the school registration number analogy - every student gets a unique number automatically, nobody assigns it manually. email = Column(String, unique=True) got a direct question on the spot:

"What happens if two students try to use the same email?"

The database rejects it. We enforce that rule once, here, and never have to check for duplicate emails manually anywhere else in the code.

Eleven lines. A complete table definition. No CREATE TABLE statement in sight.

File 3: schemas.py - The Part That Confuses Everyone First

I paused before writing any code for this file and said: "This is the one that confuses beginners the most. You'll ask - why do I need schemas if I already have models? Let me explain before we write a single line."

I put two columns on the board:

SQLAlchemy Model	Pydantic Schema
Talks to the database	Talks to the API user
Defines table columns	Validates incoming data
Never shown to users directly	Shapes the response

"The model is what the database sees. The schema is what the user sees. If we stored passwords, the model would have a password column - but the response schema would never include it."

That distinction landed. Then the code:

from pydantic import BaseModel
from typing import Optional

class StudentCreate(BaseModel):
    name:   str
    course: str
    grade:  float = 0.0
    email:  str

class StudentUpdate(BaseModel):
    name:   Optional[str] = None
    course: Optional[str] = None
    grade:  Optional[float] = None

class StudentResponse(BaseModel):
    id:     int
    name:   str
    course: str
    grade:  float
    email:  str

    class Config:
        from_attributes = True

Three schemas, three jobs. StudentCreate has no id field - deliberately. We never ask the user for an id; the database assigns it.

StudentUpdate made everyone notice something: every field is Optional. "Why? Because if a student's name changes, why should the user have to resend the email and course too? Optional fields let people send only what changed."

StudentResponse got the most attention because of one line: from_attributes = True. I called it out directly: "Without this one line, Pydantic cannot read a SQLAlchemy object. It only understands plain dictionaries by default. This line tells it: also accept database objects." I warned them this is the number one mistake in this file - forget it, and you get a cryptic "value is not a valid dict" error.

File 4: crud.py - Where the Real Work Happens

I introduced this file with an analogy that stuck for the rest of the session: "crud.py is the kitchen. The endpoints are the waiters. The waiter takes the order from the customer, passes it to the kitchen, and brings back the plate. Waiters don't cook."

CRUD - Create, Read, Update, Delete. One function per operation.

from sqlalchemy.orm import Session
import models, schemas

def create_student(db: Session, student: schemas.StudentCreate):
    db_student = models.Student(**student.model_dump())
    db.add(db_student)
    db.commit()
    db.refresh(db_student)
    return db_student

def get_student(db: Session, student_id: int):
    return db.query(models.Student).filter(
        models.Student.id == student_id).first()

def get_students(db: Session):
    return db.query(models.Student).all()

def update_student(db: Session, student_id: int,
                   data: schemas.StudentUpdate):
    student = db.query(models.Student).filter(
        models.Student.id == student_id).first()
    if not student:
        return None
    updates = data.model_dump(exclude_unset=True)
    for field, value in updates.items():
        setattr(student, field, value)
    db.commit()
    db.refresh(student)
    return student

def delete_student(db: Session, student_id: int):
    student = db.query(models.Student).filter(
        models.Student.id == student_id).first()
    if not student:
        return None
    db.delete(student)
    db.commit()
    return student

The create_student function carries a pattern I told them to write down word for word: add, commit, refresh. Add stages the record. Commit saves it to disk. Refresh reloads it so you get the database-assigned id back. "You will use this exact three-step pattern every single time you create something in FastAPI. Memorise the order."

I also broke down the unpacking trick line by line, because it always raises eyebrows the first time:

db_student = models.Student(**student.model_dump())

model_dump() turns the Pydantic schema into a plain dictionary. ** unpacks that dictionary and passes each key-value pair as a keyword argument. It's shorthand for writing out every field manually.

The Moment exclude_unset=True Saved Alice

This was the part of the session everyone leaned forward for.

update_student has this line:

updates = data.model_dump(exclude_unset=True)

I explained it carefully, because getting this wrong is a genuinely common, genuinely damaging bug: "exclude_unset=True is the key to a correct update. Without it, every Optional field the user didn't send would come through as None and silently overwrite the existing data."

We tested it live. Alice Wanjiku was already in the database — name, course, grade, email, all set. We sent a PUT request with only this body:

{
  "grade": 92.0
}

I asked the class to predict what would happen to Alice's name and email if we'd forgotten exclude_unset=True. A few guessed correctly - wiped to null. Then we looked at the actual response:

{
  "id": 1,
  "name": "Alice Wanjiku",
  "course": "Python Fundamentals",
  "grade": 92.0,
  "email": "alice@example.com"
}

Only the grade changed. Name, course, and email - completely untouched. One keyword argument, exclude_unset=True, was the entire difference between a correct update and a destructive one.

That's the line that gets students who've already shipped something broken to a real project. They've felt this bug before they even knew its name.

File 5: main.py - Where It All Connects

"main.py is the manager. It doesn't do the work itself - it delegates to the other four files and coordinates everything."

from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
from typing import List
import models, schemas, crud
from database import engine, get_db

models.Base.metadata.create_all(bind=engine)

app = FastAPI(title="Student Grade Tracker",
              description="Track student grades with FastAPI",
              version="1.0.0")

@app.post("/students/", response_model=schemas.StudentResponse)
def create_student(student: schemas.StudentCreate,
                   db: Session = Depends(get_db)):
    return crud.create_student(db, student)

@app.get("/students/", response_model=List[schemas.StudentResponse])
def get_students(db: Session = Depends(get_db)):
    return crud.get_students(db)

@app.get("/students/{student_id}",
         response_model=schemas.StudentResponse)
def get_student(student_id: int,
                db: Session = Depends(get_db)):
    student = crud.get_student(db, student_id)
    if not student:
        raise HTTPException(404, "Student not found")
    return student

@app.put("/students/{student_id}",
         response_model=schemas.StudentResponse)
def update_student(student_id: int,
                   data: schemas.StudentUpdate,
                   db: Session = Depends(get_db)):
    student = crud.update_student(db, student_id, data)
    if not student:
        raise HTTPException(404, "Student not found")
    return student

@app.delete("/students/{student_id}")
def delete_student(student_id: int,
                   db: Session = Depends(get_db)):
    student = crud.delete_student(db, student_id)
    if not student:
        raise HTTPException(404, "Student not found")
    return {"message": "Student deleted successfully"}

I pointed out the line that quietly does the most work: models.Base.metadata.create_all(bind=engine). "This looks at every class that inherits from Base and creates the matching table if it doesn't already exist. It's safe to leave running every time - it never deletes or overwrites existing data."

Then I drew attention to how clean each endpoint looks: "Four lines. The decorator says what HTTP method and URL. response_model says what shape to return. The parameters say what data to expect. The body delegates to crud.py. FastAPI, Pydantic, and SQLAlchemy each do their part invisibly."

We Tested It Live - And Broke It On Purpose

We ran:

uvicorn main:app --reload

Opened http://127.0.0.1:8000/docs. I gave the class a moment to look at the auto-generated documentation - colour-coded endpoints, all generated from code they'd just written, zero extra effort.

Then we went through the test sequence together:

Added Alice via POST - got back id: 1, assigned automatically
Added Brian via POST - got back id: 2
Listed all students - both showed up
Got Alice specifically via GET /students/1 - only Alice came back
Updated only Alice's grade - the exclude_unset moment above
Deleted Brian - confirmed gone from the full list afterward

Then we broke it deliberately. Two tests, on purpose:

Test 7 - request a student that doesn't exist:

GET /students/99

{ "detail": "Student not found" }

A clean 404. Not a crash, not a stack trace - a clear message.

Test 8 - send the wrong data type:

{
  "name": "Charlie",
  "course": "Python",
  "grade": "very good",
  "email": "charlie@example.com"
}

422 Unprocessable Entity

FastAPI rejected it before our code even ran, with a detailed error pointing at exactly which field failed. "This is why we use schemas. Pydantic catches the wrong type before our endpoint logic ever executes."

These two tests generated the most discussion of the whole session. Students realised error handling wasn't extra work they'd have to write themselves - FastAPI and Pydantic handle most of it for free, as long as the schemas are defined correctly.

What I Noticed Teaching This Session

1. The five-file board never came down. Every time someone got lost, pointing back at the five filenames re-oriented them instantly. A visible map of where you are in a multi-file build matters more than I expected.

2. exclude_unset=True is worth a dedicated pause. This is the single line in the entire project most likely to cause a real, silent bug in production code. Slowing down here, predicting the wrong outcome out loud before showing the correct one, made the lesson stick far better than just explaining it.

3. Breaking the API on purpose teaches more than building it correctly. The 404 and 422 tests got more genuine engagement than any of the successful CRUD operations. Students want to see what happens when things go wrong - show them deliberately, in a safe environment, before they hit it by accident in their own project.

4. The kitchen/waiter analogy for separation of concerns outlived the session.

What Students Are Trying Now

Add a search query parameter to GET /students/ that filters by course name
Add a GET /students/top endpoint returning students with grade above 80
Make create_student return a 400 error if the email already exists
Add a created_at timestamp column that fills automatically

Fifteen minutes of independent struggle before any solution gets shown. Even brief independent problem-solving massively improves retention compared to just watching code appear on a screen.

What We Built

Five files. One real database. Five working endpoints. Automatic validation. Automatic error handling. Interactive documentation generated entirely from the code itself.

Not a toy. Not a shortcut tutorial. A real, working REST API - built one explained line at a time, with the class testing every success path and every failure path live.

The patterns from today repeat in every FastAPI project these students will ever build: the three-step create pattern, the exclude_unset update pattern, the 404 pattern, dependency injection through get_db. Learn it once here, reuse it everywhere.

Build Your First RAG System From Scratch - No Frameworks, Just Python

Navas Herbert — Sat, 20 Jun 2026 18:40:50 +0000

You have probably heard the term RAG thrown around in every AI discussion lately. Retrieval-Augmented Generation. It sounds complicated, but the idea is beautifully simple once you see it in action.

In this article you will build a working RAG system from scratch using pure Python and local models running on your own machine. No LangChain. No complex frameworks. Just the raw concepts so you actually understand what is happening at every step.

By the end you will have a FastAPI server you can query with questions, and you will understand exactly how it works well enough to explain it to someone else.

What is RAG and Why Should You Care?

Imagine you hire a very smart assistant who has read millions of books. If you ask them a question, they will answer confidently - but sometimes they will guess, and sometimes they will be wrong. This is what a standard LLM does. It answers from memory, and memory can be wrong or outdated.

Now imagine before asking your question, you hand that assistant the exact pages from the right book. Suddenly they are not guessing anymore. They are reading and summarising. That is RAG.

RAG fixes the two biggest problems with plain LLMs:

Hallucination - the model invents facts it does not know.
Staleness - the model's training data has a cutoff date.

With RAG, your model answers from documents you control. You can update those documents any time without touching the model itself.

The Big Picture

Before writing any code, understand the two phases of RAG:

Phase 1 - Indexing (done once)

Your document
    ↓
Split into chunks
    ↓
Convert each chunk to a vector (embedding)
    ↓
Store vectors in a vector database

Phase 2 - Retrieval and Generation (happens every question)

User asks a question
    ↓
Convert question to a vector
    ↓
Find the most similar chunks in the database
    ↓
Combine chunks + question into a prompt
    ↓
Send prompt to LLM
    ↓
Get a grounded answer

That is the entire system. Everything else is implementation detail.

What You Need

Python 3.11+
Ollama installed on your machine

Pull these two models into Ollama:

ollama pull nomic-embed-text
ollama pull llama3.2

Then start Ollama in a separate terminal:

ollama serve

Install Python dependencies:

pip install fastapi uvicorn numpy requests

Step 1 : Chunking

We cannot send an entire document to the LLM every time someone asks a question. Context windows have limits and it is wasteful. Instead we split the document into small overlapping pieces called chunks.

Create a file called chunking.py:

def chunk_text(text: str, chunk_size: int = 100, overlap: int = 20) -> list[str]:
    """
    Split text into overlapping chunks by word count.

    chunk_size: number of words per chunk
    overlap:    words repeated between consecutive chunks
    """
    words = text.split()
    chunks = []
    start = 0

    while start < len(words):
        end = min(start + chunk_size, len(words))
        chunk = " ".join(words[start:end]).strip()
        if chunk:
            chunks.append(chunk)
        # Move forward by (chunk_size - overlap) to create the overlap
        start += chunk_size - overlap

    return chunks


if __name__ == "__main__":
    with open("document.txt", "r") as f:
        document = f.read()

    chunks = chunk_text(document)
    print(f"Document split into {len(chunks)} chunks")

    for i, chunk in enumerate(chunks):
        print(f"\nChunk {i + 1} ({len(chunk.split())} words):")
        print(chunk)

Why word-based splitting? It is more natural than character-based splitting. A chunk of 100 words is roughly 2 to 4 sentences regardless of how long those words are.

Why overlap? A sentence that falls at the boundary between two chunks would get cut in half without overlap. The last 20 words of one chunk appear at the start of the next, so no sentence is ever lost.

Run it:

python chunking.py

You should see your document split into 6 to 8 chunks. Try changing chunk_size to 50 and notice how many more chunks you get.

Step 2 - Embeddings

An embedding is a list of numbers that represents the meaning of a piece of text. Similar text produces similar numbers. This is what makes search possible.

Create embedding.py:

import numpy as np
import requests


def embed_text(text: str) -> np.ndarray:
    """
    Convert text to an embedding vector using Ollama.
    Returns a numpy array of floats.
    """
    response = requests.post(
        "http://localhost:11434/api/embeddings",
        json={"model": "nomic-embed-text", "prompt": text}
    )
    response.raise_for_status()
    vector = response.json()["embedding"]
    return np.array(vector, dtype=np.float32)


def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
    """
    Measure how similar two vectors are.
    1.0 = identical meaning, 0.0 = unrelated, -1.0 = opposite
    """
    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))


if __name__ == "__main__":
    pairs = [
        (
            "RAG retrieves documents to help an LLM answer questions.",
            "Retrieval-Augmented Generation uses external knowledge.",
            "Similar topic"
        ),
        (
            "RAG retrieves documents to help an LLM answer questions.",
            "My favourite food is jollof rice.",
            "Unrelated"
        ),
    ]

    for a, b, label in pairs:
        score = cosine_similarity(embed_text(a), embed_text(b))
        print(f"{label}: {score:.4f}")
        print(f"  A: {a}")
        print(f"  B: {b}\n")

Run it:

python embedding.py

You will see the similar pair score close to 1.0 and the unrelated pair score close to 0.0. This is the mathematical foundation of RAG search.

Step 3 Vector Search

Now we embed every chunk and store it. When a question arrives, we embed it and find the chunks with the highest similarity score. This is your mini vector database.

Create vector_search.py:

import numpy as np
from importlib import import_module

chunk_text        = import_module("1_chunking").chunk_text
embed_text        = import_module("2_embedding").embed_text
cosine_similarity = import_module("2_embedding").cosine_similarity


def build_vector_store(chunks: list[str]) -> list[dict]:
    """Embed every chunk and store it with its text."""
    print(f"Embedding {len(chunks)} chunks...")
    store = []
    for i, chunk in enumerate(chunks):
        vector = embed_text(chunk)
        store.append({"text": chunk, "vector": vector})
        print(f"  [{i+1}/{len(chunks)}] done")
    return store


def search(query: str, store: list[dict], top_k: int = 3) -> list[dict]:
    """Find the top_k most relevant chunks for a query."""
    query_vector = embed_text(query)
    results = []
    for item in store:
        score = cosine_similarity(query_vector, item["vector"])
        results.append({"score": score, "text": item["text"]})
    results.sort(key=lambda x: x["score"], reverse=True)
    return results[:top_k]


if __name__ == "__main__":
    with open("document.txt", "r") as f:
        document = f.read()

    chunks = chunk_text(document, chunk_size=100, overlap=20)
    store  = build_vector_store(chunks)

    question = "What are the two phases of RAG?"
    results  = search(question, store, top_k=2)

    print(f"\nQuestion: {question}\n")
    for rank, result in enumerate(results, 1):
        print(f"#{rank} Score: {result['score']:.4f}")
        print(f"   {result['text'][:200]}...")

Run it:

python vector_search.py

The chunk about indexing and retrieval should rank first. Notice how the score reflects how relevant each chunk is.

Step 4 : Building the Prompt

This is the heart of RAG. We take the retrieved chunks and combine them with the question into a single prompt that tells the LLM to answer only from what we give it.

Create prompt_builder.py:

def build_rag_prompt(question: str, chunks: list[tuple[float, str]]) -> str:
    """
    Build the RAG prompt: instructions + context + question.
    The key instruction is: answer ONLY from the context below.
    This prevents hallucination.
    """
    context_block = "\n\n---\n\n".join(
        f"[Relevance: {score:.2f}]\n{text}"
        for score, text in chunks
    )

    return f"""You are a helpful assistant. Answer the user's question using ONLY the context below.
If the answer is not in the context, say "I do not have enough information to answer that."
Do not use any outside knowledge.

=== CONTEXT ===

{context_block}

=== QUESTION ===

{question}

=== YOUR ANSWER ==="""

This prompt has three sections:

Instructions - tells the LLM how to behave. The anti-hallucination line is critical.

Context - the retrieved chunks. The LLM reads only these.

Question - what the user actually asked.

Run it standalone to see what the prompt looks like before it reaches the LLM:

python prompt_builder.py

Seeing the raw prompt is one of the best teaching moments in RAG. Students immediately understand why the system cannot hallucinate when the instruction says answer only from the context.

Step 5 - Putting It All Together

Create rag_pipeline.py:

import requests
from importlib import import_module

chunk_text        = import_module("1_chunking").chunk_text
build_vector_store = import_module("3_vector_search").build_vector_store
search            = import_module("3_vector_search").search
build_rag_prompt  = import_module("4_prompt_builder").build_rag_prompt


def generate_answer(prompt: str) -> str:
    """Send the RAG prompt to Ollama and return the answer."""
    response = requests.post(
        "http://localhost:11434/api/chat",
        json={
            "model": "llama3.2",
            "messages": [{"role": "user", "content": prompt}],
            "stream": False,
        }
    )
    response.raise_for_status()
    return response.json()["message"]["content"].strip()


def ask(question: str, store: list[dict], top_k: int = 2) -> str:
    results    = search(question, store, top_k=top_k)
    top_chunks = [(r["score"], r["text"]) for r in results]
    prompt     = build_rag_prompt(question, top_chunks)
    return generate_answer(prompt)


if __name__ == "__main__":
    with open("document.txt", "r") as f:
        document = f.read()

    chunks = chunk_text(document, chunk_size=100, overlap=20)
    store  = build_vector_store(chunks)

    questions = [
        "What are the two phases of RAG?",
        "How does cosine similarity work?",
        "Who invented RAG and when?",   # not in the document — watch what happens
    ]

    for question in questions:
        print(f"\nQuestion: {question}")
        print(f"Answer:   {ask(question, store)}\n")
        print("-" * 60)

Run it:

python rag_pipeline.py

The last question - who invented RAG - is not in the document. A well-built RAG system should say it does not have enough information. That moment is always the most memorable for students.

Adding a Web Interface

Running scripts in a terminal is fine for learning, but a real system needs an API. Add FastAPI in a single file called app.py:

from fastapi import FastAPI
from pydantic import BaseModel
from importlib import import_module

chunk_text        = import_module("1_chunking").chunk_text
build_vector_store = import_module("3_vector_search").build_vector_store
search            = import_module("3_vector_search").search
build_rag_prompt  = import_module("4_prompt_builder").build_rag_prompt

# Import generate_answer from pipeline
from importlib import import_module
generate_answer = import_module("5_rag_pipeline").generate_answer

app = FastAPI(title="MiniRAG")

# Build vector store once at startup
with open("document.txt") as f:
    document = f.read()

chunks = chunk_text(document, chunk_size=100, overlap=20)
STORE  = build_vector_store(chunks)


class Question(BaseModel):
    question: str
    top_k: int = 2


@app.get("/")
def root():
    return {"status": "ok", "message": "MiniRAG is running"}


@app.post("/ask")
def ask(request: Question):
    results    = search(request.question, STORE, top_k=request.top_k)
    top_chunks = [(r["score"], r["text"]) for r in results]
    prompt     = build_rag_prompt(request.question, top_chunks)
    answer     = generate_answer(prompt)
    return {
        "question": request.question,
        "answer":   answer,
        "sources":  [r["text"] for r in results],
    }

Run it:

uvicorn app:app --reload

Open http://localhost:8000/docs to get an interactive interface where you can type questions and see answers directly in your browser.

What You Just Built

Let us recap what each file does:

File	Job	Needs Ollama?
`1_chunking.py`	Splits document into word chunks	No
`2_embedding.py`	Converts text to vectors	Yes
`3_vector_search.py`	Finds relevant chunks for a question	Yes
`4_prompt_builder.py`	Combines chunks and question into a prompt	No
`5_rag_pipeline.py`	Runs the full pipeline end to end	Yes
`app.py`	Exposes everything as a web API	Yes

Files 1 and 4 need no API at all. This is useful if you are teaching — you can explain chunking and prompt design without any model setup.

What to Try Next

Once you have the basics working, experiment with these:

Change chunk size. Set chunk_size=50 and notice you get more chunks. Set it to 200 and you get fewer. Ask the same question and compare the retrieved chunks. Does the answer change?

Change top_k. Set top_k=1 and the LLM gets only one chunk. Set it to 5 and it gets five. More context does not always mean better answers.

Replace the document. Swap document.txt for any text file — a company policy, an article, your CV. The entire system works on any knowledge base.

Ask off-topic questions. Ask about something completely unrelated to your document. Watch the system say it does not know instead of inventing an answer. That is the anti-hallucination guarantee in action.

The Bigger Picture

What you built today is called naive RAG or basic RAG. It works well for getting started and for teaching. When you are ready to go deeper, the next steps are:

Persistent vector store - save embeddings to disk with ChromaDB or FAISS so you do not re-embed every time you restart.

Sentence-based chunking - split at sentence boundaries instead of word count for more natural chunks.

Re-ranking - after retrieval, use a second model to reorder the chunks by relevance before passing them to the LLM.

Evaluation - use tools like RAGAS to measure how well your system is actually retrieving and answering.

Each of these is a clear upgrade path from what you built today. And because your code is split into one file per concept, you can swap out any single piece without touching the others.

The Full Project

The complete project including environment switching between Ollama locally and Groq on Render for deployment is available on GitHub:

github.com/Navashub/rag-projects

Clone it, run through the lessons in order, and then replace document.txt with something from your own domain. That is the fastest way to make RAG feel real.

If this helped you understand RAG, drop a comment with what document you tested it on. The most interesting use cases always come from the community.

Building a REST API with FastAPI from Scratch - Full CRUD, SQLite, Middleware & CORS

Navas Herbert — Fri, 19 Jun 2026 07:18:28 +0000

I am a Data Engineer and AI Engineer who also trains developers. A few weeks ago I was preparing a FastAPI session for a group of students and I wanted a project that was simple enough to understand fully, but rich enough to cover all the important concepts in one place.

The result was this Navas Task Manager API - and by the end of this article, you will have built it too.

We will cover:

Project structure and why it matters
Connecting to SQLite with SQLAlchemy
Defining database models
Validating data with Pydantic schemas
Separating database logic into a crud.py layer
Building full CRUD endpoints with APIRouter
Adding custom middleware for request logging
Configuring CORS so a frontend can talk to the API
Testing everything live in the browser - no Postman needed

The full project is on GitHub at the end of this article. Let's build it.

What We Are Building

A Task Manager API where users can create an account and manage their tasks. Two resources, full CRUD on both, one relationship between them.

Users  →  Tasks  (one user can have many tasks)

The final API will have 10 endpoints:

Method	URL	What it does
POST	/users/	Create a user
GET	/users/	List all users
GET	/users/{id}	Get one user + their tasks
PUT	/users/{id}	Update a user
DELETE	/users/{id}	Delete a user
POST	/tasks/	Create a task
GET	/tasks/	List all tasks
GET	/tasks/{id}	Get one task
PUT	/tasks/{id}	Update a task
DELETE	/tasks/{id}	Delete a task

Why FastAPI?

Before we write any code, let me answer the question beginners always ask.

FastAPI is a modern Python web framework built on top of Starlette and Pydantic. Here is what makes it stand out:

Speed - FastAPI is one of the fastest Python frameworks available, on par with Node.js and Go for async workloads.

Automatic docs - visit /docs and FastAPI generates interactive API documentation automatically. You can test every endpoint right there in the browser.

Type safety - FastAPI uses Python type hints to validate incoming data, catch errors early, and generate accurate documentation - all from the same code.

Developer experience - less boilerplate than Django, more structure than Flask, and excellent error messages that tell you exactly what went wrong.

Project Structure

Here is the folder layout we will build:

task_manager/
├── main.py          ← app entry point, middleware, CORS, routers
├── database.py      ← SQLite connection and session management
├── models.py        ← SQLAlchemy table definitions
├── schemas.py       ← Pydantic request/response schemas
├── crud.py          ← all database operations
├── tasks.db         ← auto-created SQLite file on first run
└── routers/
    ├── __init__.py
    ├── tasks.py     ← task endpoints
    └── users.py     ← user endpoints

This structure follows the separation of concerns principle -each file has one clear job. When something breaks, you know exactly which file to open.

Installation

mkdir task_manager
cd task_manager
mkdir routers
touch routers/__init__.py

pip install fastapi uvicorn sqlalchemy

Step 1 - database.py

This is the foundation. Everything else sits on top of it.

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./tasks.db"

engine = create_engine(
    DATABASE_URL, connect_args={"check_same_thread": False}
)

SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

What each part does:

DATABASE_URL - tells SQLAlchemy where the database lives. The ./ means create the file in the current folder. Switching to PostgreSQL later is as simple as changing this one string.

engine - the actual connection to the database. The check_same_thread: False argument is SQLite-specific and needed because FastAPI handles requests across multiple threads.

SessionLocal - a factory that creates database sessions. Think of a session like a shopping cart for database operations - you collect your changes, then commit them all at once.

Base - the parent class all database models will inherit from. SQLAlchemy uses it to track which Python classes map to which database tables.

get_db() - a dependency function. The yield keyword is the key here. FastAPI opens a session, yields it to the endpoint function, runs the endpoint, then the finally block closes the session automatically - even if an error occurs.

Step 2 - models.py

Models are Python classes that become database tables.

from sqlalchemy import Column, Integer, String, Boolean, ForeignKey
from sqlalchemy.orm import relationship
from database import Base

class User(Base):
    __tablename__ = "users"

    id    = Column(Integer, primary_key=True, index=True)
    name  = Column(String, nullable=False)
    email = Column(String, unique=True, index=True)

    tasks = relationship("Task", back_populates="owner")

class Task(Base):
    __tablename__ = "tasks"

    id          = Column(Integer, primary_key=True, index=True)
    title       = Column(String, nullable=False)
    description = Column(String, nullable=True)
    completed   = Column(Boolean, default=False)
    owner_id    = Column(Integer, ForeignKey("users.id"))

    owner = relationship("User", back_populates="tasks")

The important parts:

class User(Base) - inheriting from Base registers this class with SQLAlchemy. The __tablename__ attribute sets the actual name of the table in the database file.

ForeignKey("users.id") - this is how the one-to-many relationship is enforced at the database level. Every task must belong to a user.

relationship() - this is where the magic happens. Writing user.tasks in Python will automatically fetch all tasks belonging to that user. SQLAlchemy handles the SQL query behind the scenes.

Step 3 : schemas.py

This is where most beginners get confused - "why do I need schemas if I already have models?"

Here is the answer:

SQLAlchemy Model	Pydantic Schema
Talks to the database	Talks to the API user
Defines table columns	Validates request data
Never shown directly	Shapes the response

They are separate because what you store in the database and what you expose through the API are often different. You might store a hashed password but never want to return it in a response. Schemas give you that control.

from pydantic import BaseModel
from typing import Optional, List

# ─── TASK SCHEMAS ───────────────────────────────

class TaskBase(BaseModel):
    title:       str
    description: Optional[str] = None

class TaskCreate(TaskBase):
    owner_id: int

class TaskUpdate(BaseModel):
    title:       Optional[str] = None
    description: Optional[str] = None
    completed:   Optional[bool] = None

class TaskResponse(TaskBase):
    id:        int
    completed: bool
    owner_id:  int

    class Config:
        from_attributes = True

# ─── USER SCHEMAS ───────────────────────────────

class UserBase(BaseModel):
    name:  str
    email: str

class UserCreate(UserBase):
    pass

class UserUpdate(BaseModel):
    name:  Optional[str] = None
    email: Optional[str] = None

class UserResponse(UserBase):
    id:    int
    tasks: List[TaskResponse] = []

    class Config:
        from_attributes = True

The 3-schema pattern:

Base - shared fields used by both Create and Response
Create - fields the user sends to the API
Update - all fields are Optional so users only send what they want to change
Response - what the API sends back, including database-generated fields like id

from_attributes = True is the bridge between SQLAlchemy and Pydantic. Without it, Pydantic cannot read a SQLAlchemy model object - it only understands plain dictionaries by default.

Notice UserResponse includes tasks: List[TaskResponse]. When you fetch a user, their tasks come nested inside the response automatically.

Step 4 - crud.py

All database reads and writes live here. Endpoints never touch the database directly.

Think of it this way - crud.py is the kitchen, routers are the waiters. The waiter takes the order (request), passes it to the kitchen (crud), and brings back the plate (response). Waiters don't cook.

from sqlalchemy.orm import Session
import models, schemas

# ─── USERS ──────────────────────────────────────

def create_user(db: Session, user: schemas.UserCreate):
    db_user = models.User(name=user.name, email=user.email)
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

def get_user(db: Session, user_id: int):
    return db.query(models.User).filter(models.User.id == user_id).first()

def get_users(db: Session):
    return db.query(models.User).all()

def update_user(db: Session, user_id: int, data: schemas.UserUpdate):
    db_user = db.query(models.User).filter(models.User.id == user_id).first()
    if not db_user:
        return None
    updates = data.model_dump(exclude_unset=True)
    for field, value in updates.items():
        setattr(db_user, field, value)
    db.commit()
    db.refresh(db_user)
    return db_user

def delete_user(db: Session, user_id: int):
    db_user = db.query(models.User).filter(models.User.id == user_id).first()
    if not db_user:
        return None
    db.delete(db_user)
    db.commit()
    return db_user

# ─── TASKS ──────────────────────────────────────

def create_task(db: Session, task: schemas.TaskCreate):
    db_task = models.Task(**task.model_dump())
    db.add(db_task)
    db.commit()
    db.refresh(db_task)
    return db_task

def get_task(db: Session, task_id: int):
    return db.query(models.Task).filter(models.Task.id == task_id).first()

def get_tasks(db: Session):
    return db.query(models.Task).all()

def update_task(db: Session, task_id: int, data: schemas.TaskUpdate):
    db_task = db.query(models.Task).filter(models.Task.id == task_id).first()
    if not db_task:
        return None
    updates = data.model_dump(exclude_unset=True)
    for field, value in updates.items():
        setattr(db_task, field, value)
    db.commit()
    db.refresh(db_task)
    return db_task

def delete_task(db: Session, task_id: int):
    db_task = db.query(models.Task).filter(models.Task.id == task_id).first()
    if not db_task:
        return None
    db.delete(db_task)
    db.commit()
    return db_task

The 3-step create pattern - every create operation follows this exactly:

db.add(obj) -stages the record (puts it in the cart)
db.commit() - saves to disk permanently
db.refresh(obj) - reloads the object so you get the auto-generated id back

model_dump(exclude_unset=True) on updates is important. It only includes fields the user actually sent in the request. Without it, unset optional fields would come through as None and accidentally overwrite existing data.

Step 5: The Routers

Create two files: routers/tasks.py and routers/users.py.

routers/tasks.py

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from typing import List
import crud, schemas
from database import get_db

router = APIRouter(prefix="/tasks", tags=["Tasks"])

@router.post("/", response_model=schemas.TaskResponse)
def create_task(task: schemas.TaskCreate, db: Session = Depends(get_db)):
    return crud.create_task(db, task)

@router.get("/", response_model=List[schemas.TaskResponse])
def get_tasks(db: Session = Depends(get_db)):
    return crud.get_tasks(db)

@router.get("/{task_id}", response_model=schemas.TaskResponse)
def get_task(task_id: int, db: Session = Depends(get_db)):
    task = crud.get_task(db, task_id)
    if not task:
        raise HTTPException(status_code=404, detail="Task not found")
    return task

@router.put("/{task_id}", response_model=schemas.TaskResponse)
def update_task(task_id: int, data: schemas.TaskUpdate, db: Session = Depends(get_db)):
    task = crud.update_task(db, task_id, data)
    if not task:
        raise HTTPException(status_code=404, detail="Task not found")
    return task

@router.delete("/{task_id}")
def delete_task(task_id: int, db: Session = Depends(get_db)):
    task = crud.delete_task(db, task_id)
    if not task:
        raise HTTPException(status_code=404, detail="Task not found")
    return {"message": "Task deleted successfully"}

routers/users.py

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from typing import List
import crud, schemas
from database import get_db

router = APIRouter(prefix="/users", tags=["Users"])

@router.post("/", response_model=schemas.UserResponse)
def create_user(user: schemas.UserCreate, db: Session = Depends(get_db)):
    return crud.create_user(db, user)

@router.get("/", response_model=List[schemas.UserResponse])
def get_users(db: Session = Depends(get_db)):
    return crud.get_users(db)

@router.get("/{user_id}", response_model=schemas.UserResponse)
def get_user(user_id: int, db: Session = Depends(get_db)):
    user = crud.get_user(db, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

@router.put("/{user_id}", response_model=schemas.UserResponse)
def update_user(user_id: int, data: schemas.UserUpdate, db: Session = Depends(get_db)):
    user = crud.update_user(db, user_id, data)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

@router.delete("/{user_id}")
def delete_user(user_id: int, db: Session = Depends(get_db)):
    user = crud.delete_user(db, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return {"message": "User deleted successfully"}

Three concepts to understand in the routers:

APIRouter(prefix="/tasks", tags=["Tasks"]) - a mini-app for one resource. The prefix means every route here automatically starts with /tasks. The tags group them neatly on the /docs page.

db: Session = Depends(get_db) - FastAPI's dependency injection. Instead of manually creating a database session in every function, FastAPI calls get_db(), hands you a fresh session, and closes it automatically when done.

response_model=schemas.TaskResponse - controls the exact shape of the response. Even if the database object has more fields, only what is defined in the schema goes out. This prevents accidentally leaking sensitive data.

raise HTTPException(status_code=404) - when a record is not found, you raise this and FastAPI returns a proper JSON error response with the correct HTTP status code.

Step 6: main.py

The final file ties everything together.

from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
import time
import models
from database import engine
from routers import tasks, users

# Create all database tables on startup
models.Base.metadata.create_all(bind=engine)

app = FastAPI(
    title="Navas Task Manager API",
    description="A simple task manager built with FastAPI and SQLite",
    version="1.0.0"
)

# ─── CORS ────────────────────────────────────────
origins = [
    "http://localhost:3000",    # React dev server
    "http://localhost:5173",    # Vite dev server
    "https://yourfrontend.com", # production frontend
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# ─── LOGGING MIDDLEWARE ──────────────────────────
@app.middleware("http")
async def log_requests(request: Request, call_next):
    start_time = time.time()
    print(f"→ {request.method} {request.url}")
    response = await call_next(request)
    duration = time.time() - start_time
    print(f"← {response.status_code} completed in {duration:.3f}s")
    return response

# ─── ROUTERS ─────────────────────────────────────
app.include_router(users.router)
app.include_router(tasks.router)

@app.get("/")
def root():
    return {"message": "Welcome to Navas Task Manager API "}

Breaking this down:

models.Base.metadata.create_all(bind=engine) - looks at all your model classes and creates the tables in tasks.db if they do not exist yet. Run the app for the first time and the database file appears automatically.

CORS vs custom middleware - two different ways to add middleware:

# Way 1 - for built-in or third-party middleware classes
app.add_middleware(CORSMiddleware, allow_origins=origins, ...)

# Way 2 - for middleware you write yourself
@app.middleware("http")
async def log_requests(request: Request, call_next):
    ...

Why CORS matters: if your React or Vue frontend runs on localhost:3000 and your API runs on localhost:8000, the browser will block the request by default - because different ports count as different origins. CORS is your API's way of saying "yes, I trust that frontend."

app.include_router() - plugs the routers into the main app. Adding a new resource in the future means writing a new router file and adding one line here.

Running the API

uvicorn main:app --reload

Open your browser and go to:

http://127.0.0.1:8000/docs

You will see the interactive docs with all 10 endpoints grouped by resource, colour-coded by HTTP method. Click any endpoint, hit Execute, and test it live.

Watching the Middleware Work

As you test endpoints in the browser, watch your terminal. Every request prints something like:

→ POST http://127.0.0.1:8000/users/
← 200 completed in 0.038s

→ POST http://127.0.0.1:8000/tasks/
← 200 completed in 0.025s

→ GET http://127.0.0.1:8000/users/
← 200 completed in 0.004s

This is your logging middleware running for every single request — method, URL, status code, and response time. In a production app you would send these logs to a monitoring service. Here they are a clear way to see the request lifecycle in action.

The Nested Response - Where It All Comes Together

Call GET /users/ and look at the response:

[
  {
    "name": "Alice",
    "email": "alice@example.com",
    "id": 1,
    "tasks": [
      {
        "title": "Learn FastAPI",
        "description": "Build the task manager project",
        "id": 1,
        "completed": false,
        "owner_id": 1
      }
    ]
  }
]

The user's tasks are nested inside the response automatically. No extra query was written. This works because:

UserResponse schema includes tasks: List[TaskResponse]
The User model has relationship("Task", back_populates="owner")
from_attributes = True lets Pydantic read the SQLAlchemy object

Three files collaborating silently to produce one clean response.

What To Build Next

Once you are comfortable with this project, here are natural next steps:

Add authentication - hash passwords with passlib and protect endpoints with JWT tokens using python-jose.

Filter by owner - right now GET /tasks/ returns all tasks from all users. Add a query parameter so users only see their own tasks.

Add pagination - add skip and limit parameters to list endpoints so you are not returning the entire database on every call.

Switch to PostgreSQL- change DATABASE_URL from sqlite:///./tasks.db to postgresql://user:password@localhost/dbname and install psycopg2. Everything else stays the same.

Add a due date - add a due_date column using SQLAlchemy's DateTime type and filter tasks by whether they are overdue.

My Final Thoughts

What I love about FastAPI is that the concepts build on each other cleanly. Once you understand get_db as a dependency, the rest of the dependency injection system makes sense. Once you understand one router, you can write any router. Once you write update_task, writing update_user takes two minutes.

That compounding clarity is what makes it a great framework to teach - and to learn.

GitHub Repository

The full project with all files, a clean README, and the .gitignore already configured is available here:

🔗 task-manager-fastapi

Let's Connect

I write about Data Engineering, AI Engineering, and backend development. If this article helped you, follow me here on dev.to for more.

If you are working on something with FastAPI, Python, or data pipelines and want to collaborate - or just want to talk through an idea - drop a comment below or send me a message. Always happy to connect with people building things.

Built and written by Navas - Data Engineer & AI Engineer
EOF

I Built an AI Document Intelligence API to Demo to My Internship Students - Here's the Full Story

Navas Herbert — Thu, 18 Jun 2026 17:13:00 +0000

Monday morning. My internship students walk in - Amina, Brian, Njeri, Otieno, Wanjiku and the rest of the cohort. I pull up a browser tab, upload a PDF, type a question in plain English, and the system finds the relevant sections and answers it in two seconds.

Then I tell them: "You're building your own version of this. Five days. Skeleton repo is ready. Go."

That's the plan. But before Monday I had to actually build the thing - and it didn't go smoothly. This is the honest story of DataPulse AI: what it does, every tool I tried, every error that broke me, and what finally got it deployed and working end to end.

If you're a junior developer in Nairobi wondering whether you could build something like this - read to the end. The answer is yes. But it'll take some detours.

What Is RAG? (The Open-Book Exam Analogy)

Before the stack, a concept.

RAG stands for Retrieval Augmented Generation. It sounds intimidating. It isn't.

Think of a closed-book exam versus an open-book exam.

A closed-book LLM (like ChatGPT with no plugins) answers from memory - whatever it learned during training. It's fast, but it has no idea what's in your document. Ask it about the contents of your specific company report, your custom dataset, your uploaded PDF - and it'll hallucinate or say it doesn't know.

RAG gives the model an open book. Before answering, it searches your documents, retrieves the most relevant sections, and hands those to the LLM as context. The model doesn't guess - it reads the relevant pages and answers from them.

That's DataPulse AI. Upload any document. Ask a question. The system finds what matters and generates a grounded answer from the actual content.

No hallucinations from thin air. Answers tied to your source material.

The Stack - And Why I Chose Each Piece

Here's what DataPulse AI is built with, and more importantly, why:

FastAPI - the API framework. Fast, async, automatic docs at /docs, Python-native. For a RAG system that needs to handle file uploads, vector searches, and LLM calls, async matters. FastAPI was the obvious call.

PostgreSQL on NeonDB - stores document metadata. Which files have been uploaded, when, what their status is. NeonDB gives you a serverless Postgres instance with a generous free tier. Perfect for a demo project that needs a real database without paying for one.

LanceDB - vector database for semantic search. This is where document chunks live after being embedded. More on why I chose LanceDB specifically in a moment - there's a story there.

fastembed - converts text chunks into vector embeddings. Small, fast, pure Python. Also a story here.

Groq API with llama3 - the LLM that generates the final answer. Groq runs llama3 on custom inference hardware and it is fast. We're talking two seconds for a full response.

Render - backend deployment. Free tier. Enough said.

Vercel - frontend deployment. Clean dark-themed HTML/JS interface. Also free.

The architecture in one sentence: user uploads a document → it gets chunked and embedded into LanceDB → user asks a question → question gets embedded → LanceDB finds the nearest chunks → Groq generates an answer from those chunks → user gets a grounded response.

Simple concept. Getting there was not simple.

The Errors - Every Wall I Hit

This is the part I want every junior developer to read carefully. The finished product looks clean. The journey was not.

Wall 1: Ollama Was Too Heavy to Deploy

I started with Ollama for local LLM inference. It worked beautifully on my machine. ollama run llama3, ask it questions, get answers. Clean.

Then I tried to deploy it.

Ollama's model files are gigabytes. Render's free tier doesn't have the disk space or RAM for that. Not even close. The deployment would time out before the model even loaded.

Local development: great. Cloud deployment on a free tier: not happening.

Switched to: Groq API. Same llama3 model, running on Groq's cloud infrastructure. Free tier available. Response time dropped from 14 seconds (local Ollama on my laptop) to under 2 seconds. That's not a small improvement - that's a completely different user experience.

Wall 2: ChromaDB Killed Windows Students

My first vector database choice was ChromaDB. Popular, well-documented, easy Python API.

The problem: ChromaDB has C++ dependencies under the hood. On Mac and Linux, the pip install works fine. On Windows - which is what most of my students are running - the build errors were brutal.

error: Microsoft Visual C++ 14.0 or greater is required

I was not going to start a student internship with "first, install Visual Studio build tools and configure your PATH." That kills momentum before day one.

Switched to: LanceDB. Pure Python. No C++ anywhere in the dependency tree. pip install lancedb and it works - on Windows, Mac, Linux, no exceptions. For a student project where everyone has different machines, that matters enormously.

Wall 3: sentence-transformers Ate All the RAM

For generating embeddings I started with sentence-transformers - the standard library, widely used, excellent quality.

The RAM usage on startup: 1.5GB.

Render's free tier gives you 512MB.

The deployment would crash every single time the embedding model tried to load. I tried lazy loading, tried quantising, tried everything. The math just didn't work on 512MB.

Switched to: fastembed. Same idea - generates sentence embeddings - but built for efficiency. RAM usage on startup: around 50MB. The quality is slightly lower than sentence-transformers for some tasks, but for document Q&A on a free-tier server? Completely fine. It runs. That matters more.

Wall 4: The First Deployment That Actually Stuck

After switching all three components - Groq for LLM, LanceDB for vectors, fastembed for embeddings - I pushed to Render.

It deployed. The health check passed. I uploaded a test document. I asked a question.

The API returned an answer in 1.8 seconds.

I sat there for a moment and just looked at it.

The Moment It Worked

The test document was a short PDF about Nairobi's public transport system - matatus, routes, fares, the usual chaos.

I asked: "What are the main challenges with matatu operations in Nairobi?"

The system:

Embedded the question into a vector
Searched LanceDB for the three most semantically similar chunks from the uploaded document
Sent those chunks as context to Groq's llama3
Got back a structured, grounded answer in 1.8 seconds

The answer cited specific sections of the document. It didn't make anything up. It said "based on the document" and then actually referred to the document.

That's when RAG stopped being a concept and became something real.

What the API Actually Does

A quick look at the core endpoints:

Upload a document:

POST /documents/upload
Content-Type: multipart/form-data
file: [your .txt or .pdf file]

The system chunks the document into overlapping segments, embeds each chunk with fastembed, and stores the vectors in LanceDB alongside the chunk text. PostgreSQL records the document metadata.

Ask a question:

POST /documents/{doc_id}/query
{
  "question": "What does this document say about deployment costs?"
}

Response:

{
  "answer": "According to the document, deployment costs depend primarily on...",
  "sources": [
    { "chunk": "...relevant section text...", "score": 0.91 },
    { "chunk": "...second relevant section...", "score": 0.87 }
  ],
  "response_time_ms": 1823
}

The sources array is important. Students can see which chunks the model used to generate the answer. That's the grounding — not just an answer, but evidence.

List documents:

GET /documents/

Returns all uploaded documents with metadata. The frontend uses this to populate the document selector.

What Students Will Build: The 5-Day Internship Project

Monday morning I demo the finished product. Then I hand them the skeleton repo.

Here's the five-day breakdown:

Day 1 - Setup & Document Ingestion
Get the project running locally. Implement the document upload endpoint. Connect to NeonDB. Chunk text documents into overlapping segments. No vectors yet - just get files in and stored.

Day 2 - Embeddings & Vector Storage
Integrate fastembed. Embed each chunk on upload. Store vectors in LanceDB. By end of day, uploaded documents should be fully embedded and searchable.

Day 3 - Query Pipeline
Build the question-answering endpoint. Embed the incoming question. Retrieve the top-k most similar chunks from LanceDB. Return the raw chunks with similarity scores. No LLM yet - just search.

Day 4 - LLM Integration & Answer Generation
Connect Groq. Pass the retrieved chunks as context. Prompt the model to answer the question grounded in the provided sections only. Full pipeline: question in, grounded answer out.

Day 5 - Frontend, Testing & Demo Prep
Build a simple HTML/JS frontend that talks to the API. Upload a document, ask questions, display answers and sources. Deploy on Vercel. Prep a 5-minute demo for the cohort.

Five days. One working RAG system. Built from scratch.

Lessons for Builders

Four honest takeaways from this build:

1. Deploy early, deploy often - not at the end.
I built almost the entire system locally before trying to deploy. That's why the RAM and C++ issues blindsided me. If I'd tried to deploy after Day 1, I'd have hit those walls immediately and switched tools before writing any application code. Now I teach this: get a hello world deployed first. Then build.

2. Free-tier constraints are features, not bugs.
Render's 512MB RAM limit forced me to find fastembed, which is genuinely a better choice for this use case than sentence-transformers. The constraint made the system leaner and faster. Sometimes the limits push you toward better solutions.

3. Pure Python dependencies win on student projects.
ChromaDB was technically fine. But one C++ build error on one student's Windows machine would have cost half a day of troubleshooting before anyone wrote a line of application code. LanceDB being pure Python is not just a technical choice - it's a teaching choice. Reduce friction at setup, maximise time on actual learning.

4. Groq is genuinely fast and the free tier is real.
I expected the free Groq tier to be throttled or limited enough to feel broken. It isn't. Two-second responses on llama3, reasonable rate limits, clean API. For a demo project or a student internship, it's exactly right. Use it.

Try It / See the Code

The full system is live:

API docs: https://datapulse-ai-zsv7.onrender.com/docs
GitHub: https://github.com/Navashub/datapulse-ai

Upload a .txt or .pdf file and ask it a question. The API docs are interactive - you can test every endpoint directly from the browser without writing any code.

If you want to build your own version: start with the API docs, understand the three endpoints, then implement them one at a time in the order above. The skeleton repo will be public after Monday's demo.

What Monday Looks Like

8:30am. Students file in. I pull up the live UI.

I upload a PDF - something relevant to them, probably a Kenya tech industry report or a data engineering reference doc. I ask a question. The answer comes back in under two seconds, with sources highlighted.

Then I say: "Your skeleton repo is in the chat. You have five days."

And we'll see what they build.

I'll write about how that goes next week.

I'm a data trainer in Nairobi running a full data programme -
Python foundations → Data Science or Data Engineering specialisations.
I write weekly about what we covered, what worked, and what surprised me.
Follow along or drop your questions in the comments.

Today I Taught Linux File Permissions - And Alice Couldn't Read the Salary File

Navas Herbert — Tue, 09 Jun 2026 06:27:57 +0000

I opened today's session with a question.

"Imagine you leave your laptop open in a coffee shop in Westlands. What stops a stranger from reading your files?"

Silence. A few answers. Then I said: "On Linux - the answer is permissions. Every single file on this server has a set of rules that says who can touch it. Today we are going to learn exactly how that works, live on a real server."

New cohort. Fresh faces. Some had never touched a terminal before. By the end of two hours, they had created real user accounts, organised them into groups, locked down files, and proved - by trying to break in as a different user -that their permissions actually worked.

Here's how it went.

First: Getting On a Real Server

No local files. No virtual machines. We SSH'd into a live Ubuntu server.

ssh root@159.x.x.x

That first SSH fingerprint warning - the one that looks scary - causes a pause in every cohort:

The authenticity of host '159.x.x.x' can't be established.
Are you sure you want to continue connecting (yes/no)?

I explained: "Linux is asking - I've never seen this server before, do you trust it? We say yes." After that, the prompt changed:

Welcome to Ubuntu 22.04 LTS
root@server:~#

That # symbol. I made sure everyone understood what it meant - root, the most powerful user on the system. The whole reason permissions exist is to protect files from that kind of power being used carelessly.

The Mental Model: Three Questions Linux Always Asks

Before any commands, I drew three questions on the board:

WHO owns this file? - the Owner
What GROUP is it in? -the Group, a shared team of users
Is everyone else allowed? - Others

And for each of those three, Linux grants up to three abilities:

Symbol	Name	On a file	On a directory
`r`	read	Open and read it	Run `ls` inside
`w`	write	Edit or delete it	Create/delete files inside
`x`	execute	Run it as a program	`cd` into it
`-`	none	Denied	Denied

Then the 10-character string that wraps all of this together:

- r w x   r - x   r - -
  ─────   ─────   ─────
  owner   group   others
└── file type: - = file, d = directory

Five minutes of theory. Then hands-on immediately.

Creating Real Users: Alice and Bob

We created two users directly on the server - alice and bob. These would be our test subjects for the whole session.

adduser alice

Linux walked through everything interactively - set a password, created a home folder at /home/alice, created a group with the same name. I made the point: "Notice Linux did several things at once. It created the user, created a private group for her, and gave her a home folder that belongs to her alone."

id alice

uid=1001(alice) gid=1001(alice) groups=1001(alice)

Three ways to verify a user exists - id, checking /etc/passwd, and listing /home/. I showed all three so students knew different tools rather than memorising one path.

Groups: The Company Department Analogy

The real-world analogy I use every time: a company. Everyone in the Development team can read the source code. Everyone in Finance can read payroll files. You don't set permissions for every individual - you create a group and add people to it.

groupadd devteam
usermod -aG devteam alice
usermod -aG devteam bob
groups alice

alice : alice devteam

The -aG warning always needs emphasis. Use -G without -a and you silently remove all the user's existing groups. One missing letter, broken access. I've seen that mistake cause real problems in production environments. Worth saying twice in class.

Reading Permissions: The ls -l Moment

We created a /project folder with three files:

mkdir /project
echo 'This is the main app code' > /project/app.py
echo 'Top secret salary data'    > /project/salaries.txt
echo 'Public readme'             > /project/README.txt
ls -l /project/

-rw-r--r-- 1 root root 26 Jan  1 10:00 app.py
-rw-r--r-- 1 root root 24 Jan  1 10:00 README.txt
-rw-r--r-- 1 root root 23 Jan  1 10:00 salaries.txt

All three files showing -rw-r--r--. I pointed at salaries.txt and said: "Right now, any user on this server can read the salary file. That's a problem. Let's fix it."

chmod: Locking Things Down

Two ways to use chmod - numbers (fast) and symbols (readable). I teach both.

The number system: each permission has a value. r=4, w=2, x=1. Add them up for each group. Owner, group, others — three digits.

The numbers worth memorising:

Number	String	Use
`777`	`rwxrwxrwx`	Everyone everything - dangerous
`755`	`rwxr-xr-x`	Programs, public directories
`644`	`rw-r--r--`	Normal files
`640`	`rw-r-----`	Team files - group reads, others locked
`600`	`rw-------`	Private (SSH keys, credentials)

We set them live:

chmod 600 /project/salaries.txt
chmod 640 /project/app.py
chmod 644 /project/README.txt
ls -l /project/

-rw-r--r-- 1 root root 24 Jan  1 10:00 README.txt
-rw-r----- 1 root root 26 Jan  1 10:00 app.py
-rw------- 1 root root 23 Jan  1 10:00 salaries.txt

The Moment That Made the Session

Then we switched to alice and tried to read the salary file:

su - alice
cat /project/salaries.txt

cat: /project/salaries.txt: Permission denied

The room reacted. A few people laughed. One student said "it actually works."

That's the moment I wait for every cohort. Not because it's complicated — it isn't. But because seeing a real system refuse access, because of rules they set, makes it concrete in a way no amount of theory can. They didn't just learn about permissions. They used them.

chown: Handing Ownership to the Right Person

Permissions control what can be done. Ownership controls who the rules apply to. chown transfers ownership:

chown alice:devteam /project/app.py
ls -l /project/app.py

-rwxr----- 1 alice devteam 26 Jan  1 10:00 app.py

Now alice owns the file and devteam is the group. Because bob is in devteam, the group permission (r--) applies to him - he can read, but not write.

We proved it:

su - bob
cat /project/app.py          # works - group has r
echo 'bob was here' >> /project/app.py  # denied - group has no w

This is the main app code
bash: /project/app.py: Permission denied

"Bob can read the code but can't change it. That's how a real team works."

What I Noticed Teaching This Session

1. The SSH fingerprint warning catches everyone. It looks dangerous. A quick calm explanation - "Linux is asking if you trust this server" - is all it takes. Don't skip it.

2. The Permission denied moment is worth engineering. I could have just explained that permissions work. Instead I made them set up a file, lock it down, then try to break in as another user. Seeing their own rules enforced is the most memorable minute of the session.

3. The -aG warning needs to be said out loud, twice. Silent data loss - user loses all group memberships with one wrong flag - is the kind of mistake that causes real incidents. Beginners need to hear that this is serious before they learn the command, not after.

4. New cohort energy is different. These students had never touched a terminal before today. By the end they were switching between user accounts, testing access, reading permission strings without help. That progression in two hours is why I love this job.

Try It Yourself

You don't need a paid server. Spin up a free Ubuntu instance on:

Oracle Cloud Free Tier — always free, real Ubuntu server
WSL2 — Windows Subsystem for Linux, runs locally

Then run through the sequence: create two users, a group, three files with different permissions, and prove it works by switching between accounts. The Permission denied message will feel like a win, not an error.

I'm a data trainer in Nairobi running a full data programme -
Python foundations → Data Science or Data Engineering specialisations.
I write daily about what I taught, what worked, and what surprised me in the classroom.
Follow along or drop your questions in the comments.

Python Week 6: Our Programs Finally Read Real Files

Navas Herbert — Tue, 09 Jun 2026 05:47:50 +0000

Every program we'd built so far had one problem.

The moment you closed it, everything disappeared. The students we added to the registry. The scores we calculated. The transactions we analysed. Gone. You'd open the program again, and it would start from scratch.

Real software doesn't work like that. Real software reads from files, processes data, writes results back out. Real software persists.

Week 6 was the week we crossed that line.

I walked in with a file called students.csv - 30 rows of messy, real-looking student data. Names in wrong cases. Missing scores. Inconsistent course names. I put it on the projector and said: "By the end of today, Python will read this, clean it, and report on it. Without us touching a single row manually."

The room got quiet in the good way.

String Methods: Cleaning Up Messy Text

Before we touched any file, we needed sharper tools for working with text. Real data is almost always dirty - inconsistent capitalisation, rogue spaces, mixed formats.

These are the methods that fix it:

name = "  amina WAWERU  "

print(name.strip())       # remove leading/trailing spaces
print(name.lower())       # all lowercase
print(name.upper())       # all uppercase
print(name.title())       # Title Case - first letter of each word
print(name.strip().title())  # chain them together

amina WAWERU
  amina waweru  
  AMINA WAWERU  
  Amina Waweru  
Amina Waweru

That last line - chaining .strip() and .title() - is where students start thinking like data cleaners. One messy string in, one clean string out.

More essential methods:

course = "  data engineering "

print(course.strip())              # "data engineering"
print(course.strip().title())      # "Data Engineering"
print(course.strip().replace("engineering", "science"))  # "data science"
print("Data Engineering".startswith("Data"))    # True
print("Data Engineering".endswith("ing"))       # True
print("Data Engineering".count("a"))            # 2
print("Data Engineering".split(" "))            # ['Data', 'Engineering']

data engineering
Data Engineering
data science
True
True
2
['Data', 'Engineering']

The SQL connection came up again naturally. Wanjiku said: ".strip() is TRIM(). .title() is INITCAP(). We already know this."

Exactly. Different language, same ideas. This is why learning SQL first pays off.

String Checking Methods

These return True or False - perfect for validation:

score_input = "88"
name_input = "Amina123"
empty_input = "   "

print(score_input.isdigit())      # True - all digits
print(name_input.isalpha())       # False - has numbers
print(empty_input.strip() == "")  # True - effectively empty
print("amina@lux.co.ke".find("@"))  # 5 - position of @

True
False
True
5

We used these to write a simple input validator - the kind of check every real form needs before saving data:

def validate_student_input(name, score_str):
    errors = []

    if not name.strip():
        errors.append("Name cannot be empty")
    if not score_str.isdigit():
        errors.append("Score must be a whole number")
    elif not (0 <= int(score_str) <= 100):
        errors.append("Score must be between 0 and 100")

    return errors

# Test it
print(validate_student_input("Amina", "88"))      # []
print(validate_student_input("", "88"))            # ['Name cannot be empty']
print(validate_student_input("Brian", "abc"))      # ['Score must be a whole number']
print(validate_student_input("Njeri", "150"))      # ['Score must be between 0 and 100']

[]
['Name cannot be empty']
['Score must be a whole number']
['Score must be between 0 and 100']

An empty list means everything is valid. A list with items means something failed. Clean, readable, reusable - everything we learned in Week 4 (functions) and Week 5 (lists) coming together.

File Handling: Reading From the Real World

Now the main event.

Python opens files with open(). But instead of using open() directly, we use the with statement - it opens the file, lets you work with it, and automatically closes it when you're done. No risk of leaving files hanging open.

with open("greeting.txt", "r") as file:
    content = file.read()
    print(content)

The modes:

"r" — read (file must exist)
"w" — write (creates file, overwrites if it exists)
"a" — append (adds to the end without deleting)

Writing a file:

with open("notes.txt", "w") as file:
    file.write("Python Week 6 Notes\n")
    file.write("Topic: File Handling\n")
    file.write("Status: Mind blown\n")

print("File written!")

File written!

Reading it back:

with open("notes.txt", "r") as file:
    for line in file:
        print(line.strip())    # .strip() removes the \n at the end of each line

Python Week 6 Notes
Topic: File Handling
Status: Mind blown

Simple. But the moment students saw their own data surviving after the program closed - there was a visible shift in the room.

Reading a CSV File Manually

This is the moment the session had been building toward.

A CSV (Comma-Separated Values) file is the most common format for tabular data. Every spreadsheet, every database export, every dataset you'll ever work with -almost certainly starts as a CSV at some point.

Here's what our students.csv looked like:

name,course,score
amina waweru,data engineering,88
BRIAN OTIENO,Data Science,74
njeri kamau ,DATA ENGINEERING,91
kamau mwangi,data science,
wanjiku achieng,Data Engineering,79
aisha baraka,DATA SCIENCE,85

Messy. Inconsistent capitalisation. One missing score. Trailing spaces. Real.

Reading it line by line:

with open("students.csv", "r") as file:
    header = file.readline()    # skip the header row
    print(f"Columns: {header.strip()}")

    for line in file:
        row = line.strip().split(",")
        print(row)

Columns: name,course,score
['amina waweru', 'data engineering', '88']
['BRIAN OTIENO', 'Data Science', '74']
['njeri kamau ', 'DATA ENGINEERING', '91']
['kamau mwangi', 'data science', '']
['wanjiku achieng', 'Data Engineering', '79']
['aisha baraka', 'DATA SCIENCE', '85']

Now we could see exactly what we were dealing with. Messy input, structured as lists. Time to clean it.

The Moment That Got Everyone: The Full Pipeline

We combined everything- file reading, string methods, validation, data structures - into one script. I walked through it step by step, building it live:

def clean_name(name):
    return name.strip().title()

def clean_course(course):
    return course.strip().title()

def parse_score(score_str):
    score_str = score_str.strip()
    if score_str.isdigit():
        return int(score_str)
    return None   # missing or invalid score

def calculate_grade(score):
    if score is None: return "N/A"
    if score >= 80: return "A"
    elif score >= 70: return "B"
    elif score >= 60: return "C"
    elif score >= 50: return "D"
    else: return "F"

# Read and process the file
students = []

with open("students.csv", "r") as file:
    file.readline()   # skip header

    for line in file:
        parts = line.strip().split(",")
        if len(parts) != 3:
            continue  # skip malformed rows

        name   = clean_name(parts[0])
        course = clean_course(parts[1])
        score  = parse_score(parts[2])
        grade  = calculate_grade(score)

        students.append({
            "name": name,
            "course": course,
            "score": score,
            "grade": grade
        })

# Print the cleaned report
print(f"\n{'='*55}")
print(f"  LUX ACADEMY - CLEANED STUDENT REPORT")
print(f"{'='*55}")
print(f"  {'NAME':<20} {'COURSE':<20} {'SCORE':<7} GRADE")
print(f"  {'-'*50}")

for s in students:
    score_display = str(s['score']) if s['score'] is not None else "MISSING"
    print(f"  {s['name']:<20} {s['course']:<20} {score_display:<7} {s['grade']}")

print(f"{'='*55}")

# Summary
valid_scores = [s['score'] for s in students if s['score'] is not None]
print(f"\n  Total students : {len(students)}")
print(f"  Missing scores : {len(students) - len(valid_scores)}")
print(f"  Class average  : {sum(valid_scores)/len(valid_scores):.1f}")
print(f"  Highest score  : {max(valid_scores)}")
print(f"  Lowest score   : {min(valid_scores)}")

=======================================================
  LUX ACADEMY - CLEANED STUDENT REPORT
=======================================================
  NAME                 COURSE               SCORE   GRADE
  --------------------------------------------------
  Amina Waweru         Data Engineering     88      A
  Brian Otieno         Data Science         74      B
  Njeri Kamau          Data Engineering     91      A
  Kamau Mwangi         Data Science         MISSING N/A
  Wanjiku Achieng      Data Engineering     79      B
  Aisha Baraka         Data Science         85      A
=======================================================

  Total students : 6
  Missing scores : 1
  Class average  : 83.4
  Highest score  : 91
  Lowest score   : 74

The room went silent when that output appeared.

Then Brian said: "We just built a data pipeline."

He wasn't wrong. Read raw data from a file. Clean it. Validate it. Structure it. Report on it. That's a pipeline - the same pattern that powers every data engineering workflow, just without the framework around it yet.

I told them: "When you get to Airflow, you'll write DAGs that do exactly this. The logic is identical - the scaffolding just gets more powerful."

Writing Results to a File

The last piece - saving the cleaned output so it persists:

with open("cleaned_students.csv", "w") as output:
    output.write("name,course,score,grade\n")

    for s in students:
        score_str = str(s['score']) if s['score'] is not None else ""
        output.write(f"{s['name']},{s['course']},{score_str},{s['grade']}\n")

print("Cleaned data saved to cleaned_students.csv ✅")

Cleaned data saved to cleaned_students.csv ✅

Input file in. Cleaned file out. The program did in seconds what would take a human twenty minutes of careful spreadsheet work — and it never makes a typo.

Practice Problems

Easy:

# 1. Write a program that asks for 3 lines of text and saves them to a file called "notes.txt"
# 2. Read "notes.txt" back and print each line numbered (1. line one, 2. line two...)
# 3. Clean this list of messy names using string methods:
#    names = ["  AMINA waweru", "brian OTIENO  ", "NJERI kamau  "]

Medium:

# Write a function that reads a text file and returns:
# - Total number of lines
# - Total number of words
# - The longest line

def analyse_file(filename):
    pass  # your code here

# Test with any .txt file you create

Challenge:

# Build a contact book that saves to and loads from a CSV file
# contacts.csv format: name,phone,email
#
# Your program should:
# 1. Load existing contacts from file on startup
# 2. Allow adding new contacts
# 3. Allow searching by name
# 4. Save all contacts back to the file on exit
#
# Bonus: validate that the email contains "@" and the phone is digits only

What I Noticed Teaching This Session

1. "We just built a data pipeline" is the sentence I wait for every cohort. When a student names what they've built - without being told - it means they understood not just the code but the concept. Brian earned that moment.

2. The SQL comparison came up again unprompted. At this point, students with the SQL background are making connections constantly - strip() is TRIM(), split() is like parsing, filtering a list is a WHERE clause. This is the compounding return on teaching SQL first.

3. Messy data was a better teacher than clean data. I could have given them a perfectly formatted CSV. Instead I gave them one with caps inconsistency, a missing score, and trailing spaces. Every problem they hit was a real problem real data has. Fixing it felt like real work.

4. The with statement is a habit worth building early. Some students tried open() without with first. When I showed what happens if the program crashes mid-write without proper closure - they switched immediately and never looked back.

What's Coming in Week 7: Error Handling & Practical Modules

So far our programs assume everything goes right. The file exists. The score is a number. The user types what we expect.

Real programs don't get that luxury:

try:
    score = int(input("Enter score: "))
    print(f"Score accepted: {score}")
except ValueError:
    print("That's not a number. Please enter a valid score.")
except FileNotFoundError:
    print("File not found. Check the filename and try again.")
finally:
    print("Validation complete.")

We'll also cover the csv module (which handles CSV files properly - quoted fields, commas in values, headers), json for API data, os for working with folders and paths, and datetime for timestamps.

Week 7 is where Python stops being fragile and starts being robust. See you then.

Try It Yourself

Create your own messy CSV - names in wrong cases, a missing value or two - and run the full pipeline on it. The messier you make it, the more satisfying the clean output.

Python Week 5: One Variable, Many Values (Data Structures!)

Navas Herbert — Sun, 07 Jun 2026 11:14:18 +0000

Every variable we'd worked with for four weeks held exactly one thing.

One name. One score. One balance. One grade.

That's fine for simple programs. But real data doesn't come in ones. A school has hundreds of students. A shop has thousands of products. M-Pesa processes millions of transactions every day.

I opened Week 5 with a question: "How do you store 500 student names in Python?"

Someone said: name1 = "Amina", name2 = "Brian" ...

I let them get to name5 before raising my hand.

"What about name 500?"

This week we got the answer. Not one box - a whole warehouse.

Lists: The Numbered Shopping List

A list is an ordered, changeable collection. Think of it as a numbered shopping list - item 1, item 2, item 3. The order matters. You can add things, remove things, change things.

students = ["Amina", "Brian", "Njeri", "Kamau", "Wanjiku"]

print(students)         # the whole list
print(students[0])      # first item — Amina
print(students[2])      # third item — Njeri
print(students[-1])     # last item — Wanjiku

['Amina', 'Brian', 'Njeri', 'Kamau', 'Wanjiku']
Amina
Njeri
Wanjiku

That -1 index caused the first pause of the session. "Negative indexing?"

Yes. In Python, -1 always means the last item. -2 is second from last. It's Python's shortcut for "count from the back" -useful when you don't know how long the list is.

List Methods: What You Can Do With a List

Lists come with built-in tools:

scores = [78, 45, 92, 61, 88]

scores.append(73)          # add to the end
print(scores)

scores.insert(0, 100)      # insert at position 0
print(scores)

scores.remove(45)          # remove first occurrence of 45
print(scores)

scores.sort()              # sort in place
print(scores)

print(len(scores))         # how many items?
print(max(scores))         # highest value
print(min(scores))         # lowest value
print(sum(scores))         # total

[78, 45, 92, 61, 88, 73]
[100, 78, 45, 92, 61, 88, 73]
[100, 78, 92, 61, 88, 73]
[61, 73, 78, 88, 92, 100]
6
100
61
492

And looping through a list - which felt familiar from Week 3:

for score in scores:
    if score >= 80:
        print(f"{score} ✅ Pass")
    else:
        print(f"{score} ❌ Below average")

61 ❌ Below average
73 ❌ Below average
78 ❌ Below average
88 ✅ Pass
92 ✅ Pass
100 ✅ Pass

Tuples: The Sealed Envelope

A tuple looks like a list but uses round brackets - and once you create it, you cannot change it. It's sealed.

coordinates = (-1.286389, 36.817223)   # Nairobi CBD coordinates
rgb_blue = (0, 0, 255)
weekdays = ("Mon", "Tue", "Wed", "Thu", "Fri")

print(coordinates[0])    # -1.286389
print(len(weekdays))     # 5

-1.286389
5

Try to change it:

coordinates[0] = 99   # trying to modify a tuple

TypeError: 'tuple' object does not support item assignment

"Why would you ever want something you can't change?"

Good question - and it's the right one to ask. Tuples are for data that should not change. GPS coordinates. Days of the week. A student's ID number and date of birth. If you use a list for these and something accidentally modifies it, your data is wrong. A tuple makes that impossible.

Rule I gave them: if the data shouldn't change - use a tuple. If it might change - use a list.

Dictionaries: The Contacts Book

This is the one that changed how students thought about data.

A dictionary stores data in key-value pairs. Instead of looking things up by position (item 0, item 1), you look them up by name.

My analogy: a contacts book. You don't flip to page 7 to find someone's number - you look them up by their name. The name is the key. The number is the value.

student = {
    "name": "Amina Waweru",
    "age": 24,
    "course": "Data Engineering",
    "city": "Nairobi",
    "score": 88
}

print(student["name"])     # Amina Waweru
print(student["score"])    # 88
print(student["course"])   # Data Engineering

Amina Waweru
88
Data Engineering

Adding, updating, and removing entries:

# Add a new key
student["email"] = "amina@luxacademy.co.ke"

# Update an existing value
student["score"] = 92

# Remove a key
del student["age"]

print(student)

{'name': 'Amina Waweru', 'course': 'Data Engineering', 'city': 'Nairobi', 'score': 92, 'email': 'amina@luxacademy.co.ke'}

Looping through a dictionary:

for key, value in student.items():
    print(f"{key}: {value}")

name: Amina Waweru
course: Data Engineering
city: Nairobi
score: 92
email: amina@luxacademy.co.ke

The Moment That Stopped the Room

We'd been working with one dictionary - one student. Then I asked: "What if we had a list of dictionaries? One per student?"

students = [
    {"name": "Amina",  "course": "Data Engineering", "score": 88},
    {"name": "Brian",  "course": "Data Science",      "score": 74},
    {"name": "Njeri",  "course": "Data Engineering",  "score": 91},
    {"name": "Kamau",  "course": "Data Science",      "score": 62},
    {"name": "Wanjiku","course": "Data Engineering",  "score": 79},
]

for student in students:
    print(f"{student['name']} | {student['course']} | Score: {student['score']}")

Amina | Data Engineering | Score: 88
Brian | Data Science | Score: 74
Njeri | Data Engineering | Score: 91
Kamau | Data Science | Score: 62
Wanjiku | Data Engineering | Score: 79

Otieno looked at it for a moment, then said: "This is basically a table. Like SQL."

The room shifted.

He was exactly right. Each dictionary is a row. Each key is a column. A list of dictionaries is a table - the same structure that SQL uses, the same structure that Pandas DataFrames use. The students headed for Data Engineering had just seen their first dataset. The ones headed for Data Science had just seen their first DataFrame — before ever importing Pandas.

I told them to remember this moment.

Filtering a List of Dictionaries

Once they saw the table connection, the next step was obvious - filtering:

# Find all Data Engineering students
de_students = []

for student in students:
    if student["course"] == "Data Engineering":
        de_students.append(student)

for s in de_students:
    print(f"{s['name']}: {s['score']}")

Amina: 88
Njeri: 91
Wanjiku: 79

Someone said quietly: "That's a WHERE clause."

Yes. Exactly. We'd just written a Python WHERE filter - no SQL, no Pandas, just a loop and a conditional. These concepts connect across every tool they'll ever use.

Sets: The Register With No Duplicates

The last structure - and the one with the best surprise moment.

A set is an unordered collection with no duplicates. If you try to add the same item twice, it just ignores the second one.

# Imagine students signing up for a workshop
signups = ["Amina", "Brian", "Amina", "Njeri", "Brian", "Brian", "Kamau"]

unique_signups = set(signups)
print(unique_signups)
print(f"Unique attendees: {len(unique_signups)}")

{'Njeri', 'Kamau', 'Amina', 'Brian'}
Unique attendees: 4

"It just... removed the duplicates?!"

Yes. Automatically. No loop. No checking. Just set().

Aisha immediately said: "So this is like SELECT DISTINCT in SQL?"

Exactly. Different syntax, same idea. Sets exist for moments when uniqueness is what matters - unique visitors, unique products, unique error types. If you need order or labels - use a list or dictionary. If you just need to know what's there without repetition - use a set.

Choosing the Right Structure

I ended the theory section with a decision table:

I need to...	Use
Store items in order, change them later	List
Store items that should never change	Tuple
Look things up by name/label	Dictionary
Store unique items, no duplicates	Set

This table ended up on everyone's notes. The question isn't "how do I use each one" - it's "which one fits what I'm trying to do."

We Built This Together: Student Registry System

The session project - combining all four structures plus functions from Week 4:

# Our student registry - a list of dictionaries
registry = []

def add_student(name, course, score):
    student = {
        "name": name,
        "course": course,
        "score": score,
        "grade": calculate_grade(score)
    }
    registry.append(student)

def calculate_grade(score):
    if score >= 80: return "A"
    elif score >= 70: return "B"
    elif score >= 60: return "C"
    elif score >= 50: return "D"
    else: return "F"

def print_registry():
    print(f"\n{'='*50}")
    print(f"  LUX ACADEMY - STUDENT REGISTRY")
    print(f"{'='*50}")
    for s in registry:
        print(f"  {s['name']:<15} {s['course']:<20} {s['score']}  ({s['grade']})")
    print(f"{'='*50}")
    print(f"  Total students: {len(registry)}")

def course_summary():
    courses = set(s["course"] for s in registry)
    print("\n--- Course Summary ---")
    for course in courses:
        enrolled = [s for s in registry if s["course"] == course]
        avg = sum(s["score"] for s in enrolled) / len(enrolled)
        print(f"  {course}: {len(enrolled)} students | Avg score: {avg:.1f}")

# Populate the registry
add_student("Amina Waweru",    "Data Engineering", 88)
add_student("Brian Otieno",    "Data Science",     74)
add_student("Njeri Kamau",     "Data Engineering", 91)
add_student("Kamau Mwangi",    "Data Science",     62)
add_student("Wanjiku Achieng", "Data Engineering", 79)
add_student("Aisha Baraka",    "Data Science",     85)

print_registry()
course_summary()

==================================================
  LUX ACADEMY — STUDENT REGISTRY
==================================================
  Amina Waweru    Data Engineering     88  (A)
  Brian Otieno    Data Science         74  (B)
  Njeri Kamau     Data Engineering     91  (A)
  Kamau Mwangi    Data Science         62  (C)
  Wanjiku Achieng Data Engineering     79  (B)
  Aisha Baraka    Data Science         85  (A)
==================================================
  Total students: 6

--- Course Summary ---
  Data Engineering: 3 students | Avg score: 86.0
  Data Science: 3 students | Avg score: 73.7

That output on the projector got a round of quiet impressed noises. It looks like something you'd actually use. Because it is.

Practice Problems

Easy:

# 1. Create a list of 5 Kenyan cities. Print the first, last, and middle one.
# 2. Create a tuple of your top 3 favourite foods. Try to change one item — read the error.
# 3. Create a set from this list and print how many unique items there are:
#    items = ["unga", "sukari", "unga", "mafuta", "sukari", "chumvi", "unga"]

Medium:

# Build a simple phone book using a dictionary
# It should support: add contact, lookup contact, delete contact

phone_book = {}

def add_contact(name, number):
    pass  # your code here

def lookup(name):
    pass  # your code here - handle missing contacts gracefully

def delete_contact(name):
    pass  # your code here

add_contact("Amina", "0712 345 678")
add_contact("Brian", "0723 456 789")
print(lookup("Amina"))     # 0712 345 678
print(lookup("Njeri"))     # "Contact not found"
delete_contact("Brian")

Challenge:

# M-Pesa transaction log analyser
# Given this list of transactions, find:
# 1. Total amount sent
# 2. Largest single transaction
# 3. Unique recipients (use a set)
# 4. How many transactions were above KES 1000

transactions = [
    {"recipient": "Amina",   "amount": 500,  "type": "send"},
    {"recipient": "Brian",   "amount": 2000, "type": "send"},
    {"recipient": "Amina",   "amount": 750,  "type": "send"},
    {"recipient": "Njeri",   "amount": 150,  "type": "send"},
    {"recipient": "Brian",   "amount": 3500, "type": "send"},
    {"recipient": "Kamau",   "amount": 1200, "type": "send"},
    {"recipient": "Amina",   "amount": 800,  "type": "send"},
]

# Your analysis here...

What I Noticed Teaching This Session

1. The list-of-dictionaries moment is the pivot point of the whole course. When Otieno said "this is basically a table" - that connection to SQL, to DataFrames, to real data - is what separates Python-as-syntax from Python-as-a-data-tool. Make sure that moment has space to breathe.

2. Sets always get the best surprise reaction. Students expect deduplication to require a loop and a lot of logic. When set() does it in one word, the reaction is genuine. Let them sit with it before explaining why.

3. The decision table mattered more than I expected. Students kept coming back to it during exercises - "should I use a list or a dictionary here?" The fact that they were asking that question at all means the concept landed.

4. Functions + data structures together feel like real software. The registry project is the first thing we've built that genuinely looks like something you'd find in a codebase. That matters for motivation - especially as we head into the home stretch of the foundations course.

What's Coming in Week 6: String Methods & File Handling

So far all our data has lived inside the program. We type it in, it disappears when the program ends.

Week 6 changes that — we read data from files. Real files. CSV files:

with open("students.csv", "r") as file:
    for line in file:
        print(line.strip())

name,course,score
Amina,Data Engineering,88
Brian,Data Science,74
Njeri,Data Engineering,91

A file full of student records - read into Python, processed with loops and dictionaries, results written back out. For the Data Engineering students, this is the beginning of pipelines. For the Data Science students, this is the step right before Pandas.

One session away. See you then.

Try It Yourself

Download Python 3
Download VS Code
This week's code on GitHub ← link coming soon

Start with the M-Pesa transaction analyser - it uses all four structures and will tell you immediately which concepts need more practice.

Python Week 4: We Taught Python to Remember Things (Functions!)

Navas Herbert — Sun, 07 Jun 2026 11:03:39 +0000

I opened this session by pulling up a student's code from Week 3.

It was good work - loops, conditionals, everything working correctly. But one thing stood out. The grade calculation logic appeared three times. In three different places. Word for word identical.

I put it on the screen without saying anything. Let the class look at it.

"What's wrong with this code?" I asked.

Silence. Then Brian said: "It's... the same thing written three times?"

Exactly. And that's the problem functions solve.

The DRY Principle: Don't Repeat Yourself

Before any code, I wrote three letters on the board: DRY.

Don't Repeat Yourself.

It's one of the oldest rules in programming. If you're writing the same logic in more than one place, something is wrong. What happens when the logic needs to change? You have to find every copy and update them all. Miss one, and your program behaves differently in different places. That's how bugs are born.

Functions are the solution. You write the logic once, give it a name, and call it by that name whenever you need it.

Your First Function

The syntax is straightforward:

def greet():
    print("Habari! Welcome to the system.")

greet()
greet()
greet()

Habari! Welcome to the system.
Habari! Welcome to the system.
Habari! Welcome to the system.

def tells Python: I'm about to define a function.
The name (greet) is what you'll use to call it later.
The colon and indented block is the function body — the code that runs every time you call it.

Simple. But not very useful yet - it does the same thing every time. That's where parameters come in.

Parameters: The Ingredients You Swap Out

My analogy for functions: a recipe card. You write the recipe once - the steps, the method, the timing. But the ingredients can change. Chapati with butter. Chapati with jam. Same recipe, different inputs.

Parameters are the ingredients:

def greet(name):
    print(f"Habari {name}! Welcome to the system.")

greet("Amina")
greet("Otieno")
greet("Wanjiku")

Habari Amina! Welcome to the system.
Habari Otieno! Welcome to the system.
Habari Wanjiku! Welcome to the system.

One function. Three different results. The name changes - the recipe doesn't.

Multiple parameters work exactly as you'd expect:

def introduce(name, course, city):
    print(f"Name: {name} | Course: {course} | From: {city}")

introduce("Brian", "Data Engineering", "Mombasa")
introduce("Njeri", "Data Science", "Nairobi")

Name: Brian | Course: Data Engineering | From: Mombasa
Name: Njeri | Course: Data Science | From: Nairobi

return: The Dish That Comes Out

Here's where a lot of beginners get confused - and I was deliberate about this moment.

There's a big difference between a function that prints something and a function that returns something.

# This function prints - you can see the result, but can't USE it
def add_print(a, b):
    print(a + b)

# This function returns - you get the result back to work with
def add_return(a, b):
    return a + b

Watch what happens when you try to use each one:

result1 = add_print(3, 4)    # prints 7
result2 = add_return(3, 4)   # gives back 7

print(result1)   # None — print() gives nothing back
print(result2)   # 7 — return gives the value back

7
None
7

That None caused a proper reaction. "Why is it None?!"

Because print() is a one-way announcement - it shows something on screen and gives you nothing back. return hands the value back to whoever called the function, so you can store it, add to it, pass it to another function.

Rule of thumb I gave them: if you need to do something with the result later - use return. If you just need to display it - print() is fine.

Now the grade calculator from the teaser made full sense:

def calculate_grade(score):
    if score >= 80:
        return "A"
    elif score >= 70:
        return "B"
    elif score >= 60:
        return "C"
    elif score >= 50:
        return "D"
    else:
        return "F"

# Now we can USE the result
score = 74
grade = calculate_grade(score)
print(f"Score: {score} → Grade: {grade}")

# Or pass it directly into another function
print(f"Kamau's grade: {calculate_grade(88)}")
print(f"Aisha's grade: {calculate_grade(43)}")

Score: 74 → Grade: B
Kamau's grade: A
Aisha's grade: F

And just like that, Brian's three repeated grade blocks became one clean function called three times. His code got shorter. More importantly, it got trustworthy.

Scope: The Moment That Broke Everyone

I knew this was coming. It happens every cohort.

A student - Njeri this time - wrote a function, defined a variable inside it, then tried to use that variable outside the function. And got an error.

def calculate_total(price, quantity):
    total = price * quantity   # total is created inside the function
    return total

calculate_total(250, 3)
print(total)   # NameError - total doesn't exist out here

NameError: name 'total' is not defined

"But I just calculated it?!"

Yes , inside the function. Variables created inside a function live inside the function. When the function finishes, they disappear. This is called scope.

The analogy: a function is like a separate room. What happens in that room, stays in that room. If you want something to come out, you have to hand it through the door — which is what return does.

result = calculate_total(250, 3)   # catch what comes through the door
print(result)                       # now you have it

Once the room analogy landed, scope clicked for everyone. A variable inside a function is local , it only exists in that room. A variable defined outside, at the top level, is global , accessible everywhere.

Default Arguments: When Some Ingredients Are Optional

Sometimes you want a function to have a sensible default behaviour, but still let the caller override it if they want.

def send_sms(recipient, message, sender="Lux Systems"):
    print(f"To: {recipient}")
    print(f"From: {sender}")
    print(f"Message: {message}")
    print("---")

# Use the default sender
send_sms("Amina", "Your results are ready.")

# Override the default
send_sms("Brian", "Staff meeting at 3pm.", sender="HR Department")

To: Amina
From: Lux Systems
Message: Your results are ready.
---
To: Brian
From: HR Department
Message: Staff meeting at 3pm.
---

One rule: default parameters always go at the end. You can't have a default parameter before a regular one - Python won't know which is which.

*args: Wait, Unlimited Arguments?

This one earned the best reaction of the session.

What if you don't know in advance how many values someone will pass to your function? *args handles it:

def calculate_total(*prices):
    total = 0
    for price in prices:
        total += price
    return total

print(calculate_total(50))                    # one item
print(calculate_total(50, 120, 75))           # three items
print(calculate_total(200, 450, 30, 75, 90))  # five items

50
245
845

"Wait - the same function works for any number of inputs?!"

Yes. *args collects everything passed in and gives it to you as a tuple you can loop through. You don't have to know in advance how many there will be.

A practical example - a receipt generator that handles any number of items:

def print_receipt(customer, *items):
    print(f"\n=== Receipt for {customer} ===")
    total = 0
    for item, price in items:
        print(f"  {item}: KES {price}")
        total += price
    print(f"  ---------------")
    print(f"  TOTAL: KES {total}")

print_receipt(
    "Wanjiku",
    ("Unga 2kg", 180),
    ("Sukari 1kg", 130),
    ("Mafuta 500ml", 95)
)

=== Receipt for Wanjiku ===
  Unga 2kg: KES 180
  Sukari 1kg: KES 130
  Mafuta 500ml: KES 95
  ---------------
  TOTAL: KES 405

We Built This Together: Student Report Generator

The session project — combining everything: parameters, return, default arguments, loops:

def calculate_average(scores):
    return sum(scores) / len(scores)

def get_grade(average):
    if average >= 80:
        return "A"
    elif average >= 70:
        return "B"
    elif average >= 60:
        return "C"
    elif average >= 50:
        return "D"
    else:
        return "F"

def print_report(name, scores, school="Lux Academy"):
    average = calculate_average(scores)
    grade = get_grade(average)

    print(f"\n{'='*35}")
    print(f"  {school}")
    print(f"  Student Report")
    print(f"{'='*35}")
    print(f"  Name:    {name}")
    print(f"  Scores:  {scores}")
    print(f"  Average: {average:.1f}")
    print(f"  Grade:   {grade}")
    print(f"{'='*35}")

print_report("Kamau Njoroge", [78, 85, 90, 72, 88])
print_report("Aisha Mwangi", [55, 62, 48, 70, 59])
print_report("Baraka Odhiambo", [91, 88, 95, 97, 92], school="Greenwood Academy")

===================================
  Lux Academy
  Student Report
===================================
  Name:    Kamau Njoroge
  Scores:  [78, 85, 90, 72, 88]
  Average: 82.6
  Grade:   A
===================================

===================================
  Lux Academy
  Student Report
===================================
  Name:    Aisha Mwangi
  Scores:  [55, 62, 48, 70, 59]
  Average: 58.8
  Grade:   D
===================================

===================================
  Greenwood Academy
  Student Report
===================================
  Name:    Baraka Odhiambo
  Scores:  [91, 88, 95, 97, 92]
  Average: 92.6
  Grade:   A
===================================

When this ran cleanly, the room went quiet for a second - then someone said "that looks like actual software."

That's the moment. Functions calling functions, clean output, reusable logic. That's not a tutorial exercise anymore. That's the beginning of how real programs are built.

Practice Problems

Easy:

# 1. Write a function that takes a name and prints a welcome message
# 2. Write a function that takes two numbers and returns the larger one
# 3. Write a function that takes a score and returns "Pass" or "Fail" (pass mark: 50)

Medium:

# M-Pesa transaction fee calculator
# Safaricom charges different fees based on amount sent (simplified):
# KES 1 – 100      → KES 0 (free)
# KES 101 – 500    → KES 7
# KES 501 – 1000   → KES 13
# KES 1001 – 5000  → KES 28
# Above 5000       → KES 52

def calculate_mpesa_fee(amount):
    # Your code here
    pass

print(calculate_mpesa_fee(250))    # should return 7
print(calculate_mpesa_fee(1500))   # should return 28
print(calculate_mpesa_fee(80))     # should return 0

Challenge:

# Build a complete BMI calculator with interpretation
# Formula: BMI = weight(kg) / height(m)²
# Underweight: BMI < 18.5
# Normal: 18.5 – 24.9
# Overweight: 25 – 29.9
# Obese: BMI >= 30

def calculate_bmi(weight, height):
    pass

def interpret_bmi(bmi):
    pass

def bmi_report(name, weight, height):
    pass  # Call both functions above and print a clean report

bmi_report("Njeri", 58, 1.65)

What I Noticed Teaching This Session

1. The DRY reveal works best with their own code. Showing a student their own repeated logic - not a made-up example - makes the problem feel real and personal. It's not abstract. It's their code that needs fixing.

2. print vs return is the most important distinction in this session. Don't rush it. The None moment - where a student expects a value and gets nothing - is the best teacher. Engineer it deliberately.

3. Scope clicks fastest with a physical analogy. The "separate room" analogy for local scope worked better than any code-first explanation. Give the analogy, then show the code, then show the error. In that order.

4. Functions calling functions is a mindset shift. When students saw print_report call calculate_average and get_grade internally, something shifted. Programs stopped being a list of instructions and started feeling like a system of parts. That's the beginning of thinking like a software developer.

What's Coming in Week 5: Data Structures

So far every variable we've worked with holds one thing. One name. One score. One balance.

Week 5 changes that entirely:

# A list - ordered, changeable
scores = [78, 45, 92, 61, 88]

# A dictionary - look things up by name
student = {
    "name": "Amina",
    "course": "Data Engineering",
    "score": 92
}

print(student["name"])    # Amina
print(scores[2])          # 92

One variable. Multiple values. And when you combine these with the functions we just learned - you're building real data structures. That's next week.

Try It Yourself

Download Python 3
Download VS Code
This week's code on GitHub ← link coming soon

Start with the M-Pesa fee calculator — it's a real-world function with clear inputs, clear outputs, and conditions you can verify. If it passes all three test cases, you've got functions figured out.

Python Week 2: We Taught Python to Make Decisions

Navas Herbert — Mon, 25 May 2026 20:41:39 +0000

Last week, our programs were polite but passive. They'd take your name, store your age, print a receipt - but they couldn't respond to what you gave them. Every program ended the same way no matter what you typed.

This week, that changed.

Week 2 was about teaching Python to think. Or at least, to choose. We covered operators and conditionals - the building blocks that let a program look at a value and say: "based on this, I'll do one thing and not another."

It sounds small. It's not.

First: Operators - Asking Python Yes/No Questions

Before any if statement, students needed to understand comparison operators - the tools Python uses to evaluate whether something is true or false.

I framed it simply: an operator is just a question you ask Python. It always answers yes or no.

age = 20

print(age > 18)     # Is age greater than 18?
print(age == 20)    # Is age exactly 20?
print(age != 25)    # Is age NOT 25?
print(age >= 18)    # Is age 18 or older?
print(age <= 15)    # Is age 15 or younger?

True
True
True
True
False

Clean. Simple. Everyone got it immediately.

Then came the mistake I wait for every single cohort.

The Mistake Everyone Makes Exactly Once

age = 20

if age = 18:
    print("You are exactly 18")

SyntaxError: invalid syntax

"But I used equals?"

Right. And that's the problem. In Python, = means "store this value". == means "are these the same?" They look almost identical. They do completely different things.

age = 20          # ASSIGNMENT — put 20 in the box called age
age == 20         # COMPARISON — is age the same as 20? (True/False)

I told them: you will make this mistake. It will confuse you. You will stare at it for two minutes. Then you'll see the missing = and feel silly. That's normal. It happens to everyone, including people who've been coding for ten years.

After that, they started double-checking their equals signs. Good habit, hard-earned.

Logical Operators: Combining Questions

Sometimes one question isn't enough. We covered and, or, and not:

age = 22
has_id = True

# AND — both conditions must be True
if age >= 18 and has_id:
    print("Welcome in.")
else:
    print("Sorry, not tonight.")

Welcome in.

The analogy I used: a bouncer at a club in Westlands. They check your age and your ID. One isn't enough - both conditions have to pass or you're not getting in. and is the strict bouncer.

or is more relaxed:

is_student = False
has_discount_card = True

if is_student or has_discount_card:
    print("Discounted fare: KES 30")
else:
    print("Full fare: KES 50")

Discounted fare: KES 30

And not simply flips the answer:

is_raining = False

if not is_raining:
    print("No umbrella needed today.")

No umbrella needed today.

if / elif / else: The Decision Tree

Now the main event.

The structure is straightforward once you see it as a sequence of questions Python asks in order - stopping as soon as one is true:

score = 74

if score >= 80:
    print("Grade: A")
elif score >= 70:
    print("Grade: B")
elif score >= 60:
    print("Grade: C")
elif score >= 50:
    print("Grade: D")
else:
    print("Grade: F - please see your teacher")

Grade: B

Key rule I drilled in: Python checks from top to bottom and stops at the first True condition. It doesn't check the rest. This matters when conditions overlap:

score = 85

# WRONG — overlapping conditions, wrong order
if score >= 50:
    print("Grade: D")   # This fires for 85! Python stops here.
elif score >= 80:
    print("Grade: A")   # Never reached

Grade: D

Someone in the room got this wrong on their first attempt - which was exactly what I needed. We looked at the output together, traced through the logic, and found the bug. That exercise is worth more than five explanations.

The Moment That Got Everyone: The M-Pesa Checker

At the end of Week 1, I teased this program. This week we actually built it.

balance = float(input("Enter your M-Pesa balance (KES): "))

if balance >= 1000:
    print("✅ You're good. Send that money.")
elif balance >= 100:
    print("⚠️  Low balance — top up soon.")
elif balance > 0:
    print("❌ Very low. You can barely send a text.")
else:
    print("💀 Broke. Completely broke.")

One student - Otieno - typed 0 and got the last message. He laughed so hard the whole room started laughing. Then someone else typed their actual balance just to see what Python would tell them.

That's the moment. When the program stops being an exercise and becomes something they interact with. When they're not running code — they're using software.

After that, everyone wanted to build their own version.

Nested Conditions: An If Inside an If

Once students were comfortable with basic if/elif/else, we pushed further — what if the decision has layers?

age = int(input("Enter your age: "))
has_ticket = input("Do you have a ticket? (yes/no): ")

if age >= 18:
    if has_ticket == "yes":
        print("Enjoy the show! 🎬")
    else:
        print("You're old enough, but you need a ticket first.")
else:
    print("Sorry - this show is 18+.")

Enter your age: 22
Do you have a ticket? (yes/no): yes
Enjoy the show! 🎬

"You can put an if inside an if?"

Yes. And you can put one inside that one too - though I warned them: deeply nested conditions are a code smell. If you're four levels deep, step back and rethink. For now, two levels is fine.

We Built This Together: Matatu Fare Calculator

The session project. Students built this step by step, from scratch:

print("=== Nairobi Matatu Fare Calculator ===")

distance = float(input("Distance in km: "))
is_peak_hour = input("Is it peak hour? (yes/no): ")

# Base fare calculation
if distance <= 5:
    fare = 50
elif distance <= 15:
    fare = 100
elif distance <= 30:
    fare = 150
else:
    fare = 200

# Peak hour surcharge
if is_peak_hour == "yes":
    fare = fare * 1.5
    print(f"Peak hour surcharge applied.")

print(f"\nDistance: {distance} km")
print(f"Total fare: KES {fare:.0f}")

=== Nairobi Matatu Fare Calculator ===
Distance in km: 12
Is it peak hour? (yes/no): yes
Peak hour surcharge applied.

Distance: 12.0 km
Total fare: KES 150

What I loved about this exercise: students had to think about the real world to write correct code. What counts as peak hour? What if someone enters a negative distance? What if they type "YES" instead of "yes"? Those questions came up naturally - and they're exactly the kind of edge-case thinking that makes a good programmer.

Practice Problems

Try these yourself:

Easy:

# 1. Ask the user for a number. Print whether it's positive, negative, or zero.
# 2. Ask for two numbers. Print which one is larger (or "they're equal").
# 3. Ask for a temperature in Celsius. Print "Hot" if above 30, "Cold" if below 15, "Comfortable" otherwise.

Medium:

# A simple login checker
username = input("Enter username: ")
password = input("Enter password: ")

# Expected: username = "admin", password = "1234"
if username == "admin" and password == "1234":
    print("✅ Access granted. Welcome.")
elif username == "admin":
    print("❌ Wrong password.")
else:
    print("❌ Username not found.")

Challenge:

# Build a simple NHIF contribution calculator
# Rules (simplified):
# Gross salary < 5,999 → KES 150
# 6,000 – 7,999 → KES 300  
# 8,000 – 11,999 → KES 400
# 12,000 – 14,999 → KES 500
# 15,000 and above → KES 600

salary = float(input("Enter gross monthly salary (KES): "))
# Your if/elif/else here...

What I Noticed Teaching This Session

1. The = vs == error is a rite of passage - let it happen. Don't pre-warn students so much that they never make the mistake. Making it, reading the error, and fixing it themselves is how it sticks.

2. Real-world stakes make conditions more fun. The M-Pesa checker worked because students had an emotional relationship with their balance. Abstract exercises like if x > 5 don't carry that. Always anchor the condition in something that matters to them.

3. Students naturally found edge cases. Once they built the matatu calculator, they immediately started trying to break it — negative distances, letters instead of numbers. That curiosity is the beginning of a testing mindset. Don't discourage it.

4. elif takes a minute to click. A few students kept writing separate if statements instead of elif. I had to show them what goes wrong - multiple conditions firing for the same input - before they understood why elif exists.

I'm a data trainer in Nairobi running a full data programme —
Python foundations → Data Science or Data Engineering specialisations.
I write weekly about what we covered, what worked, and what surprised me.
Follow along or drop your questions in the comments.

Python Week 3: We Stopped Repeating Ourselves (Loops!)

Navas Herbert — Mon, 25 May 2026 20:22:12 +0000

I started this session with a challenge.

"Jose," I said, "print the names of all 40 students in this dataset - one per line."

He looked at me. Then at his keyboard. Then started typing print("Amina").

I let him get to the third name before I stopped him.

"What if there were 10,000 students?"

Silence.

"What if the list changed every week?"

More silence.

That's the setup for loops. You don't teach loops by explaining them - you first make people feel the pain of not having them. Then the solution lands differently.

The for Loop: Working Through a List

The for loop is Python's way of saying: go through every item in this collection and do something with each one.

My analogy: a class register. The teacher calls each name in order, marks attendance, moves to the next. They don't skip anyone. They don't stop early. They go through the whole list.

students = ["Amina", "Brian", "Njeri", "Kamau", "Wanjiku"]

for student in students:
    print(f"Good morning, {student}! 👋")

Good morning, Amina! 👋
Good morning, Brian! 👋
Good morning, Njeri! 👋
Good morning, Kamau! 👋
Good morning, Wanjiku! 👋

Five names. One loop. If the list had 10,000 names, same code - still works.

Jose closed his half-written print() statements and deleted them. That reaction is why I love teaching this session.

range(): Counting Without a List

Sometimes you don't have a list of items - you just want to repeat something a specific number of times. That's what range() is for.

for i in range(5):
    print(f"Attempt {i + 1}")

Attempt 1
Attempt 2
Attempt 3
Attempt 4
Attempt 5

Then came the question I wait for every cohort.

"Why does range(5) go from 0 to 4? Why not 1 to 5?"

Because Python counts like a programmer - starting from zero. range(5) means "give me 5 numbers starting at 0" - so 0, 1, 2, 3, 4.

If you want 1 to 5, you tell it explicitly:

for i in range(1, 6):
    print(i)

You can even count in steps:

# Count in 10s - like a matatu filling up every 10km
for km in range(0, 51, 10):
    print(f"Distance covered: {km} km")

Distance covered: 0 km
Distance covered: 10 km
Distance covered: 20 km
Distance covered: 30 km
Distance covered: 40 km
Distance covered: 50 km

Doing Real Work Inside a Loop

A loop is only useful if you do something meaningful inside it. We levelled up from printing names to processing data:

scores = [78, 45, 92, 61, 55, 88, 34, 73]
total = 0

for score in scores:
    total = total + score

average = total / len(scores)
print(f"Class average: {average:.1f}")

Class average: 65.8

Then we added a conditional inside the loop - finding students who failed:

scores = [78, 45, 92, 61, 55, 88, 34, 73]

print("Students who need support:")
for i in range(len(scores)):
    if scores[i] < 50:
        print(f"  Student {i + 1}: scored {scores[i]} - below pass mark")

Students who need support:
  Student 2: scored 45 - below pass mark
  Student 7: scored 34 - below pass mark

This is where students started to see it. A loop plus a conditional is already a mini data pipeline. You're iterating through records, applying a rule, flagging what matters.

The while Loop: Keep Going Until Something Changes

The for loop goes through a fixed collection. The while loop is different - it keeps running as long as a condition is true, and you don't always know in advance how many times that will be.

My analogy: a matatu waiting at the stage. It doesn't leave after a fixed number of passengers - it waits until it's full. While there's space, keep accepting passengers.

passengers = 0
capacity = 14

while passengers < capacity:
    passengers += 1
    print(f"Passenger {passengers} boards. Seats remaining: {capacity - passengers}")

print("Matatu is full. Twende!")

Passenger 1 boards. Seats remaining: 13
Passenger 2 boards. Seats remaining: 12
...
Passenger 14 boards. Seats remaining: 0
Matatu is full. Twende!

A more practical use - a simple login system that keeps asking until you get it right:

password = "lux2024"
attempts = 0

while True:
    entry = input("Enter password: ")
    attempts += 1

    if entry == password:
        print(f"✅ Access granted after {attempts} attempt(s).")
        break
    else:
        print("❌ Wrong password. Try again.")

Enter password: wrongpass
❌ Wrong password. Try again.
Enter password: lux2024
✅ Access granted after 2 attempt(s).

The Infinite Loop Nobody Saw Coming

This was the moment of the session.

One student - Aisha - was building the login checker and forgot the break. Her loop just kept asking for the password. Forever. Her laptop stopped responding to anything else.

"How do I stop it?!"

Ctrl + C. Always Ctrl + C.

She pressed it. The program stopped. The room exhaled.

I told everyone to write Ctrl + C at the top of their notes and circle it. It's the emergency exit for every infinite loop - and you will need it at some point. Better to learn it when Aisha accidentally teaches you than when you're alone at midnight wondering why your computer is hot.

The lesson from Aisha's loop: every while True must have a break inside it. Without a way out, the loop runs until you force-quit the program or your laptop gives up.

break and continue: Taking Control of the Loop

Once students understood that loops run to completion, I showed them two ways to interrupt that:

break - stop the loop entirely and exit:

# Search for a student in the register
register = ["Amina", "Brian", "Njeri", "Kamau", "Wanjiku"]
target = "Njeri"

for student in register:
    if student == target:
        print(f"Found {target}! ✅")
        break   # No need to keep searching
    print(f"Checking {student}...")

Checking Amina...
Checking Brian...
Found Njeri! ✅

continue - skip this item and move to the next one:

# Print all scores, but skip anyone who was absent (score = 0)
scores = [78, 0, 92, 0, 55, 88]

for score in scores:
    if score == 0:
        continue   # Skip absent students
    print(f"Score: {score}")

Score: 78
Score: 92
Score: 55
Score: 88

The analogy that landed for continue: a teacher calling the register and the student is absent. You don't stop the whole class - you just say "absent" and move to the next name.

Nested Loops: A Loop Inside a Loop

I saved this for the end - the concept that always gets a dramatic reaction.

# Multiplication table (3x3 preview)
for i in range(1, 4):
    for j in range(1, 4):
        print(f"{i} x {j} = {i * j}")
    print("---")

1 x 1 = 1
1 x 2 = 2
1 x 3 = 3
---
2 x 1 = 2
2 x 2 = 4
2 x 3 = 6
---
3 x 1 = 3
3 x 2 = 6
3 x 3 = 9
---

"The outer loop runs - and every time it does, the inner loop runs all the way through."

You could see people mentally tracing the logic. I gave them a minute to sit with it before moving on. Some concepts need a moment, not a faster explanation.

A practical example - checking every student against every subject:

students = ["Amina", "Brian", "Njeri"]
subjects = ["Maths", "English", "Science"]

for student in students:
    for subject in subjects:
        print(f"{student} → {subject}")
    print()

Amina → Maths
Amina → English
Amina → Science

Brian → Maths
Brian → English
Brian → Science

Njeri → Maths
Njeri → English
Njeri → Science

Practice Problems

Easy:

# 1. Print numbers 1 to 20 using a for loop and range()
# 2. Print only even numbers between 1 and 30
# 3. Loop through this list and print each item in uppercase:
#    groceries = ["unga", "sukari", "mafuta", "chumvi"]

Medium:

# A simple ATM PIN checker - give the user 3 attempts
correct_pin = "4821"
attempts = 0
max_attempts = 3

while attempts < max_attempts:
    pin = input("Enter your PIN: ")
    attempts += 1

    if pin == correct_pin:
        print("PIN accepted. Welcome.")
        break
    else:
        remaining = max_attempts - attempts
        if remaining > 0:
            print(f"Wrong PIN. {remaining} attempt(s) left.")
        else:
            print("Account locked. Please visit your branch.")

Challenge:

# Sales summary - loop through a list of daily sales,
# calculate total, find the highest day, count days below target

daily_sales = [12400, 8750, 15200, 6300, 19800, 11050, 9400]
target = 10000

# Your code here:
# 1. Total sales for the week
# 2. Best day (highest sales)
# 3. How many days missed the target

What I Noticed Teaching This Session

1. The pain-first setup works every time. Making Jose start writing 40 print() statements - even for just 3 names - made the loop feel like a rescue, not a concept.

2. Aisha's infinite loop was the best teaching moment of the week. An accident in front of the class, handled calmly, teaches Ctrl + C and loop safety more effectively than any slide ever could. I didn't plan it. I didn't need to.

3. Students started thinking like data people. When we looped through scores and flagged students below 50, someone said: "This is basically filtering - like SQL WHERE." That connection was electric. That's exactly what it is.

4. break and continue need contrast to make sense. Showing them without break (loop continues past the found item) before showing with break made the difference immediately visible.

What's Coming in Week 4: Functions

Right now our programs do things — but they can't remember how to do them. If we need to calculate a grade three times in different places, we write the logic three times. That's wrong.

Functions fix this:

def calculate_grade(score):
    if score >= 80:
        return "A"
    elif score >= 70:
        return "B"
    elif score >= 60:
        return "C"
    elif score >= 50:
        return "D"
    else:
        return "F"

print(calculate_grade(85))   # A
print(calculate_grade(62))   # C
print(calculate_grade(41))   # F

Write it once. Use it anywhere. That's next week.

Try It Yourself

Download Python 3
Download VS Code
This week's code on GitHub ← link coming soon

Start with the ATM PIN checker - it combines everything from Week 2 (conditionals) and Week 3 (while loops). If that runs cleanly, you're ready for functions.

We Switched From SQL to Python - Here's How Week 1 Went

Navas Herbert — Tue, 19 May 2026 19:14:34 +0000

Students just finished a full SQL journey - JOINs, window functions, CTEs, a hotel capstone dataset. They were dangerous with PostgreSQL. Confident. A little smug, even.

Then I told them we were switching to Python.

The energy in the room shifted. SQL felt structured - you ask a question, the table talks back. Python felt like a blank page. No table. No schema. Just a cursor blinking at you.

Week 1 was about changing that feeling. Here's exactly what we did.

First Question I Asked the Room

Before touching a keyboard, I asked everyone: "What do you think code actually is?"

Answers ranged from "instructions for a computer" to "I have no idea but it looks scary in movies."

Here's what I told them:

Code is just a very precise way of talking to a computer. The computer is not smart - it does exactly what you say, nothing more. Your job as a programmer is to be clear enough that it doesn't get confused.

That framing - the computer is not smart, you have to be precise - removes a lot of the intimidation. You're not learning to be a genius. You're learning to communicate clearly.

Setting Up: Python + VS Code

We installed Python 3 and VS Code. This part takes longer than it should with a full class (there's always one laptop that does something unexpected), but we got everyone running.

First file. First line of code:

print("Hello, Nairobi!")

Output:

Hello, Nairobi!

Simple. Silly, even. But I could see people smile when their computer actually said something back. That moment matters more than people realise - it's the first time the machine responds to them.

Variables: The Labelled Box Analogy

The first real concept: variables.

My analogy: imagine a variable is a labelled box. You put something inside the box, you write a name on the outside, and later you can pick up the box by its name and use whatever's inside.

name = "Amina"
age = 25
city = "Nairobi"

print(name)   # Amina
print(age)    # 25
print(city)   # Nairobi

Then we showed them that the box can be updated - the label stays the same but the content changes:

score = 40
print(score)   # 40

score = 85
print(score)   # 85

Someone asked: "So the old value just disappears?" Exactly. The box only holds one thing at a time. The new value replaces the old one.

Data Types: Not All Boxes Are The Same

Here's where it gets interesting. Python cares about what kind of thing you put in the box. We covered the four core types:

Type	Example	What it is
`int`	`42`	Whole numbers
`float`	`3.14`	Decimal numbers
`str`	`"Amina"`	Text (always in quotes)
`bool`	`True` / `False`	Yes or no — that's it

students = 30          # int
average_score = 74.5   # float
school_name = "Lux Academy"  # str
is_open = True         # bool

print(type(students))     # <class 'int'>
print(type(average_score))  # <class 'float'>
print(type(school_name))  # <class 'str'>
print(type(is_open))      # <class 'bool'>

The type() function became a favourite immediately. Students started wrapping everything in it just to check. Good habit, honestly.

The Mistake That Catches Everyone (And I Mean Everyone)

Mixing types without converting them first. This one gets everybody:

age = input("How old are you? ")
next_year = age + 1
print(next_year)

Error:

TypeError: can only concatenate str (not "int") to "str"

The confusion on their faces was real. "But I typed a number!"

Here's the thing: input() always returns a string, even if the user types 25. Python received the text "25", not the number 25. You have to tell it explicitly to treat it as a number:

age = int(input("How old are you? "))
next_year = age + 1
print("Next year you will be", next_year)

Output (if user types 25):

Next year you will be 26

This lesson - Python doesn't assume, you have to be explicit - is one of the most important mindset shifts for beginners. And once they've hit this error, they never forget it.

Type Conversion: Speaking Python's Language

We covered the three conversion tools they'll use constantly:

# String to integer
price_text = "250"
price = int(price_text)
print(price + 50)    # 300

# String to float
weight_text = "72.5"
weight = float(weight_text)
print(weight * 2)    # 145.0

# Number to string (for building sentences)
items = 5
message = "You have " + str(items) + " items in your cart"
print(message)       # You have 5 items in your cart

The last one - str() for building messages - connected immediately because we also introduced f-strings as a cleaner alternative:

name = "Brian"
balance = 4500
print(f"Hey {name}, your M-Pesa balance is KES {balance}")

Output:

Hey Brian, your M-Pesa balance is KES 4500

f-strings are technically Session 6 material but the students loved them so much I let it slide. Sometimes you follow the energy.

input(): Making Programs Interactive

input() is where things start feeling like actual software.

name = input("What is your name? ")
print(f"Welcome to the system, {name}!")

We built a small interactive program on the spot - a basic student registration prompt:

name = input("Enter student name: ")
age = int(input("Enter age: "))
course = input("Enter course: ")

print("--- Student Record ---")
print(f"Name:   {name}")
print(f"Age:    {age}")
print(f"Course: {course}")

Sample Run:

Enter student name: Wanjiku
Enter age: 23
Enter course: Data Engineering

--- Student Record ---
Name:   Wanjiku
Age:    23
Course: Data Engineering

This was the session highlight. Students went from writing print("Hello") to building something that takes input and structures a response - in one session. The room felt different after that exercise.

Practice Problems We Ran

A few of the exercises we worked through - try them yourself:

Easy:

# 1. Store your name, age, and city in variables. Print them.
# 2. Ask the user for two numbers and print their sum.
# 3. Use type() to check what type "3.14" is before and after float() conversion.

Medium:

# A kiosk receipt printer - ask for item name and price, print a formatted receipt
item = input("Item name: ")
price = float(input("Price (KES): "))
quantity = int(input("Quantity: "))

total = price * quantity
print(f"\n--- Receipt ---")
print(f"Item:     {item}")
print(f"Price:    KES {price}")
print(f"Qty:      {quantity}")
print(f"Total:    KES {total}")

Challenge:

# Temperature converter - ask user for Celsius, convert to Fahrenheit and Kelvin
celsius = float(input("Enter temperature in Celsius: "))
fahrenheit = (celsius * 9/5) + 32
kelvin = celsius + 273.15

print(f"{celsius}°C = {fahrenheit}°F = {kelvin}K")

What I Noticed Teaching This Session

The SQL background helped more than I expected. Students who came from our SQL class already understood the idea of data having types - a VARCHAR column vs an INT column. Python's str and int felt familiar. That prior context is genuinely useful.

input() is the best motivator at this stage. The second a program asks them a question and responds to their answer, it stops feeling like a tutorial and starts feeling like real software. Use it early and often.

The TypeError from input() is a gift. Don't avoid it -engineer it. Make students hit that error deliberately, read it, understand it, and fix it themselves. Error messages are information, not judgement.

What's Coming in Week 2

Next session: operators and conditionals. We'll teach Python to make decisions - if, elif, else - and build programs that respond differently depending on the input.

A little teaser for the students:

balance = float(input("Enter your M-Pesa balance: "))

if balance >= 1000:
    print("You're good to send money.")
elif balance >= 100:
    print("Low balance — top up soon.")
else:
    print("Insufficient balance.")

Suddenly Python isn't just printing things - it's thinking. See you next week.

Try It Yourself

All you need to follow along:

Download Python 3
Download VS Code
Create a file called week1.py, paste any example above, and run it

No setup complexity. No cloud accounts. Just Python and a text editor.

I'm a data trainer in Nairobi running a full data programme - Python foundations → Data Science or Data Engineering specialisations. I write weekly about what we covered, what worked, and what surprised me. Follow along or drop your questions in the comments , especially if you're teaching or learning Python from scratch.

I Taught SQL to Complete Beginners: Here's What Actually Happened

Navas Herbert — Sat, 16 May 2026 10:49:20 +0000

Let me set the scene.

A room full of people who had never written a single line of SQL in their lives. Some came from accounting. Some from operations. One person told me they still used Excel to track hospital records manually. And they were all looking at me like I was about to teach them magic.

Honestly? I kind of was.

This is my retrospective on our SQL journey - what we covered, what broke people's brains (in a good way), and the moments I realised teaching this stuff is genuinely one of the most fun things I do.

Where We Started: "What Even Is a Database?"

Before I could show anyone a SELECT statement, I had to answer the most fundamental question first: why does this exist?

My go-to analogy: a database is like a very organised filing cabinet. Each drawer is a table. Each folder inside the drawer is a row. Each label on the folder is a column. SQL is just the language you use to ask the filing cabinet questions.

Once that clicked, the first query felt almost anticlimactic - in a good way.

SELECT first_name, last_name
FROM students
WHERE grade = 'A';

"Wait… that's it?" Yes. That's it. The magic is in building from there.

Week 1: The Foundation (And the First Confused Faces)

We started with the basics - SELECT, WHERE, ORDER BY, GROUP BY, HAVING. We used a school dataset called Nairobi Academy (fictional Nairobi school - felt very local and relatable) and a hospital dataset called City Hospital.

The moment that got everyone: understanding the difference between WHERE and HAVING.

-- WHERE filters rows BEFORE grouping
SELECT department, COUNT(*) AS total_staff
FROM employees
WHERE status = 'Active'
GROUP BY department;

-- HAVING filters AFTER grouping
SELECT department, COUNT(*) AS total_staff
FROM employees
GROUP BY department
HAVING COUNT(*) > 5;

I used the analogy of a matatu route: WHERE is the conductor deciding who even boards the matatu. HAVING is checking at the destination who actually made it the whole way. That one landed really well.

The Thing That Broke Everyone (In the Best Way): JOINs

I won't lie - JOINs are where beginner SQL classes either soar or crash. I've seen it go both ways.

We covered:

INNER JOIN - only rows that match in both tables
LEFT JOIN - all rows from the left, matched where possible
RIGHT JOIN - all rows from the right
SELF JOIN - a table joining itself (yes, this is a thing)
LEFT JOIN + IS NULL - finding orphaned records

The self-join is always the one that causes dramatic pauses.

-- "Who is each employee's manager?" - same table, different roles
SELECT 
    e.first_name AS employee,
    m.first_name AS manager
FROM employees e
LEFT JOIN employees m ON e.manager_id = m.employee_id;

"Wait… it's joining to itself?"

Yes. Yes it is. Welcome to SQL.

Window Functions: When SQL Starts Feeling Like a Superpower

This is the week I could see people's eyes light up.

Window functions let you do calculations across rows without collapsing them into a group. We covered ROW_NUMBER, RANK, DENSE_RANK, NTILE, running averages with AVG OVER, and time-travel queries with LAG and LEAD.

-- Rank students by score within each class
SELECT 
    student_name,
    class,
    score,
    RANK() OVER (PARTITION BY class ORDER BY score DESC) AS class_rank
FROM results;

And LAG - the one that made the data analysts in the room go quiet for a moment before saying "oh wow":

-- Compare this month's sales to last month's
SELECT 
    month,
    total_sales,
    LAG(total_sales) OVER (ORDER BY month) AS previous_month,
    total_sales - LAG(total_sales) OVER (ORDER BY month) AS difference
FROM monthly_sales;

No subquery. No join. Just clean, readable SQL. This is the moment people stop thinking of SQL as "just for pulling data" and start seeing it as an analytical tool.

CTEs: Writing SQL Like a Human Being

Before CTEs, students were writing nested subqueries that looked like abstract art. Beautiful in theory, impossible to read three days later.

Common Table Expressions (WITH ... AS) changed everything.

-- Find students who scored above the class average
WITH class_averages AS (
    SELECT class, AVG(score) AS avg_score
    FROM results
    GROUP BY class
)
SELECT r.student_name, r.class, r.score
FROM results r
JOIN class_averages ca ON r.class = ca.class
WHERE r.score > ca.avg_score;

The rule I drilled in: write your CTEs like you're telling a story. First set up your averages, then filter against them. Each CTE is a chapter.

Data Cleaning: Where Reality Hits

Every SQL class eventually gets to the uncomfortable truth: real data is messy. Dirty, inconsistent, full of rogue spaces and names typed in ALL CAPS at 4pm on a Friday.

We built a dedicated dirty dataset and went to town with:

-- Standardise names that arrived inconsistently
UPDATE employees
SET 
    first_name = INITCAP(TRIM(first_name)),
    last_name = INITCAP(TRIM(last_name));

-- Strip non-numeric characters from phone numbers
UPDATE contacts
SET phone = REGEXP_REPLACE(phone, '[^0-9]', '', 'g');

-- Fill in missing values rather than leaving NULLs
SELECT 
    COALESCE(department, 'Unassigned') AS department
FROM employees;

Golden rule we repeated every cleaning session: always run a SELECT first before an UPDATE or DELETE. See exactly what you're about to change. Only then pull the trigger.

The Capstone: Tembo Hotel

The final project was set in Tembo Hotel - a fictional Nairobi hotel with ~285 rows of genuinely messy booking data. Students worked in groups to clean it, analyse it, and answer real business questions:

Which room types generate the most revenue?
Which months have the highest no-show rates?
Who are our repeat guests?

Watching groups go from "this data is a disaster" to producing clean queries with CTEs and window functions across a few sessions was something else.

What I Learned Teaching This

A few honest takeaways from being on the teaching side:

1. Analogies are not optional. Every concept needs a real-world anchor before any code appears. If you skip the analogy and go straight to syntax, you lose half the room.

2. Local context matters more than I expected. Using Nairobi names, M-Pesa examples, matatu analogies - students were visibly more engaged when the data felt like their world.

3. PostgreSQL is the right call for beginners. Clean syntax, no shortcuts, no backtick weirdness. If you learn PostgreSQL first, everything else makes sense later.

4. The moment someone writes their first CTE that actually works, they look different. Slightly smug. Entirely justified.

What's Next?

SQL was the foundation. Now we've moved into Python - same students, same energy, new language. We're building toward a full data programme where they'll split into Data Science and Data Engineering tracks.

I'll be writing about that journey too. Follow along if you're building something similar, learning from scratch yourself, or just enjoy watching beginners turn into dangerous analysts one query at a time.

See you next week.

I'm a data engineer in Nairobi. I write weekly about what I'm teaching, what's working, and what surprised me in the classroom. If you're a fellow trainer or a self-taught analyst, let's talk in the comments.