Play the game — Little Differences

Let’s take a little break from reading about technology. Today, I’m sharing something I loved long before I wanted to become a software developer: spotting differences between two pictures.

As a child, I used to look forward to our monthly children’s magazine from Children’s Book Trust in India. One of my favourite pages had two similar black-and-white pictures and a challenge: spot the ten differences between them.

I loved doing that.

Finding the differences was only part of the excitement. I would mark them all, cut out the page, and post my completed entry to the publisher’s address. Sometimes, I won prizes! Imagine the joy of finding tiny details in a picture and then receiving a prize for it.

That memory stayed with me.

So I decided to make Little Differences, a small browser game inspired by those magazine puzzles. It’s my attempt to relive that joy and share a little of it with others.

The game starts with ten black-and-white picture puzzles, each with three differences to find. Some differences take a closer look to spot. There’s one hint per puzzle if you get stuck, and a timer if you fancy challenging yourself. Once you finish, “you can try another puzzle.

You don’t to create an account to play this. And this time, no scissors, envelopes, or postage stamps either. 😊

Play the game — Little Differences

If you remember solving puzzles like these in magazines, I’d love to hear your memories. And if this is your first time, I hope you enjoy that little moment of satisfaction when you finally spot the difference.

Two pictures, ten differences, and a childhood memory was originally published in No Time on Medium, where people are continuing the conversation by highlighting and responding to this story.

When you send a query to a hosted LLM, do you fear whether that model is learning from what you just sent it? You could have shared and queried about something sensitive, such as an employment contract details, or a half-formed idea that you were brainstorming with the model. And right after hitting the send button (believe me, it is always after clicking on send!), a voice inside you questions whether that was safe and if that information could surface in responses sent to another user (your boss or a colleague)?

This post is about that fear.

The naive version of your fear is wrong because that is not how models learn. However, your fear is justified, but for other reasons. To understand this confusing answer, you’ll need to understand how models learn, as covered in this post.

We’ll use the kitchen analogy from the first post, with one change. Before any chef works in the real world, they usually go to a culinary school to learn their craft.

Let’s start with a simple (and important) question.

Do models learn from your conversations?

No. A released model’s weights are frozen. Nothing you say in a chat changes them.

When a model “remembers” what you said three messages ago, that is not because its learning from your conversations, it is because the messages history is being handed back to it as input. Some models send a summary of your previous chats as part of your prompt to a model.

So the naive fear that your information or data is being used to train the model you are querying, is incorrect.

But hold that thought, because the fear comes back, and the second time it’s right. To see why, you have to know what “frozen weights” actually means, which means knowing how the model got un-frozen in the first place, through three different styles of learning.

1. Supervised learning

Compare supervised learning with learning from examples that come with the correct answer attached. Imagine examples such as the following where each item includes a label so you could verify your learning:

1. This photo: cat.
2. This email: spam.
3. This product: defective.

The model guesses, compares it with the correct answer and adjusts to close the gap. The “supervision” is that answer key accompanying every example.

(A naming note: you’ll sometimes hear this being referred to as “classified learning”. The standard term is supervised learning, paired with unsupervised learning.)

Analogy: a head chef tastes everything

Picture a kitchen. Supervised learning is a trainee working next to a head chef who tastes everything they make. Trainee makes a sauce, head chef tastes it. If the chef thinks that the sauce is too thin, sour or anything else, they instruct the trainee accordingly. Every attempt (from the trainee) gets a verdict from someone (the chef) who already knows what a good sauce tastes like.

It works beautifully, but it doesn’t scale. Though extremely valuable, chef’s is the bottleneck. Every attempt has to be personally tasted. That’s the cost of the answer key.

2. Unsupervised learning

Compare unsupervised learning with finding the structure hiding inside data nobody labelled.

There is no answer key or labels to tell what it is. Just a pile of data and the task of finding its patterns. The model discovers that a group of customers behave alike, or a group of documents cluster, or perhaps, a transaction resembles nothing else.

Since nothing needs labelling, it scales to enormous piles. The trade-off: you get structure, not answers. It can tell you what goes together, not what to call it.

Analogy: alone in the walk-in fridge

Imagine a kitchen where a trainee is let loose in the walk-in fridge with no instructions. Nobody labelled anything. But after enough time they notice that a few food items go soft in a day, others are good for weeks, a group smells related, one item resembles nothing else in the room. However, the trainee still might not be able to tell you which group is “herbs” because nobody taught them the word.

3. Reinforcement learning

Compare reinforcement learning with learning from consequences instead of any answer keys or labels. The model acts, an outcome follows, and it was either good or bad. Based of the consequences, a model ‘learns’ to do more of what worked, less of what didn’t.

Analogy: running your own restaurant

Imagine you are running your own restaurant now. There are no head chef tasting your sauce, just customers. Some plates come back clean, some half-eaten, and nobody explains why. You changed four things on Tuesday, but it went badly. Which of the four? You’ll work it out over months of Tuesdays. This learning is slower, but it is also the only way to learn what nobody can demonstrate. No head chef can taste “did the customer enjoy their whole evening.” Only the consequence tells you that.

Now that you’ve had a bare minimum understanding of the three ways in which models learn, let’s look at other concepts, such as, weights of a model to understand how published models can’t continue to learn.

What are weights of a Model? Why published models can’t continue to learn?

Think of weights of a model as the numbers that store what the model has learned.

When an LLM is trained , it repeatedly looks at examples, makes predictions, compares them with the expected results, and adjusts these numbers. Each adjustment could be tiny, but training repeats this process billions of times.

At the beginning, the weights are essentially random, so the model produces nonsense. As training progresses, the weights gradually change to capture patterns in language: which words tend to go together, how sentences are structured, how concepts relate, and so on.

When training is complete, the resulting set of weights is saved. That set of numbers is the Model Weights.

There isn’t a little database inside the model containing every sentence it learned, or a collection of recipes filed away for later. Instead, what the model has learned is encoded in the enormous pattern of numbers called weights.

Compare training weights with the numbers inside the model that hold everything it learned.

Analogy

Picture a chef whose skills have been shaped by years of training: how to hold a knife, adjust the heat, and season a dish. Those learned instincts are like model weights.

Now imagine that when the chef finishes culinary school, their learned skills are locked in place. They can still cook new dishes, but what happens in the kitchen doesn’t change those skills.

That’s the key difference. Humans can learn from experience. A deployed LLM can generate new answers, but its weights don’t change as a result of those interactions.

