DEV Community: Navas Herbert

SQL Filtering: The Five Operators That Let You Ask Smarter Questions

Navas Herbert — Mon, 13 Jul 2026 20:17:55 +0000

Last week we covered the core SQL keywords - SELECT, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT. Students could retrieve data, summarise it, sort it.

But there was a problem. Every WHERE clause we wrote used exactly one condition. price > 100. stock_level < 30. Clean, simple, single.

Real questions are never that simple.

"Show me all Dairy products that cost less than KES 70." That's two conditions. "Show me every product name that starts with the letter M." That's a pattern, not a value. "Show me products whose price is somewhere between 60 and 200 shillings." That's a range.

This session was about teaching how to ask those questions - and the five families of operators that make them possible.

The Dataset: Mama Nia's Duka

Same table we've been using all month - duka.duka_products. Mama Nia's shop. Products, categories, suppliers, prices, stock levels. A dataset that feels like a real place, which is exactly why the queries feel like real questions.

Five operator categories on the board before any code:

Category	Operators
Comparison	`=`, `!=`, `>`, `<`, `>=`, `<=`
Logical	`AND`, `OR`, `NOT`
Range	`BETWEEN`, `NOT BETWEEN`
Membership	`IN`, `NOT IN`
Search	`LIKE`, `ILIKE`

"By the end of today, you will use all five in the same query. Let's go one at a time."

Section 1: Comparison Operators - The Foundation

These are the ones students already half-know from mathematics. The only one that catches people is != - not equal to. The rest feel immediately natural.

Three examples, three different operators:

-- Example 1: Products above 150 shillings
SELECT product_name, price
FROM duka.duka_products
WHERE price > 150
ORDER BY price;

-- Example 2: Low on stock - less than or equal to 30 units
SELECT product_name, stock_level
FROM duka.duka_products
WHERE stock_level <= 30
ORDER BY stock_level;

-- Exact match
SELECT product_name
FROM duka.duka_products
WHERE price = 65.00;

I told the class: "Comparison operators are the vocabulary of filtering. Everything else we learn today uses these as building blocks."

The one worth pausing on: >= and <=. In English, "products with stock level 30 or below" translates directly to stock_level <= 30. The boundary value - 30 - is included. Students who meet BETWEEN later in the session sometimes forget that < alone excludes the boundary. A small distinction with meaningful consequences in inventory and financial queries.

Section 2: Logical Operators - AND, OR, NOT

AND - Both Must Be True

-- Dairy products that cost more than 70 shillings
SELECT product_name, product_category, price
FROM duka.duka_products
WHERE product_category = 'Dairy' AND price > 70;

AND is the strict filter. Both conditions must be true for a row to pass. Think of it as two bouncers at the door - the row has to get past both.

OR - At Least One Must Be True

-- Products that are either Beverages OR Household
SELECT product_name, product_category
FROM duka.duka_products
WHERE product_category = 'Beverages' OR product_category = 'Household';

OR is more relaxed. One condition being true is enough. The row passes if it satisfies either condition - or both.

NOT - Negate Everything

-- Everything that is NOT in Grains & Cereals
SELECT product_name, product_category
FROM duka.duka_products
WHERE NOT product_category = 'Grains & Cereals'
ORDER BY product_category;

NOT flips the result. Sometimes cleaner than writing the negative condition directly, especially when the positive condition is complex.

The Trap Nobody Sees Coming: AND Before OR

This is the moment of Section 2, and I engineer it deliberately every cohort.

PostgreSQL evaluates AND before OR - the same way multiplication happens before addition in mathematics. You learned BODMAS in school. SQL has its own version, and most beginners don't know it.

Here's the trap. Mama Nia wants Dairy products where price is either below KES 70 OR above KES 85:

-- WRONG — no parentheses
SELECT product_name, product_category, price
FROM duka.duka_products
WHERE product_category = 'Dairy' AND price < 70 OR price > 85;

This looks right. It isn't. SQL reads it as:

-- What PostgreSQL actually runs:
WHERE (product_category = 'Dairy' AND price < 70) OR price > 85

The AND binds first. The result: every product above KES 85 comes through — regardless of category - because the OR on the right has no category condition attached to it.

The fix is one pair of brackets:

-- CORRECT - parentheses group the OR together
SELECT product_name, product_category, price
FROM duka.duka_products
WHERE product_category = 'Dairy' AND (price < 70 OR price > 85);

We ran both versions live and compared the row counts. Different numbers. Visibly, provably different. That proof lands better than any explanation.

I told the class: "Any query that mixes AND and OR - use brackets. Not because you are unsure of the precedence, but because the next person reading your query definitely isn't. Brackets are documentation."

Section 3: BETWEEN - Ranges Made Readable

Without BETWEEN, a range filter needs two conditions joined by AND:

-- The long way
SELECT product_name, price
FROM duka.duka_products
WHERE price >= 60 AND price <= 200
ORDER BY price;

With BETWEEN:

-- The short way
SELECT product_name, price
FROM duka.duka_products
WHERE price BETWEEN 60 AND 200
ORDER BY price;

Same result. The BETWEEN version reads more like English - "price between 60 and 200" — which is exactly what we mean.

BETWEEN also works in reverse:

-- Products with stock level in range 20–40
SELECT product_name, stock_level
FROM duka.duka_products
WHERE stock_level BETWEEN 20 AND 40
ORDER BY stock_level;

-- Flip it: products OUTSIDE the 20–40 range
SELECT product_name, stock_level
FROM duka.duka_products
WHERE stock_level NOT BETWEEN 20 AND 40
ORDER BY stock_level;

Critical detail I repeat twice: BETWEEN is inclusive. BETWEEN 60 AND 200 includes products priced exactly 60 and exactly 200. If you want to exclude the boundaries, use > 60 AND < 200 instead.

This matters most in financial and date-range queries. A billing report BETWEEN two dates either includes or excludes those dates - and the answer matters. Know your boundaries.

Section 4: IN and NOT IN - Membership Checks

Without IN, filtering for multiple specific values means chaining OR:

-- The long way
SELECT product_name, product_category
FROM duka.duka_products
WHERE product_category = 'Dairy' OR product_category = 'Household';

With IN:

-- The short way
SELECT product_name, product_category
FROM duka.duka_products
WHERE product_category IN('Dairy', 'Household');

Same result. One tenth of the typing. Add a third category - just add it to the list. No restructuring the query.

NOT IN gives you the inverse. Mama Nia wants to see all products except those from two specific suppliers:

-- Products NOT from these two suppliers
SELECT product_name, supplier
FROM duka.duka_products
WHERE supplier NOT IN('Kenya Grain Millers', 'Brookside Dairy');

IN also works on specific product names:

-- Check prices for specific products by name
SELECT product_name, price
FROM duka.duka_products
WHERE product_name IN('Sukari', 'Mkate', 'Maharagwe');

One honest warning about NOT IN: it behaves unexpectedly when any value in the list is NULL. If the column being checked has NULL values, NOT IN may return zero rows - silently, with no error. For this dataset all our values are populated, so we noted the warning and moved on. Worth knowing before you hit it in a real project.

Section 5: LIKE and ILIKE - Pattern Matching

Sometimes you don't know the exact value. You know it starts with something, or contains something, or follows a certain shape. That's what LIKE and ILIKE are for.

