It can refer to other files, pull in instructions from different sources, and connect to other systems when needed. It operates beyond a simple prompt-response flow and acts more like a coding agent that can carry out a sequence of actions to get to an outcome.

Honestly, it is a really useful tool to have in your developer workflow. Here are some of the things I found useful while using it.

Adding Context to a Project for Claude

When working on a project, giving Claude the right context is key. Providing too much information at once can actually reduce its performance. Claude works best when instructions are structured clearly and concisely.

One way to set this up is by running the /init command in Claude on your project. This lets Claude analyse the entire codebase to understand the project’s purpose, architecture, important commands, critical files, coding patterns, and structure. After this analysis, Claude generates a summary and writes it to a Claude.md file, usually stored in the home directory of your project.

The Claude.md file serves two purposes. First, it guides Claude through the codebase by highlighting important aspects like coding style, architecture, and structure. Second, it allows you to include custom instructions for Claude. Every request you make to Claude automatically includes this file, acting like a persistent system prompt. Without it, you would need to repeat context in each prompt, which can be tedious.

The Claude.md file can exist in three locations:

1. Claude.md – Generated with the /init command, this version can be committed to version control and shared with other engineers.

2. Claude.local.md – Contains personal or private instructions that should not be shared.

3. ~/.claude/Claude.md – Applies to all projects on your machine, providing global instructions that Claude should always follow.