That’s what “frozen weights” means.

So why is everyone still worried about their query data?

If the model in front of you can’t learn from your data, why do companies panic about their prompts being used for training? If nothing you type changes the model, where’s the risk?

This is because two different things are being confused as one.

The model you are using is frozen. It cannot learn on your data. However, the provider running it can still keep your data. And that data can be used to train the next model version.

The learning doesn’t happen for the version of the model you are using. It happens later, when the provider gathers what it collected and trains a fresh version. Your data isn’t teaching this chef. It might be teaching next year’s class.

Analogy

The chef in front of you won’t improve no matter what you order, and they’ll forget your table the moment you leave.

But imagine the restaurant keeps a notebook and writes down every order or conversation. The secret recipe you shared with the chef could be recorded in the notebook too. Noting changes today. Next year, the new batch of chefs might know how to make your family’s dish.

The risk isn’t just that the model might learn your data. The bigger risk is what happens to your data after you send it.

The risks go far beyond training

Once sensitive data leaves your hands, several things can happen:

1. Retention & breach
Your prompt may be stored. If that storage is breached, your data is exposed whether or not it was ever used for training. The safest data is data that was never kept.

2. Human review
People may review samples of conversations for quality or safety. Your “private” prompt could therefore be seen by a human.

3. Legal discovery
Stored data can potentially be subpoenaed or provided to authorities. Data that doesn’t exist can’t be compelled.

4. Subprocessors
Your data may pass through infrastructure, storage, or annotation vendors. Every additional party adds another point of exposure.

5. Regulatory exposure
For health, financial, or other regulated data, simply sending the data to a provider without the required agreement or safeguards can itself create a compliance problem. Training doesn’t have to happen for the problem to exist.

6. Policy drift
Today’s promises may not be tomorrow’s policies. The data can outlive the terms under which you originally shared it.

There could be many more risks.

So what actually protects you?

Instead of asking “Does the model learn from my conversation?”, ask “What happens to my data after I send it?”

Ask three questions:

• Retention: Is my data stored? For how long?
• Training: If stored, can it be used to train future models?
• Access: Who can see it, including employees, contractors, and subprocessors?

“We don’t train on your data” does not mean “we don’t store it.” And “we don’t store it” does not mean the same thing as “no one can ever see it.” A real data-governance decision has to consider all three: retention, training, and access.

So what should you do?

Don’t send sensitive data to an LLM casually.

A sensible policy is:

• Public / low-risk data: Use LLMs freely.
• Internal / confidential data: Use an approved business/API deployment with appropriate retention, training, access, and security controls.
• Highly sensitive or regulated data: Keep it out of the LLM unless the provider, contract, architecture, and compliance controls explicitly allow it.

Summary

Should you fear that an LLM learns from your conversation? Not in the way you might fear. A released model has frozen weights, so it can’t learn from your prompt, data, or documents.

But that doesn’t make sharing sensitive data safe. Your data can still be stored, reviewed, exposed in a breach, subject to legal demands, or potentially used to train a future model.

So don’t focus only on “Is the model learning from me?” Ask the more important question: “What happens to my data after I send it?” Use LLMs with caution. Understand the difference between the model learning from your data and the provider storing your data.

Buy me a Coffee

Found this useful? If you’d like to support my Java articles, you can buy me a coffee. Thank you for reading!

You are a human, and there are some simple tests for you to attempt to prove it. And no, these tests will not go anywhere near your emotions, your empathy or your love. They will not even ask you an intelligent question like explaining the philosophy of life, because let’s be honest, AI is much better at answering that one anyway.

So let’s find out what these tests are. And if you need help preparing for them, do connect with me, I’m running a live masterclass on this topic next week.

Captchas (with dancing letters or numbers)

Have you ever clicked a photo of a toddler or a teenager who doesn’t want their photo clicked (like at a family function)? The teenagers often look grumpy and turn their face at the exact moment, and the toddlers stand in all sorts of poses, poking fingers in their noses or sticking out their tongues, while trying all sorts of gymnastics. This is how the letters and digits in a captcha look to me.

A request to the folks creating these captchas. Could you please stop harassing the letters and numbers for photographs? Your photos make it hard for me to determine if a letter is an inverted ‘v’, or an ‘I’ bent to the left, or an ‘L’ lying down after a long day. And who has ever been able to tell the difference between a 0, an O and an o? Not me, not you. Still, we humans endure this torture to prove we are humans.

The Audio Option

Captchas also have an audio option, which is the button you click after you have given up on your eyes. A voice reads out the captcha, except that the voice has either a weird accent or the way of saying those letters and numbers is off. A follow up question. How many of you have been able to figure out if the audio option said 8BVN or ABDN on the first attempt?

Sometimes I wonder if this was designed by companies trying to figure out which humans have impaired hearing. I mean why do I see advertisements for hearing aids right after I fail to enter a captcha correctly :D.

So yes, I successfully proved I’m a human, perhaps with a hearing issue (with maybe a hearing aid in my shopping cart).

Click a checkbox that says ‘You are a human’

I love this one. This is the simplest one to prove anyone is a human. Just a click and it proves one is human, no matter how inhumane they are in real life.

But here is my problem with it. As a developer advocate and a power user of an IDE, I have been promoting the use of the keyboard over the mouse for the last couple of years. And then this checkbox arrives, and I have to squirm and reach out for my mouse just to prove I’m a human. I know I could tab to it and hit the spacebar, but web pages are weird, because then they just scroll. So I seriously think this one is designed to test whether humans can recall where their mouse is.. and whether they still have the ability to use it.

And the funniest part is, the checkbox does not even care about the click. It is busy enjoying the sight of me squirming over the question.. really.. I need to check this box to prove I’m a human? I believe it loves to JUDGE humans. Are we being ranked on our grumpiness? Is this another trick to sell ‘wellness sessions’ to us :D

Select boxes with a car/ traffic light etc.

C’mon! First of all, don’t show those blurry images to me. It is difficult to figure out whether it has a car, or whether the brick just seems like the boot of the car. And no, my vision is not that bad. If you want to check my vision, give me another test. Don’t give me blurry images and then JUDGE me, telling me I’m not a human!

And then there is this classic example about selecting boxes with traffic lights. Is the pole a part of the traffic light or not? Nobody knows. Google does not know. That is exactly why they are asking me! So there I am at 11 in the night, taking a policy decision on behalf of a self driving car, and unpaid. And the moment I click a square, it fades out and a new square slowly fades in, and that one also has a bicycle. Everything has a bicycle. I did not come here for bicycles, I came here to reset my password.