Two wildcard characters:

Symbol	Meaning
`%`	Matches any number of characters (including zero)
`_`	Matches exactly one character

-- Products starting with 'M'
SELECT product_name
FROM duka.duka_products
WHERE product_name LIKE 'M%';

-- Products containing 'ai' anywhere in the name
SELECT product_name
FROM duka.duka_products
WHERE product_name LIKE '%ai%';

-- The _ wildcard - exactly one character before 'kate'
SELECT product_name
FROM duka.duka_products
WHERE product_name LIKE '_kate';

-- ILIKE - case-insensitive search
-- 'SUKARI' matches 'Sukari', 'SUKARI', 'sukari'
SELECT product_name
FROM duka.duka_products
WHERE product_name ILIKE 'SUKARI';

LIKE is case-sensitive - LIKE 'sukari' won't match 'Sukari'. ILIKE is PostgreSQL's case-insensitive version.

The three % placement patterns, left on the board for the rest of the session:

LIKE 'M%'    →  starts with M
LIKE '%a'    →  ends with a
LIKE '%ai%'  →  contains 'ai' anywhere

The _ underscore matches exactly one character. LIKE '_kate' matches 'Mkate' - one character then 'kate'. Useful for product codes with fixed-length formats.

Rule of thumb I gave the room: "If a human is typing the search term into any kind of input box, use ILIKE. They'll type 'SUKARI', 'sukari', 'Sukari' - and you want all of them to match."

All Five Together - The Session Closer

SELECT product_name, product_category, price, supplier, stock_level
FROM duka.duka_products
WHERE product_category IN('Dairy', 'Beverages')          -- membership
AND price BETWEEN 50 AND 200                              -- range
AND supplier ILIKE '%brook%'                              -- pattern
AND product_name NOT IN('Maziwa')                         -- exclusion
AND stock_level > 20                                      -- comparison
ORDER BY price;

The Cheat Sheet: When to Use What

You want to…	Use
Match an exact value	`=`
Exclude a specific value	`!=`
Both conditions required	`AND`
Either condition is enough	`OR`
Negate a condition	`NOT`
Mix AND and OR	Brackets — always
Number or date range	`BETWEEN`
Exclude a range	`NOT BETWEEN`
One of several specific values	`IN`
Exclude several specific values	`NOT IN`
Pattern match, case-sensitive	`LIKE`
Pattern match, case-insensitive	`ILIKE`

Practice Problems

Easy:

-- 1. Show all products where stock_level is between 25 and 60
-- 2. Show products from 'Dairy' OR 'Beverages' category
-- 3. Show product names that start with the letter 'S'

Medium:

-- Mama Nia wants to review specific products:
-- Show 'Sukari', 'Mkate', and 'Maharagwe' only if price is above 50
-- Order by price descending

SELECT product_name, price
FROM duka.duka_products
WHERE product_name IN('Sukari', 'Mkate', 'Maharagwe')
AND price > 50
ORDER BY price DESC;

Challenge:

-- Restock priority report:
-- Products NOT supplied by 'Kenya Grain Millers' or 'Brookside Dairy'
-- AND whose name contains the letter 'a' anywhere (case-insensitive)
-- AND whose stock level is NOT BETWEEN 30 AND 80
-- Order by stock_level ascending (most urgent first)
-- Your query here...

What's Next: JOINs

Every query we have written so far has touched exactly one table. Next session, Mama Nia's duka gets a second table - and we start connecting them.

-- A preview
SELECT p.product_name, p.price, s.contact_person, s.phone
FROM duka_products p
JOIN suppliers s ON p.supplier_id = s.id
WHERE p.stock_level < 30;

One query. Two tables. The database starts feeling like a real system. See you then.

Try It Yourself

Dataset: Mama Nia's Duka — link coming soon
This week's SQL script on GitHub — link coming soon

Focus your practice on the AND + OR parentheses trap - write a query that gives the wrong answer without brackets, confirm the wrong row count, then fix it. That one exercise teaches more about SQL logic than a dozen clean examples.

SQL Week: We Deleted Products, Dropped Tables, and Found Out Which Supplier Was Sitting on the Most Stock

Navas Herbert — Sun, 12 Jul 2026 06:14:56 +0000

Mama Nia's duka has been running for a few months now.

The shelves are stocked. The products are categorised. The suppliers are logged. Everything is in the database - tidy, structured, exactly where it should be.

This week I walked into the classroom and told the cohort: "We're going to start by deleting things."

A few nervous looks. One student - Kamau - actually moved his laptop slightly further away from the edge of the desk, as if SQL could fall off.

That reaction is why I always start the table manipulation session with DELETE before anything else. Once students are comfortable removing data on purpose, with control, they stop being afraid of the database and start being curious about it. That shift is everything.

Part 1: DELETE - Removing Rows You No Longer Need

Mama Nia has decided to stop selling two products. Mafuta ya Taa isn't moving. Biskuti keeps going stale before it sells. Time to remove them from the system.

-- Remove a discontinued product
DELETE FROM duka.duka_products
WHERE product_name = 'Mafuta ya Taa';

-- Remove another
DELETE FROM duka.duka_products
WHERE product_name = 'Biskuti';

Two things I told the class before running either of these.

First - always run a SELECT with the same WHERE clause first. Before you delete, see exactly what you're about to remove:

SELECT * FROM duka.duka_products
WHERE product_name = 'Mafuta ya Taa';

If that SELECT returns what you expected - one row, correct product - then you delete. If it returns five rows or nothing at all, you've caught a problem before it became permanent.

Second - DELETE with no WHERE clause deletes every row in the table. The table structure stays. The data is gone. This is not a theoretical warning. Every experienced SQL developer has either done this once or knows someone who has. Always write the WHERE clause first, before the DELETE.

The DELETE ran. Two rows gone. The table still existed, just two products lighter. Kamau moved his laptop back to its normal position.

Part 2: DROP TABLE - When the Whole Table Needs to Go

Different situation. We created a draft table for a New Year promotion - new_year_sale_draft- and now that planning phase is over. The whole table needs to go.

-- First, create it
CREATE TABLE new_year_sale_draft(
    product_name    VARCHAR(50),
    discount_percent INT
);

-- Then remove it entirely
DROP TABLE duka.new_year_sale_draft;

The question I wait for every cohort came right on time - Aisha asked: "What's the difference between DROP and TRUNCATE?"

TRUNCATE removes all rows instantly but keeps the table structure, like wiping a whiteboard clean without removing the whiteboard. DROP removes everything - the whiteboard, the frame, the wall mount.

I put the three-way comparison on the board:

The table makes the distinction concrete: DELETE (WHERE) removes some rows, TRUNCATE wipes all rows, DROP removes the data and the structure. One column - Removes structure? - is the entire difference between TRUNCATE and DROP. Students who see that column stop confusing the two.

Part 3: Core SQL Keywords - Asking Better Questions

Now the main event. The same duka_products table. The same data. Seven keywords that let you ask increasingly sophisticated questions.

SELECT - Choose Your Columns

The most basic question: what do you want to see?

-- Mama Nia just wants to see product names and prices
SELECT product_name, price
FROM duka.duka_products;

product_name          | price
----------------------|-------
Unga wa Ngano         | 145
Sukari                | 110
Mafuta ya Kupikia     | 220
...