You can also add or edit instructions directly. Typing a hash (#) followed by a command, like # XYZ, updates the appropriate section in your Claude.md file. To reference files in your project, you can use the at sign (@) to point Claude to a specific file, either in your codebase or within your Claude.md file.

This system keeps Claude aligned with your project, ensures consistent behaviour, and allows for customisations without repeating instructions.

Modes

Two modes Claude can be used in are planning and thinking.

Planning mode is for reviewing what Claude intends to do before it actually executes a task. Instead of producing the implementation right away, it shows the steps it plans to take. This is especially useful for complex tasks that require extensive research across the codebase.

To enable planning mode, press Shift and tap twice. This prevents Claude from starting implementation immediately, so you can approve its plan first. If you already have auto-accept edits enabled, pressing Shift + Tab once also puts you in planning mode.

Thinking mode is for deeper analysis. It is triggered by keywords that control the depth of reasoning:

• think – basic reasoning

• think more – extended reasoning

• think a lot – comprehensive reasoning

• think longer – extended time reasoning

• ultra-think – maximum reasoning capacity

Use the thinking mode when you want Claude to analyse a problem deeply before addressing it. Planning mode, in contrast, focuses on broader research across the project rather than deep analysis.

Buy Fafa a coffee ☕️ 💰

You can combine both modes to guide Claude more intentionally, but doing so consumes more tokens. This combination helps you be deliberate about what changes are made, when they happen, and what to expect from those changes.

Managing Context with /compact

One command that becomes very useful for maintaining and controlling context in your conversations is the /compact command.

When you are working on a task over a long conversation, the context can build up quickly. You may not want to start a new thread, but at the same time, you might be done with the existing context in that conversation.

The /compact command solves this by compressing the entire conversation history into a summary. This frees up more context while still preserving the key information from what has already been discussed.

It is a practical way to continue working in the same conversation or transition into a new one without losing the important context you have built up.

Custom Commands

Claude comes with built-in commands that you can access by typing /. But you can also create your own custom commands.

This is especially useful for repetitive tasks where you want to maintain consistency in how things are done. Instead of rewriting the same instructions every time, you can define a custom command once and reuse it.

To set this up, you create a .claude folder in your project directory. Inside it, you create another folder called commands. For each custom command, you create a markdown file named after the command, for example command-name.md.

To use the command in Claude, you simply type /command-name.

You can also make these commands more flexible by passing arguments to them, such as file paths, text, or numbers. This allows you to adapt the command to different situations while keeping the structure consistent.

This approach helps you standardise workflows and repeatedly provide specific instructions as part of your context.

MCP Servers

MCP is a way to enhance the functionality of Claude Code and coding agents by giving them access to external software. Instead of figuring everything out on their own, they can leverage tools that already exist to perform specific tasks.

For example, if you want to interact with a database, run tests on your application, integrate with a development tool, or perform operations on your file system, there is already software designed for these use cases. MCP allows AI to access that software through MCP servers, rather than trying to handle everything itself.

To use an MCP server, you add it to your project using a command like claude mcp add followed by the server details. You can then manage permissions in the .claude/settings.local.json file, where you define what the server is allowed to do.

Once connected, you can simply reference the capability in your prompt. For example, if an MCP server is available for working with databases, you can ask Claude to build or connect to a database, and it will use that server to carry out the task.

This makes it easier to extend what Claude can do by plugging into tools that are already built for those functions.

Before discussing package management and dependency handling in a Python project, it helps to understand the basic building blocks Python uses to organise and reuse code. The Python documentation clearly defines modules, packages, and imports, but it does not explicitly define libraries or dependencies, even though these terms are commonly used in everyday development discussions. Understanding how these ideas relate to one another makes it easier to reason about project structure and dependency management.

Modules

A module is the simplest unit of organisation in Python. It is essentially a single Python file that contains code such as functions, classes, or variables.

Modules exist to organise code logically. Instead of writing everything in a single large file, you break your program into smaller files, with each module handling a specific responsibility.

Example:

# math_utils.py

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

This file is a module. Another Python file can use it by importing it.

import math_utils

result = math_utils.add(2, 3)

At the most basic level, modules are how Python organises code into manageable units.

Packages

A package is a collection of modules grouped into a directory so they can be organised and reused as a single unit.

Packages make it easier to structure larger projects and to distribute code that performs a specific function. If modules are individual files, packages are folders that contain related modules.

The key idea behind a package is shareability and reuse. Packages allow code that implements a specific functionality to be packaged in a way that others can install and import into their own projects.

Example package structure:

my_package/
    __init__.py
    math_utils.py
    string_utils.py

You can then import from that package:

from my_package import math_utils

In practice, packages are how most third-party functionality is distributed in Python. When you install something using pip, you are usually installing a package.

Example:

pip install django-debug-toolbar

After installing it, you can import it into your project because the package is now available in your Python environment.

So a useful way to think about it is:

• Modules organise code inside a file

• Packages organise modules into a reusable structure

Libraries

A library is generally a broader collection of packages and modules that provide related functionality.

Unlike the previous terms, “library” is not a strict technical construct defined by Python itself. It is more of a conceptual grouping used by developers to describe a large body of reusable code.

For example, Python ships with what is commonly called the standard library, which includes modules and packages that come pre-installed with Python.

Examples from the Python standard library include:

• datetime for working with dates and times

• json for working with JSON data

• os for interacting with the operating system

• math for mathematical operations

Example usage:

import datetime

now = datetime.datetime.now()

You do not need to install these because they come bundled with Python.

So in simple terms:

• A package is a structured unit of code distribution

• A library is a broader collection of packages and modules that provide related capabilities

Libraries often contain multiple packages.

Dependencies

A dependency is anything a project relies on to run correctly.

This term is less about code structure and more about project requirements. When we say a project has dependencies, we are referring to external packages or libraries that must be present for the application to function.

For example, if a web application uses Django and requests, those packages must exist in the environment before the application can run.

Example dependency list:

Django==4.2
requests==2.31.0
psycopg2==2.9.7

These dependencies are often recorded in files such as:

• requirements.txt

• pyproject.toml

• Pipfile

This allows other developers to recreate the same environment.

Example:

pip install -r requirements.txt

In that sense, dependency is a contextual term. It describes the relationship between your project and the external code it needs.

Putting It All Together

These concepts are closely related but operate at different levels.

• Module: A single Python file containing code.

• Package: A directory of modules organised so they can be reused and distributed.

• Library: A broader collection of packages and modules that provide related functionality.

• Dependency: Any external library or package that your project requires to run.

So when working on a real Python project, the flow often looks like this:

1. Developers write modules.

2. Modules are grouped into packages.

3. Packages may belong to a larger library.

4. When your project uses that library, it becomes a dependency of your project.

Managing your project packages efficiently

What actually makes a good package management workflow in Python?

There are many tools available today. Some are older and widely used, such as pip. Others are newer and attempt to solve problems that developers have historically struggled with. One of the most recent tools gaining attention is uv.

To reason about which tools are better, it helps to define the criteria that matter.

1. Usability

The first consideration is usability.

A good package management tool should be easy to understand and easy to use. The commands required to initialise a project, install dependencies, or update packages should not be overly complex.

Good documentation is also critical. Developers will inevitably run into issues such as dependency conflicts or installation errors. When that happens, clear documentation makes the difference between solving the issue quickly and spending hours debugging environment problems.

In practice, tools that require fewer steps and clearer commands tend to reduce friction in development workflows.

2. Virtual Environment Management

Another important factor is how the tool handles virtual environments.

Virtual environments isolate project dependencies so that different projects can use different packages or versions without interfering with each other.

For many beginners, this is one of the first confusing parts of Python development. It is very common to see developers install packages globally without realising that different projects may require different versions of the same dependency.

Some tools expect the developer to create and manage virtual environments manually. Others automatically create and manage environments as part of their workflow.

Understanding how a tool handles this isolation is important because environment issues are one of the most common causes of broken Python setups.

3. Python Version Management

Python version compatibility is another critical consideration.

Different packages support different Python versions. A dependency that works perfectly with Python 3.11 might not work with Python 3.8, and vice versa.

A good package management tool should allow a project to clearly define which Python versions it supports. This ensures that the environment used during development matches the environment used in production.

Without this control, it becomes very easy to accidentally create setups that work locally but fail when deployed elsewhere.

4. Dependency Management

The core responsibility of a package management workflow is tracking dependencies.

A project should have a clear and easily readable definition of the packages it depends on and their versions.

Developers should be able to add, remove, and inspect dependencies without manually editing configuration files or trying to infer what was installed previously.

Historically, many Python projects used a requirements.txt file for this purpose. However, tools like uv now rely on pyproject.toml, which has become the modern standard for defining project metadata and dependencies.

5. Reproducibility

Reproducibility is one of the most important properties of a production grade system.

When a developer clones a repository and installs its dependencies, the environment they create should behave exactly the same as the environment used by the original developers.

Without reproducibility, applications may work today but fail weeks or months later when dependency versions change.

This is where lock files become essential.

6. Collaboration

Finally, package management workflows should make collaboration straightforward.

Developers working on different operating systems such as macOS, Linux, or Windows should all be able to recreate the same environment.

A well defined dependency configuration and lock file ensure that every collaborator installs the exact same dependency graph, preventing the classic “it works on my machine” problem.

Why Modern Tools Like uv Are Gaining Popularity

Traditionally, Python developers relied on pip to install packages.

pip works well as a package installer, but it was never designed to manage an entire dependency workflow. As a result, developers often had to combine multiple tools together:

• pip for installing packages

• venv for creating virtual environments

• requirements.txt for tracking dependencies

This workflow works, but it requires manual steps.

For example, when using pip, developers often regenerate the dependency list manually using:

pip freeze > requirements.txt

This command captures the packages installed in the environment and writes them into the requirements file.

Modern tools like uv streamline this process.

uv integrates several pieces of functionality into a single workflow:

• installing packages

• managing virtual environments

• resolving dependencies

• maintaining dependency definitions

• generating lock files

It also performs dependency resolution extremely quickly. Because uv is implemented in Rust, it can resolve dependencies dramatically faster than traditional Python based tooling, often by an order of magnitude.

Instead of manually updating dependency files, uv automatically records project dependencies in the pyproject.toml file when new packages are added.

For example:

uv add fastapi

This command both installs the dependency and updates the project’s dependency definition.

Why Lock Files Matter

One of the most important features introduced by modern dependency managers is the lock file.

A dependency definition file such as pyproject.toml usually describes the acceptable versions of dependencies.

For example:

fastapi >=0.110

This means any compatible version of FastAPI can be installed.

However, dependencies themselves have their own dependencies. Over time, newer versions of those packages may be released. This can lead to different combinations of packages being installed at different times.

A project that worked perfectly today might fail months later because one of the indirect dependencies has changed.

A lock file solves this problem.

Instead of describing acceptable ranges, the lock file records the exact versions of every dependency in the entire dependency graph, including transitive dependencies.

For example:

fastapi 0.110.0
pydantic 2.6.1
typing_extensions 4.9.0

Because these versions are pinned, every environment created from the lock file will install the exact same package versions.

This guarantees that the environment used by one developer will match the environment used by another developer, as well as the environment used in production.

In uv, this information is stored in the uv.lock file.

When this file is committed to version control, anyone working on the project can recreate the same environment deterministically.

This dramatically reduces environment related bugs and makes Python applications far more reliable to build and maintain.

Actually Using uv in a Project

After understanding why dependency management matters and why modern tools like uv are becoming popular, the next step is very simple: actually using it in a project.

One of the things I like about uv is that the workflow is straightforward. The commands are minimal, and the tool handles a lot of the environment and dependency management automatically.

Initialising a Project

The first step is to initialise uv inside your project directory.

uv init

Running this command sets up the project for dependency management. It creates the necessary project configuration so that uv can track dependencies and manage the environment for the project.

In most cases, this will create or configure the pyproject.toml file, which is where the project metadata and dependency definitions live.

Adding Dependencies

Once the project is initialised, dependencies can be added using the uv add command.

uv add fastapi

This installs the package and automatically records the dependency in the project’s configuration.

At the same time, uv generates a lock file called:

uv.lock

This file captures the exact versions of all dependencies, including transitive dependencies. Because of this, the environment can be recreated exactly the same way across different machines.

Unlike older workflows where dependency files often needed to be manually updated, uv updates the project definition automatically when new packages are added.

Grouping Dependencies

Another useful feature is dependency grouping.

Not all dependencies serve the same purpose. Some are required for running the application, while others are only needed for development tasks such as testing or linting.

uv allows dependencies to be grouped so that they are organised more clearly.

For example:

uv add --group dev pytest

This adds pytest to a development dependency group instead of the main runtime dependencies.

Structuring dependencies this way keeps the project configuration cleaner and makes it easier to understand which packages are required for which part of the workflow.

Running Commands with uv

To run commands within the project’s managed environment, uv provides the uv run command.

uv run python app.py

This runs the command using the environment that uv manages for the project. All dependencies defined in the project configuration and lock file are available when the command executes.

This removes the need to manually activate virtual environments before running scripts. uv ensures the correct environment is used automatically.

Why This Workflow Works Well

What stands out to me about uv is how it simplifies several steps that historically required multiple tools.

Instead of juggling environment creation, package installation, dependency tracking, and lock files separately, uv brings these pieces together into a single workflow.

The result is a setup that is easier to reason about, easier to reproduce, and much less prone to the environment issues that Python developers have traditionally struggled with.

For a production project where reproducibility and collaboration matter, that is a significant improvement.

Glossary and Definitions

Based on Offical Python docs.

namespace: The place where a variable is stored. Namespaces are implemented as dictionaries. There are the local, global and built-in namespaces as well as nested namespaces in objects (in methods). Namespaces support modularity by preventing naming conflicts.

importing: The process by which Python code in one module is made available to Python code in another module.

For me, that moment happened while working on an endpoint that generated a report. On the surface, the code looked perfectly fine. The endpoint returned a structured output assembled from several related models. It worked locally. It returned the correct data. Everything seemed normal.

Until I inspected the SQL queries.

That single API request triggered 627 database queries to generate a report for just five experiment objects.

At that point, I realised something important. As backend engineers, it is not enough for an API to work. We also need to understand how it works at the database level.

This post walks through the exact thought process I used to investigate the problem and reduce those queries to 9. If you build APIs with Django, you will eventually run into this pattern.

The Scenario

Imagine we are building a research platform.

Researchers submit studies. Each study has experiments. Each experiment records observations. Observations can contain notes and references to datasets.

Now, imagine we want to generate a research report for a study.

The report needs to include:

• experiments

• observations

• notes

• datasets referenced

All nested under the study.

Data Models

Here is a simplified version of the models.

class Study(models.Model):
    title = models.CharField(max_length=200)
    created_at = models.DateTimeField()


class Experiment(models.Model):
    study = models.ForeignKey(
        Study,
        related_name=”experiments”,
        on_delete=models.CASCADE
    )
    title = models.CharField(max_length=200)


class Observation(models.Model):
    experiment = models.ForeignKey(
        Experiment,
        related_name=”observations”,
        on_delete=models.CASCADE
    )
    description = models.TextField()


class Note(models.Model):
    observation = models.ForeignKey(
        Observation,
        related_name=”notes”,
        on_delete=models.CASCADE
    )
    text = models.TextField()


class DatasetReference(models.Model):
    observation = models.ForeignKey(
        Observation,
        related_name=”datasets”,
        on_delete=models.CASCADE
    )
    dataset_name = models.CharField(max_length=200)

Entity Relationship Overview

You can visualise the relationships like this:

Study
  |
  └── Experiment
        |
        └── Observation
              |        \
              |         \
              |          \
            Note     DatasetReference

This kind of hierarchy is very common in real systems.

Buy Fafa a Coffee ☕️ 💰

The Reporting Endpoint

Now we build an API endpoint that generates a report for a study.

class StudyReportView(APIView):

    def get(self, request, study_id):
        study = get_object_or_404(Study, id=study_id)

        report = []

        for experiment in study.experiments.all():
            for observation in experiment.observations.all():

                notes = [n.text for n in observation.notes.all()]
                datasets = [d.dataset_name for d in observation.datasets.all()]

                report.append({
                    “experiment”: experiment.title,
                    “observation”: observation.description,
                    “notes”: notes,
                    “datasets”: datasets
                })

        return Response(report)

At first glance, this code is perfectly readable. Nothing seems obviously wrong.

But the problem is hidden in the loops.

Every .all() triggers a database query.

The Hidden N+1 Problem

Let’s assume this study contains:

• 5 experiments

• 25 observations

• 75 notes

• 50 dataset references

Without optimisation, Django performs queries like this:

1 query → load experiments
5 queries → load observations for each experiment
25 queries → load notes
25 queries → load dataset references
75 queries → load related datasets
490 repeated nested queries from loops

Total:

627 queries

And this grows quickly as the dataset grows.

In a real system, this can easily become hundreds or thousands of queries.

Detecting the Problem with Django Debug Toolbar

The easiest way to inspect this is the Django Debug Toolbar.

Install it:

pip install django-debug-toolbar

Add it to INSTALLED_APPS and middleware.

Then run your API locally and open the endpoint in your browser.

The toolbar appears on the right side of the page.

Click SQL.

You will see something like this:

Total queries: 627
Duplicate queries: 598

Scrolling through the queries usually reveals the pattern immediately.

SELECT ... FROM observation WHERE experiment_id = 1
SELECT ... FROM observation WHERE experiment_id = 2
SELECT ... FROM observation WHERE experiment_id = 3
SELECT ... FROM observation WHERE experiment_id = 4
SELECT ... FROM observation WHERE experiment_id = 5

That repetition is the classic N+1 query problem.

Why This Happens

When Django encounters this line:

experiment.observations.all()

It runs a query.

If you do that inside a loop, Django runs the same query structure repeatedly.

1 query for experiments
N queries for observations
N queries for notes
N queries for datasets

The database is doing unnecessary work.

The Fix: Prefetch Related

Django provides a built-in way to solve this.

prefetch_related

It tells Django to fetch all related objects in bulk before the loop runs.

Instead of querying one object at a time, Django loads everything into memory first.

Optimized Query

Update the queryset like this:

study = (
    Study.objects
    .prefetch_related(
        “experiments”,
        “experiments__observations”,
        “experiments__observations__notes”,
        “experiments__observations__datasets”
    )
    .get(id=study_id)
)

Now Django runs a small number of queries.

1 query -> study
1 query -> experiments
1 query -> observations
1 query -> notes
1 query -> datasets

Total:

5 queries

That is a massive reduction.

What Changed

Instead of this pattern:

Loop → Query
Loop → Query
Loop → Query

Django now does this:

Query everything once
Serve related objects from memory

The loops remain the same. Only the queryset changed.

What to Look For During Debugging

When debugging database performance in Django APIs, I now follow a simple checklist.

1. Open the endpoint locally with Django Debug Toolbar.

2. Inspect the SQL panel.

3. Look for repeated queries.

4. Identify which relationship causes them.

5. Add prefetch_related or select_related.

6. Run the request again and compare query counts.

A healthy endpoint usually executes single-digit queries for most operations.

The Result

In the case that triggered this investigation, the numbers looked like this:

Before optimisation:

627 queries

After optimisation:

9 queries

Same endpoint. Same output. Just a better use of the ORM.

A Habit I Now Follow Before Merging Backend Code

Before merging any endpoint that assembles nested data, I now do three things:

1. Run the endpoint locally.

2. Inspect SQL queries with Django Debug Toolbar.

3. Confirm the query count is reasonable.

This small habit has saved me from shipping inefficient endpoints more than once.

Final Thoughts

This experience reinforced something easy to forget when writing application code.

Code can look perfectly reasonable and still generate hundreds of unnecessary database queries.

The Django ORM is powerful, but it hides a lot of complexity. If you do not occasionally inspect what SQL is actually being executed, performance issues can slip in without you noticing.

The Django Debug Toolbar is one of the simplest tools you can add to your workflow. It gives immediate visibility into how your views interact with the database.

If you are building APIs, especially ones that assemble nested data structures, it is worth checking your query counts before merging your code.

Your future self and your database will thank you.

“What AI tools should I learn?”

“How do I actually build with AI?”

“Is it too late to get into this space?”

“What skills really matter anymore?”

That’s why I wrote _Human + Machine: Practical Skills to Build, Ship, and Grow with AI_. (discount codes to download for FREE at the end of this post)

I kept noticing a gap between understanding AI agents, automation, and generative models and actually confidently using them. There’s also a gap between fear of being replaced and learning how to become more capable by leveraging AI.

Before anyone can build with AI, critique it, or contribute meaningfully to any AI discussion, they need solid foundational AI knowledge. This is where this book begins. We break down generative AI, agents, computer vision, speech systems, natural language processing, information extraction, and decision support in simple terms (what they are, how they’re used, and where they appear in real life).

For example, understanding how generative AI has transformed work (by allowing people to generate code, analyse data, draft technical documentation, and prototype ideas in hours instead of weeks) is just as important as knowing what these systems can’t reliably do. They can’t deeply understand context like humans do, take full responsibility, make complex architectural trade-offs with lived judgment, or navigate ambiguity with intuition.

That gap isn’t a weakness. It’s the point. It’s where humans still play a vital role.

That’s why this book exists. It enables individuals to navigate the current AI landscape as both consumers and builders, adopting it as a tool in new and emerging tech careers.

What’s Inside the Book

Staying Valuable in the Age of AI

This chapter is about mindset and strategy. It answers the hard questions people are quietly asking about their careers. How do you stay relevant when AI can write code, draft documents, and automate tasks? What skills still matter?

We break down the human advantages that remain critical. Judgment. Context. Responsibility. Clear thinking. You will also learn practical strategies for working with AI in a way that improves your output without turning you into a copy-and-paste engineer. The focus is simple. Use AI to raise your standard, not lower it.

Using AI to Improve Your Tech Skills

Here, AI becomes a practical tool for growth. You will learn how to use it as a senior colleague who reviews your ideas, challenges your assumptions, and helps you learn faster. We cover communication, documentation, prototyping, feedback, and automation with clear examples of how to actually do it.

This chapter shows you how to structure prompts, refine your thinking, clean up your writing, and accelerate your learning. The goal is skill amplification, not dependency.

Using AI to Build Software

This section walks through the full journey from idea to shipped product. From defining a problem and writing clear specifications, to thinking through architecture and trade-offs, to implementing and reviewing code.

We also address vibe coding directly. When it works. When it fails. How to debug AI-generated code and avoid confidence errors. You will learn how to review outputs critically and maintain quality. We also introduce AI agents and integrations so you understand what they actually do and how to use them responsibly.

Prompt Engineering

If AI is a tool, prompting is the interface. This chapter focuses on how to give clear instructions, break complex tasks into smaller steps, iterate on responses, and evaluate results properly.

We cover practical techniques such as providing context, organising prompts, versioning them, and improving them over time. The emphasis is on clarity and control so you can consistently get useful results instead of random outputs.

New Careers in the AI Era

AI is not only changing tasks. It is reshaping roles. In this chapter, we map out emerging career paths such as AI engineer, AI agent systems engineer, AI creator, AI governance and policy specialist, and AI-focused founders.

For each path, we explain what the role involves, why it exists now, the skills that transition well, and how to become job-ready. You get a realistic view of what these careers look like and how to position yourself for them.

What To Do Next

The book closes with direction. How to learn AI professionally. How to practice intentionally. How to assess your own usage and improve it over time.

How to Get the Book

Human + Machine: Practical Skills to Build, Ship, and Grow with AI is available directly from my personal online shop.

If you purchase through my shop, you can use one of the discount codes below at checkout.

These are first-come, first-served:

• AIWITHFAFA31 — 100% off (25 copies available)

• AIWITHFAFA30 — 75% off (50 copies available)

• AIWITHFAFA29 — 50% off (75 copies available)

• AIWITHFAFA28 — 25% off (100 copies available)

Download for FREE 🆓

If a code does not work, it means all available uses have been claimed. Once the codes are gone, the book will return to its standard price of £20 in my shop.

The book is also available on Amazon in both e-book and paperback formats. If you are subscribed to Kindle Unlimited, you can read it for FREE as part of your subscription. If not, the Kindle edition and paperback are available worldwide for £20. You can also download and read a FREE sample on Amazon to get a feel for the book before deciding to purchase.

Buy on Amazon 💰

If you have any issues accessing the book in your region, send me an email, and I will help. And if cost is a barrier, reach out, and we can talk.

If you do read it, I would genuinely value your feedback. Leave a review, send a message, or reply to this post. I want this book to be useful, practical, and worth your time.

That’s it. If you’ve been thinking about taking AI seriously, this is a good place to start.

Share

RAG. RAG. RAG.

I’ve written about it before, and I’ll say it again: Retrieval-Augmented Generation (RAG) is everywhere right now. And honestly, you can’t really call yourself an AI engineer today if you don’t know how to connect your own data to an LLM. That’s the entire point of RAG.

At its core, RAG is about grounding LLM responses in your data. Not generic internet knowledge. Not hallucinated guesses. Actual, specific, proprietary context.

And that’s exactly what makes it so powerful and so unavoidable.

Why RAG Matters (Especially for Enterprises)

A classic RAG use case is within enterprise organisations that want AI systems (chatbots, internal tools, or full-blown AI agents) to produce reliable, grounded answers from a defined data set.

That data might be:

• Internal documents (PDFs, text files)

• Chat histories

• Knowledge bases

• Proprietary databases

Large language models like ChatGPT or Claude are impressive, but they’re not tailored to your business out of the box. They don’t know your internal processes, your data definitions, or your source of truth.

So if you want context-aware responses that are only based on your data, you need RAG. More specifically, you need agentic retrieval, where the system decides what to retrieve, when, and how to use it to answer a query.

The Project: Conversational Search Over Spotify Artist Data

To level up my hands-on experience with RAG, vector data, and agentic retrieval, I built a small but practical application: a conversational search experience over a knowledge base.

The idea was simple:

• Take a real dataset

• Index it properly

• Let users “chat” with the data using natural language

The Data

I used a Spotify artists dataset from Kaggle. It’s a CSV file containing information for over 70,000 artists, including:

• Spotify ID

• Artist name

• Number of followers

• Popularity score

• Genres

• Main genre

The goal was to build a chatbot that could answer questions like:

“Which artists in this genre have the most followers?”
“How popular is this artist compared to others?”

All answers needed to come only from the dataset. No external knowledge.

The Stack: Azure AI Search + Microsoft Foundry

This project uses Azure’s RAG-friendly tooling to wire everything together.

We’re building a conversational search experience powered by:

• Azure AI Search for indexing, vector search, and agentic retrieval

• Microsoft Foundry for embeddings and LLM reasoning

What Is Azure AI Search?

Azure AI Search is a fully managed, cloud-hosted search service that supports both:

• Traditional keyword-based search

• Vector and semantic search for LLM-assisted retrieval

It handles a lot of the heavy lifting for RAG:

• Chunking

• Vectorisation

• Indexing

• Semantic relevance

Getting Started: Setup and Configuration

Before writing any code, there’s a fair bit of setup involved.

What You’ll Need

• An Azure account

• Azure AI Search service

• A Microsoft Foundry project

• Azure CLI

• A programming IDE (I used PyCharm)

When you create an Azure account, you get $200 in free credits, which is more than enough to experiment with a project like this. That’s exactly what I used.

Configuration Steps

At a high level, the setup looks like this:

1. Create an Azure AI Search resource in the Azure Portal

2. Set up a Microsoft Foundry project

3. Install and authenticate Azure CLI locally

4. Ensure your CLI has permission to access both resources

You’ll also need to grab the endpoints for:

• Azure AI Search

• Microsoft Foundry

These endpoints are unique URLs that provide network access to the services, and you’ll store them as environment variables in your project.

Models Used

This project uses two models:

• Embedding model for text-to-vector conversion

  • text-embedding-3-large (3072 dimensions)

• LLM for query planning and answer generation

  • GPT-5-mini (though any supported Foundry model works)

The LLM serves two purposes:

• Planning the retrieval query

• Generating the final answer

Development Flow

Once authenticated via az login, the actual development work begins.

Dependencies

The core libraries used are:

• azure-identity

• azure-search-documents

• langchain

Additional Python dependencies are listed in the project’s requirements.txt.

Preparing the Data

The Kaggle dataset is downloaded as a CSV file with 70k+ rows. Each row includes:

• ID

• Artist name

• Followers

• Popularity

• Genre

• Main genre

If you don’t want to work with the full dataset, you can easily subset it (e.g., first 100 rows) for faster iteration.

CSV to JSON

Before indexing, the CSV data is converted to JSON using a simple script. The JSON structure uses the CSV headers as field names:

• id

• name

• followers

• popularity

• genre

• main_genre

This format makes it easier to generate embeddings and upload documents.

Indexing and Vector Search

With the data ready, the next step is writing a Python script that can:

• Create a search index

• Upload documents

• Create a knowledge source

• Create a knowledge base

• Run the retrieval pipeline

• Maintain conversational context

Creating the Search Index

The search index defines both the fields and the search behaviour. It supports vector and semantic search.

Key fields include:

• ID

• Artist text

• Artist embedding (3072-dimensional vector)

• Artist number

Uploading Documents

For each artist, we construct a readable text representation by combining fields like:

• Name

• Main genre

• Follower count

• Popularity

• Additional genres

This text becomes the basis for embeddings.

Embeddings are generated using LangChain’s embed_query method, producing a vector of floats for each artist. All of this (text, vectors, metadata) is uploaded into the search index.

From the Azure AI Search resource, we can search for information.

Knowledge Base and Agentic Retrieval

Once indexing is complete:

1. A knowledge source is created from the search index

2. A knowledge base is built on top of that source

This knowledge base becomes the system’s source of truth.

When a user asks a question, we use the Knowledge Base Retriever classes to ensure:

• Queries are grounded in the indexed data

• Retrieval happens semantically, not just via keywords

• The system responds “I don’t know” when no relevant data exists

This is where embeddings really matter. Semantic similarity allows the system to match user intent to the most relevant indexed entries even when the wording isn’t exact.

Wrapping Up

The frontend for this project is built with Streamlit, which makes it easy to test and iterate on the conversational experience.

That’s the full pipeline:

• Data → vectors → index

• Index → knowledge base

• Knowledge base → grounded conversational search

If you want to try something similar, Azure’s Quickstart documentation is genuinely helpful for understanding how agentic retrieval works end to end.

You can also view my full project code on GitHub if you’d like to replicate this project.

RAG isn’t just a buzzword. It’s the backbone of practical, trustworthy AI systems. And once you’ve built one of these pipelines yourself, it becomes very clear why everyone keeps talking about it.

I know this because I just did it.

I built an end-to-end pipeline that takes text as input, runs it through a trained ML model, and returns a prediction through a web interface. No deep learning yet. Just a clean, working MVP that proved a point to myself: this is doable.

The Tech Stack

Here’s what I used to make it happen:

• Backend: FastAPI + Uvicorn

• ML: Scikit-learn (TF-IDF + Logistic Regression), Joblib

• Frontend: HTML + Vanilla JS + Jinja2

• Data: Google Trends CSV export (UK, last 7 days)

The Idea: Can We Predict If a Topic Will Trend?

While reviewing Google Trends data, I had a simple thought:

What if I could build an app that predicts whether a given topic will trend or not?

That’s it. That curiosity alone was enough to justify building a small experiment.

Now, a big caveat upfront:
This model still needs a ton of work.

• It was trained on ~1,800 rows of data

• The labelling logic is based on a simple heuristic I came up with

• The goal wasn’t perfection—it was learning

This is very much an MVP. A baseline. Something to confirm assumptions quickly before investing more time and complexity.

Understanding the Data

From the Google Trends homepage, you can export trend data based on filters. I exported:

• Region: UK

• Time range: Past 7 days

• Category: All

• Trends: All

This produced a CSV file with 1,881 rows and the following columns:

• Trends

• Search volume

• Started

• Ended

• Trend breakdown

• Explore link

Is this enough data to build a production-grade system? Absolutely not.
Is it enough to test an end-to-end ML pipeline? Perfectly.

That’s the key distinction.

Defining “Trending”: Start Simple or Don’t Start at All

Before touching the data, I had to answer an important question:

How do we decide if a topic actually “trended”?

For this first version, I used a very simple heuristic:

If search volume is high, then the topic is trending.

Why? Because if a lot of people are repeatedly searching for a phrase at a specific time, it’s clearly important at that moment.

Now, that “at that moment” part is crucial.
A more robust definition should factor in duration, velocity, and decay. But I intentionally ignored all of that for now.

Good ML practice isn’t about cramming every possible signal into v1. It’s about:

• Starting simple

• Monitoring outputs

• Iterating with intent

Trying to build a “perfect” model from the start is a big no-no.

Buy Fafa a Coffee ☕️ 💰

Step 1: Loading the Data

First, I loaded the CSV into a Pandas DataFrame and did some basic sanity checks to make sure everything looked right.

# =========================================
# STEP 1: ROBUST CSV LOADING
# =========================================
script_dir = os.path.dirname(os.path.abspath(__file__))
csv_filename = 'trending_GB_7d_20260113-1342.csv'
csv_path = os.path.join(script_dir, csv_filename)

if not os.path.exists(csv_path):
    print(f"❌ {csv_filename} not found in {script_dir}")
    print("Available CSV files:")
    csv_files = [f for f in os.listdir(script_dir) if f.endswith('.csv')]
    print(csv_files)
    exit(1)

df = pd.read_csv(csv_path)
print(f"✅ Loaded {len(df)} rows from {csv_path}")
print("\nSample data:")
print(df[['Trends', 'Search volume']].head())

Step 2: Cleaning and Feature Engineering

It’s never good practice to assume data is clean.

While reviewing the CSV, I noticed:

• Missing values

• Non-English text

• Inconsistent formatting

This was manageable with ~1.8k rows, so just by visual inspection, I could see that the data needed to be cleaned.
Scale this to hundreds of thousands (or millions) and… yeah, bruh (I’m in danger).

I cleaned and combined the main trend text with its top related terms:

# =========================================
# STEP 2: FEATURE ENGINEERING
# =========================================
def clean_trend(row):
    """Extract main trend + top 5 related terms"""
    trend = str(row['Trends']).strip('" ')
    breakdown = str(row['Trend breakdown']).strip('" ') if pd.notna(row['Trend breakdown']) else ''
    related_terms = re.split(r'[,\s]+', breakdown)
    related = ', '.join([t.strip().lower() for t in related_terms[:5] if t.strip()])
    return f"{trend.lower()} {related}".strip()

df['text'] = df.apply(clean_trend, axis=1)

Step 3: Labelling the Data (and Discovering Imbalance)

To train the model, I needed a target column: trending.

• 1 → Trending

• 0 → Not trending

I defined trending as search volumes of 100K+ and above.

# =========================================
# STEP 3: TRUE TRENDING LABELS (100K+ ONLY)
# =========================================
def is_trending(vol):
    """1 = Viral (100K+), 0 = Not"""
    vol_str = str(vol).strip('" ').upper()
    high_volumes = ['100K+', '200K+', '500K+', '1M+']
    return 1 if any(hv in vol_str for hv in high_volumes) else 0

df['trending'] = df['Search volume'].apply(is_trending)

df = df[df['text'].str.len() > 10].copy()
print(f"\n📊 After cleaning: {len(df)} rows")
print("Class distribution:")
print(df['trending'].value_counts())
print(f"Trending %: {df['trending'].mean():.1%}")

After cleaning, I had ~1.7k rows.

Here’s the interesting (and problematic) part:
Only ~2.1% of the data was labelled as trending.

That means a naïve model could be “accurate” by predicting Not Trending every time and still be useless.

I didn’t solve this fully yet, but I accounted for it during training.

Step 4: Train/Test Split

I separated inputs and labels and used stratification to ensure both sets preserved the class imbalance.

# =========================================
# STEP 4: TRAIN/TEST SPLIT
# =========================================
X = df['text']
y = df['trending']

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.25, random_state=42, stratify=y
)