Summary

Proving you are a human is much simpler in this AI era. Just a click here and there. And you are kind of fine.

My blogs on AI agents resumes from the next post with all the serious AI stuff I have been writing all this while. I just needed a break from it, and going by the state of the internet, I suspect you needed one too. Think of this post as the captcha you had to clear before the real content loads.

Buy me a Coffee

Found this useful? If you’d like to support my Java articles, you can buy me a coffee. Thank you for reading!

Are you a human? was originally published in No Time on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you’re starting out with building AI agents, you’ve probably run into words like workflows, skills, orchestration, tools, MCP server, loop engineering, guardrails, and harnessing. The list gets overwhelming fast. Learning these terms first builds a strong foundation before you write any code.

A quick note: people use “Agents” and “AI Agents” to mean the same thing. These are fairly new terms, so the exact meaning often depends on who you ask.

In this new series, I’m learning how to create AI agents and sharing each step. This first post explains those terms using simple analogies. Most of them compare a human worker with an LLM, since both can reason and analyze to some degree (how well depends on which person, or which model, you’re talking to :D).

This isn’t an exhaustive list, just the terms worth knowing to get going. Let’s start.

1. What is an Agent?

This is a simple question but it could have multiple answers depending on whom you are talking with.

Compare an Agent with a worker who has thinking capabilities. Depending on how much freedom an agent has, they could be following a predefined process (such as a worker on an assembly line), or changing the course as they see fit (such as a Chef in a restaurant kitchen). In computing scenarios, every agent would include some sort of LLM to achieve its goal. It would take in information, decide, act, and produce an output.

Analogy

Picture a Chef in a kitchen and an assembly line worker as your agents.

A Chef might have more freedom to prepare a dish. They course correct and improvise, depending on the availability of ingredients, their quality, or special requests from customers. However, an assembly line worker might not have a lot of wiggle room. They usually follow pre-defined steps.

An assembly line worker has limited flexibility as compared to a Chef. But, this is NOT a flaw in the system. It is the intent. If every assembly line worker decides independently on how an item should be handled, the whole production system would fall apart.

Let’s talk about the ways in which agents are designed, such as workflows.

2. What is a workflow?

Compare a Workflow with a predefined sequence of steps followed in order. The path is defined in advance, such as, do A, then B, then C. It’s reliable and predictable, but it can’t stray from the script. If something unexpected happens, course correction steps could be pre-defined too.

Analogy

Picture a kitchen again. A workflow is a recipe that defines a fixed set of steps that are followed to prepare a dish. It has the same ingredients, same process, every single time. It still needs a person (an agent) to prepare this dish though. In a workflow, a cook (or an LLM) follows a path someone else laid out.

Can a workflow’s sub task be performed by another agent?

Most real systems are hybrids, where an agent might run inside a workflow, or a workflow might call an agent for one tricky step. The line blurs in practice.

Let’s see how tasks are performed by an agent or a workflow using tools.

3. What are tools?

Compare tools with the external capabilities an agent or a workflow can call on. A tool is any function the system can invoke to take an action or fetch information. A language model can reason and decide, but it can’t search your database, or send an email on your behalf. Tools give it those extra powers. Behind a tool could be a local method, an external API, or even another LLM (though that needs further coordination, as covered later in this post). The tool itself is the capability the model is handed; each time it uses one, that’s a call to the tool.

Analogy

Picture the kitchen again. The chef (an agent) has the skill and judgment, but they still need equipment to cook. A knife to chop, an oven to bake, a phone to call a supplier when an ingredient runs out. Those are the tools. The chef decides which one to grab for the task at hand, uses it, sees the result, and moves on. Without tools, the chef could plan a great meal in their head but never actually make it.

4. What are skills?

Compare Skills with the know-how to do a task well. A skill is a set of instructions, expertise, and sometimes helper files that teaches an agent how to do a job. It usually captures the process to follow and the expectations for the output, and it can also include information about how a business works, its rules, terminology, and edge cases. It often carries guidelines, best practices, or gotchas for the task. Where a tool is a capability the agent invokes, a skill is guidance the agent reads and follows.

Analogy

Picture the kitchen again. The chef’s tools are the equipment, but their skills are the techniques they’ve trained in, such as, how to fillet a fish, how to build a proper sauce, how to plate a dish so it looks right. Notice how the two work together: filleting a fish takes the knife (the tool) and the filleting technique (the skill) at the same time. When an order calls for fish, the chef draws on that filleting know-how without being taught it fresh each time. That learned, reusable expertise, ready to apply when the task calls for it, is a skill.

A sample SKILL.md

Skills are conventionally written as Markdown files and named SKILL.md, so that’s what you’ll see in the wild. It also usually includes a, that is, the block at the top. That’s where the description of your skill files lives, and the description is what tells a system when to reach for the skill. A good one is what makes a skill actually get used.

Here’s sample of SKILL.md:

---
name: fillet-a-fish
description: Use when a dish calls for a boneless fish portion. Covers how to
  fillet a whole fish cleanly. Do NOT use for shellfish or pre-cut portions.
---

# Skill: Filleting a fish

## Steps to follow
1. Lay the fish flat and locate the spine.
2. Cut behind the gills, then run the knife along the spine to the tail.
3. Flip and repeat on the other side.
4. Trim the belly bones and pull out any pin bones.

## Good technique (what makes it clean)
- Keep the blade angled toward the bones, not the flesh, to waste less.
- Use long, smooth strokes rather than sawing.

## Gotchas
- Missed pin bones ruin the dish. Always run a finger along the fillet to check.
- A dull knife tears the flesh. Sharpen before starting.

## Checks
- [ ] Are both fillets free of bones?
- [ ] Is the flesh smooth, not shredded?

SKILLS.md or SKILL.md?

It is easy to overlook that simple difference, but it is always SKILL.md.
So what do you do, if you want to include more skills for your project?

Does one project have exactly one skill.md file?

A project can have many skills, not just one.

Each skill lives in its own folder, and inside that folder is a single file named SKILL.md. The skills are told apart by the folder name, not by the filename. So the filename is always the same, SKILL.md (singular, note, not SKILLS.md), while the folder gives each skill its identity. You end up with a layout like:

skills/
├── fillet-a-fish/
│   └── SKILL.md
├── build-a-sauce/
│   └── SKILL.md
├── plate-a-dish/
│   └── SKILL.md
└── knead-dough/
    └── SKILL.md