Never use SELECT * in production queries, I told them. It pulls every column whether you need it or not. Name what you want. Your future self, and anyone reading your queries later, will thank you.

WHERE - Filter Before You Analyse

Which products cost more than KES 100?

SELECT product_name, price
FROM duka.duka_products
WHERE price > 100
ORDER BY price;

Which products need restocking - stock below 30 units?

SELECT product_name, stock_level
FROM duka_products
WHERE stock_level < 30;

The analogy I use: WHERE is the bouncer. It checks every row at the door before anything else happens. Only rows that pass the condition get into the query results.

ORDER BY - Sort the Results

Mama Nia wants to see her most expensive products first:

SELECT product_id, product_name, price
FROM duka.duka_products
ORDER BY price DESC;

And her lowest-stock items first - so she knows what to reorder soonest:

SELECT product_id, product_name, stock_level
FROM duka.duka_products
ORDER BY stock_level ASC;

ASC is the default. DESC flips it. Students who forget which is which remember "DESC sounds like descending, like going downstairs" - which is either helpful or annoying depending on who I ask.

LIMIT - Cap the Results

Top 3 most expensive products:

SELECT product_name, price
FROM duka_products
ORDER BY price DESC
LIMIT 3;

And a more specific version - the 2 priciest products specifically within Grains & Cereals:

SELECT product_id, product_name, price, product_category
FROM duka.duka_products
WHERE product_category = 'Grains & Cereals'
ORDER BY price DESC
LIMIT 2;

This is the WHERE + ORDER BY + LIMIT combination that shows up constantly in real reporting. Filter first, sort second, cap third.

GROUP BY- Summarise by Category

Now the queries that start to feel like real analysis.

How many products does Mama Nia carry in each category, and what's the average price per category?

SELECT product_category, COUNT(*) AS num_products, AVG(price) AS avg_price
FROM duka.duka_products
GROUP BY product_category
ORDER BY product_category;

product_category    | num_products | avg_price
--------------------|--------------|----------
Cooking Essentials  | 4            | 187.50
Grains & Cereals    | 5            | 132.00
Household Goods     | 3            | 95.00
...

Then the one that generated the most energy in the room - which supplier is sitting on the most stock value?

SELECT supplier, COUNT(*) AS num_products,
SUM(price * stock_level) AS total_stock_value
FROM duka.duka_products
GROUP BY supplier
ORDER BY total_stock_value DESC;

When that ran and a specific supplier came out top, Njeri said: "So Mama Nia should probably have a closer relationship with that supplier — they're holding the most of her money."

That's the moment. When a SQL query produces a genuine business insight, not just a correct output.

HAVING - Filter the Groups Themselves

This is WHERE's more specific sibling - and the one that confuses beginners most.

WHERE filters individual rows before grouping. HAVING filters groups after grouping. They look similar. They do very different things. The timing is everything.

Which categories have at least 2 different products?

SELECT product_category, COUNT(*) AS num_products
FROM duka.duka_products
GROUP BY product_category
HAVING COUNT(*) >= 2
ORDER BY product_category;

Notice: HAVING COUNT(*) >= 2, not HAVING num_products >= 2. The alias num_products doesn't exist yet when HAVING runs - it only exists in the final output. I put this on the board explicitly because it's the exact mistake everyone makes the first time:

--  This will error
HAVING num_products >= 2

--  This works
HAVING COUNT(*) >= 2

Which categories average over KES 100 per product?

SELECT product_category, AVG(price) AS avg_price
FROM duka.duka_products
GROUP BY product_category
HAVING AVG(price) > 100
ORDER BY avg_price DESC;

Same pattern - repeat the aggregate function in HAVING, not the alias.

The Capstone - Everything Together

The session closer. One query that uses everything:

Which categories are holding more than KES 10,000 worth of stock?

SELECT product_category, SUM(price * stock_level) AS total_stock_value
FROM duka.duka_products
GROUP BY product_category
HAVING SUM(price * stock_level) > 10000
ORDER BY total_stock_value DESC;

And the inverse - which supplier-category combinations are holding less than KES 10,000?

SELECT product_category, supplier, SUM(price * stock_level) AS total_stock_level
FROM duka.duka_products
GROUP BY product_category, supplier
HAVING SUM(price * stock_level) < 10000
ORDER BY product_category, supplier;

I left this on the board for the entire capstone section:

This is the sequence SQL actually runs your query - not the order you write it. Understanding this sequence explains why aliases don't work in HAVING, why WHERE runs before grouping, and why LIMIT always caps the final sorted output. Every confusion about SQL clauses traces back to not knowing this order.

Practice Problems

Easy:

-- 1. Show all products from the 'Household Goods' category, ordered by price
-- 2. Which products have a stock level above 50? Show name and stock level only.
-- 3. Show the top 5 cheapest products

Medium:

-- Find the total stock value per supplier (price * stock_level)
-- Only show suppliers whose total stock value is above 5,000
-- Order by total stock value, highest first

SELECT supplier, SUM(price * stock_level) AS total_stock_value
FROM duka.duka_products
GROUP BY supplier
HAVING SUM(price * stock_level) > 5000
ORDER BY total_stock_value DESC;

Challenge:

-- Mama Nia wants a restocking priority report:
-- Show categories where the average stock level is below 40
-- Include: category name, number of products, average stock level, total stock value
-- Order by average stock level ascending (most urgent first)
-- Your query here...

What I Noticed Teaching This Session

1. Starting with DELETE was the right call every time. Fear of the database is the biggest obstacle beginners carry. The moment students deliberately remove data and see the table still running correctly - just smaller - the fear converts to confidence.

2. WHERE vs HAVING needs more than one explanation. I explained it twice, showed the alias error deliberately, and still had students reach for the alias in their own queries. The only fix that works is letting them hit the error themselves, reading it, and tracing back to why. Budget time for this.

3. The supplier stock value query produced the best discussion. "Which supplier is Mama Nia most dependent on?" is a real business question. When SQL answers it, students stop thinking of queries as exercises and start thinking of them as tools. That shift is the whole point of using a realistic dataset.

4. The order of operations diagram is worth drawing every session. FROM → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT - written on the board and left visible. Every question about why something doesn't work traces back to a misunderstanding of this sequence.

What's Next

Next session: JOINs. Mama Nia's duka is about to get a second table - a suppliers table with contact details and payment terms. And we'll start connecting the two.

-- A preview of what's coming
SELECT p.product_name, p.price, s.contact_person, s.payment_terms
FROM duka_products p
JOIN suppliers s ON p.supplier = s.supplier_name
WHERE p.stock_level < 30;

Two tables. One query. The data starts to feel like a real system. See you then.

*I'm a data trainer in Nairobi running a full data programme -
Python foundations → Data Science or Data Engineering specialisations.

Follow along or drop your questions in the comments.*

FastAPI Just Got Its Own Deployment Platform - And It's One Command

Navas Herbert — Sun, 05 Jul 2026 16:35:17 +0000

I came across: FastAPI Cloud.

Built by the same team behind FastAPI itself. Still in beta. Free hobby tier, no credit card, up to 3 apps.

The pitch is simple: deploying a FastAPI app has always required work that has nothing to do with FastAPI - writing a Dockerfile, configuring ports, setting up a Render or Railway dashboard, writing a Procfile, remembering to add uvicorn to requirements.txt. None of that is your actual application. It's all overhead that stands between finishing your code and having it live on a real URL.