print(f"\nTrain: {len(X_train)} | Test: {len(X_test)}")

Step 5: Training the Model

• TF-IDF converts text into numerical vectors, removing common stop words

• Logistic Regression learns word weights associated with trending likelihood

• class_weight='balanced' prevents the model from defaulting to “Not Trending”

# =========================================
# STEP 5: PRODUCTION PIPELINE
# =========================================
pipeline = Pipeline([
    ('tfidf', TfidfVectorizer(
        max_features=5000,
        stop_words='english',
        ngram_range=(1, 2),
        min_df=1
    )),
    ('clf', LogisticRegression(
        random_state=42,
        max_iter=3000,
        class_weight='balanced',
        C=1.5
    ))
])

print("\n🚀 Training model...")
pipeline.fit(X_train, y_train)

Step 6: Evaluation

The model outputs:

• A hard prediction: 1 or 0

• A probability score (confidence)

# =========================================
# STEP 6: EVALUATION
# =========================================
y_pred = pipeline.predict(X_test)
y_proba = pipeline.predict_proba(X_test)[:, 1]

accuracy = accuracy_score(y_test, y_pred)
print(f"\n✅ Accuracy: {accuracy:.3f}")

print("\n📈 Classification Report:")
print(classification_report(y_test, y_pred, target_names=['Not Trending', 'Trending']))