One folder has exactly one SKILL.md, but a project can hold as many skill folders as you like, each with its own. The folder name is effectively the skill’s name (and it usually matches the name field in the frontmatter).

Does each skill folder exactly one file, that is, skill.md?

The folder can hold more than just SKILL.md, with helper file. An example:

fillet-a-fish/
├── SKILL.md              ← the know-how (steps, technique, gotchas)
├── knife-cuts.png        ← a reference sheet showing the cut angles
└── fish-guide.md         ← details on different fish (where bones sit, etc.)

Now the SKILL.md could be shortened, and it could point to the other two files instead of cramming everything in:

## Steps to follow
1. Lay the fish flat and locate the spine.
2. Check fish-guide.md for where the pin bones sit in this species.
3. Follow the cut angles shown in knife-cuts.png.
4. Trim the bones, then run the checks.

When does the line between tools and skills blurs?

The line between a skill and a tool can blur. When an agent invokes it to get a result (a database, an API), it is a tool. If it’s guidance on how to do something (steps, conventions, domain knowledge), it is skill. The two can even live together. A skill folder might include a small script the agent runs to resize an image, and that script is a tool sitting inside a skill.

5. What is a MCP Server?

MCP Server is a standardized way to plug tools and data into an agent.

MCP (Model Context Protocol) is an open standard that defines how an agent and an external capability talk to each other. An MCP server is a program that exposes a set of tools or data sources (a database, your email, a file system, a company’s internal API) in this common format. Because they all speak the same protocol, any agent that “speaks MCP” can connect to any MCP server without custom wiring for each one.

Analogy

Picture the kitchen again. Every appliance, the oven, the blender, the mixer, could come with its own oddly shaped plug, forcing you to rewire the kitchen for each one. An MCP server is like a standard power outlet on the wall. Any appliance built to that standard just plugs in and works. The chef (the agent) doesn’t care about the wiring behind the wall. They see a socket, plug in the tool they need, and start cooking.

Why is MCP important?

Without MCP, every provider is a new custom integration. With MCP, every provider is reached through the same three steps: connect, list tools, call a tool. You still have one server per provider, but you stop writing custom code for each one.

Since this is a bit complicated to understand, let me use an example that is for sending an email via Gmail and Outlook.

Custom code for each provider (without MCP Server):

# --- Gmail: custom integration ---
gmail = GmailClient(api_key = "...")
gmail.login_with_google_oauth()
gmail.messages.send(to = "sam@x.com", subject = "Hi", body = "Hello")

outlook = OutlookClient(tenant = "...", secret = "...")
outlook.authenticate_microsoft()
outlook.mail.post(recipient = "sam@x.com", title = "Hi", content = "Hello")

With MCP Server:

# Connect to any MCP server the SAME way
gmail   = connect_mcp("https://gmail-mcp-server")
outlook = connect_mcp("https://outlook-mcp-server")

# Ask a server what tools it offers
gmail.list_tools()     # -> ["send_message", "search", ...]
outlook.list_tools()   # -> ["send_mail", "search", ...]

# Call a tool through the same standard method
gmail.call_tool("send_message", { to: "sam@x.com", body: "Hello" })
outlook.call_tool("send_mail",  { to: "sam@x.com", body: "Hello" })

The connection code is now identical: connect_mcp(…), list_tools(), call_tool(…). Look at the tool names: Gmail exposes send_message, Outlook exposes send_mail. The way you call them is the same, but the names can differ. So MCP makes connecting uniform, not the tools themselves identical.

6. What is an inference API?

As the name suggests, it is an API to talk to an LLM. You can send your query as text to an LLM, via an API, and receive text back. Depending on the API, you could also get JSON objects as a response. You could get all of the response text in one go, or as a stream (received as the chunks of the response are generated). You could also send images or other formats and receive back text, images, or other formats, such as video, sound, and documents, and many more.

7. What is orchestration?

Orchestration is the coordination of multiple agents, tools, and steps toward one larger goal. When a task is too big for a single agent or a single step, orchestration is the layer that decides who does what, in what order, and how the pieces hand off to each other. It routes the work, passes results between components, handles what happens when a step fails, and keeps everything moving toward the final outcome.

In short, agents do the work, and orchestration is the coordination that makes many of them work together as one system.

Analogy

Picture a big kitchen on a busy night. You have several chefs, one on sauces, one on grilling, one on desserts, plus ovens and prep stations all running at once. Orchestration is the head chef calling the pass, deciding which dish starts when, making sure the steak and the sides finish at the same moment, rerouting work when one station falls behind, and sending each plate out only when it’s complete. No single cook or chef sees the whole picture. The head chef’s coordination is what turns separate efforts into one smooth service.

Does orchestration come in multiple styles?

Yes. In centralized orchestration, one controller directs everyone (the head chef model above). In decentralized orchestration, agents coordinate among themselves without a single boss, more like experienced cooks who know the rhythm and hand off to each other directly. Most real systems lean on the centralized version first because it’s easier to reason about.

8. What are guardrails?

Guardrails are the rules and limits that keep an agent’s behavior safe and on-track. Because an agent decides its own steps, you need boundaries on what it’s allowed to do, say, or access. Guardrails are the checks that sit around the agent: filtering harmful or off-topic outputs, blocking risky actions, keeping it within its intended scope, and validating that inputs and outputs meet your standards. They can run before the agent acts, while it acts, or after, catching problems the agent’s own judgment might miss.

In short, an agent decides freely, and guardrails are the boundaries that make sure its freedom stays safe and appropriate.

Analogy

Picture the kitchen again. A skilled chef has freedom to improvise, but the kitchen still has rules they can’t cross, such as, don’t serve anything with an allergen the customer flagged, don’t send out undercooked chicken, keep raw meat away from the salad station, and stay within the day’s budget. Those food-safety and house rules are the guardrails. They don’t tell the chef how to cook, but they draw hard lines the chef must not step over, no matter how creative they get.

Is guardrails only about blocking bad outputs?

No, they also work on the way in. An input guardrail can catch a malicious or manipulative instruction before the agent ever acts on it (for example, someone trying to trick the agent into ignoring its rules). Splitting it into input-side and output-side guardrails is a clean way to show your audience that safety wraps around the whole system, not just the final answer.

9. What is harnessing?

Harnessing is the supporting code that turns a model into a working agent.