FastAPI Cloud removes all of it. The deploy command is:

fastapi deploy

That's it. I sent the link to the cohort group chat and then immediately opened my own terminal to try it.

What Actually Happened

I pointed it at a simple bookshop API I had sitting in a local folder - GET /books, POST /books, nothing fancy. Ran fastapi deploy. The CLI asked if I wanted to log in, opened a browser auth page, and I was authenticated in under a minute.

Then it asked which team to deploy to. I selected RAG AI (my workspace), confirmed the directory, and it started building.

The build log scrolled through installing dependencies, copying source code, configuring the working directory - and then:

Ready the chicken! 🐔
Your app is ready at https://bookshop-api.fastapicloud.dev

I genuinely laughed at "Ready the chicken." Then I clicked the link.

Green checkmark. us-east-1. Last updated 36 seconds ago. A real deployed app on a real public URL, from a project folder sitting on my Windows laptop, in under three minutes total.

/docs - live, interactive, the full Swagger UI. GET /books, POST /books, Book schema in the Schemas section. A complete deployed API with automatic documentation, no configuration file written, no dashboard manually created.

Why This Matters for Teaching

The hardest part of teaching FastAPI to beginners isn't FastAPI. It's everything that comes after - "now how do I show someone else what I built?"

Getting a student from working local API to public URL currently takes anywhere from 20 minutes to an entire class session, depending on which platform you use and what breaks. Docker confusion, Render free-tier cold starts, missing environment variables, wrong start commands - all of that is friction that has nothing to do with the actual skill we're trying to teach.

fastapi deploy collapses that to three minutes and one command. For a teaching context, that's not a small improvement. That changes what's possible in a single session.

Caveats Worth Knowing

It's in beta. The free hobby tier covers up to 3 apps, which is enough for ssomeone projects and quick demos. I don't know yet how it handles environment variables for projects with API keys (the RAG build would need that), persistent storage, or what happens at higher traffic. Those are questions for when they're out of beta.

But for what it does right now - take a FastAPI project and put it on a live public URL with one command - it works exactly as advertised.

Try It

pip install "fastapi[standard]"
fastapi deploy

You need a FastAPI project already set up locally. Head to fastapicloud.com, sign up for the hobby tier, and try it against something you've already built. The deploy takes about two minutes. The /docs URL works immediately.

If you've been putting off deploying a project because the setup felt like too much overhead - this removes the excuse.

Not all chunking is equal.

Navas Herbert — Thu, 02 Jul 2026 15:19:17 +0000

The strategy you pick at ingestion quietly determines how good your RAG retrieval will ever be - no matter how good your embedding model is.

Six strategies, ranked from baseline to production-grade:

𝗙𝗶𝘅𝗲𝗱-𝗦𝗶𝘇𝗲 - split every N characters, regardless of meaning. Fastest to implement. Cuts mid-word, mid-sentence. Baseline only.

𝗙𝗶𝘅𝗲𝗱 + 𝗢𝘃𝗲𝗿𝗹𝗮𝗽 - same as above, but consecutive chunks share a repeated tail. Reduces hard cuts. Still not semantically aware. A quick upgrade, not a real fix.

𝗥𝗲𝗰𝘂𝗿𝘀𝗶𝘃𝗲 𝗦𝗽𝗹𝗶𝘁 - tries natural separators in order: paragraph → sentence → word → character. Respects language structure. The default choice for most general-purpose RAG.

𝗠𝗮𝗿𝗸𝗱𝗼𝘄𝗻-𝗔𝘄𝗮𝗿𝗲 - splits on document headers and sections. Each chunk is one logical topic. Free section metadata for filtering. Requires structured documents.

𝗦𝗲𝗺𝗮𝗻𝘁𝗶𝗰 - embeds every sentence, measures similarity between consecutive ones, cuts where similarity drops sharply. Chunks align with actual meaning. Costs more at ingest time.

𝗔𝗴𝗲𝗻𝘁𝗶𝗰 / 𝗣𝗿𝗼𝗽𝗼𝘀𝗶𝘁𝗶𝗼𝗻 - an LLM rewrites each piece into a self-contained atomic fact. No dangling pronouns, no lost context. Best possible retrieval quality. Most expensive.

The one thing worth remembering across all of them: overlap is a band-aid, not a fix. It reduces boundary cuts but doesn't make chunks semantically coherent.

Choose your strategy based on what you're optimizing for - ingestion speed, retrieval quality, or cost.

Sharing what I'm learning in public.

RAG #AI #Python #LLM #LearningInPublic

Day 2 of 3: We Added an LLM and the Project Became a Real Product

Navas Herbert — Wed, 01 Jul 2026 20:42:58 +0000

I opened Day 2 with the same diagram I drew on Day 1.

Question → [embed] → [search vectors] → top-k chunks → [stuff into prompt] → LLM → Answer + sources

I pointed at the left half - everything up to and including top-k chunks. "Yesterday we built all of this. We proved retrieval works, with zero AI model involved. Distance numbers, real chunks, real search."

Then I pointed at the right half - [stuff into prompt] → LLM → Answer + sources.

"Today is this. Two new ideas, one new file. By the end of this session, your project stops being a search engine and becomes a product."

One New File: touch rag.py

Yesterday's project had three files. Today it gets one more.

That's it. One file. I wrote its job on the board before we touched it: "rag.py has exactly two jobs - build a prompt that forces the model to answer only from our chunks, and call an LLM with that prompt. It never touches ChromaDB. It never touches FastAPI. It just receives chunks and returns an answer."

The updated folder structure:

interdoc/
    |--app/
           |---- ingestion.py
           |---- vectorstore.py
           |---- rag.py          ← new today
           |---- main.py

File 4: rag.py - The Heart of Day 2

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

I stopped immediately at line one. "Notice the API key never appears as text anywhere in our code. It lives in .env, which must be in .gitignore. If this project ever goes on GitHub, that key must never go with it."

build_prompt() - The Most Important Function of the Week

def build_prompt(question: str, chunks: list[str], metadatas: list[dict]) -> str:
    blocks = []
    for i, (chunk, meta) in enumerate(zip(chunks, metadatas), start=1):
        blocks.append(f"[Source {i}: {meta['source']}, chunk {meta['chunk_index']}]\n{chunk}")
    context = "\n\n".join(blocks)
    return (

"Use the context below to answer the question" - curbs the model from reaching into its own training data and answering from memory.

"If context does not contain the answer, say so politely or say you don't have enough information - do not guess" - this is the safety valve against hallucination. I told the class to remember this line specifically. Every RAG system that gives confidently wrong answers is missing this instruction somewhere.

"Reference relevant source using [Source N]" - we are telling the model the exact citation format to use. We built the [Source 1: filename, chunk N] labels in the blocks loop above, so the model can actually reference them. The citation capability comes from us, not from the model.

One sentence in the prompt is the entire difference between a trustworthy system and a hallucinating one.

generate_answer() - Calling the Model

def generate_answer(question: str, search_results: dict) -> dict:
    chunks = search_results["documents"][0]
    metadatas = search_results["metadatas"][0]
    if not chunks:
        return {"answer": "No documents have been uploaded yet.", "sources": []}

    prompt = build_prompt(question, chunks, metadatas)
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        max_tokens=500,
        messages=[{"role": "user", "content": prompt}],
    )

    answer_text = response.choices[0].message.content
    sources = [{"source": m["source"], "chunk_index": m["chunk_index"]} for m in metadatas]
    return {"answer": answer_text, "sources": sources}