Step 7: Saving the Model

Using joblib I saved both the trained pipeline and some metadata for later use.

# =========================================
# STEP 7: SAVE MODEL
# =========================================
joblib.dump(pipeline, 'trend_model.joblib')

metadata = {
    'accuracy': accuracy,
    'classes': pipeline.classes_.tolist(),
    'n_features': len(pipeline.named_steps['tfidf'].get_feature_names_out()),
    'train_pos_ratio': y_train.mean()
}

joblib.dump(metadata, 'model_metadata.joblib')

print("\n💾 SAVED:")
print("  trend_model.joblib  ✅")
print("  model_metadata.joblib ✅")

Serving the Model with FastAPI

The rest was fairly straightforward.

Using FastAPI, I created a simple backend with a /predict endpoint that loads the model and returns predictions.

# Load model
model = joblib.load('trend_model.joblib')

@app.get("/", response_class=HTMLResponse)
async def predict_form(request: Request):
    return templates.TemplateResponse("index.html", {"request": request})

@app.post("/predict", response_class=HTMLResponse)
async def predict(request: Request, text: str = Form(...)):
    prediction = model.predict([text.lower()])[0]
    prob = model.predict_proba([text.lower()])[0][1]

    result = "WILL trend" if prediction == 1 else "will NOT trend"
    confidence = f"{prob:.2%}"

    return templates.TemplateResponse("index.html", {
        "request": request,
        "prediction": result,
        "confidence": confidence,
        "input_text": text
    })

Trying It Out

I built a very simple frontend where you can input any text and get a prediction.

Of course, the model’s outputs are entirely constrained by:

• Limited data

• A narrow heuristic

• Text-only features

But that’s fine. That’s the point.

Conclusion

This project was a great experiment in building and deploying an end-to-end ML pipeline.

It doesn’t predict the future.
It doesn’t forecast growth.

What it does do is text-based trend classification, and for an MVP, that’s more than enough.

More importantly, it reinforced a key lesson for me:

You don’t need a perfect model to start.
You need a working one.

View the full project code on GitHub.

Share

I just built a data pipeline and it’s publicly available for anyone who wants to explore it.

“Data is the new oil.”
“Knowledge is power.”

And if that’s true… then let me have my moment. (Yes, I am king 🙂).

If you’ve ever wanted to know what Nigerians are talking about at any given time (what’s trending, what’s controversial, what’s getting people really talking) I’ve got you covered.

This project pulls live data from Reddit to surface trending topics in the Nigerian space, stores it in a database, and visualises it through a dashboard.

The Idea: Why This Pipeline Exists

The core idea is:

Collect first-hand signals about what Nigerians are discussing online and make that data accessible.

I used:

• API requests

• Data analysis and visualisation

The goal is to make this information useful for businesses, organisations, institutions or anyone who needs insight into what’s happening or being discussed in Nigeria right now.

The project is basically just clean data sourcing and collection with structure, and visibility.

The Database: Why I Chose Supabase

For storage, I used Supabase and honestly, it was a great choice.

Why?

• Cloud-based

• Free tier

• Easy to set up

• PostgreSQL under the hood

After creating a Supabase project, I set up a database and created a table called reddit_posts using SQL:

CREATE TABLE IF NOT EXISTS reddit_posts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    subreddit TEXT NOT NULL,
    title TEXT NOT NULL,
    upvotes INTEGER,
    comments INTEGER,
    author TEXT,
    permalink TEXT UNIQUE,
    created_utc TIMESTAMP,
    collected_at TIMESTAMP DEFAULT NOW()
);