Harnessing is the supporting code that turns a model into a working agent. An agent is the whole thing (model + harness working together). The harness is just the code part, without the model. In short, the model is the reasoning core that makes the decisions, and the harness is the machinery around it that calls the tools, and remembers past steps.

Analogy

Picture the kitchen again. The chef is brilliant, but a brilliant chef alone in an empty room can’t cook. The harness is the working kitchen built around them: the station where ingredients arrive, the ticket rail that hands over one order at a time, the runner who carries finished plates out and brings back the next request, and the loop that keeps the whole cycle turning. The chef supplies the judgment, but the harness is what feeds them work, carries out their instructions, and brings back results so they can keep going.

10. What is Loop engineering?

An agent works in a loop: think, use a tool, look at the result, then think again, until the task is done. Loop engineering is the work of making that loop run well, deciding when it should stop, keeping it from repeating itself, and controlling how much time or cost it can use.

Analogy

Picture the kitchen again. The chef works in a taste-adjust-taste cycle: taste the sauce, add salt, taste again, adjust, until it’s right. Loop engineering is setting the smart rules around that cycle. Know when it’s good enough to send out rather than fussing forever, don’t keep adding salt in a way that never converges, and don’t burn the whole night’s time perfecting one sauce while other orders pile up. It’s the judgment about how to run the loop, not the cooking itself.

Summary

This is a beginner-friendly guide to the jargon behind AI agents, agentic AI, workflows, tools, MCP servers, guardrails, and more, explained with simple analogies before you start building.

Buy me a Coffee

Found this useful? If you’d like to support my Java articles, you can buy me a coffee. Thank you for reading!

This is the payoff of the series. I covered a lot of concepts related to a RAG application via my previous posts: what a vector database is, what a 384-dimension vector looks like, how closeness is measured, how to chunk, and how to ask a PDF a question.

That last post stopped at retrieval. Here we add the missing step: hand the retrieved chunks to Gemini and get a written answer, with the page still attached. Same PDF, same Qdrant, same local embeddings.

One step at a time below. The complete file is at the end.

Step 0: Keys