search_results is exactly what search_chunks() from yesterday returns - we didn't change that function at all. Day 2 plugs into Day 1's output without touching it.

The if not chunks guard at the top: "Always check before calling an expensive API. If nobody has uploaded anything yet, we return a clear message immediately instead of making an API call that would produce a useless response."

The sources list at the bottom: "Why do we return sources as a separate structured list instead of just leaving the citations inside the answer text? Because whoever builds a frontend on Day 3 can now display sources separately - highlight them, make them clickable, show the actual chunk text on hover. Buried inside an answer string, that's impossible."

Adding /query to main.py

We didn't rewrite main.py. We added to it - keeping everything from Day 1 exactly as it was.

from pydantic import BaseModel
from app.vectorstore import search_chunks
from app.rag import generate_answer

class QueryRequest(BaseModel):
    question: str
    top_k: int = 4

@app.post("/query")
async def query_documents(request: QueryRequest):
    results = search_chunks(request.question, top_k=request.top_k)
    return generate_answer(request.question, results)

I pointed at the endpoint body. "Two lines of real logic. Retrieve, then generate. Every endpoint we've written follows the same shape: receive the request, delegate the work to the right specialist file, return the result. main.py still doesn't do any real work itself."

Someone asked why there's no response_model here the way the Grade Tracker endpoints had last week. Good question — the answer structure coming back from generate_answer() is a plain dict that varies depending on how many sources come back. We'd need a Pydantic model to enforce a strict shape. For today's session that's a Day 3 polish item, not today's concern.

First Test: Confirm /upload Still Works

Before touching /query, we re-uploaded the document.

chunks_created: 34 - small_language_research.pdf, 34 chunks stored and embedded. Day 1's pipeline still running clean. This step is not optional: if ChromaDB has no vectors to search, /query returns empty results and the LLM produces a confused non-answer. Upload first, always.

The Moment of the Session: We Tried to Break It

Now the part I look forward to most in every AI session - deliberately trying to make the system fail.

We opened /docs, expanded POST /query, clicked Try it out, and typed a question I knew was nowhere in the uploaded document:

{
  "question": "Where is company Datapulse ai headquarted?",
  "top_k": 3
}

The document was a language research paper. There is no "Datapulse AI" in it. No headquarters. Nothing even close.

The response:

I read this out loud and said: "Look at what just happened. Retrieval found the three chunks it considered most relevant to that question - and they're all from the language research paper, which has nothing to do with Datapulse. The LLM received those chunks, saw they contained no useful information, and said exactly that. It did not make something up. It refused."

Then the line I want everyone to remember: "When the model correctly refuses to answer something it doesn't know - that is not the system being unhelpful. That is the system working exactly as designed. A confident wrong answer would have been the actual failure."

The sources array is visible in the response even on a refusal. That's correct - the system is being transparent about what it searched, even when what it found wasn't enough to answer. On Day 3 when students build frontends, they can display those sources as "searched but insufficient"- which is genuinely more trustworthy than silence.

We ran two more stress tests before closing:

Asking something vague - a fuzzy, poorly-phrased question about the same document. The answer came back, but less precisely. We talked about why: retrieval quality depends on the closeness between how the question is phrased and how the relevant chunk is worded. Better questions get better retrieval. Prompt quality matters on both ends.

Uploading two documents on different topics, then asking a question only answerable from one - the sources in the response correctly pointed to the right file, not the irrelevant one. Vectors from separate documents live in the same space, and the closest ones win regardless of which file they came from.

What Exists Now

I said this slowly at the end of the session:

"Upload any PDF or text file. Ask any question in plain English. The system embeds your question, searches the stored vectors for the most relevant chunks, builds a grounded prompt from those chunks, calls an LLM with strict instructions to answer only from what it was given, and returns an answer with citations pointing to the exact source chunks. If the answer isn't in the documents, it says so. That's a real product."

One new file. rag.py. That's all today took to cross the line from "interesting search engine" to "document intelligence API."

I'm an AI engineer in Nairobi
Follow along or drop your questions in the comments.

Day 1 of 3: We Built the Retrieval Half of RAG - Before Touching a Single AI Model

Navas Herbert — Tue, 30 Jun 2026 15:36:29 +0000

I opened today's session with a sentence I wanted everyone to hold onto for the next three days:

"By the end of today, you will be able to upload a real document through an API endpoint, and have it automatically split into chunks, turned into vectors, and stored so it can be searched by meaning, not just by keyword. We will not touch any AI model today - that is on purpose. We want you to see retrieval working on its own first."

This is Day 1 of a 3-day Document Intelligence API build with the cohort 6 interns. Same FastAPI skills they used last week building the Grade Tracker- Depends, response models, endpoints - but a new kind of database underneath. Today was retrieval only. No LLM, no generation, no API key required. Just proving that the search half of the system actually works.

Here's how it went.

Three Ideas, Whiteboard Only, Ten Minutes

Before any code, I drew three ideas on the board and told the room: "I want you to be able to redraw this from memory by the end of today."

Embedding: a piece of text turned into a list of numbers, a vector, such that text with similar meaning ends up close together in that number space. "Cat" and "dog" land near each other. "Cat" and "spreadsheet" land far apart. The model was never told what a cat is - it learned this closeness from patterns in huge amounts of text.

Vector search : just nearest-neighbour search in that number space. Take a question, embed it the same way, find which stored vectors sit closest. That closeness is what "relevant" means here.

RAG (Retrieval-Augmented Generation) - retrieve the relevant chunks first, then paste them into the LLM's prompt, so it answers using your data instead of guessing from what it memorised during training.

Question --> [embed] --> [search vectors] --> top-k chunks --> [stuff into prompt] --> LLM --> Answer + sources

I said the one sentence I repeat every time I teach this, slowly, twice: "The LLM never sees your documents unless retrieval puts the right chunk into the prompt." That single idea, if it clicks on Day 1, makes the rest of the week make sense. Everything else is implementation detail around that one fact.

Setting Up: Real Folders, Built Live in the Terminal

No starter repo. No zip file. We built the project structure from nothing, together, in the terminal.

mkdir interdoc && cd interdoc
mkdir app && cd app
touch ingestion.py vectorstore.py main.py

Three empty files. I wrote their names on the board before we touched any of them - ingestion.py, vectorstore.py, main.py - and pointed at each one as we built it. This cohort already knows this rhythm from last week's database.py, models.py, schemas.py, crud.py, main.py build. One file, one job. Files talk to each other through clean function calls, not by reaching into each other's internals.

I also had the Day 1 goals written out as a checklist before we started - explain what an embedding is and why similar meanings end up as nearby vectors, explain the difference between keyword and vector search, upload a real file through your own endpoint and have it chunked and stored, explain why chunk overlap matters, run a search query with zero AI involved, and know exactly what's still missing to call this a real product.