The schema mirrors the structure of Reddit’s response data.

Data Sourcing: Pulling Posts from Reddit

Fetching data from Reddit turned out to be surprisingly seamless.

Reddit allows access via HTTP requests using Python’s requests library. I targeted the Nigeria subreddit and pulled the posts for each day, capped at 100 posts per request.

Key settings:

• Subreddit: nigeria

• Time filter: day

• Limit: 100

Here’s the core setup:

SUBREDDIT = "nigeria"
TIME_FILTER = "day"
LIMIT = 100
REDDIT_USERNAME = os.getenv("REDDIT_USERNAME")

REDDIT_URL = f"https://www.reddit.com/r/{SUBREDDIT}/top/.json?t={TIME_FILTER}&limit={LIMIT}"
HEADERS = {"User-Agent": f"trend-scraper/0.1 by {REDDIT_USERNAME}"}

And the fetch function:

def fetch_reddit_posts():
    response = requests.get(REDDIT_URL, headers=HEADERS, timeout=10)
    response.raise_for_status()
    return response.json()["data"]["children"]

Each post is then inserted into the database using an INSERT statement with conflict handling on the permalink:

INSERT INTO reddit_posts (
    subreddit, title, upvotes, comments, author, permalink, created_utc
)
VALUES (%s, %s, %s, %s, %s, %s, %s)
ON CONFLICT (permalink) DO NOTHING;

This ensures we don’t store duplicates.

Buy Fafa a Coffee ☕️ 💰

Displaying the Data: Streamlit + Pandas

To make the data usable, I built a Streamlit dashboard.

Once connected to the database, I:

• Queried the reddit_posts table

• Loaded the results into a Pandas DataFrame using SQLAlchemy

From there, the fun began.

With the data in a DataFrame, I could:

• Show total number of posts collected

• Calculate average upvotes

• Calculate average number of comments
  (These folks really be yapping.)

total_items = len(df_filtered)
avg_upvotes = int(df_filtered[”upvotes”].mean()) if total_items > 0 else 0
avg_comments = int(df_filtered[”comments”].mean()) if total_items > 0 else 0
col1.metric(”Total posts”, total_items)
col2.metric(”Avg upvotes”, avg_upvotes)
col3.metric(”Avg comments”, avg_comments)

Filtering and Exploring Trends

I added a filter that lets users select posts based on minimum upvotes. This makes it easier to focus on high-engagement content.

The UI displays:

• Post title

• Upvotes

• Comments

• Author

• Created date

This allows users to inspect the raw data before jumping into charts.

Visualising the Data

I used Plotly for interactive charts.

1. Upvotes Distribution

A bar chart showing:

• X-axis: Number of upvotes

• Y-axis: Number of posts

This helps answer questions like:

How many posts actually get significant engagement?

2. Posts Over Time

Another chart groups posts by day using the created_at field:

• X-axis: Date

• Y-axis: Number of posts

This makes it easy to spot spikes or drops in activity over time.

Exporting the Data

If someone wants the raw data, they can export it.

A download button:

• Takes the filtered DataFrame

• Saves it as a CSV file

• Uses the default name: filtered_reddit_trends.csv

Automation: Keeping the Data Fresh

A data pipeline isn’t much use if it goes stale.

To keep things updated, I set up a cron job on my local machine that runs the data-fetching script daily at a fixed time.

This ensures:

• The database is continuously populated

• Charts update automatically as new data comes in

• Trends evolve naturally over time

Next Steps: Making It More Robust

Running cron jobs on my personal laptop isn’t ideal.

What happens if:

• My PC is turned off?

• I forget to run it?

• Something crashes silently?

A better solution:

• Convert the script into an AWS Lambda function

• Use AWS EventBridge to trigger it daily

That would significantly reduce the risk of missed updates and make the pipeline more production-ready.

However, ain’t nobody got money for this. 🤦‍♀️

Conclusion

So, there we have it.

I built a free, end-to-end data pipeline that:

• Collects trending topics in the Nigerian space using Reddit data

• Stores them in a structured database

• Automates ingestion over time

• Visualises trends through a Streamlit dashboard

• Allows data export for further analysis

Core Python and Data libraties used are;

• os - Environment variables

• requests - HTTP API calls to Reddit JSON endpoint

• psycopg2 - PostgreSQL database connection

• datetime - Timestamp handling

• dotenv - Load .env files

• pathlib - File path resolution

• streamlit - Web dashboard framework (st, @st.cache_data)

• pandas - Data processing (pd.read_sql, DataFrames)

• matplotlib.pyplot - Charts (plt.subplots, st.pyplot)

• sqlalchemy - Database ORM (create_engine)

This project helped me to connect a lot of dots from database design, to data ingestion, to automation and to visualisation.

Would you like access to the data or the project code?
Let me know in the comments, and I’ll make it available.

Share

How do I know this model will actually solve the problem in the product I’m building?

This is where many ML projects quietly fail. Not because the model is bad, but because “success” was never clearly defined. That’s why metrics and planning are the foundation of any useful ML system and not just bureaucratic overhead.

Before writing a single line of training code, you need to decide how you’ll judge whether the model is doing a good job.

Defining What “Good” Means in an ML Product

Before you start building, ask yourself:

What metrics will I use to decide if my model is producing good results?

Broadly, four categories of performance determine whether an ML model is actually useful in a product.

1. Business Performance: Does the Model Make the Product Better?

If the problem your model is solving is clearly defined, then business metrics often tell you whether the model is succeeding.

For example, imagine building a recommender system for an entertainment app like Netflix or Spotify. The real question to judge model accuracy becomes:

• How often do users click on recommendations?

• How frequently do they skip them?

• Do recommendations increase watch time, listens, or retention?

To measure this, the product itself needs to capture user interactions. The UI has to log whether recommendations are accepted or ignored. Without this feedback loop, you can’t connect model outputs to real-world impact.

Business performance is usually something you only see after deployment, but that doesn’t make it optional.

2. Model Performance: Do the Predictions Make Sense?

Unlike business metrics, model performance can (and should) be evaluated before launch. These are often called offline metrics.

After training, you test your model on held-out data to assess its accuracy and reasonableness.

For example:

• A classifier that predicts whether an image shows a traffic offence can be tested on labelled traffic images before it’s ever used in production.

But there’s an important caveat here:

A model is only as good as the data it was trained on.

If that traffic offence model was trained mostly on daytime images in clear weather, its performance may degrade badly when tested on:

• Nighttime images

• Poor weather conditions

• Different camera angles or environments

3. Freshness and Distribution Shift: Will It Still Work Tomorrow?

Supervised models usually perform best when production data looks like training data. When that assumption breaks, things get interesting, and often ugly.

Consider a model trained to predict someone’s age from passport photos:

• If it were trained mostly on images of men, it may perform poorly on women.

• If cosmetic procedures become more common, people may look significantly younger than their chronological age.

Over time, real-world data changes. This is known as a distribution shift.

If you don’t plan for this, your model’s outputs slowly become obsolete. That’s why it’s critical to think ahead:

• How will you monitor changes in input data?

• How often will the model be retrained?

• What signals will tell you that performance is degrading?

Freshness is not a “nice to have.” It’s essential for long-lived ML systems.

4. Speed: How Fast Is Fast Enough?

Performance is also about latency.

How quickly does your model need to return a result?

That depends entirely on the product:

• A writing assistant needs to predict the next word in fractions of a second.

• An image generator can take several seconds without harming the user experience.

Speed requirements should be explicit. Otherwise, you risk building a model that works perfectly… but too slowly to be useful.

Scoping the Project and Anticipating Challenges

Once you know how you’ll measure success, the next step is understanding the scope of what you’re building and the challenges you’re likely to face.

Two approaches help a lot here.

Buy Fafa a Coffee ☕️ 💰

Leverage Domain Expertise

For each performance metric, you should be able to answer a simple question:

How do I check whether this result is actually good?

Domain experts are invaluable for this. Often, a short conversation reveals how people in that field intuitively judge quality.

If you don’t have access to domain experts, your next best option is the data itself:

• Examine examples of successful outcomes.

• Look for simple, interpretable patterns.

For example, if you’re building a model that predicts whether an Instagram post will go viral, you might start by analysing viral posts and looking for common trends:

• Time or date of posting

• Topic or content type

• Follower count of the creator

You’re basically trying to understand the problem first before building the perfect model.

Stand on the Shoulders of Giants

Reinventing the wheel is rarely a good idea in ML.

Before working in isolation, ask:

• Do similar models already exist?

• Are there public datasets relevant to this problem?

• Is there open-source code I can learn from or adapt?

Common sources of public data include:

• Reddit

• Kaggle

• Common Crawl

• Wikipedia

• The Internet Archive

Leveraging existing work doesn’t make your solution more realistic.

Build a Simple Prototype (Seriously)

Once you’ve defined metrics, explored the problem space, and identified data sources, the next step is surprisingly simple:

Build a basic prototype.

At this stage, your goal is not perfection. It’s to see how your model behaves with:

• The data you have

• The code you’ve written

You should expect the model to be rough. That’s fine. The aim is incremental improvement, not a one-shot masterpiece.

A Minimal ML Pipeline

At the very least, your project should have two pipelines:

Training

This is where you teach the model to make predictions. You iterate on data and code until the outputs start to make sense according to your defined metrics.

Inference

This is how the trained model is actually used. In production, inference usually involves:

• Receiving new data

• Preprocessing it

• Running it through the model

• Returning a prediction

Keeping these pipelines conceptually separate helps you reason clearly about your system.

Conclusion: Start Small, Measure Clearly

Defining core metrics before building your model is one of the most important steps in any ML project. It gives you a clear way to judge effectiveness early on and keeps your work grounded in reality.

Once metrics are defined:

1. Build a simple training and inference pipeline.

2. Observe how the model performs.

3. Improve it iteratively.

It’s far better to start small and refine your way toward your goals than to aim for a “perfect” model from the outset and miss the mark entirely.

In ML, clarity beats cleverness every time.

Share

But before jumping straight in, one critical question must come first:

Is machine learning actually the right solution for this problem?

And if it is, what kind of ML model makes sense?

Think about recommender systems on Amazon, Spotify, or Netflix; features like “Jobs You May Be Interested In” on LinkedIn, “People You May Know” on Instagram; or even writing suggestions in Grammarly. These are real-world examples of ML improving functionality and user experience.

In this post, I’ll discuss how AI Engineers evaluate whether ML should be applied, by considering the project goal, the data available, and the existence of suitable models to decide whether machine learning is the right tool, or if an alternative approach makes more sense.