Two things in your environment. Qdrant Cloud (get them as in the vector database post) and a free Gemini key from Google AI Studio (https://aistudio.google.com/apikey → Create API key).

export QDRANT_CLUSTER_ENDPOINT="YOUR-CLUSTER.cloud.qdrant.io"   
export QDRANT_API_KEY="..."
export GEMINI_API_KEY="..."

Step 1: Dependencies

BOM manages the langchain4j modules. Only langchain4j-google-genai is new versus the PDF post.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>dev.langchain4j</groupId>
      <artifactId>langchain4j-bom</artifactId>
      <version>1.17.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency><groupId>dev.langchain4j</groupId><artifactId>langchain4j</artifactId></dependency>
  <dependency><groupId>dev.langchain4j</groupId><artifactId>langchain4j-document-parser-apache-tika</artifactId></dependency>
  <dependency><groupId>dev.langchain4j</groupId><artifactId>langchain4j-embeddings-all-minilm-l6-v2</artifactId></dependency>
  <dependency><groupId>dev.langchain4j</groupId><artifactId>langchain4j-qdrant</artifactId></dependency>
  
  <!-- NEW: Gemini via the Google GenAI SDK -->
  <dependency><groupId>dev.langchain4j</groupId><artifactId>langchain4j-google-genai</artifactId></dependency>
  
  <!-- PDF text + page rendering, OCR, logging -->
  <dependency><groupId>org.apache.pdfbox</groupId><artifactId>pdfbox</artifactId><version>3.0.5</version></dependency>
  <dependency><groupId>net.sourceforge.tess4j</groupId><artifactId>tess4j</artifactId><version>5.14.0</version></dependency>
  <dependency><groupId>org.slf4j</groupId><artifactId>slf4j-simple</artifactId><version>2.0.16</version></dependency>
</dependencies>

If the BOM doesn’t resolve the dependency for Google GenAI, use the following (the versions change faster now. Check on Maven Central if this still doesn’t work):

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-google-genai</artifactId>
    <version>1.17.2-beta27</version>
</dependency>

Step 2: The embedding model

Runs locally, no API key. Its dimension (384) is what the collection must match.

static final EmbeddingModel embeddingModel = new AllMiniLmL6V2EmbeddingModel();

int vectorDimension = embeddingModel.dimension();   // 384

Step 3: Connect to hosted Qdrant

Same host, gRPC port 6334, but TLS on and the API key set — that is the only difference from a local instance (refer to section 0 to get the keys).

static QdrantClient openQdrant() {
    return new QdrantClient(
        QdrantGrpcClient.newBuilder(qdrantHost, 6334, true)   // true = TLS, for Qdrant Cloud
                        .withApiKey(qdrantApiKey)
                        .build());
}

Step 4: Create the collection

Size it to the embedding model, compare by Cosine. Wipe any old copy first so re-runs start clean.

static void ensureCollection(QdrantClient qdrant, int vectorDimension) throws Exception {
    if (qdrant.collectionExistsAsync(collectionName).get()) {
        qdrant.deleteCollectionAsync(collectionName).get();
    }
    qdrant.createCollectionAsync(
            collectionName,
            VectorParams.newBuilder()
                        .setDistance(Distance.Cosine)
                        .setSize(vectorDimension)
                        .build()
    ).get();
}

Step 5: Build the embedding store

This is the LangChain4j handle you read from and write to. It points at the collection you just made.

static EmbeddingStore<TextSegment> buildStore() {
    var builder = QdrantEmbeddingStore.builder()
                                      .host(qdrantHost)
                                      .port(qdrantPort)
                                      .useTls(qdrantUseTls)
                                      .collectionName(collectionName);
    if (qdrantApiKey != null && !qdrantApiKey.isBlank()) {
        builder.apiKey(qdrantApiKey);
    }
    return builder.build();
}

Step 6: Read the PDF page by page

Read one page at a time so page numbers survive. If a page has almost no text, it is a scan, so render it and OCR it.

for (int pageNumber = 1; pageNumber <= totalPages; pageNumber++) {
    stripper.setStartPage(pageNumber);
    stripper.setEndPage(pageNumber);              // read just this one page
    String text = stripper.getText(pdf).strip();
    String extraction = "text";
    if (text.length() < MIN_TEXT_CHARS_PER_PAGE) {
        if (renderer == null) renderer = new PDFRenderer(pdf);
        text = ocrPage(renderer, pageNumber - 1).strip();   // the page is a scan
        extraction = "ocr";
    }
    rawText[pageNumber - 1] = text;
    method[pageNumber - 1]  = extraction;
}

Step 7: Strip repeated headers and footers

Any line that shows up on most pages is the running header/footer, not content. Detect it once, drop it everywhere.

Set<String> boilerplate = detectRepeatedLines(rawText);   // lines on >= 60% of pages
String cleaned = removeBoilerplate(raw, boilerplate);     // also drops "Page 3 of 5"

Step 8: Tag every page with where it came from

Each page becomes a Document carrying its source file and page number. LangChain4j copies this onto every chunk, so the citation follows the text.

Metadata metadata = new Metadata();
metadata.put("source", file.getFileName().toString());
metadata.put("page", pageNumber);
metadata.put("total_pages", totalPages);
metadata.put("extraction", method[pageNumber - 1]);
pages.add(Document.from(cleaned, metadata));

Step 9: Chunk the pages

Split each page into overlapping segments. The metadata rides along automatically.

DocumentSplitter splitter = DocumentSplitters.recursive(MAX_SEGMENT_CHARS, SEGMENT_OVERLAP_CHARS);
List<TextSegment> segments = new ArrayList<>();
for (Document document : documents) {
    segments.addAll(splitter.split(document));
}

Step 10: Embed and store, in batches

Turn each chunk into a vector and upsert (update or insert) it. Batching keeps memory flat on big files.

for (int start = 0; start < segments.size(); start += EMBED_BATCH_SIZE) {
    List<TextSegment> batch = segments.subList(start, Math.min(start + EMBED_BATCH_SIZE, segments.size()));
    List<Embedding> vectors = embeddingModel.embedAll(batch).content();
    embeddingStore.addAll(vectors, batch);
}

Ingestion is done. The rest is querying.

Step 11: Retrieve the nearest chunks

Embed the question the same way, then ask Qdrant for the closest chunks above a score threshold.

Embedding queryVector = embeddingModel.embed(question).content();
EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
                                                       .queryEmbedding(queryVector)
                                                       .maxResults(MAX_RESULTS)
                                                       .minScore(MIN_SCORE)
                                                       .build();
List<EmbeddingMatch<TextSegment>> matches = embeddingStore.search(request).matches();

Step 12: Assemble the RAG prompt

Question + retrieved passages, each tagged with its citation, and an instruction to answer only from that context.

StringBuilder input = new StringBuilder();
input.append("Answer the question using only the context below.\n");
input.append("Cite the source file and page for every fact you use.\n\n");
input.append("QUESTION:\n").append(question).append("\n\nCONTEXT:\n");
int n = 1;
for (EmbeddingMatch<TextSegment> hit : matches) {
    Metadata m = hit.embedded().metadata();
    String citation = m.containsKey("page") ? m.getString("source") + " p." + m.getInteger("page")
                                            : m.getString("source");
    input.append("[").append(n++).append("] ").append(citation).append("\n");
    input.append(hit.embedded().text().strip()).append("\n\n");
}

Step 13: Hand it to Gemini

The one line the previous post left out. Build the model once, send it the prompt, print the answer.

ChatModel llm = GoogleGenAiChatModel.builder()
        .apiKey(System.getenv("GEMINI_API_KEY"))
        .modelName("gemini-3.5-flash")
        .build();

String answer = llm.chat(prompt);   
System.out.println(answer.strip());

That is the whole loop: read → chunk → embed → store → retrieve → answer.

The complete code

package com.gupta.compele_rag_appl;

import dev.langchain4j.data.document.Document;
import dev.langchain4j.data.document.DocumentSplitter;
import dev.langchain4j.data.document.Metadata;
import dev.langchain4j.data.document.loader.FileSystemDocumentLoader;
import dev.langchain4j.data.document.parser.apache.tika.ApacheTikaDocumentParser;
import dev.langchain4j.data.document.splitter.DocumentSplitters;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.embedding.onnx.allminilml6v2.AllMiniLmL6V2EmbeddingModel;
import dev.langchain4j.model.google.genai.GoogleGenAiChatModel;
import dev.langchain4j.store.embedding.EmbeddingMatch;
import dev.langchain4j.store.embedding.EmbeddingSearchRequest;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.qdrant.QdrantEmbeddingStore;
import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;
import io.qdrant.client.grpc.Collections.Distance;
import io.qdrant.client.grpc.Collections.VectorParams;
import net.sourceforge.tess4j.Tesseract;
import org.apache.pdfbox.Loader;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.rendering.ImageType;
import org.apache.pdfbox.rendering.PDFRenderer;
import org.apache.pdfbox.text.PDFTextStripper;

import java.awt.image.BufferedImage;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.*;

public class RagOverPdf {

    static final String qdrantHost = env("QDRANT_CLUSTER_ENDPOINT", "localhost");
    static final String qdrantApiKey = System.getenv("QDRANT_API_KEY"); // null for a local instance

    static final int qdrantPort = 6334;
    static final boolean qdrantUseTls = true;     // true for Qdrant Cloud
    static final String collectionName = "worldcup_2026";
    static final Path inputFile = Path.of("C:\\code\\LangChain4jDemo\\src\\main\\resources\\pdf\\fifa-world-cup-2026-knockout-log.pdf");
    static final String tessdataDir = "/usr/share/tesseract-ocr/5/tessdata";

    // Indexing behavior. These are constants, not config, because they decide
    // what gets embedded: change any of them and you must re-index.
    static final int MAX_SEGMENT_CHARS = 900;
    static final int SEGMENT_OVERLAP_CHARS = 150;
    static final int EMBED_BATCH_SIZE = 64;

    // Retrieval behavior.
    static final int MAX_RESULTS = 2;
    static final double MIN_SCORE = 0.30;

    // A page that yields fewer usable characters than this is treated as scanned
    // and sent to OCR. Raise it for dense layouts, lower it for sparse forms.
    static final int MIN_TEXT_CHARS_PER_PAGE = 80;
    static final int OCR_DPI = 300;
    static final String OCR_LANGUAGE = "eng";

    // Reuse one embedding model instance. It is thread safe and loading it is expensive.
    static final EmbeddingModel embeddingModel = new AllMiniLmL6V2EmbeddingModel();

    public static void main(String[] args) throws Exception {
        if (!Files.isRegularFile(inputFile)) {
            System.err.println("Input file not found: " + inputFile.toAbsolutePath()
                               + "\nPut fifa-world-cup-2026-knockout-log.pdf next to this program, or edit inputFile.");
            return;
        }

        int vectorDimension = embeddingModel.dimension();

        // The LLM. This is the step the previous post left out.
        ChatModel llm = GoogleGenAiChatModel.builder()
                .apiKey(System.getenv("GEMINI_API_KEY"))
                .modelName("gemini-3.5-flash")
                .build();

        try (QdrantClient qdrant = openQdrant()) {
            ensureCollection(qdrant, vectorDimension);
            EmbeddingStore<TextSegment> embeddingStore = buildStore();

            // ---- Extract: one Document per PDF page (Tika for other formats) ----
            List<Document> documents;
            if (isPdf(inputFile)) {
                documents = extractPdfPages(inputFile);
            } else {
                documents = List.of(extractWithTika(inputFile));
            }
            long ocrPages = documents.stream()
                                     .filter(d -> "ocr".equals(d.metadata().getString("extraction")))
                                     .count();

            // ---- Split: chunk each Document. Metadata is copied onto every segment. ----
            DocumentSplitter splitter = DocumentSplitters.recursive(MAX_SEGMENT_CHARS, SEGMENT_OVERLAP_CHARS);
            List<TextSegment> segments = new ArrayList<>();
            for (Document document : documents) {
                segments.addAll(splitter.split(document));
            }
            System.out.printf("Split %d page(s) into %d chunks (max %d chars, overlap %d).%n",
                              documents.size(), segments.size(), MAX_SEGMENT_CHARS, SEGMENT_OVERLAP_CHARS);

            // ---- Embed and upsert in batches ----
            int stored = 0;
            for (int start = 0; start < segments.size(); start += EMBED_BATCH_SIZE) {
                List<TextSegment> batch = segments.subList(start, Math.min(start + EMBED_BATCH_SIZE, segments.size()));
                List<Embedding> vectors = embeddingModel.embedAll(batch).content();
                embeddingStore.addAll(vectors, batch);
                stored += batch.size();
            }

            System.out.printf("Ingested %s: %d page(s) (%d via OCR), %d chunks stored in '%s'.%n",
                              inputFile.getFileName(), documents.size(), ocrPages, stored, collectionName);

            // ---- Ask a question, get an answer, repeat until 'exit' ----
            System.out.println("\nAsk a question about the 2026 World Cup. Type 'exit' to quit.");
            try (Scanner scanner = new Scanner(System.in)) {
                while (true) {
                    System.out.print("\n> ");
                    if (!scanner.hasNextLine()) break;
                    String question = scanner.nextLine().strip();
                    if (question.isEmpty()) continue;
                    if (question.equalsIgnoreCase("exit") || question.equalsIgnoreCase("quit")) break;
                    runQuery(embeddingStore, llm, question);
                }
            }
            System.out.println("Goodbye.");
        }
    }

    /**
     *   1. Embeds the question and retrieves the closest chunks from Qdrant,
     *   2. Builds the RAG payload (question + retrieved chunks with citations),
     *   3. Sends it to Gemini and prints the written answer,
     *   4. Prints the sources so the answer stays checkable.
     */
    static void runQuery(EmbeddingStore<TextSegment> embeddingStore, ChatModel llm, String question) {
        Embedding queryVector = embeddingModel.embed(question).content();
        EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
                                                               .queryEmbedding(queryVector)
                                                               .maxResults(MAX_RESULTS)
                                                               .minScore(MIN_SCORE)
                                                               .build();
        List<EmbeddingMatch<TextSegment>> matches = embeddingStore.search(request).matches();

        if (matches.isEmpty()) {
            System.out.println("\nNothing in the document cleared the similarity threshold.");
            return;
        }

        String prompt = buildLlmInput(question, matches);
        String answer = llm.chat(prompt);

        System.out.println("\n===================== ANSWER =====================");
        System.out.println(answer.strip());
        System.out.println("==================================================");

        System.out.println("Sources:");
        for (EmbeddingMatch<TextSegment> hit : matches) {
            Metadata metadata = hit.embedded().metadata();
            String citation = metadata.containsKey("page")
                    ? metadata.getString("source") + " p." + metadata.getInteger("page")
                    : metadata.getString("source");
            System.out.printf("  %.0f%% match  %s%n", hit.score() * 100, citation);
        }
    }

    /**
     * Assemble the message a RAG app hands to an LLM: a short instruction, the
     * user's question, and the retrieved passages, each tagged with its citation
     * so the model can attribute the facts it uses.
     */
    static String buildLlmInput(String question, List<EmbeddingMatch<TextSegment>> matches) {
        StringBuilder input = new StringBuilder();
        input.append("Answer the question using only the context below.\n");
        input.append("Cite the source file and page for every fact you use.\n\n");
        input.append("QUESTION:\n").append(question).append("\n\n");
        input.append("CONTEXT:\n");
        int n = 1;
        for (EmbeddingMatch<TextSegment> hit : matches) {
            Metadata metadata = hit.embedded().metadata();
            String citation = metadata.containsKey("page")
                    ? metadata.getString("source") + " p." + metadata.getInteger("page")
                    : metadata.getString("source");
            input.append("[").append(n++).append("] ").append(citation).append("\n");
            input.append(hit.embedded().text().strip()).append("\n\n");
        }
        return input.toString().strip() + "\n";
    }

    /**
     * PDF path: extract page by page so page numbers survive, remove repeated
     * headers and footers, and OCR any page that has no text layer.
     */
    static List<Document> extractPdfPages(Path file) throws Exception {
        try (PDDocument pdf = Loader.loadPDF(file.toFile())) {
            int totalPages = pdf.getNumberOfPages();
            String[] rawText = new String[totalPages];
            String[] method = new String[totalPages];

            PDFTextStripper stripper = new PDFTextStripper();
            PDFRenderer renderer = null; // created lazily, only if a page needs OCR

            // Pass 1: pull the raw text of each page, with OCR fallback for scans.
            for (int pageNumber = 1; pageNumber <= totalPages; pageNumber++) {
                stripper.setStartPage(pageNumber);
                stripper.setEndPage(pageNumber);
                String text = stripper.getText(pdf).strip();
                String extraction = "text";
                if (text.length() < MIN_TEXT_CHARS_PER_PAGE) {
                    if (renderer == null) renderer = new PDFRenderer(pdf);
                    text = ocrPage(renderer, pageNumber - 1).strip();
                    extraction = "ocr";
                }
                rawText[pageNumber - 1] = text;
                method[pageNumber - 1] = extraction;
            }

            // Detect lines that repeat across most pages. Those are the running
            // header and footer, and they are noise, not content.
            Set<String> boilerplate = detectRepeatedLines(rawText);

            System.out.println("Extracting " + file.getFileName() + " (" + totalPages + " pages):");

            // Pass 2: build one clean Document per page, carrying its provenance.
            List<Document> pages = new ArrayList<>();
            for (int pageNumber = 1; pageNumber <= totalPages; pageNumber++) {
                String raw = rawText[pageNumber - 1];
                String cleaned = removeBoilerplate(raw, boilerplate);

                System.out.printf("  page %d: %d chars via %s, %d chars after header/footer removal%n",
                                  pageNumber, raw.length(), method[pageNumber - 1], cleaned.length());

                if (cleaned.isBlank()) continue;

                Metadata metadata = new Metadata();
                metadata.put("source", file.getFileName().toString());
                metadata.put("path", file.toAbsolutePath().toString());
                metadata.put("page", pageNumber);
                metadata.put("total_pages", totalPages);
                metadata.put("extraction", method[pageNumber - 1]);
                pages.add(Document.from(cleaned, metadata));
            }
            return pages;
        }
    }

    /** Lines that appear on 60 percent or more of the pages are treated as running header/footer. */
    static Set<String> detectRepeatedLines(String[] pages) {
        Map<String, Integer> frequency = new HashMap<>();
        for (String page : pages) {
            Set<String> seenOnThisPage = new HashSet<>();
            for (String line : page.split("\\R")) {
                String trimmed = line.strip();
                if (!trimmed.isEmpty() && seenOnThisPage.add(trimmed)) {
                    frequency.merge(trimmed, 1, Integer::sum);
                }
            }
        }
        int threshold = Math.max(2, (int) Math.ceil(pages.length * 0.6));
        Set<String> boilerplate = new HashSet<>();
        for (Map.Entry<String, Integer> entry : frequency.entrySet()) {
            if (entry.getValue() >= threshold) boilerplate.add(entry.getKey());
        }
        return boilerplate;
    }

    /** Drop the detected boilerplate lines plus per-page markers like "Page 3 of 5". */
    static String removeBoilerplate(String text, Set<String> boilerplate) {
        StringBuilder kept = new StringBuilder();
        for (String line : text.split("\\R")) {
            String trimmed = line.strip();
            if (trimmed.isEmpty()) continue;
            if (boilerplate.contains(trimmed)) continue;
            if (trimmed.matches("(?i)page \\d+ of \\d+")) continue;
            kept.append(trimmed).append("\n");
        }
        return kept.toString().strip();
    }

    /** Render one PDF page to an image and read it with Tesseract. */
    static String ocrPage(PDFRenderer renderer, int pageIndex) throws Exception {
        BufferedImage image = renderer.renderImageWithDPI(pageIndex, OCR_DPI, ImageType.RGB);
        Tesseract tesseract = new Tesseract();
        tesseract.setDatapath(tessdataDir);
        tesseract.setLanguage(OCR_LANGUAGE);
        return tesseract.doOCR(image);
    }

    /**
     * Office and text formats: Apache Tika auto detects and parses almost anything.
     * Tika does not expose reliable page numbers, so these are cited by source file.
     * Note: ApacheTikaDocumentParser is stateful, so build a fresh one per file.
     */
    static Document extractWithTika(Path file) {
        Document document = FileSystemDocumentLoader.loadDocument(file, new ApacheTikaDocumentParser());
        Metadata metadata = document.metadata();
        metadata.put("source", file.getFileName().toString());
        metadata.put("path", file.toAbsolutePath().toString());
        metadata.put("extraction", "text");
        return document;
    }

    // ---- Qdrant plumbing ----

    static QdrantClient openQdrant() {
        QdrantClient client = new QdrantClient(QdrantGrpcClient.newBuilder(qdrantHost,
                                                                           6334,
                                                                           true)
                                                               .withApiKey(qdrantApiKey)
                                                               .build());
        return client;
    }

    /** Create the collection sized to the embedding model. Optionally wipe it first. */
    static void ensureCollection(QdrantClient qdrant, int vectorDimension) throws Exception {
        if (qdrant.collectionExistsAsync(collectionName).get()) {
            qdrant.deleteCollectionAsync(collectionName).get();
        }
        qdrant.createCollectionAsync(
                collectionName,
                VectorParams.newBuilder()
                            .setDistance(Distance.Cosine)
                            .setSize(vectorDimension)
                            .build()
        ).get();
    }

    static EmbeddingStore<TextSegment> buildStore() {
        var builder = QdrantEmbeddingStore.builder()
                                          .host(qdrantHost)
                                          .port(qdrantPort)
                                          .useTls(qdrantUseTls)
                                          .collectionName(collectionName);
        if (qdrantApiKey != null && !qdrantApiKey.isBlank()) {
            builder.apiKey(qdrantApiKey);
        }
        return builder.build();
    }

    // ---- helpers ----

    static boolean isPdf(Path file) {
        return file.getFileName().toString().toLowerCase().endsWith(".pdf");
    }

    static String env(String key, String fallback) {
        String value = System.getenv(key);
        return (value == null || value.isBlank()) ? fallback : value;
    }
}

Run it

Point inputFile at your PDF and run RagOverPdf. Same question as the last post — now with a written answer:

> Why did Egypt not win the 2026 World Cup?

===================== ANSWER =====================
Egypt were knocked out in the Round of 16: they lost 3-2 to Argentina in
Atlanta on 7 July 2026, after beating Australia on penalties in the Round
of 32. So they were out before the quarterfinals.
[fifa-world-cup-2026-knockout-log.pdf p.5, p.3]
==================================================
Sources:
  71% match  fifa-world-cup-2026-knockout-log.pdf p.5
  69% match  fifa-world-cup-2026-knockout-log.pdf p.3

Summary

Two weeks ago I set out to build a RAG app. The hard part wasn’t the code, but everything it assumed I was already aware of, such as, what a vector is, how closeness is measured, where to chunk, and how to cite the right page. So I broke it into a series, one concept at a time.

This is the final piece: no stories, just the code. Connect to hosted Qdrant, ingest a PDF page by page, embed with a local model, retrieve the nearest chunks, and hand them to Gemini for a sourced answer , each step a small block, with the full class at the end. Hope it helps you!