That last line on the checklist : "hio ni kesho" (that's tomorrow) - was a deliberate boundary. Today is retrieval. Generation is Day 2's problem, not today's.

File 1: ingestion.py - Extract Text, Then Chunk It

"This file has exactly one job: take raw bytes from an uploaded file and turn them into a list of clean text chunks, ready to be embedded. It never talks to ChromaDB and it never talks to FastAPI."

import io
from pypdf import PdfReader

def extract_text(filename: str, file_bytes: bytes) -> str:
    if filename.lower().endswith(".pdf"):
        reader = PdfReader(io.BytesIO(file_bytes))
        return "\n".join(page.extract_text() or "" for page in reader.pages)
    return file_bytes.decode("utf-8", errors="ignore")

io.BytesIO lets us treat raw bytes sitting in memory as if they were a file, without ever saving anything to disk. The uploaded file arrives as bytes - PdfReader expects something that behaves like a file - so this bridges the two. I made a point of telling the class: "Notice we are not saving the uploaded file anywhere. We pull the bytes straight out of memory, extract the text, and the original file is gone. For this project that's fine - we only care about the text inside, not the file itself."

Someone asked: "What about Word documents? Scanned PDFs?" Honest answer: scanned PDFs need OCR - a separate tool that reads text out of images - and Word docs need a different library entirely. Today we keep it to PDF and plain text on purpose, so the lesson stays about retrieval, not file-format archaeology.

Then the function the whole session would orbit around:

def chunk_text(text: str, chunk_size: int = 300, overlap: int = 50) -> list[str]:
    words = text.split()
    chunks = []
    start = 0
    while start < len(words):
        end = start + chunk_size
        chunk = " ".join(words[start:end])
        if chunk.strip():
            chunks.append(chunk)
        start += chunk_size - overlap
    return chunks

"This is the function I want you to be able to explain to a friend tonight. We cannot embed an entire document as one giant vector - it would be too vague, mixing twenty different ideas into one point in space. So we split the text into smaller pieces and embed each chunk separately."

We did it by hand on the board with tiny numbers - chunk_size=5, overlap=2, on a 12-word sentence. First chunk: words 0 to 5. Next start: 0 + 5 - 2 = 3. Second chunk: words 3 to 8. Words 3 and 4 appear in both chunks - that's the overlap. Why does that matter? If the answer to someone's question sits right at the boundary between two chunks, without overlap you'd cut that sentence in half and lose it in both pieces.

The REPL Moment - And a Real Typo

We tested chunk_text() live, in the interactive Python shell, before wiring up anything else.

from app.ingestion import chunk_text

text = "An embedding is a piece of text turned into a list of numbers (vector) - such that text with similar MEANING ends up close together in that number space"
chunks = chunk_text(text, chunk_size=15, overlap=5)
len(chunks)

I typed chunk[0] to look at the first piece - forgetting the s. Python answered immediately with NameError: name 'chunk' is not defined. Did you mean: 'chunks'?

I left it on screen and let the class read it out loud. Then corrected it: chunks[0].

'An embedding is a piece of text turned into a list of numbers (vector) -'

chunks[1]

'list of numbers (vector) - such that text with similar MEANING ends up close together'

I pointed directly at the repeated words - "vector" and "-" sitting at the start of chunks[1], the same words that closed out chunks[0]. That's the overlap, working exactly as designed, visible in real output rather than just described in theory.

I told the room: "That NameError is going to happen to every single one of you this week, probably more than once. Python tells you exactly what it thinks you meant. Read the error before you panic." A typo in a live REPL is one of the most useful teaching moments available - it shows that errors are information, not failure.

We also walked through what happens if overlap >= chunk_size deliberately - start never moves forward, or moves backward, and the while loop never terminates. I had a volunteer try it on a short string and watch it hang, then Ctrl+C out. A great bug to see once, on purpose, in a safe sandbox, rather than discover by accident at midnight.

File 2: vectorstore.py : Where Chunks Become Vectors

"File two is where chunks actually become vectors and get saved somewhere we can search later. Two new ideas live here: sentence-transformers, which turns text into numbers, and ChromaDB, which stores those numbers and knows how to search them."

import chromadb
from chromadb.utils import embedding_functions

client = chromadb.PersistentClient(path="./data/chroma_db")

embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

collection = client.get_or_create_collection(
    name="documents",
    embedding_function=embedding_fn,
)

def add_chunks(doc_id: str, chunks: list[str]) -> int:
    ids = [f"{doc_id}_{i}" for i in range(len(chunks))]
    metadatas = [{"source": doc_id, "chunk_index": i} for i in range(len(chunks))]
    collection.add(documents=chunks, metadatas=metadatas, ids=ids)
    return len(chunks)

def search_chunks(query: str, top_k: int = 4):
    return collection.query(query_texts=[query], n_results=top_k)

PersistentClient(path="./data/chroma_db") means Chroma writes everything to disk, in that folder. Stop the server, restart it tomorrow, your uploaded documents are still there. I made a point of this line specifically: "This single line is the entire 'database connection' for our vector store. There's no separate server running in the background like there would be with PostgreSQL. Chroma is a library that reads and writes a folder on disk. That's the whole infrastructure."

The embedding function deserved its own callout: "This model runs locally. It downloads once, the first time you use it, then every embedding after that happens on your own laptop, for free, forever. Compare that to the LLM we plug in tomorrow, which calls out to a paid API. Embeddings are cheap and local. Generation is the part that costs money."

I pointed directly at metadatas in add_chunks() - "this is the detail that turns a toy demo into a real product. Without it, we'd have vectors with no idea which document or which part of a document they came from, and no way to show a citation when we answer a question later."

And search_chunks() got the moment of the file: "Sit with this for a second. One line of code is doing embed-the-question, then nearest-neighbour search across however many chunks we have stored, and returning the best matches with their distances. Everything before this was preparation. This line is the actual retrieval in Retrieval-Augmented Generation."

When someone asked why ChromaDB and not Pinecone, Weaviate, or pgvector - honest answer: those are excellent production choices, but every one of them needs an account, an API key, or a running server process. Chroma needs none of that, which is exactly why it's the right teaching tool this week. The concepts transfer directly the day you need a production-grade option.

File 3: main.py - Small on Purpose

"Notice how small this file is. ingestion.py and vectorstore.py do all the real work; main.py just connects an HTTP request to the right function calls."

from fastapi import FastAPI, UploadFile, File
from app.ingestion import extract_text, chunk_text
from app.vectorstore import add_chunks

app = FastAPI(title="Document Intelligence API")

@app.get("/")
def root():
    return {"status": "alive"}

@app.post("/upload")
async def upload_document(file: UploadFile = File(...)):
    contents = await file.read()
    text = extract_text(file.filename, contents)
    chunks = chunk_text(text)
    n = add_chunks(doc_id=file.filename, chunks=chunks)
    return {"filename": file.filename, "chunks_created": n}

Same separation-of-concerns rule as crud.py last week - main.py doesn't extract text, doesn't embed anything, doesn't touch the database directly. It receives the HTTP request and hands the work to the right specialist file.

"Look at how this endpoint reads almost like a sentence: read the file, extract the text, chunk it, add it to the store, confirm it worked. Five lines, five clear steps. Every endpoint we write this week follows this same 'receive, delegate, confirm' shape."

Starting the Server - Another Honest Typo

uvicorn app.main:app --reload

First attempt, I fat-fingered it: --relaod. Uvicorn didn't recognise the flag and complained. I caught it, fixed the spelling, and reran it.

I didn't edit that moment out of how I told the story to the class either. "This is what live coding actually looks like. I've typed this command hundreds of times and I still mistype it occasionally. The terminal tells you exactly what went wrong. Read it, fix it, move on." Once corrected, the server started cleanly with auto-reload watching for file changes.

We opened http://127.0.0.1:8000/docs, expanded POST /upload, clicked Try it out, chose a short sample text file, and hit Execute.

{
  "filename": "sample_notes.txt",
  "chunks_created": 4
}

A real number greater than zero. The whole pipeline - upload, extract, chunk, embed, store - had just run, end to end, through an actual HTTP request.

I warned the room ahead of time: if chunks_created comes back as 0, the most common cause is a scanned PDF with no extractable text layer - extract_text() returns an empty string for every page in that case. Always keep a backup plain-text file ready for exactly this situation.

The Payoff: Proving Retrieval Works, Zero LLM Involved

"This next part is the payoff for today. We are going to prove that our system can already find the right information, before we ever connect an AI model."

A throwaway script, scratch.py, in the project root:

from app.vectorstore import search_chunks

results = search_chunks("what is this document about?", top_k=3)

for doc, meta, dist in zip(
    results["documents"][0],
    results["metadatas"][0],
    results["distances"][0],
):
    print(f"[{meta['source']} chunk {meta['chunk_index']}] (distance={dist:.3f})")
    print(doc[:150], "...")
    print()

python scratch.py

Real chunks came back, each with a distance score attached. I read the output out loud and pointed straight at the distance numbers: "Lower means more similar. That's it. That's the whole mystery of 'similarity search' : it's just a number, and we are sorting by it."

Then the checkpoint question that ties the whole day together: change the question in scratch.py to something completely unrelated to the uploaded document, rerun it, and watch what happens to the distance values. When the question has nothing to do with what's stored, the distances jump noticeably higher - visible, numeric proof that the system genuinely doesn't know things it was never given.

What Exists Right Now, With Zero AI Generation Involved

I said this out loud at the end of the session, slowly:

"A real API endpoint that accepts any PDF or text file, automatically splits it into overlapping chunks, turns those chunks into vectors using a local embedding model, and stores them so they can be found again by meaning, not by exact keyword match. That's the entire retrieval half of RAG - working, and testable, right now."

Tomorrow we build the other half: taking those retrieved chunks, handing them to an LLM, and getting back an answer with citations. That's when this stops being a search engine and becomes a product.

What I Noticed Teaching This Session

1. The "redraw it from memory" bar works. Telling students up front that they'll need to reproduce the embeddings diagram themselves changes how closely they listen to the first ten minutes. Theory with an explicit accountability check lands differently than theory alone.

2. Real typos teach better than clean demos. The chunk[0] NameError and the --relaod flag mistake weren't planned, but I didn't edit either one out of how I narrated the session. Seeing an instructor make and fix a real mistake, live, removes a huge amount of fear from a beginner's own inevitable errors.

3. Distance numbers demystify "AI search" instantly. The moment students see an actual float next to each retrieved chunk, and watch that number change when the question stops being relevant, "semantic search" stops being a buzzword and becomes something they can reason about directly.

4. Drawing the line at "no LLM today" was the right call. It would have been tempting to wire in generation on Day 1 for a flashier demo. Keeping retrieval isolated meant every student could see, concretely, exactly what part of the system was doing the finding - before any model got a chance to paper over a weak retrieval step with a confident-sounding answer.

Homework Before Day 2

Upload 2–3 real documents - your own notes, a resume, a public FAQ page saved as text, anything
Edit scratch.py and try at least 5 different questions against your own documents
Try a question that should not be answerable from your documents, and look closely at the distance values compared to one that should be

Next: generation, citations, and the moment this stops being a search engine.

*I'm a data trainer in Nairobi running a full data programme -
Python foundations → Data Science or Data Engineering specialisations.

Follow along or drop your questions in the comments.*

I Taught Git the Right Way - Branch, PR, Tag the Issue, Merge

Navas Herbert — Mon, 29 Jun 2026 16:05:58 +0000

Most beginners learn Git as three commands: add, commit, push. Straight to main. Every time.

That works until you're contributing to a real project - a job, an open-source repo, a team codebase. Then suddenly there are branches, pull requests, code reviews, and issue numbers you're supposed to reference. Nobody just pushes to main anymore.

Today I didn't want to explain that workflow. I wanted to live it, in front of the class, on a real repository - task_manager - with real issues already open for contribution. Fourteen of them, in fact. Things like adding JWT auth, dockerizing the app, building a frontend. Real tasks, waiting for real pull requests.

I picked Issue #1 - "Add priority field to Task" - and we worked it end to end, exactly the way it should be done. Here's every step, with the actual screenshots from the session.

Step 1: Look at the Actual Issue First

Before touching the terminal, we read the issue itself. This is the part beginners skip - they jump straight to coding before understanding what's actually being asked.

The issue had a clear description, a checklist of what to do, labels (backend, good-first-issue), and acceptance criteria. I told the class: "This is how real work arrives. Not as a vague request - as a structured ticket. Read the whole thing before you write a single line."

The checklist told us exactly what was needed: add a priority column to the Task model, add it to the TaskCreate and TaskUpdate schemas, add it to TaskResponse, and make sure it's optional on updates.

Step 2: Never Work Directly on main

This is the rule I repeat every single session: you never commit straight to main. You create a branch named after what you're doing, work there, and only bring it into main through a reviewed pull request.

git checkout -b feature/add-priority-field

Switched to a new branch 'feature/add-priority-field'

Notice the terminal prompt itself changes - (main) becomes (feature/add-priority-field). I pointed this out immediately: "Your terminal is telling you exactly where you are. Always look at that before you commit anything."

The naming convention matters too: feature/ prefix, then a short, clear description. Not fix-stuff or update2. Six months from now, someone reading your branch list should understand what each one did without opening a single file.

Step 3: Make the Change, Then Commit With a Real Message

We edited models.py to add the priority column, and schemas.py to add it to the three Pydantic schemas the issue described. Then:

git add models.py schemas.py
git commit -m "feat: add priority field to Tas model (#1)"
git push -u origin feature/add-priority-field

[feature/add-priority-field 487325e] feat: add priority field to Tas model (#1)
 2 files changed, 6 insertions(+), 2 deletions(-)

Two things I made the class stop and look at here.

First - the commit message format. feat: at the start tells anyone reading the history what kind of change this is, without opening the diff. This is called Conventional Commits, and it's used widely in real projects. feat: for a new feature, fix: for a bug fix, docs: for documentation, refactor: for restructuring without changing behaviour.

Second - the (#1) at the end. That's the issue number. I told them: "This single detail is what turns a random commit into a traceable piece of work. Anyone looking at this commit message instantly knows which issue it addresses." (Yes - I also typo'd "Task" as "Tas" in the live commit message, which I left in the screenshot on purpose. Even trainers make typos mid-demo. It happens. The lesson doesn't change.)

git push -u origin feature/add-priority-field sends the branch to GitHub. The -u flag sets up tracking so future pushes from this branch just need git push, no extra arguments. GitHub even gives you a direct link in the terminal output to open a pull request - convenient, and worth pointing out so students don't go hunting for the button manually.

Step 4: The Repo, Fully Loaded With Real Issues

Before opening the PR, I showed the class the bigger picture - the full issue board waiting for contributors.

Fourteen open issues. Labels for difficulty (advanced, intermediate, good-first-issue) and area (backend, frontend, devops, security, testing). This is deliberate - a real contribution workflow needs real work waiting to be picked up. I told the class: "Pick any one of these. Today we're doing #1 together. The rest are yours to practice on this week."

Step 5: Compare the Branches

Back to the terminal output's link, or directly on GitHub - comparing what changed between main and our feature branch before opening anything formal:

Able to merge - GitHub confirming there's no conflict. One commit, two files changed, six additions, two deletions. This comparison view is where you do a last sanity check on exactly what you're about to propose merging. I told the class: "Always look at this diff view before opening the PR. If you see a file you didn't mean to touch, fix it now - not after someone reviews it."

Step 6: Open the Pull Request - and Tag the Issue

This is the step that ties the whole workflow together, and it's the one beginners forget most often.

In the PR description, typing Closes #1 and then selecting the actual issue from the dropdown - not just typing the number and hoping - does something genuinely useful: when this PR gets merged, GitHub automatically closes the issue for you. No separate step. No manually clicking "close" afterward and risking forgetting.

I made sure guys understood the vocabulary GitHub recognises: Closes, Fixes, and Resolves all trigger this auto-close behaviour, followed by the # and the issue number. Get the keyword and the number right, and GitHub does the bookkeeping.

"This is the line that connects your code change to the conversation that requested it. Anyone reading the issue later sees exactly which PR resolved it. Anyone reading the PR sees exactly what it was solving for. That traceability is the entire point."

Step 7: Review Before You Merge

Once opened, the PR ran its checks automatically.

All checks have passed - a GitGuardian security scan confirming no secrets were accidentally committed, and No conflicts with base branch. On the right sidebar: Closes #1 listed clearly under Development, which is GitHub surfacing the same link we set up in the description.

I paused here to make a point that matters more as projects grow: "In a team, this is where someone else reviews your code before merge - not you. Today we're working solo, so we'll review and merge it ourselves, but the pattern is the same one you'll use everywhere: PR opens, checks run, reviewer approves, then it merges."

Step 8: Merge - and Write a Clear Merge Commit

Clicking Merge pull request doesn't just merge - it gives you one more chance to write a clear commit message for the merge itself.

The default message GitHub suggests is already clear: Merge pull request #15 from Navashub/feature/add-priority-field, with the extended description carrying over the original commit message. I told students: "You can edit this if you want, but GitHub's default is already good practice - it tells you which PR, which branch, and what feature. Don't just blindly accept defaults everywhere, but this one's worth keeping."

Step 9: The Merge - and the Branch Cleanup

Pull request successfully merged and closed

GitHub immediately offers: "You're all set - the feature/add-priority-field branch can be safely deleted."

This is a habit worth building early: delete the branch after merging. The work is already in main. The branch served its purpose. Leaving dozens of stale merged branches around a repo makes it harder to see what's actually active. Click delete. It's gone from GitHub, but the commit history stays exactly intact in main forever.

Step 10: The Payoff - Watch the Issue Close Itself

This is the moment I wanted the whole class to see, because it's the proof that everything we did was connected correctly.

Issue #1 - closed. Automatically. Nobody opened the issue tab and clicked a button. The Closes #1 text in the pull request description did it the moment the merge happened.

That's the full loop: an issue describes work → a branch isolates that work → commits reference the issue number → a pull request formally proposes merging it and links back to the issue → checks verify it's safe → merging brings it into main → the issue closes itself as proof the work is genuinely done.

Why I did This Way

I could have explained this as a diagram on a whiteboard. Branch, commit, push, PR, merge - five boxes with arrows. Guys would nod and forget it by the following week.

Instead we did it on a real repository with real open issues, using the exact same commands and the exact same GitHub interface they'll use the moment they contribute to any actual project - open source, a job, a personal repo with collaborators. The typo in the commit message, the GitGuardian check actually scanning for secrets, the dropdown autocomplete for linking the issue - none of that is staged. It's what really happens.

What's Next for This Cohort

Thirteen issues remain open on task_manager. Each one is real practice for this exact workflow:

Create a branch named after the issue
Reference the issue number in your commit messages
Open a PR that says Closes #<number>
Get it merged, watch the issue close itself

Next time I write about this, it'll be their pull requests on screen, not mine.

Try It Yourself

If you want to practice this exact workflow on a real project:

Fork any repo with open issues labelled good-first-issue
Create a branch following the type/short-description pattern
Reference the issue number in your commit message
Open a PR with Closes #<number> in the description
Watch the issue close itself when it merges

That sequence is the actual day-to-day rhythm of working on a real codebase with other people. Practice it on a toy repo before you need it on a real one.

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.

𝙷̲𝚊̲𝚕̲𝚕̲𝚞̲𝚌̲𝚒̲𝚗̲𝚊̲𝚝̲𝚒̲𝚘̲𝚗̲ ̲𝚖̲𝚒̲𝚝̲𝚒̲𝚐̲𝚊̲𝚝̲𝚒̲𝚘̲𝚗̲

Navas Herbert — Sat, 27 Jun 2026 10:26:19 +0000

A question that exposes how much people misunderstand RAG: "How do you stop the LLM from hallucinating?"

Honest answer: you don't, fully. You layer mitigations, and none of them are bulletproof alone.

𝗙𝗶𝗿𝘀𝘁 𝗹𝗮𝘆𝗲𝗿 - 𝘵𝘩𝘦 𝘱𝘳𝘰𝘮𝘱𝘵 𝘪𝘵𝘴𝘦𝘭𝘧. You explicitly instruct the model to use only the provided context, and give it a fallback phrase for when the answer isn't there. This helps, but LLMs don't perfectly follow instructions, so it reduces hallucination, it doesn't eliminate it.

𝗦𝗲𝗰𝗼𝗻𝗱 𝗹𝗮𝘆𝗲𝗿 - 𝘳𝘦𝘵𝘳𝘪𝘦𝘷𝘢𝘭 𝘲𝘶𝘢𝘭𝘪𝘵𝘺. This one matters more than people think. No amount of clever prompting saves you if you retrieved the wrong chunks in the first place. 𝗚𝗮𝗿𝗯𝗮𝗴𝗲 𝗶𝗻, 𝗴𝗮𝗿𝗯𝗮𝗴𝗲 𝗼𝘂𝘁, no matter how polite your prompt is.

𝗧𝗵𝗶𝗿𝗱 𝗹𝗮𝘆𝗲𝗿 - 𝘵𝘳𝘢𝘯𝘴𝘱𝘢𝘳𝘦𝘯𝘤𝘺. Always return the actual source chunks alongside the answer. If the model does hallucinate, the user can check the claim against the cited text immediately. This one's not really a technical fix - it's a trust mechanism. You're not preventing the lie, you're making it easy to catch.

That third layer is the one I think gets underrated. Sometimes the most valuable engineering decision isn't solving the hard problem - it's making the unsolved part visible instead of hidden.

Sharing what I'm learning in public.

RAG #LLM #AI #PromptEngineering #LearningInPublic

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.

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.

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.