Why Not Just Solve It With Code?

Let’s assume you have a clearly defined problem or a new feature you want to build.

For example:
A dog grooming app requires users to upload images of their dogs. You want to ensure that the uploaded image actually contains a dog.

Using traditional programming, you might try to write a series of rules and conditions:

• Does it have four legs?

• Does it have a tail?

• Are there whiskers?

• Does it have pointy ears?

If you’ve written code before, you can already see the problem.

This approach quickly turns into a maintenance nightmare full of loopholes and edge cases. What about dogs with cropped ears? Dogs lying down? Dogs partially out of frame? Wolves? Foxes? Stuffed toys?

Now compare that to a machine learning approach.

With ML, you can train an image classification model that learns patterns from thousands of labeled images and confidently determines whether an uploaded image contains a dog or not.

This is why a core skill for AI Engineers is knowing which problems are better solved with machine learning and identifying the appropriate ML approach to use.

Evaluating Whether Machine Learning Is Feasible

To decide if machine learning is a viable solution, two fundamental questions must be answered:

1. What data is required for this task?

2. What machine learning models can be applied using that data?

Let’s break these down.

Data: The Foundation of Machine Learning

Data is one of the most valuable commodities of the 21st century (and for good reason).

Machine learning systems learn from data. That means AI is only as good as the data it was trained on.

For example, voice assistants trained primarily on accents from a limited geographic region will perform poorly for users outside that group. Imagine my grandmother, with her thick Igbo accent, trying to use Alexa or Siri.

(internal screaming)

Even I have to code-switch when speaking to AI systems. And honestly, having to do that unconsciously after finally unlearning it in human conversations is wild.

When evaluating data for machine learning, two key factors matter:

• The type of data required

• The availability of that data

Buy Fafa a Coffee ☕️ 💰

Data Type: What Exactly Do You Need?

You cannot determine the type of data you need unless you are crystal clear about the problem you’re solving.

Some examples:

• A dog grooming app → images of dogs

• A writing assistant → text samples with excellent grammar

• A sales forecasting system → historical sales data

• A recommendation system → user behavior and interaction data

The problem definition always comes first. The data follows.

Data Availability: Where Will the Data Come From?

This is often the hardest part of the evaluation.

Where will your data come from?

• Web scraping

• Organizational or internal data

• Open-source or public datasets

• Synthetic data

The type of machine learning model you choose also determines the kind of data you’ll need.

• Labeled data is essential for supervised learning tasks like classification. For example, a pet classifier requires images labeled as dog, cat, not a pet, etc.

• Weakly labeled data can be inferred from user behavior. For example, Spotify may interpret skipping a song early as a signal that the user didn’t enjoy it and adjust future recommendations accordingly.

• Unlabeled data is useful for discovering hidden patterns or trends that aren’t immediately obvious to humans.

Choosing the Right Machine Learning Model

Once you understand your data, the next step is identifying the appropriate ML model for your problem.

Here are some common categories of machine learning models used in real-world applications.

Classification and Regression

• Classification assigns data to predefined categories.
  Examples include spam detection, fraud detection, or determining whether an image contains a dog.

• Regression focuses on prediction.
  For example: predicting house prices, future sales, or economic trends.

Will Nigeria win the next World Cup?

(I hate that I don’t need AI to answer this question 😭)

Knowledge Extraction

Knowledge extraction models transform unstructured data into structured insights.

Examples include:

• Analyzing customer reviews to identify popular product features

• Examining airport traffic data to uncover common travel routes or preferred airlines

Catalog Organization and Recommendation Systems

These models learn from past user behavior to make future recommendations.

Examples:

• “People You May Know” on Facebook

• Product recommendations on Amazon

• Content suggestions on Netflix

(Yes, I viewed her profile. No, I did not follow her. Please stop suggesting her before I accidentally send a friend request 😭)

Generative Models

Generative models focus on creating new data eg, text, images, audio, or video.

This is currently the most popular application of AI. However, because outputs are open-ended, evaluating their reliability and safety in production environments becomes a challenge of its own.

Conclusion: When Machine Learning Makes Sense

Before committing to machine learning as a feature in your application, an AI Engineer must evaluate:

• The problem being solved

• The type and availability of data required

• The appropriate machine learning model

Once these pieces are clear, you can confidently move forward with training models, validating results, and integrating ML into production systems.

Easy peasy. Lemon squeezy.

(…or not 😈)

Share

The analogy is intentional.

Just as USB-C created a universal way for devices to connect to power, data, and peripherals, MCP creates a standard interface for AI models to connect to external tools, data sources, and environments. This simple idea unlocks something powerful: interoperability across the AI ecosystem.

At its core, MCP extends what AI models can do by allowing them to safely and consistently access more information and capabilities without custom, brittle integrations.

Why MCP Matters: Solving the M×N Problem

Before MCP, developers who wanted their AI application to interact with external tools faced a familiar engineering challenge: the M×N problem.

• M AI applications

• N external tools or data sources

• Result: M × N unique integrations

Each new tool required a custom implementation for each AI app. This approach does not scale.

MCP changes this entirely.

With MCP:

• Each AI application implements the client side once

• Each tool or data source implements the server side once

This transforms the problem from M×N to M+N.

The result is a standardised, interoperable AI ecosystem, where tools become reusable, composable, and accessible across applications.

Core MCP Concepts

To understand how MCP works, it helps to clarify its key components:

• Host: The AI application the user interacts with directly
  Example: Anthropic’s Claude Desktop

• Client: An intermediary between the Host and a specific MCP Server

• Server: A program or service that exposes capabilities via the MCP protocol

• Tool: A function the AI model can call to perform a task

• Resources: Read-only data sources exposed to the model

• Prompts: Structured communication between users, models, and available capabilities

• Sampling: Server-initiated requests that ask the Host/Client to perform LLM interactions

Together, these components create a clean, predictable way for AI systems to interact with the outside world.

A Practical Example: CivicShield MCP

To make this concrete, let’s look at a real project.

CivicShield MCP is an AI-powered Digital Rights Risk Analyzer for Activists.

View project code on GitHub.

Digital rights activists are often required to engage with documents such as:

• Platform Terms of Service

• Donor agreements

• Data protection laws

• Surveillance and security policies

These documents are:

• Legally complex

• Written for corporations, not communities

• Potentially harmful if misunderstood

CivicShield MCP helps activists understand risk before harm happens.

Buy Fafa a Coffee ☕️ 💰

Core Technology Stack

For this project, I used:

• FastMCP: To orchestrate tools, handle routing, and expose an MCP-compatible API

• Gradio: To serve a lightweight, frictionless frontend for the application

This combination allows me to focus on functionality while keeping the user experience simple and accessible.

How the Application Works

The project begins with an app.py file.

When the virtual environment is activated and the app is run using:

python app.py

The application launches locally and opens in the browser, displaying the landing page.

From there, the user can upload a PDF document for analysis.

MCP in Action: Tool-Based Analysis

When the user clicks “Analyse Document”, the application calls four tools defined in the server.py file using FastMCP:

• analyze_risks

• extract_clauses

• simplify_text

• recommend_actions

Each tool internally calls the OpenAI Chat Completions API, using carefully designed prompts to generate its response.

The key point here is architectural:

The application does not need to know how the OpenAI API works, it only knows which tools to call.

from mcp.server.fastmcp import FastMCP
from api_tool import chat_completions

# -------------------------------
# MCP Server Setup
# -------------------------------
mcp = FastMCP("CivicShield MCP")

model = "gpt-4o"


@mcp.tool()
async def analyze_risks(text: str, context: dict) -> str:
    """
    Analyze a document to identify digital rights risks for activists in a given
    region and activism context.
    """
    prompt = f""" ... """
    return chat_completions(model, prompt)


@mcp.tool()
async def extract_clauses(text: str) -> str:
    """
    Identify and explain clauses in a document that could pose risks to activists.
    """
    prompt = f""" ... """
    return chat_completions(model, prompt)


@mcp.tool()
async def simplify_text(text: str, audience: str) -> str:
    """
    Rewrite complex legal or policy text in plain language for a specific audience.
    """
    prompt = f""" ... """
    return chat_completions(model, prompt)


@mcp.tool()
async def recommend_actions(text: str, context: dict) -> str:
    """
    Suggest practical safety and advocacy actions based on identified risks and context.
    """
    prompt = f""" ... """
    return chat_completions(model, prompt)

Why This Is the Magic of MCP

If I deploy my MCP server, any other application can immediately call these tools without re-implementing logic or understanding the OpenAI API at all.

This is where MCP truly shines.

• Tools become reusable services

• AI capabilities become modular

• Developers can integrate powerful AI functionality without deep LLM expertise

Yes, I could hard-code OpenAI API calls directly inside app.py, and the application would still work perfectly.

But that approach:

• Tightly couples AI logic to the app

• Requires every developer to understand OpenAI’s API

• Does not scale well as integrations grow

Now imagine adding multiple AI providers, new data sources, or entirely different capabilities.

Without MCP, complexity grows fast.

With MCP, integration stays clean.

Final Thoughts

For me, this is the real power of Model Context Protocol.

MCP lowers the barrier to building AI-powered applications, encourages reuse, and moves us closer to an open, interoperable AI ecosystem where tools can be shared, extended, and composed across projects.

That’s really good engineering.

Share

Still, the use case really resonated with me, so I decided to take some personal time to try out the task myself.

The challenge was simple:

Build a prototype of an AI-powered search bot that can look through a “data lake” of company PDFs (policy guides, handbooks, etc.) and return clear, human-readable answers to employee questions.

Example Use

Input:
A query around a particular policy or area in the app
e.g. “How many days of annual leave do I get at HHL?”

Output:
A clear, human-readable answer pulled from internal documents
e.g. “You get 28 days of annual leave.”

Solution Overview

I took a stab at solving this using LangChain, and at a high level, what we’re building is a Retrieval-Augmented Generation (RAG) application.

View project repo on GitHub.

In simple terms, this search bot:

• Searches internal documents using semantic similarity

• Retrieves the most relevant content

• Uses an LLM to generate a grounded, human-readable response

• Restricts answers strictly to the provided documents

The goal is to simulate conversational interactions with employees via text, while ensuring that responses are accurate, explainable, and sourced from internal documentation.

What Are We Doing, Simply?

At its core, this is a question-answering system over private data using RAG.

Our solution uses a RAG agent that makes a single LLM call per query, performing contextual search over embedded documents and generating an answer based only on retrieved context.

This approach is particularly useful for organisations that:

• Have sensitive internal documents

• Cannot expose sensitive internal documents to public-facing AI systems.

• Still want to apply AI meaningfully to internal workflows

Core Concepts (Quick Overview)

Before diving into the build, let’s briefly cover the core concepts involved. If you’re already familiar with RAG, feel free to skip ahead to the implementation section.

Embeddings

Embeddings are numerical representations of content that allow machines to process and understand text. They convert text into vectors that capture semantic meaning while discarding irrelevant detail.

The distance between two embeddings indicates how semantically similar they are. In LangChain:

• embed_query() is used to generate embeddings for a single query

• embed_documents() is used to generate embeddings for multiple documents

Below is a simple example that demonstrates how embeddings capture semantic similarity between words.

import getpass
import os
from dotenv import load_dotenv
from scipy.spatial.distance import pdist, squareform
import numpy as np
import pandas as pd
from langchain_openai import OpenAIEmbeddings

load_dotenv()

if not os.getenv("OPENAI_API_KEY"):
    os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")

os.environ["LANGSMITH_TRACING"] = "true"

if not os.getenv("LANGSMITH_API_KEY"):
    os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")

embeddings = OpenAIEmbeddings(
    model="text-embedding-3-large"
)

words = ["cat", "dog", "computer", "animal"]
doc_vectors = embeddings.embed_documents(words)

X = np.array(doc_vectors)
dists = squareform(pdist(X))

df = pd.DataFrame(data=dists, index=words, columns=words)
styled = df.style.background_gradient(cmap="coolwarm")
styled.to_html("embedding_distances.html")

Running this script generates a table showing the Euclidean distances between embeddings for the words cat, dog, computer, and animal.

As expected, cat–animal and cat–dog are much closer semantically than cat–computer.

Buy Fafa a Coffee ☕️ 💰

Vector Storage

Vector storage refers to how embeddings are stored and retrieved. There are three important concepts here:

1. Vector indexing: Organising vectors so similar ones are stored close together

2. Vector libraries: Tools that perform vector operations and similarity search

3. Vector databases: Systems for storing, managing, and querying large sets of vectors

Vector Indexing

Vector indexing structures embeddings so that similar vectors can be retrieved efficiently. Common algorithms include:

• Product Quantization (PQ)

• Locality-Sensitive Hashing (LSH)

• Hierarchical Navigable Small World (HNSW)

The choice of indexing algorithm depends on trade-offs between search speed, accuracy, and memory usage.

Vector Libraries

Vector libraries allow us to store embeddings and perform similarity search using Approximate Nearest Neighbour (ANN) algorithms.

Examples include:

• FAISS (Facebook AI Similarity Search)

• Annoy (by Spotify)

FAISS supports indexing algorithms such as PQ, LSH, and HNSW and is commonly used for similarity search and clustering over dense vectors.

Vector Databases

Vector databases manage and query vector data at scale. Their primary application is semantic search.

Popular options include:

• Chroma

• Qdrant

• Milvus

• Pinecone

Prototype Development

Now that we’ve covered the core concepts, let’s move on to the build.

The prototype follows two main phases:

1. Indexing

2. Retrieval and generation

Indexing

Document Loading

We use LangChain’s DirectoryLoader to load all PDFs from a directory. This folder acts as the knowledge base for the search bot.

loader = DirectoryLoader(documents_dir, glob="*.pdf", loader_cls=PyPDFLoader)
status_text.text("Loading PDF documents...")
progress_bar.progress(20)

try:
    docs = loader.load()
    status_text.text(f"Loaded {len(docs)} pages from {len(pdf_files)} files.")
    progress_bar.progress(40)
except Exception as e:
    st.error(f"❌ Error loading PDFs: {str(e)}")
    return None

Text Splitting

Large documents are split into smaller chunks to improve retrieval quality. Here, we use 1,000-character chunks with a 200-character overlap to preserve context and metadata.

splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200,
)

status_text.text("Splitting documents into chunks...")
progress_bar.progress(60)

chunks = splitter.split_documents(docs)
status_text.text(f"Created {len(chunks)} text chunks.")
progress_bar.progress(80)

FAISS Vector Store

We then generate embeddings for each chunk and store them in a FAISS vector index.

embedding_dim = len(embeddings.embed_query("test"))
index = faiss.IndexFlatL2(embedding_dim)

vector_store = FAISS(
    embedding_function=embeddings,
    index=index,
    docstore=InMemoryDocstore({}),
    index_to_docstore_id={},
)

status_text.text("Generating embeddings and indexing...")
vector_store.add_documents(chunks)
progress_bar.progress(100)
status_text.text("✅ Vector store ready!")

Retrieval and Generation

Retrieval

When a user submits a query, we perform a similarity search over the vector store to retrieve the most relevant document chunks.

retrieved_docs = vector_store.similarity_search(query, k=3)

Context Building and Prompting

We then construct a context from the retrieved documents and explicitly instruct the LLM to use only that context when answering.

context = "\n\n".join(
    f"Source: {doc.metadata.get('source', 'Unknown')} (Page {doc.metadata.get('page', 'N/A')})\n{doc.page_content}"
    for doc in retrieved_docs
)

prompt = f"""
You are an internal HR policy assistant.

Answer the user’s question using ONLY the information provided in the context.
If the answer is not present, say:
“I couldn’t find this information in the available documents.”
Always cite the source file and page after relevant facts.

Context:
{context}

Question:
{query}

Answer:
"""

Generation

We invoke the LLM to generate a response grounded in the retrieved context.

@st.cache_resource
def load_models():
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    embeddings = OpenAIEmbeddings(model="text-embedding-3-large")
    return llm, embeddings

response = llm.invoke(prompt)

The UI then displays the answer, with an expandable section showing source metadata such as filenames and page numbers.

with st.expander(f"📚 Sources ({len(retrieved_docs)} documents)", expanded=False):
    for i, doc in enumerate(retrieved_docs, 1):
        st.markdown(
            f"**Source {i}:** `{os.path.basename(doc.metadata.get('source', 'Unknown'))}`"
        )
        st.markdown(f"**Page:** {doc.metadata.get('page', 'N/A')}")
        st.markdown("**Content:**")
        st.write(
            doc.page_content[:500] + "..."
            if len(doc.page_content) > 500
            else doc.page_content
        )

Demo

To run the app locally, activate your virtual environment, install the dependencies, and run:

 python -m streamlit run app.py

You can then ask any question that may (or may not) be contained in the PDFs and view the generated responses along with their sources.

Conclusion

I genuinely enjoyed building this app. Not just because it worked, but because of how much I learned revisiting core concepts like embeddings, vector databases, and indexing.

The RAG use case is particularly ingenious. Many organisations have sensitive internal documents that should not be exposed publicly, yet still need AI applied to them in a safe and controlled way. RAG offers a powerful solution to that problem.

I’m looking forward to doing more with RAG and exploring how it can be applied as a core capability when building other applications.

Bruhhh… have you ever tried to place an order, pour your heart out in a relationship, delegate a task, or narrate an experience to someone, only for them to totally misunderstand you? Almost like speaking to a brick wall sometimes. Or maybe the misunderstanding arises from your poor communication skills. There are scenarios where you don’t even want to try to express yourself directly, so you hire an expert or bring in a third party to communicate on your behalf. Just so nothing gets lost in translation or taken out of context.

And this is while communicating with fellow humans 😄
What happens when we have to communicate with machines?
Smiles in confusion.

How can you get a foundation AI model to do exactly what you want?

Nothing more. Nothing less.

This is commonly known as prompt engineering. It is the process of crafting instructions that guide a model to generate the desired outcome.

Prompting AI

Depending on your use case, you can give prompts to foundation AI models using different styles. Some people talk to AI the same way they would talk to a friend or fellow human. But after a while, you may realise that you’re not very satisfied with the responses the model generates.

This could be caused by several factors:

• Very open-ended prompts where you assume the AI knows what you’re referring to, the same way a human would, but of course, it doesn’t.

• Not clearly stating what you want, or including typos and grammatical errors that completely change the meaning of your request.

• Not providing explicit boundaries for the depth or scope of the response.

• The level of “intelligence” of the model with respect to completing the specified task.

Giving a model a good prompt is directly related to the quality of the response it generates. It’s basically a garbage-in, garbage-out scenario. If you give AI a rubbish prompt, you’ll most likely get a rubbish response 🤓.

I feel compelled to share that in my not-so-finest moments, I have gotten very frustrated with ChatGPT’s responses and spiralled while prompting, causing the entire chat to turn into one big back-and-forth that eventually resulted in model hallucinations.
(Bows head in shame and commits to doing better.)

So whether you’re using system prompts, user prompts, or leveraging the model’s context window, you need to think critically about:

• The outcomes you require from the model

• How your instructions might be misinterpreted

• What the model should use as a source of truth

• How clearly all of this is communicated

Buy Fafa a Coffee ☕️ 💰

Best Practices for Prompt Engineering

I believe that how a model understands information in a prompt largely depends on the quality of the model itself. However, beyond model-specific prompting techniques, there are general guidelines you should follow to communicate clearly and get the desired results.

Write clear and explicit instructions

Some tips for writing clear instructions for AI models include:

• Explaining unambiguously what you want the model to do

• Asking the model to adopt a specific persona

• Providing examples

• Specifying the desired output format

Provide sufficient context

Context helps the model understand where to gather information from. For example, you might specify that the model should reference a particular document or web link when generating its response.

Break complex tasks into simpler subtasks

Instead of writing one very large, complex prompt, break it down into smaller subtasks. This helps the model understand the task better.

For example, in a ChatGPT session involving a large task like a code review, you can start by explaining the overall goal and then provide separate prompts for each individual step.

Give the model time to think

Chain-of-thought prompting enables the model to critique itself. This is especially helpful when you’re unsure what a “good” response should look like.

Personally, when I’m uncertain about a response, I ask the model to “explain its reasoning” or provide a step-by-step breakdown of how it arrived at the answer.

Iterate on your prompts

Sometimes you need to experiment. Try different ways of asking the model to perform the same task and observe how the responses change.

This requires a lot of out-of-the-box thinking, but it helps you better understand how the model processes information.

Evaluate prompt engineering tools

There are tools designed to help generate effective prompts for specific tasks, such as OpenPrompt, DSPy, DeepMind’s PromptBreeder, and Stanford’s TextGrad.

One thing I personally like doing is asking AI to generate a suitable prompt for me. For example, when vibe-coding with Lovable or Goose, I use ChatGPT to generate a prompt for a feature I want to build, then copy and paste it into the vibe-coding platform.

That said, sometimes a hiccup arises in how to prompt ChatGPT to generate the right prompt for the vibe-coding tool.
(Screams internally.)

The chicken-and-egg problem: who came first? 😈
Do I now use a prompt engineering tool to generate a prompt that I’ll use to generate another prompt for vibe coding? Bruh.

Organise and version your prompts

When working with a model API, maintaining code quality is important. For readability, testing, and collaboration, you should keep prompts in separate files and import them into your code as needed.

Conclusion

Prompt engineering is a very big deal. At this point, it’s essentially the ability to get AI to do anything within its constraints.

There are strict limits in place to prevent harmful use of AI and that’s a topic we can explore in another post. But generally speaking, AI isn’t inherently “smart.” A lot of effort is required to ensure it generates the results you want.

Nothing more. Nothing less.

Share

Which Foundation AI Model Gives the Best Responses?

I’ve been thinking about this lately. Ever since the growing popularity and adoption of foundation AI models, what is the real benchmark for saying that a model gives very good responses?

Foundation models like ChatGPT, Claude, and Gemini now support a wide range of use cases, both for personal use and for building AI-based software.

But how can we properly evaluate the responses from these models?

Other AI models, such as classifier models, are quite binary in their use. For example, with a model trained to detect spam emails, it is very easy to determine whether the model works optimally or not. You can test it on 10,000 sampled emails and immediately see which ones are spam and which are not. Easy peasy, lemon squeezy.

From those results, you can determine how efficient the model is: how many emails it correctly classified as spam and how many it wrongly classified.

However, when using foundation models like ChatGPT, Gemini, or Claude for personal use, it becomes much harder to determine whether a response is satisfactory or not.

Let’s do a quick experiment. I’ll give the same prompt to three foundation models and evaluate their responses. Imagine I want to create an AI-based service for generating poems, and I want to use an AI model for this feature.

Here is the prompt:

“Write a short poem for me.”

Below are the responses from OpenAI’s ChatGPT, Anthropic’s Claude, and Google’s Gemini.

To be honest, I’m not really a poet, but here are my thoughts on the three responses:

• ChatGPT: It knows my name. shy 🙈
  Maybe because this is my most-used foundation AI model, the poem honestly feels very personalised. It is almost like it reflects a stage in my life that I’m currently going through. In my opinion, the response is too personalised. Maybe I’m the only one who can tell, because I’m the only one who knows what I’ve discussed previously on the platform.
  For context, I’m logged into my personal account for all of these experiments. However, remember that the idea here is to build an AI-based product that generates poems (not necessarily poems for me personally).

• Claude: Not bad at all, per se.

• Gemini: If I needed an AI-generated poem, I would definitely choose Claude’s response over Gemini’s.

Now, this works because we are able to give feedback on the responses. We already have some idea of what a “good” poem might look like.

Let’s take it up a notch.

What if we want an AI response for a task where we don’t know what a good response should look like? What if we need a model to summarise a large body of text that we haven’t already read?

How do we know if it has done a good job?

Da dauuumm…
These are the real issues.

So how can we say which model provides the best response for a specific task? How do we know which model to adopt for personal use or for embedding AI features into applications via APIs?

The truth is that responses from foundation models are currently very subjective. There is no direct or easy method to assess their output quality universally.

However, there are metrics that individuals and developers can apply when deciding which model to adopt for a specific task.

Buy Fafa a Coffee 💵

1. Data Privacy

Any information you provide to a model via a prompt can potentially become part of the model’s knowledge base. This can lead to severe data leaks in use cases where privacy is critical.

Think about this from both national security and proprietary business perspectives. Before using a model, you need to understand where the model hosts its data. Are you comfortable with your data being hosted outside your national servers? What is the model’s policy on using prompt data for training and improvement?

2. Data Lineage and Copyright

Although IP laws around AI are still evolving, understanding a model’s training data sources is crucial (especially for commercial use). If a model is trained on copyrighted data and you use it to generate a digital product, can you fully defend your product’s intellectual property?

3. Performance

It has become obvious that many foundation models perform better when you pay for them (internal screaming). Open-source models often do not yet match proprietary ones in performance. Sad but true.

That said, history shows us that open-source software eventually catches up. At some point, open-source foundation models will likely reach parity with proprietary models.

4. Functionality

For me, this should be the defining factor.

Instead of asking which model is “the best,” we should ask how well a model performs the specific task we care about. Reviewing response quality for your particular use case is often the most practical way to decide.

In my earlier example, the experiment was inconclusive because the prompt itself wasn’t well-suited to the use case. I didn’t specify that the poem should be generic enough for something like an electronic billboard in a city centre. Expecting the model to infer that was unrealistic.

5. Control

When ChatGPT launched in 2022, people built entire SaaS products around its API. Wild times.

But what happens when a model is deprecated, its API changes, or access is restricted entirely? There’s a real risk in tightly coupling your product to a single external model. This needs to be considered before committing long-term.

6. Cost

Depending on pricing, rate limits, and SLAs, building your own model can sometimes be the better option.

Okay, calm down. I’m not screaming “build your own foundation model” like it’s a sponge cake. But when you factor in cost per API call and long-term scalability for commercial applications, it’s at least worth considering.

Conclusion

Selecting the appropriate foundation model is still a subjective process. It depends on factors such as cost, training data, privacy requirements, control, and most importantly, whether you’re satisfied with the responses for your use case.

I encourage everyone, especially application developers embedding AI features, to include a clear model-evaluation plan before committing to a foundation model. Being able to critically justify why you chose a particular model is now a best practice, not a nice-to-have.

Let me know in the comments what issues you’ve faced when using foundation models and whether switching models could have mitigated those problems.

These are all statements we’ve heard repeatedly over the last two years, following the rapid innovations and developments in the AI sector. And to a large extent, I actually believed them.

I remember the first time I saw AI generate code. I thought, “OMG, I’m screwed. AI is going to replace me.”

Anyway, fast forward to today. If you’ve been paying attention to the industry, you’ll realise that AI has not done such a good job of “replacing” software engineers across all levels.

Let’s take a quick look at a few shockers we’ve witnessed in recent years:

• Replit’s AI coding assistant deleting an entire production database

• McDonald’s hiring chatbot exposing data of 64 million applicants (password: 123456)

• A biased lending AI that cost a bank $2.5 million in fines

• The ChatGPT diet that landed a man in the hospital

What these incidents reveal is that, although AI is disruptive, it may be too disruptive in its current state.

It’s not ready. At least not 100% yet.

There are still too many edge cases and scenarios that make deploying AI without multiple layers of human intervention extremely risky.

How does this relate to software engineering jobs?

All of the incidents above demonstrate one thing: AI in 2025 could not be fully trusted.

Humans (software engineers) are still critically needed to ensure AI systems don’t embarrass companies, violate regulations, or cause real-world harm. The cost of failure is simply too high, both for tech companies and for organisations outside the tech sector.

Can we really vibe-code a SaaS in 30 minutes?

Another popular belief this year is vibe coding.

Don’t get me wrong, I’m not against vibe coding. But I do think the term, at face value, made non-technical folks believe they could build the next Facebook using only natural language.

Internal screaming.

I think this belief is what many people were referring to when they claimed AI would eliminate software engineering jobs.

So, can we vibe-code a SaaS in 30 minutes?

The honest answer is: it depends.

1. The scale of the application

The more complex the app (in terms of features, expected users, geographic distribution, and security requirements), the harder it becomes to vibe-code.

A simple one-page app? Absolutely doable.

The next Facebook in 30 minutes?
For lack of better words… crazy.

2. The experience level of the developer

This is the biggest factor.

I wouldn’t bet on someone who’s watched three Python videos on YouTube to vibe-code Facebook. But I would put money on a seasoned engineer/CTO/senior/founding engineer/PhD/MSc/BSc (I’ve run out of titles and qualifications, but you get the point).

Vibe coding works best when you already know what to do, but you’re just too lazy, too busy, or too time-constrained to do it manually.

AI-generated code still needs to be thoroughly inspected to ensure it’s correct, optimised, secure, and production-ready.

3. The AI tools being used

Some LLMs are better at generating code than others. Some integrate deeply with terminals, IDEs, and deployment pipelines, making semi-autonomous development possible.

Vibe coding requires knowing which tools to use, how to combine them, and where their limits are.

Why humans still matter

Human-in-the-loop is one of the most practical approaches to AI-assisted software engineering today.

It means using AI to build software while keeping critical decision-making in human hands.

Right now, a human developer should always be responsible for deciding:

• How the software actually solves user problems

• What security risks exist, and how they’re mitigated

• Which architectural decisions are appropriate

• What criteria must be met before real users can access the system

These are not decisions we should hand over entirely to AI.

What’s next for software developers?

AI is not going to replace software engineers, but it will change how we work.

It introduces a new set of skills developers must adopt to work effectively with AI agents.

Prompt engineering

At one point, people thought this would become a standalone career.

While that may not be the case, clear communication with AI is now a core skill:
writing structured prompts, using markdown, defining constraints, understanding context windows, and being explicit about what the AI should and should not do.

System design

If you’ve tried to vibe-code an app, you’ll quickly realise that dumping one massive prompt doesn’t work.

System design remains the developer’s responsibility. You must break complex problems into smaller, well-defined tasks for AI agents and sub-agents.

This is not something we can outsource to AI.

Quality assurance

From my perspective, QA is one of the safest roles in the AI era.

Do we really expect AI to reliably test AI?
More internal screaming.

Being able to validate, test, and reason about AI-generated code is now a critical skill for all developers.

Integration

Modern applications depend on multiple external services and APIs. These integrations must be designed carefully and not left open-ended for AI to guess.

Conclusion

AI won’t replace software engineers, but engineers who refuse to adapt may struggle.

If you’re already a developer, learn how to use AI to increase your productivity, not replace your thinking.

If you’re just starting, focus on building strong foundations while recognising that the industry has shifted. Don’t get stuck learning things that AI can already do effortlessly. Instead, learn why things work, then apply AI to build faster and better.

Understand the shift.
Join the wave.

That’s all for now.

Number one is the Stanford Online YouTube channel. This contains extremely high-quality lectures on building LLMs, deep learning and agentic AI.

https://www.youtube.com/@stanfordonline/videos

For number two, we have the Learn AI Engineering repo on GitHub. This repo is a well-curated guide on a range of core AI topics, including math foundations for AI, ML frameworks, and generative AI, and it is updated frequently.

https://github.com/ashishps1/learn-ai-engineering

And finally, on number three, the Learn Machine Learning community on Reddit released a Google Drive with free ML, AI, and deep learning books, mostly from O’Reilly, that would typically cost an arm and a leg to purchase on Amazon.

https://www.reddit.com/r/learnmachinelearning/comments/1i443cm/free_ml_ai_and_dl_books_google_drive_link/

That’s all.

Have fun. Cheers.