Messenger of the Gods

Protector of travelers

Oh so many titles

Great is your speed

Great is your might

As a Greek mythology lover I could not help to look for a poem or related phrase to Hermes and use it to open the article with it since I’ll be talking about an agent that carries his name. You can read the full poem some good fella wrote in Reddit.

With this in mind, last week I built a football analytics Skill for my football analytics tutorial repo using a stack I felt curious about: Hermes Agent + DeepSeek V4 Flash + Orca ADE.

Since someone I follow on X mentioned it, I decided to give it a go with a simple task: refactor the old repo and package it as a Skill to automate the process of generating football post match reports for teams and players.

In this article I’m talking about how to set it up, how much it costed, how I reviewed it, and the potential of using these harnesses for agentic coding.

The Setup

Hermes is Nous Research's autonomous agent → it’s MIT-licensed, it’s like a general agent with persistent memory and its own skills that good at code. Depending on their plan, they include more than 300+ models.

DeepSeek V4 Flash is the model I used, both the Flash and the official 0731, a 284B-parameter mixture-of-experts model with 1M-token context, built specifically for agentic and coding tasks.

Orca is the ADE (Agentic Development Environment) that runs both. It’s helpful to orchestrate agents and session to writes code so you can direct it and review it. Orca runs any CLI agent (Hermes, Claude Code, Codex, etc.) in isolated git worktrees, with terminals, diffs, and browser preview in one app.

Installing the pieces

Hermes Agent installs with one command:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

It pulls in uv, Python 3.11.15, ripgrep, ffmpeg, and Chromium (via Playwright) as dependencies, and drops the binary at this path:

~/.local/bin/hermes

You can also run:

hermes doctor 

To check if it came back clean, with no critical errors.

Nous Portal is the provider behind it

hermes portal 

It oppens an OAuth login in the browser, and once you’re in, in the billing and tool layer (Nous Portal).

I loaded $5.10 in credit ($5 top-up + $0.10 courtesy of the subscription) and got access to a tool gateway with many perks: top LLM model providers, web search/extract via Firecrawl, image and video generation via FAL, speech-to-text via Whisper, text-to-speech, and browser automation, all callable from Hermes.

DeepSeek V4 Flash was the main model I ran, Nous Portal exposes both deepseek-v4-flash at $0.11 / $0.22 per Mtok and a cheaper deepseek-v4-flash-0731 variant. More on the actual split in the cost section below.

Orca is where I actually worked. I installed it directly from its web. Once installed, you can get Hermes set as the default agent CLI inside Orca, and that’s the set I actually worked with: Orca as the workspace → Hermes as the CLI agent → DeepSeek as the model underneath.

Once installations were verified, I registered the football repo as its own workspace

orca repo add --path ~/orca/workspaces/football-analytics-tutorials

The Approach and How Much it Costed

Together, Hermes and Orca give you what's called a harness (the tools, memory, and execution control around a model), already built for you.

What I had to design was the goal loop → which is how you give it a goal, how you check its work, and when you call it done.

I asked Hermes to refactor the repo into a package and wrap it as a Skill that could be useful for any agent. Basically what I did was setting the /goal functionality and told it to:

• Check the repo and understand how it was structured: the web scraping, the visualization code, the metrics.

• A simple way of parametrizing the process with scripts and testing using software engineering best practices.

• Wrapping it under a skill that receives an input URL and outputs a rendered match report.

After the generation, I reviewed the generated charts (a process called human in the loop) and flagged what looked off.

There were minimal things in the charts like bad rendering on pass networks, stat labels that were unreadable against the background.

So I pointed them out to Hermes, which re-ran the tests and re-rendered the charts. I was based solely on how the chart looked like, so no elaborated eval for now. Same thing for both team and player reports.

When I checked the match report was good enough, I asked the LLM to document the results in a SESSION.md, to keep track of what was done, including decisions, mistakes and how it fixed it.

This helped a ton to build the player report, which was built a bit different than the match report, with a set of specific charts.

The model made less mistakes this time cause it had the context of what was being built.

Checking costs in Nous Portal

Verifying how much credits/tokens is the agent spending is crucial for budget and observability matters.

In Nous Portal you can track this easily, they even give you a CSV to export for analytics purposes.

Looking at the numbers the whole session cost $2.88.

Almost all of that went to two DeepSeek V4 Flash variant models, the default deepseek/deepseek-v4-flash which processed 119.5 million input tokens and 351K output tokens for $2.82, and the cheaper deepseek/deepseek-v4-flash-0731 which added 24.5 million input tokens and 213K output for another $0.05.

Combined: ~144 million tokens for $2.87. The rest was a few free calls to Step 3.7 Flash and some Firecrawl tool usage for lighter tasks along the way.

Key Takeaways

Cost effective models can do real work if the harness carries the memory. DeepSeek V4 Flash isn’t Claude of course but for the price, what it offers, and a tool gateway, the output was pretty decent. Hopefully there’ll be more competent models at better prices and with better harnesses.

SESSION.md helped the agent to improve the task. The player report came out with fewer mistakes than the match report, the fact that I had it to keep record of what broke last time and read before it started also improved the output.

Human-in-the-loop by analyzing the report result. There was a noticeable error in the match report where substitute players kept showing up labeled on the pass network with the same marker as starters a bug I caught cause I looked at the chart, flagged it, and told Hermes where the error was. It found the fix and ultimately solved it.

If you’ve ben using agentic coding tools and/or open models, what challenges have you find so far? Let me know in the comments!

Subscribe now

PS: As effect of August 16th DeepSeek increased their model pricing for V4 series.

Till next time,

Ricardo.

Although it worked as a standalone notebook and was well received, I wanted to give it some love. I wanted to improve it as a Python package and create a Skill that anyone can reuse to plug it into their preferred agent in order to automate the generation of single post match reports.

Much has changed in the AI landscape since I created that notebook.

Yesterday I was playing around with a setup I saw on X/Twitter → Hermes Agent + DeepSeek V4 Flash + Orca as Agentic IDE, so I decided to set it up and test it by giving it this repo and letting it run with clear goals: refactor it, improve the report, test it and build the skill.

In this article I’ll talk about the repo itself, the skill and its result. I’ll talk briefly about the tools I used to generate this but will leave the setup details and what they are for another article since I believe they deserve their own piece.

What you’ll get in this article: a skill that receives one URL from WhoScored as input and generates a 24-chart report out, ready to use in an agent that can run the whole thing for you.

Let’s see what changed.

The new feature

I wanted to make a simple skill which core capability was just one thing → you input a Match URL from WhoScored and obtain a post match report out.

uv run football-match-report scrape "<whoscored-url>" --out ./data
uv run football-match-report render --data ./data --out ./report

These two commands turn any match into two PNGs: the team report and the zone analysis (a new part of the report I included)

I tested it end to end on Salzburg 0–3 Real Madrid from last year Club World Cup, and on Chelsea 2–1 Tottenham from the Premier League from last season.

Data Sources

The report merges two data sources:

• WhoScored, scraped through headless Chromium, provides the full event stream: passes, tackles, carries, and recoveries with coordinates. That powers the passing networks, defensive blocks, progressive passes and carries, and the xT momentum chart.

• FotMob, fetched with plain requests and no token, provides shots with xG and xGOT, the official stats, the player of the match, and real team colors. A tricky part: mapping the date and team names which is pretty much solved from the WhoScored data (check the repo for more details)

The charts follow the Post-Match-Report-2.0 blueprint from my pal Adnaan. The pitch is rendered using UEFA pitch coordinates at 105×68, black background, shirt numbers inside player nodes, circles for starters and squares for subs, and an xT momentum bar. Assembling sixteen chart types into two figures of twelve panels each.

The professional Python package

The repo now behaves like a real open-source package.

The code lives in src/football_match_report/, split into core, io, and viz modules.

src/football_match_report/     # the package
  core/events.py               # event pipeline: carries, possession, xT, UEFA scaling
  core/stats.py                # match/shot statistics
  io/whoscored.py              # Playwright scraper
  io/fotmob.py                 # FotMob API (id resolve, matchDetails)
  viz/pass_network.py          # passing networks (shirt numbers, line heights)
  viz/defensive_block.py       # defensive KDE heatmaps
  viz/progressive.py           # progressive passes & carries
  viz/shots.py                 # shot map + goalkeeper saves
  viz/momentum.py              # xT momentum chart
  viz/match_stats.py           # stats bars
  viz/zones.py                 # 8 advanced zone charts
  viz/report.py                # 2x 4x3 figure assembly
  cli.py                       # scrape + render commands
skills/football-match-report/  # installable agent skill (SKILL.md + thin wrappers)
tests/                         # offline unit + render tests (synthetic match data)
docs/                          # sample report images

This way you can use the package to install, import, test, and extend it as you wish. The scraping logic, the coordinate conversions, and the chart code are separate modules with single responsibilities in order to follow software development best practices.

The Skill Itself

The same repo ships as an installable agent skill → skills/football-match-report/ contains a SKILL.md, reference docs, and the scripts the agent needs.

An agent that has this skill installed can run the whole workflow from a natural-language request, because the skill carries the knowledge: the commands, the data format, the coordinate conventions, the verification steps.

Launching it from Hermes, my code agent, takes one request.

The skill lives in the agent’s skills folder. From there, asking for the report for a WhoScored URL match is enough. The agent hands me the two PNGs.

That’s the shift I wanted to give it and what I love about the process of creating skills. You can move all the knowledge from your head into a document and then handing over the execution to the agent.

The process

The original dashboard was created along with by Claude Sonnet 4 in Cursor last year but this version was built on a different setup, one I chose as an alternative to Claude Code.

I built it with this agent stack:

Hermes running DeepSeek V4 Flash as the default model, inside Orca, an agentic development environment.

The agent did the heavy lifting during the 3-4 hours session: the package structure, the scrapers, the test suite, the CI workflow, the skill packaging.

I did the human in the loop review by opening the rendered PNGs and looking at potential errors.

Doing this loop I caught some rendering issues problems, like: every player node rendered as a circle, because WhoScored only sets isFirstEleven on starters, substitutes get NaN, and bool(np.nan) evaluates to True in Python.

So in order to fix it I had to: tell the agent where the fix was → tell it to test it again with the data and logic → check the rendered result again.

How I set up that stack, the models, the cost, and why it works as a Claude Code alternative deserves its own post in the upcoming days.

Next steps

Using this report as the foundation to generate a new player-level dashboards with top passers, individual pass maps, per-player shot and defensive stats from that specific match.

Maybe more leagues and competitions and a simple persistent storage for the scraped data would turn one-off reports into a history you can track (which is something I was trying to do with my Football RAG project).

Why this matters

This is an improved version of the tutorial repo.

You as a fan, technical person, or curious coach/scout that knows Python and wants to see tactical execution from a match, flag a concrete player, analysts spot patterns across matches, can reuse this in a more straightforward way.

The difference now is that instead of plotting everything each time by yourself you can run two commands or a Skill in natural language with an agent.

If you build football analytics, or you build with agents, the repo is open source: https://github.com/ricardoherediaj/football-analytics-tutorials

Enjoy it, and feel free to share with anyone!

Subscribe now

Till next time,

Ricardo.

At the end of the month I'd copy everything into a “cleaner format”, add up the totals, and try to understand where my money actually went.

More recently I moved the capture part to Notion, which made the notes prettier but didn't remove the manual copying making it boring still.

For me, knowing my balance at the end of the month matters because I can tell how much I spent, saved, and invested, and that helps me decide how I organize the next month. The issue comes when tracking lags two weeks behind, so entries pile up.

Notion 🤝 Superhuman

One day probably in 2024, in an online investing community I'm part of, the owner shared a finance template built in an app called Coda (now renamed as Superhuman). I see it like Notion but with steroids.

The template has three pages with databases and charts linked between each other: one for expenses, one for income, and a balance page that recalculates income, spending, and savings per month on its own. For each row you just need a date, and the monthly formulas do the rest.

Here are pictures with some mocked data:

So my process became: register expenses in Notion each day → then move them to Superhuman at the end of the week or month, row by row.

There were like thirty plus entries every single month, and doing it by hand became tedious.

A Simple Solution

Both Notion and Superhuman have MCP servers, which means Claude can read and write to them directly. I’m trying to make Claude the manager of many areas of my life by using its skills. So far I have a writing skill that helps me create and review articles like this one. Now I’ve created one to automate my finances.

So I wrote a Claude Code skill called finance-sync that does the tedious part for me by connecting to both Notion and Superhuman through the MCP servers in my Claude settings.

In case you’re not familiar with skills yet, as defined by Anthropic they basically are:

A way to turn your expertise, procedures, and best practices into reusable capabilities so Claude can apply them automatically, every time.

And if you want a quick understanding on what MCP is you can read this article with a practical example I built a while ago or redirect to the official site.

The daily habit stays the same: I type each expense into a small Notion database, one per month, with four fields: concept, amount, a free-text category, and a date. There's a fifth field too, a checkbox called Synced, which is the actual checkpoint that lets me know what I have already tracked.

When I want to sync, I run the skill.

Claude reads every row where the checkbox is unchecked, figures out whether each one is an expense or income, maps my lazy free-text categories to the real category rows in Superhuman, shows me a summary table, and waits for my confirmation.

Only then does it write the rows into Superhuman and ticks the checkboxes back in Notion.

The Superhuman balance page actually needs nothing from the skill cause its formulas pick up the new rows by date and recalculate the month on their own.

How to set it up for yourself

Create free accounts in Notion and Superhuman.

Connect the MCP servers. To do it Claude Desktop, you can go to Settings, Connectors, and Add them. I added Notion and Superhuman the same way you’d connect to any other app: log in, authorize, done.

Grab the template and write the skill. I made a copy with mocked data of my Superhuman doc so you can duplicate this Finances 2026 template yourself, so instead of starting from a blank page you have some fake data to play around with.

Once you have your own copy, adding the skill is as simple as dropping in a markdown file that tells Claude the shape of your tables: the column IDs, the category list, and one hard rule, never mark a row as synced until the write actually succeeds. I put my own version in this Drive link, so you can download the files and adapt them.

This is how it’s structured:

finance-sync/
├── SKILL.md # the file that tells Claude how to do the task
└── references/ # folder Claude uses as a reference to run the skill right
    ├── notion.md # reference of the Notion database tracker
    ├── coda.md # Coda/Superhuman template, rename it to superhuman.md
    └── categories.md # existing categories reference

To install it: in Claude Desktop, go to Settings → Capabilities → Skills → Add → Upload or "Write the skill's instructions," and paste it in. If you use Claude Code instead, drop the same file at ~/.claude/skills/finance-sync/SKILL.md, plus its references/ folder, and Claude picks it up automatically.

Run it once and check by hand before trusting it. The first time, I compared Claude’s proposed summary against my own notes for one full month before saying go. After that, I just run it.

Three problems I found out

The first problem was duplicates. If I run the sync twice, I don't want my rent showing up twice in October for example. There's no reliable way to detect duplicates on the Superhuman side, so the Synced checkbox in Notion is the only source of truth for what's pending.

The ordering is what makes it safe: rows get marked as synced only after the Superhuman write succeeds. If the write fails halfway, the unwritten rows stay unchecked and nothing is lost. If you run the skill on a month with no pending rows it just reports "nothing pending" and touches nothing.

The only caveat: if that checkbox is wrong, the sync is wrong too. There's no real duplicate detection here, just one checkbox per row. For a personal tracker, that's good enough.

The second problem was categories. Notion lets me type whatever category I want; Superhuman expects a reference to an existing category row. Most of the time the mapping is obvious. But when I typed "Donation" for a charity gift and no such category existed in Superhuman, instead of guessing Claude proposed creating the new category and asked me first. I said yes, and it created the row and used it. That confirmation step I like: the model classifies but I approve.

The third problem was that the Superhuman MCP has a 30 message quota for the free plan which is the one I’m using, so this made me want to look for other flexible options but keeping the same workflow.

The first real run

The first time I ran it for real, I had 5 unsynced rows from June and 19 from July, eleven days of expenses I hadn't moved, which tells you how well the manual process was going.

One run: 24 expenses and 1 income written into the template, two new categories created with my confirmation, every checkbox ticked, and the July balance recalculated by the time the skill reported back.

The part that used to take me more than 30 minutes now takes a couple of seconds by just writing:"sync my finances." or “/finance-sync”

What I'd tell you to steal

Build a skill that moves the data to wherever you actually analyze it, and use a checkbox to track what's already been moved. Any two tools with MCP servers can play these roles.

My version still has rough edges. The template doc only works for one year, so I’ll need a new one every January. And the whole thing trusts one checkbox right now.

That’s what I want to find out next: how it holds up after a few more months of real use.

I hope this approach gives you an idea on how to use Claude to work with skills and MCP servers to automate boring tasks.

Till next time,

Ricardo.

Geologists call this a "doublet". It’s defined as two major quakes close in time.

We’ve had earthquakes before but none like this.

Entire buildings collapsed. Families torn apart. Kids, pets, men, women buried under concrete. La Guaira became one of the most affected areas of loss. Over 100 residential and tourist buildings collapsed entirely. And many people with them.

At the time of writing this, the numbers are still moving, which is the worst part cause people are still being rescued. As of June 27, the official toll sits near 920 dead and over 3,300 injured. The UN estimates more than 50,000 people are still missing under the rubble. Citizen-made lists circulating on social media name over 52,000. Still everyone is affected directly or indirectly by this.

Supporting From the Distance

I left Venezuela five years ago, I built a different reality, in another country but when something like this happens you realize the migratory grief was always there, latent, underneath.

Thankfully, my family is safe since they live in a state outside the worst-hit zones. Still I can’t feel relieve because of seeing other people suffer, as that suffering becomes mine too.

I saw colleagues and friends of mine driving from one state to another carrying supplies (water, food, clothes, medicine), showing up to hospitals already overwhelmed, rescue workers and regular neighbors digging through collapsed concrete with their bare hands and tools to rescue people.

Several businesses and companies gathering supplies, giving free rides, and gathering funds (like Yummy) to aid the victims.

All of this made me feel really proud and moved. It’s the reason I’m writing this. To showcase the best part of Venezuela: their people.

Other countries showed up too. More than 17 countries sent aid. Over 30 international search-and-rescue teams with hundreds of specialists deployed on the ground, like El Salvador’s, Madrid’s own ERICAM, American rescuers, and many others giving a hand to a catastrophe this country was never prepared for.

Why the consequences are worse than they should be

Simply: because of twenty-six years of Chavismo.

Hospitals were already damaged and under-resourced before the earthquake.

More than 90% of households reported chronic failures in basic water and electricity before June 24.

Nearly 8 million people already needed humanitarian assistance before a single building fell.

Fire departments, police, public infrastructure, building codes, roads, systematically downgraded on purpose. Gutting the country’s capacity to protect itself by stealing the money to enrich themselves.

This is the worst tragedy of all the daily tragedies these 26 years have produced. All made on purpose. There’s enough material for a series of articles, movies, and series of Netflix on how the regime destroyed our nation, but the goal of this post is to highlight what the citizens in and out of Venezuela are doing right at this very moment, and how to actually help wherever you are reading this.

How to Help From Anywhere

• Deliver supplies in your city: Look for Venezuelan collection points (centros de acopio) in your area this might be churches, community organizations, warehouses. Diaspora groups are coordinating shipments. What's most needed: water, non-perishable food, hygiene kits, blankets, flashlights, batteries, first aid supplies, medications, USEFUL clothes. Check this web to locate centers in and out of Venezuela: Donation centers for Venezuela

• Donate money: in my opinion this is the highest-impact option from abroad, because it lets organizations buy exactly what's needed locally.

  These are some verified and trustworthy links you can point to:

🆘 Emergency Relief for Venezuela Earthquake Victims (GoFundMe) organised by the I Love Venezuela Foundation

🏠 The House Project providing on-the-ground support

🤝 Venezuelan Chamber of American Commerce for direct donations

❤️ Cáritas por Venezuela humanitarian aid

🛵 Yummy Venezuela

• Spread the word on these type of webs that the tech ecosystem is building for Venezuela: redquipu.com

I hope the one reading this now or further in time can connect with the suffering and needs of Venezuela. I also hope this takes part of our collective memorial. To remember we stood together during tough times.

Please share this with anyone you think can help and want to have some context on the situation.

For all the victims, all the families who lost someone they loved.

Share

There’s not just one way of building them, it depends on what you want to achieve and the level of control you want to have over your agentic system.

Today, I want to talk to you about a real use case applied to football so you can see how is it to define the scope of building an agent, the rationale behind choosing certain tools, the errors, and thoughts on the process.

A Basic Stats Analyst

I recently built an agent with my teammates during the Context Engineering course by Twelve Football that finished just a couple weeks ago.

The goal was to build a basic stats analyst agent that answered questions grounded on the Premier League 2024/2025 season dataset from Wyscout.

For that we used a defined set of tools:

• Pydantic models for data validation and structured outputs

• OpenAI tool calling

• DuckDB as our light weight SQL and vector database

• OpenAI LLM and embeddings models

• Streamlit as frontend for demo purposes

Down the road, we found out these were our preferred tools to build it, but it started out slightly different.

The First Version (v1)

In the beginning we had a shaky Python script with ~1,400 lines of regex code that relied heavily on pattern matching, and it broke every time we asked something different.

The LLM was giving responses but only those that were included in the if/else loops.

Questions like these were answered pretty well, but if you wanted to follow up the conversation, it lost context entirely. Also note that the wording is too verbose on metrics, a weird way to display the stats cause nobody talks like that.

So with every new question, we needed to patch more code.

We weren’t using the LLM properly to interrogate the dataset well.

The Data Goes First

Before any answer reached the user, it had to pass through two data layers.

The first was Pydantic. We used it both to structured the output and to evaluate the responses against our questions benchmark. The LLM returned a verdict whether an answer was faithful or correct against a typed schema that matched our benchmark.

passed: bool, reason: str.

If the output didn’t match, it failed explicitly to avoid wrong responses and data leakage downstream.

The second was DuckDB, a lightweight SQL database that runs in-process without servers or heavy infrastructure. It read the Wyscout parquet files natively and, through its vector similarity extension (VSS), also stored the player and team embeddings for name resolution. Giving us the power of SQL queries and vector storage in the same tables.

Both of these were used to making sure the data the agent worked with was grounded data and it gave back grounded answers.

How the Tools Work (v2)

Now with the data layer in place, we needed the agent to actually use it.

So we used Tool calling.

It is how the LLM interacts with the database without touching it directly. The user asks a question, the LLM decides which tool to call and with what parameters, Python executes it against DuckDB, the result comes back, and the LLM writes the answer from that data.

We defined 4 tools: query_player_stats, query_team_stats, query_ranking, and get_league_standings.

Each tool has a name, a description, and a parameters schema. The description is what the LLM reads to decide whether to use it. The parameters tell it what arguments to pass.

Here’s how we defined the position filter inside query_player_stats:

That description is doing what you’d write as a Python dictionary. The alias mapping, the edge cases, and the forward exception all lives in a string the LLM reads at inference time.

And it worked.

Here’s the agent handling a multi-step question about Salah, where it had to build a custom opponent bucket, compare it against the rest of the season, then filter again by Champions League teams, all in the same conversation:

But we started with 9 tools.

There were separate tools for top scorers, best passers, most progressive carriers, each its own function.

The problem was the LLM kept picking the wrong one because the descriptions overlapped. It would call get_top_scorers when it should have called query_ranking with metric=goals.

So we merged them down to 4, with broader scope and cleaner descriptions.

Going from 9 to 4 reduced routing errors more than any prompt tweak we tried. With fewer tools the LLM had fewer decisions to get wrong.

While building the position filter, we had a Python dictionary in agent_tools.py that mapped user aliases to database values at execution time.

Every time the LLM passed "CB", Python caught it and translated it to "Central Defender".

It worked. But we deleted it.

We realized the same logic could live in the tool description instead. If you write it clearly enough, like documentation, the LLM passes the right value before the code ever runs.

Memory

In v1, the conversation had no memory between turns. If you followed up on a question, the context was entirely lost.

We fixed it with one line of code using the OpenAI Responses API. It kept the conversation state through previous_response_id. You pass the last response ID and the API handles the rest.

This how it looks in code:

This is how it looked in the Streamlit UI:

How We Knew It Worked

We built a benchmark of 61 questions and ran it after every change we made. Each answer was scored by an LLM judge against the expected output, so we didn't have to go through them manually.

At the end, we threw 21 random questions at it that none of us had prepared for. It got 21 out of 21.

The screenshot also shows the agent refusing questions it can't answer. That's something we had to build explicitly in order to make it refuse out of scope questions and not hallucinated.

Wrapping Up

Right now it only covers the Premier League 2024/25. Just one league and one season.

The interesting question is whether the same approach holds when you scale it. More leagues, more seasons, harder questions.

That’s what we want to find out next.

Subscribe now

Till next time,

Ricardo.

Ryan Day (author of Hands-On APIs for AI and Data Science, O’Reilly) and writer of the Tip Sheet newsletter featured me in his issue #65 last week.

He asked eight questions about my background, my stack, and how I learn.

There were three of them I wanted to expand a bit and share some thoughts with you.

Q4: Why are side projects valuable for people learning data science?

In a side project you set the tone of what you want to build, why it matters, and how to measure if it worked.

You pick a problem you care enough about, you define the requirements, the scope, the technology and the dataset. It forces you to learn and think with a kind of clarity that structured learning rarely does.

I started with football analytics because I wanted to apply what I was learning to something I cared about and found fun enough and it has led me to push my knowledge forwards and collaborate with special people I wouldn’t think I’d meet if I didn’t build these kind of projects.

Fun fact is: this also helped to me work on healthcare data/AI projects on my day job.

Q6: What methods of skill development have you benefited from most?

I told Ryan I combine three: structured learning, project-based learning, and unstructured learning.

In this case my opinion is that the order matters.

Structured learning gives you the map and foundations to get the knowledge that you can then apply to projects. It doesn’t mean you need to learn everything there is about a topic and fall into rabbit holes, but just learning the necessary info to start building and leaving room for experimentation while you research stuff when you’re stuck.

On the other side unstructured learning like newsletters, blog posts, a well-curated social media timeline, keeps you updated to where the field is actually going. It can even give you some ideas to implement them yourself on your projects.

A dangerous trap is staying too long in one mode.

Entering tutorial hell by finishing a course and starting another course with no meaningful output (been there) creates an illusion of learning. Or jumping straight to building without a minimal foundation, spending weeks debugging something a couple hours read (or documentation) would have clarified.

The sweet spot is knowing when to shift from one to another. For example, if you’re new to something or you’re a bit confused, go with structured.

When you feel you got a good initial grasp of that knowledge, go build something even if it’s small, to make it stick.

If you feel you want to see how the field evolves, go with unstructured.

Right now I’m running all three in parallel: taking Agentic AI Engineering course at Towards AI Academy by Paul Iusztin and Louis-François Bouchard, applying it directly to a tool I’m building for myself, and constantly reading newsletters like Ryan’s to stay sharp on what people are shipping.

Q7: What would you tell people who want to keep developing their technical skills?

To make it stick, I’ll put it inside quotes:

Write about what you learn and share it online.

Not for personal branding but because explaining something forces you to actually understand it.

Every post I’ve written about RAG pipelines, MCP, or football data sources has exposed gaps in my own thinking that I didn’t know were there until I tried to put them into words. This makes me want to understand things better.

Th big myth we need to debunk is the need for a big audience. You actually don’t. The “trick” is to be consistent even if you have a “small audience” or you think nobody’s going to listen. There are people out there that will definitely benefit from your point of view.

You can write a bug you fixed, the trade-off you made when deciding on your tech stack, the framework you just learn from one field and how you applied it to solve a problem in another.

Maybe ten people will read it but one of them might be building the exact same thing and needed exactly that post. Or one of them might be writing a newsletter and looking for someone to interview 🤷🏻‍♂️

Your job is to make it exist.

Subscribe

Here’s the link to the full interview: Tip Sheet #65: Data Scientist, Doctor, Football Aficionado

Till next time,

Ricardo.

That led to dashboards and models nobody used or cared.

Then last week in the Twelve Football Context Engineering course, I realized how the concept behind the framework for measuring team and player performance they teach could be used for solving problems in other areas.

Asking questions first, then data

I’ve been taking this course for the past two weeks and the knowledge compounds incrementally from one week to another. The goal is to create a project around qualities, metrics, pitch visuals and time series approach that they emphasize at Twelve.

Their framework starts with a simple instruction:

Start with football. Not data.

The first step is asking a human question like “what you are trying to answer and for whom?”.

What insight can you bring that no-one else has brought before?

An initial question might be: What makes a good midfielder? or What makes a team dangerous in defensive transitions?

Once you’ve answered that in plain football language you move to the data. The idea is to build Qualities → composite scores that capture a specific aspect of player or team performance.

You choose 3 to 10 metrics that capture different aspects of the concept. Assign weights based on how important each one is to the original definition. Compute scores using z-scores and compare each player against the right group.

That last part is highly important.

For example when building a Passing Quality score for midfielders, you can end up with five metrics: Passes (xT), Passes into the final third (xT), Passes in the final third (xT), Crosses (xT), and Creative passes weighted at 30%, 20%, 20%, 20%, and 10% respectively. The result is a single score that tells you how threatening a midfielder’s passing is.

In this image you can see Belgian player Kevin De Bruyne scores near the top but the framework also tells you why, and which specific dimension he excels at versus where he’s merely good compared to other players.

That’s the useful part.

Context is everything

“Metrics are meaningless without context. Choosing the correct comparison group is essential.”

The comparison group (position, age, league, minutes played) is where we need to emphasize the analysis. Posing the problem and thinking clearly about it before writing the first line of code.

For example a midfielder with high progressive passes has a different meaning than an attacking midfield who sits deep in the field.

A 25 y/o player that has an elevated duel success rate has a different interpretation than a 32 y/o player in the same league.

To produce accurate insights, we need to use the same comparison pool of players.

How you can use it in other industries

Take diabetic patient monitoring. A case I’ve been actively working on in my day job.

The human question becomes: How well is this patient managing their blood sugar?

You define it in clinical terms first, consistent glucose levels, avoiding dangerous highs and lows, showing improvement over time. Then you look at what you can measure: HbA1c, time above range, time below range, trend direction, glucose variability.

You weight them by clinical importance to finally compare against patients of similar age, diabetes type, and diagnosis duration.

The output is a sentence a physician can actually use:

“This patient’s glycemic control is below average for their profile, but trending in the right direction over the last six months. The main challenge is post-meal spikes, not overnight lows.”

The focus is on turning data into a decision.

You could also apply this template for industries like customer churn in SaaS or credit risk in finance, by always starting with a human question.

Key Takeaways

The best analytical frameworks are domain-agnostic. They travel between industries.

Start with the human question by defining the concept before you open the dataset, choosing your comparison group deliberately, then let the data answer.

The framework already exists in your field and most people just never look outside their own.

Share The Underdoc

Thanks for reading one more time.

Till next time,

Ricardo.

The numbers and metrics were being computed, the LLM was receiving them, acknowledging them, and then repeating them back to me as if reading from a spreadsheet.

“Home xG was 1.2 and they scored 3 goals. Away PPDA was 4.8, indicating a high press...”

There was no enriched analysis it was just data recitation that didn’t sound like football language.

I was using claude-haiku-4.5 which is capable of writing football language. If you ask it to analyze a match in prose it’ll produce something close to what a scout would write. The model actually knew what a high press looked like, what a low block meant, defensive compactness, progressive passing patterns, etc, but by asking it to recite metrics I just wasn’t letting it “speak” football.

The problem was my prompt not the model

I was passing raw floats directly to the LLM (PPDA of 4.8, expected goals of 1.2, progressive pass counts, compactness scores) and then instructing it to “state only what the metrics directly prove” with “technical terminology and neutral tone.”

David Sumpter, the brain behind Soccermatics and Twelve Football, calls the solution → Wordalisation. The idea is straightforward: before you call the LLM, classify your raw metrics into qualitative English labels. The model never sees the numbers. It only sees what those numbers mean in the language of the domain.

Here’s what the change looked like in practice.

Before, the user prompt contained something like this:

home_ppda: 4.8
home_high_press_count: 12
home_compactness: 33.4
home_field_tilt: 67.9

After applying Wordalisation, the LLM received this instead:

home_press_style: pressed_aggressively_allowing_few_passes
home_defensive_shape: compact_block
home_territorial_dominance: dominated_final_third
home_shot_quality: created_high_quality_chances

Just English labels describing what the team actually did, derived from the real Eredivisie 2025-2026 distributions rather than arbitrary thresholds.

The smoke test output shifted the result for good:

Before:

“Home xG was 1.2 and they scored 3 goals. Away PPDA was 4.8...”

After:

“Heracles set up to frustrate, sitting deep and inviting PEC Zwolle to come at them — a coherent enough plan in isolation, but one that demanded defensive discipline and clinical use of the rare moments they could hurt the visitors on the break. A low block without the finishing to punish opponents on the counter is simply a slow surrender.”

The data from the pipeline was exactly the same, but thanks to this tweak the output changed completely.

The second change: how I formatted the context

I implemented this one from a course I’m working through called Agentic AI Engineering from Towards AI.

The lesson was about Context Engineering, the discipline of deciding what goes into a model’s context window in order to make it follow the right instructions.

One of the practical recommendations was: prefer YAML over JSON when providing structured data as input.

I’d been using Python dicts serialized as JSON. The lesson argued YAML is more token-efficient and reads more naturally alongside prose examples in a prompt.

I ran a quick comparison on my own <tactical_labels> block.

JSON version:

{
  "home_press_style": "pressed_aggressively_allowing_few_passes",
  "home_defensive_shape": "compact_block",
  "home_territorial_dominance": "dominated_final_third"
}

YAML version:

home_press_style: pressed_aggressively_allowing_few_passes
home_defensive_shape: compact_block
home_territorial_dominance: dominated_final_third

The YAML block is shorter (no brackets, no quotes, no commas), and it reads more like prose which matters when it’s sitting next to few-shot examples written in natural language. The model processes both from the same context window. Found out that small token savings compound across many calls, and a cleaner context means less noise for the model to work through.

The other Context Engineering principle I applied was prompt structure.

The lesson covered something called the “lost-in-the-middle” problem: LLMs tend to underweight information placed in the middle of long contexts, so what they remember best is what comes first and what comes last.

The practical implication: you have to put your most important instructions at the START (system prompt) and at the END (<instructions> block). Dynamic content like match labels and retrieved facts goes in the middle.

And for caching: put static content first. That way the system prompt and few-shot examples don’t change between calls. Both go at the top, before any dynamic match data. This allows the provider to cache the static prefix and skips re-processing it on every requests.

My prompt structure now looks like this:

<system_prompt>     ← static, cached
  [scouting style instructions]

<few_shot_examples> ← static, cached
  [two reference match analyses]

<match_context>     ← dynamic per call
  [YAML labels for this match]

<instructions>      ← static, repeated at end
  [core constraints, re-anchored]

The model gets its instructions twice.

Once at the top before anything else and once at the bottom after seeing the data. This is how we can avoid lost-in-the-middle.

A broader principle connecting Wordalisation and Context Engineering

Both are fundamentally about the same thing: giving the model the right kind of information.

Wordalisation says: don’t give the model numbers and ask it to interpret them. Classify the numbers into domain language first, then give the model language it can work with.

Context Engineering: don’t give the model everything you have. Select what’s relevant, compress what’s not, format it so the model can use it without fighting its own architecture.

Since the LLM does not work as a calculator nor a database we need to feed it with the right data: language.

Key Takeaways

The RAG system has a well curated data pipeline but now, at the point where structured data meets the language model, there’s a much needed translation layer that needs to be included.

The data flows like: Numbers → Labels → LLM → football insight.

That’s exactly the principle of Wordalisation applied to Context Engineering.

Hope this gives you an idea on how to translate metrics into text, by leveraging LLM’s text generation capabilities.

Till next time,

Ricardo.

At some point of our lives, someone tells you to pick a lane.

The school, a teacher, family, social media. Maybe your own head at 2am wondering if you’re interested on too many things to ever be taken seriously at any of them.

“Pick one thing, go deep enough and become an expert at that for the rest of your life.”

Although the most interesting people I’ve come across didn’t get there by picking a lane but by refusing to.

Subscribe now

Specialists & Outliers

I’ve been recently reading Dan Koe’s Purpose & Profit and a concept that grasped my attention was that the education system was never designed to help you reach your potential but to turn you into a useful workers in an interchangeable role.

Debatable but I can see the point behind it, if you’re only trained to do one thing you can’t adapt. Specialization isn't bad. But betting your entire identity on a single skill, in a world that's moving this fast, is the riskiest thing you can do.

Your Weird Combination Is the Advantage

I’ll use my own story here because it’s the most honest one I have.

I graduated from med school in Venezuela in 2019. But I felt something was off. Not wrong exactly, I knew I was supposed to be there but I wasn’t feeling fulfilled.

So I started exploring other things on the side: bartending, mobile app development, whatever I could get my hands on.

Then the pandemic hit, and I stumbled upon Python.

Something clicked.

I started applying it to football analytics and got immediately hooked.

I took MOOCs, networked with people in the industry, and eventually joined a non-profit group of analysts working with NWSL and national teams with real data from top providers like StatsBomb, Tracab, Opta.

Then I expanded into data science and machine learning applied to business. This expertise helped me land my first tech role at an AI consultancy, working on health projects and speech recognition.

Along the way, LLMs and RAGs came into the picture, and I started applying all of it to the projects I was already building.

At every step, someone raised an eyebrow.

Why tech? You are a doctor. Why football? You’re a doctor in tech.

I never had a clean answer, but I knew I was shaping the foundations of my identity.

At some point I got honest with myself about where I actually stood. I listed the gaps in my foundations: systems thinking, engineering depth, the ability to build things that work in production and not just in a notebook.

So I looked back at my background as my advantage and started building from it.

I had:

• A medical mindset

• Data/AI engineering foundations

• Football domain knowledge

• AI tools to help me build and mix all of these.

That led me to create my own Venn diagram intersection.

That’s Koe’s point when he says you are the niche.

Most people spend their careers searching for an external niche to fit into (I’ve been guilty of that too). But your specific combination of experience and context it’s already a niche. You're standing in it.

A couple of days ago on a Saturday night, I was building my football RAG system (a project that’s teaching a lot on engineering foundations), and I lost track of time. I ended working from 9pm to 3am. It felt like craft and I think that’s what happens when you stop fighting your weird path and start building from it.

Mapping Your Own Stack

Some self-awareness is necessary here to understand how to mix your skills, (might sound like a self help book advice but trust me, you need to sit with yourself on this). I want to give you something I didn’t have at the beginning of my journey: a starting point.

Start by asking yourself these three questions. Note them down on a notepad, Notion, or somewhere else you can easily go back to:

• Is there something you know that most people in your field don’t? Something specific rather than general. What context do you bring that wasn’t in the job description?

• Where do your interests converge? The things you read on weekends, the problems you notice in one domain that nobody there is thinking about because they don’t have your other domain to compare it to.

• What can you build to work at the intersection of it? Think in projects, tools, analyses, newsletters. Something concrete that only you could have built from exactly where you’re standing.

• An extra: How can you leverage the use of AI to boost your skills?

I would start from there.

May The Weird Ones Prevail

We now know the system was not designed for this but AI is compressing the value of standard skills faster than most people are ready for.

What it can’t compress is taste, context, and the specific lens you’ve built from an unusual combination of experiences.

The people who do well in what’s coming won’t be the deepest specialists or the broadest generalists.

They’ll be the ones who can see across domains, connect things that shouldn’t logically connect, and build things that require a very specific, very strange set of keys to unlock.

Your weirdness is your moat.

This newsletter is about building AI systems, using football analytics as the sandbox. But every now and then it's worth stepping back to talk about why we build what we build, and how we decide what's worth building next.

Till next time,

Ricardo.

Share The Underdoc

In previous articles we’ve covered:

• Engineering the data pipeline: RAG is a Data Engineering Heavy Problem: Building a Football ETL for AI

• Evaluating the prompt and system outputs with EDD: From Vibes to Metrics: How I Evaluated A Football RAG System

Today I’ll be talking about the challenges of designing a user interface to interact with in an effort to make it as comfortable as possible.

This marks the end of these series on how I’ve built this MVP, which I’m scaling into an automated data platform that generates football post match reports and can run on your own computer.

You can find the entire code on the GitHub repository and the new releases: Football RAG Intelligence

What’s Gradio and Why I Chose it

If you haven’t heard of it already, Gradio is an open-source Python framework that allows developers to quickly build and deploy interactive web interfaces for ML models and data pipelines.

In the context of the Football RAG platform, I used it as a lightweight presentation layer to connect the user to all the backend logic (pipelines, LLM orchestration).

At this stage of development, the goal was to keep it simple. I chose Gradio over Streamlit for these reasons:

• Avoid rerunning the script each time there’s retrieval.

• API capabilities: Gradio automatically generates a REST API for your interface, making it easier to treat the UI as modular rather than a monolith.

• LLM Integration: Gradio’s ChatInterface component is purpose-built for the conversational nature of RAG, allowing me to focus on prompt optimization rather than building widgets.

• Fast iteration: working with 108 matches, it allowed for a full database rebuild and UI refresh in seconds.

Although in the future I could move to another frontend, this was enough to validate the idea.

HuggingFace Spaces Deployment

The simplest way to host an AI/ML demo without becoming a full-time DevOps engineer was a using HuggingFace Spaces.

It’s basically a managed hosting service where you can drop your Gradio app.

Some characteristics:

• GitHub-Style Deployment: You push your code to a repository, and Spaces automatically builds the container and serves the app to a public URL.

• Seamless Integration: Since it’s natively built for the ecosystem, it handles the Gradio environment and Python dependencies out of the box.

• Free Tier: It provided the perfect “sandbox” for the MVP, giving me a URL to share it publicly using generous CPU compute.

A Reality Check: MVP vs. Production

Grado helped to build the UI easily, but making it "industrial-grade" meant facing a few technical issues.

1. Deployment Binary Bug

I hit a snag where the specific binaries for my vector store behaved differently on Mac vs. the Linux environment in Spaces.

Standardizing with uv and clean lockfiles was the way out.

2. The $0 Intent Routing Trick:

Saving tokens was necessary from the beginning, so I built a Smart Router:

• Questions like “How did this team play?” or “Why did this team had X metric during that match?” → It goes to the LLM for tactical analysis.

• Visualization commands like “Show passing network plot from the match” → These bypass the LLM and trigger my Matplotlib visualizers at zero cost.

The "Airlock" ETL

Talked about this in previous matches but decoupling the ingestion from the UI helped me caught data bugs like a "Home/Away swap" that was messing up team stats before they reached the user.

Here’s how the frontend looks for now in HF Spaces:

Lesson Learned

The biggest takeaway from building this GUI and deploying the MVP is:

90% is Data Engineering, and the AI part is just the tip.

You need to provide a well crafted plumbing so the system does meaningful retrieval and the user, through a comfortable UI can obtain valuable information.

Precalculating everything (compute 38 tactical metrics during ETL) helps for instant retrieval.

Validate with data contracts before moving the data forward (Pydantic)

Keeping it simple for the GUI, for quick adoption.

What’s Next?

Now that the demo is live and the concept is validated, I’m scaling from 108 matches to 1,000+.

I’ll be documenting that journey. In the next series we’re talking about moving to a proper infrastructure:

• MinIO for object storage (S3-compatible, runs locally)

• Dagster orchestrating the pipelines

• dbt + DuckDB handling the analytical workloads.

• Everything on-premise with Docker services

• Modal free tier for serverless LLM inference on cloud GPUs.

The goal:

An automated data platform that generates post-match tactical reports for any match, running entirely on your own machine, with cheap cloud costs for the heavy lifting.

If you’ve been following along, you now have a blueprint for building a working RAG system with documented engineering decisions.

The next series starts soon.

If there’s a specific part of the architecture you want me to dig deeper into, please let me know in the comments.

Check out the code: Football RAG Intelligence GitHub Repository

Try the live demo: HuggingFace Spaces

Thanks for reading till the end.

See you next time,

Ricardo.

I would write a massive prompt, ask the LLM to analyze a match, read the response, and think, “good enough.”

This approach is not bad at the beginning, but if you want a successful system that generates trustworthy outputs, they should be evaluated from beginning to end both subjectively and objectively.

Moving to EDD

After reviewing different approaches, I adopted the Evaluation Driven Development (EDD), a methodology discussed by in article Escaping POC Purgatory: Evaluation-Driven Development for AI Systems.

Where the core philosophy is:

You cannot optimize what you cannot measure

So instead of treating evaluation as a final step, you build the test harness before you finish building the system.

I’ll walk you through thow I used EDD to engineer my prompts in three steps:

1. The Metrics: Why I chose Retrieval Accuracy, Faithfulness, and Tactical Insights rules.

2. The Optimization Loop: Moving from Prompt V1.0 (1800 tokens, slower, and a bit more expensive) to Prompt V3.5 (360 tokens, more precise to what I wanted).

3. The Results: Critical bugs caught at the beginning.

Golden Answers

In my previous article, I broke down how I built the Golden Dataset (matches_gold.json) since it’s crucial to understand why that dataset exists in the context of evaluation.

In standard software engineering, you write unit tests based on expected inputs and outputs, that’s the traditional software development lifecycle (SDLC).

When working with LLMs, defining “expected output” is harder because these models are non-deterministic, meaning you can give an LLM the same input and get two different outputs.

This leads to a more dynamic process through the entire GenAI application lifecycle. More iterations during your development and your way to production.

In order to battle with that non-deterministic nature, I wanted to grade the system responses. See if they matched with the answers I was expecting.

That meant combining football knowledge with technology capabilities and creating a “Source of Truth” that I trusted 100% → The Golden Dataset. A ground truth that acts as the teacher’s answer key, containing the exact stats (validated by Pydantic before) for every match.

Without this, I would be just guessing and depending entirely on the LLM’s capacity.

Now that I had the answer key in hand, I needed a way to automate the grading of the system.

The Judge: A 3-Metric Framework

Since human evaluation doesn't go that far as LLM can, I adopted the "LLM-as-a-Judge" methodology. In the book AI Engineering, Chip Huyen identifies the AI judge as:

A critical evaluation method, noting its specific utility in measuring complex metrics such as the "factual consistency between the response and the whole context”. (Huyen, 2024).

By implementing this, we can automate the evaluation without only relying on manual review.

The evaluation harness uses the LLM-as-a-Judge pattern:

1. The Analyst: Claude 3 Haiku (Fast, Cheap ~$0.0001 per query) generates the report. It's optimized for speed but since speed comes with trade-offs, Haiku can occasionally miss nuances or hallucinate stats.

2. The Judge: Claude 3.5 Sonnet (Stronger, Slower) grades the report. It catches these issues. It's slower and more expensive, but it only runs during evaluation, not intended for production. This means I can test rigorously without blowing my API budget.

Why Anthropic's models? Honestly, I had a remaining balance there from previous experiments and wanted to blow them away. But I could have used Gemini, OpenAI, whatever. You can use any other "bigger" model for this, even a local one with Ollama.

The 3-Metric System

However, I needed to know why a report failed. If it was hallucination or did it ignore the charts or any other relevant part?

The evaluation framework measures three dimensions:

1. Retrieval Accuracy (30%) - Did we find the right match?

Early on, I noticed reports would analyze the wrong match or mix up team stats. The system would retrieve “Ajax vs. Heracles” when I asked about “Ajax vs. Telstar.” (I’ll show you an error like this at the end).

This metric uses metadata filtering to verify the system found the exact match requested. It’s deterministic in a way so either it got the right match (100%) or it didn’t (0%).

Evaluation Result: 100% ✅

2. Faithfulness (30%) - Are the numbers accurate?

This is the guardrail preventing “hallucinations” where the model invents stats.

Early reports claiming “Ajax had 73% possession” when the actual number was 64.3%. Or “Player #14 made 28 passes” when it was 23.

The judge uses regex to extract every number from the report, then cross-checks it against matches_gold.json. Any number not in the source data = hallucination = failed faithfulness check.

Evaluation Result: 99.4% ✅

3. Tactical Insight (40%) - Is the analysis tactically sound?

I broke it into four measurable components:

• Specificity (10%): Does it cite concrete evidence? Counts specific references like player IDs, exact percentages, tactical metrics.

• Visual Grounding (10%): Does it reference what’s actually in the visualizations? Reports should mention “The Passing Network shows Player #14 as the hub” and not just a generic commentary. This forces the system to tie text to visuals.

• Terminology (10%): Does it use correct football language? The judge verifies terms against tactical_rules.py (e.g., “Field Tilt,” “Progressive Passes,” “PPDA,” “Verticality”) to avoid generic concepts

• Relevance (10%): Does it answer the user’s actual question? If someone asks about pressing strategy, then the response shouldn’t be about passing accuracy.

A report can be factually accurate (Faithfulness = 100%) but tactically shallow (Tactical Insight = 40%).

Evaluation Result: 95.0% ✅

Codifying "Vibes" into Rules

This question was also bugging me from the start: “How do you mathematically prove a report is tactically sound?”

Since what I’m trying to do there is translating stats and tactical dashboards from post match analyses into explainable text, I couldn't let the LLM guess what the stats meant.

I had to define a way of teaching the system the coordinates used in the WhoScored and Fotmob data, how they are calculated, and displayed in the field visualizations with the mplsoccer library.

So, I built a file called tactical_rules.py that reverse-engineers the visualizations into text logic.

For example, I defined Verticality thresholds explicitly:

def interpret_verticality(verticality: float) -> str:
    if verticality > 50:
        return "direct vertical passing - quick transitions"
    elif verticality > 35:
        return "balanced build-up"
    else:
        return "patient possession-based build-up"

• Scenario: Ajax has a verticality of 72%.

• Bad Output: “Ajax played patiently.” (Judge fails this: 72% > 50%, so it must be direct).

• Good Output: “Ajax played a direct game with quick transitions.” (Judge passes this).

If Ajax has 72% verticality and the report says "patient build-up," is a vague description. The judge verifies those numbers exist and it checks if the tactical language matches what tactical_rules.py says those numbers should mean.

Think of `tactical_rules.py` as the rubric, and the judge as the grader applying it.

Of course, in the future this can change depending on what rules you want to add or readapt. This was a first attempt of contributing to the evaluation harness trustworthiness.

The Weighted Scoring Rubric

To bring it all together, I created a weighted rubric that scores every generated report on a 10-point scale.

Weighted Score = (Retrieval × 0.30) + (Faithfulness × 0.30) + (Specificity × 0.15) + (Visual Grounding × 0.15) + (Terminology × 0.15) + (Relevance × 0.15) + (Conciseness × 0.10) 

A report must score ≥ 7.0/10 to be considered production-ready.

Scoring Examples: A Good Analysis But Wrong Retrieval

Here's where evaluation gets interesting. Sometimes the system produces excellent tactical analysis but for the wrong match.

What I asked: “Analyse Feyenoord vs Ajax match”

What the system retrieved: Feyenoord vs FC Volendam

Report Generated:

That might be too small to read, here’s the answer:

“Match Overview: Feyenoord demonstrated superior territorial dominance with a significantly higher average team position (62.4m vs 33.9m). The home team’s lower PPDA of 9.2 indicated more aggressive pressing compared to Volendam’s 15.36, suggesting consistent offensive pressure and a controlled possession strategy.

xG & Shot Efficiency: Feyenoord generated substantially higher shot volume and quality, with 37 shots generating 4.82 xG versus Volendam’s 9 shots and 0.83 xG. The significant xG differential suggests consistent high-quality chance creation, with each Feyenoord shot averaging approximately 0.13 xG compared to Volendam’s 0.09 xG per shot.

Pressing & Progression: Progressive passing metrics (156 vs 114) reinforced Feyenoord’s offensive control. High press events (5 vs 3) further illustrated their tactical superiority in disrupting opponent’s build-up play. The defensive line positioning (13.0m vs 8.6m) confirmed Feyenoord’s ability to maintain more advanced, proactive defensive structure.

Key Tactical Insight: Total pass volume (513 vs 429) combined with superior progressive passing demonstrates Feyenoord’s systematic approach to ball progression and territorial domination, directly translating into offensive efficiency and match control.“

Judge Evaluation:

• Retrieval: 0/10 (30%) - Wrong match retrieved (asked for Ajax, got Volendam)

• Faithfulness: 10/10 (30%) - All numbers verified for Feyenoord vs Volendam match

• Tactical Insight breakdown:

  • Specificity: 10/10 (15%) - Dense with exact metrics (62.4m, 9.2 PPDA, 4.82 xG, 156 progressive passes)

  • Visual Grounding: 9/10 (15%) - References positional data and tactical patterns

  • Terminology: 10/10 (15%) - Perfect use of PPDA, progressive passes, xG/shot, defensive line

  • Relevance: 10/10 (15%) - Excellent explanation of tactical dominance

Conciseness: 10/10 (10%) - 220 words, slightly over but acceptable

Weighted Final Score: 6.7/10 ❌ Failed

This is a dangerous type of failure in production systems.

The analysis is tactically excellent. If you only read the commentary, you’d think the system nailed it.

But it’s analyzing the wrong match.

This is likely a vector database issue, either the embedding similarity between “Feyenoord vs Ajax” and “Feyenoord vs FC Volendam” was high enough to return the wrong match, or the metadata filtering didn’t catch it.

This example shows why without the retrieval check, this report would score 9.5/10 on analysis quality alone. But it’s completely useless because it’s not what the user asked for.

A coach asking about the Ajax match would make wrong decisions based on Volendam data.

The fix: Tighter metadata filtering + explicit team name verification in the retrieval step. This is why matches_gold.json exists, in order to verify we’re analyzing the exact match that was requested.

What Good Evaluation Looks Like and Common Failure Modes

When all three dimensions work correctly (right match retrieved, accurate numbers, insightful analysis) the system produces reports that score high ≥9.0/10:

• Retrieval: 10/10 - Correct match identified

• Faithfulness: 10/10 - Every number verified against matches_gold.json

• Tactical Insight: 9-10/10 across all four checks (Specificity, Visual Grounding, Terminology, Relevance)

• Conciseness: 10/10 - Under 200 words (it’s ok if slightly longer)

The judge validates this automatically across all 108 matches in the dataset, catching failures that manual review would miss.

That away the system surfaced three failure patterns:

1. Wrong retrieval: Feyenoord vs Volendam example above → fix with stricter metadata filtering.

2. Shallow analysis: generic commentary with no specific metrics or insights → tweaking prompt to emphasize specificity.

3. Hallucinated stats → catch errors early in the data engineering pipeline.

Takeaways from this Section

• Turn subjective quality ("does this sound good?") into objective metrics (“does this score ≥7.0/10?“)

• Numerical verification + tactical interpretation allows the system to move from "vibes-based development" to evaluation-driven development.

• A system can sound smart while being completely wrong. This helps you catch errors in an automatic way since the beginning.

The Prompt Optimization Loop: From 1800 to 360 Tokens

With the evaluation harness in place, In parallel I could measure what was actually working.

I tested prompts in Anthropic Console before touching code.

Each iteration was scored against the 10-match eval dataset.

The evolution of iteration was like this:

V1.0: 1800 tokens, 5.0/5.0 quality → Everything explicit, verbose
V2.0: 800 tokens, 3.2/5.0 quality → Removed too much, quality tanked
V3.0: 400 tokens, 3.8/5.0 quality → Added structured sections back
V3.5: 360 tokens, 4.9/5.0 quality → Winner

You can check how I stablished this prompt testing workflow in the repo: ⚽ Football RAG Intelligence

The V3.5 version added explicit metric interpretations directly in the prompt like:

• “Lower PPDA = more aggressive pressing”

• “Higher position values = more advanced positioning”

Also adding the required section headers (Match Overview, xG & Shot Efficiency, Pressing & Progression, Key Tactical Insight).

And limited constraints in the amount of text generated: “180-220 words” instead of just “be concise.”

Result: 80% token reduction, dropping the cost per query from about $0.0018 to $0.0004.

Wrapping Up

When building GenAI systems you need to stick to a set of best practices. I considered this ones:

Evaluate first optimize later. I built the judge before iterating with prompts and before creating the vector database, cause I wanted every change measured and every response in consonance with the data I had.

Prompt-first design pays off. I designed Prompt V3.5 before building the ChromaDB schema, in an attempt to reduce retrieval-generation mismatch. The ideal scenario is to align the metadata with what the prompt needs.

Pre-calculate during ingestion. 38 tactical metrics were computed during ingestion, this helps to make fast rebuilds if the logic changes, a simpler RAG pipeline, fewer tokens, and stable prompts.

Building systems requires evaluation in every step of the journey.

Using Evaluation-Driven Development to cut tokens, go from vibes to data-driven analyses, and automated validation is what helps you get more a trustworthy working product.

Thanks for reading until the end, hope this helps you think of a way to evaluate your own systems.

If so, I’d love to know what other approaches are you considering when evaluating your RAG/LLM/Agentic apps.

See you next time,

Ricardo.

FBRef announced this week they removed all the Advanced Stats provided by Stats Perform by Opta.

Something that took the football analytics community by surprise.

FBRef was maybe one of the first (if not the first) source you could think of to grab data and build high-level analysis. Whether you were a student, analyst, scout, fan, whoever, their web was a must. They these great level of detail in their data that actually made you go down rabbit holes just by looking at the granularity of their metrics.

I used to recommend it as one of the go-to places to get in contact with advanced football data stats → How to Use FBRef for Football Scouting with Python?

This new situation far from being discouraging should make us all football lovers develop our creativity to make the most out of the available sources on the internet and explore other angles. For example: places like SkillCorner Open Tracking & Physical Data or Hudl StatsBomb Event & Physical Open Data are well known data providers where you can obtain top valuable data to run different analyses but with a “detective mind”.

What I mean by that is trying to look at the data as a vehicle to derive close-to-real-world analyses of how technical staff at clubs or pro teams use this data, and also how other fellow colleagues use it.

You can see it on social media. The majority of professionals and data practitioners are active on X or LinkedIn. Perfect places to take a look at how this data is being used and inspire yourself of those signals to craft your own dashboards or reports how they consult other data sources, how they collect, clean, model and even how they present that data.

Having different POVs around how others manage sports data helps you upskill in the data field way faster, which is ultimately what we actually want: be more competent data professionals independently where the data comes from.

I also wouldn’t rule out the use of synthetic data for practicing purposes. With the rise of Generative AI and LLMs, this has become a popular alternative within the industry due to lack of access to closed source data.

Spending some time on crafting comprehensive prompts, using few shot examples, with metrics and well-defined ranges, can help you mimic real-world data for your own practice.

The main thing to remember from this FBRef situation is that it is essential that we adapt by focusing on sharpening skills with what’s available, or by creating our own way of accessing to data sources.

This is a great signal to start creating now.

Till next time,

Ricardo.

RAG efficiency relies on great Data Engineering.

This refers to building a solid ETL process: Extract, Transform, Load — the process that prevents bad retrieval and bad generation, helping the system produce accurate responses.

So, I’ll go over the origin of the data, the sources I used, and the decisions I made to build the pipeline.

Where the Data Comes From

Starting from the main goal of the system: automatically provide concise post match reports using free updated post match data from a league gathered in one place. That way, you can save time hopping from one site to another and focus on what really matters: the analysis.

To build these tactical reports, I wanted to use match event data.

I reused and improved a version of the scrapers I built for my previous dashboard project. The goal was to move from scraping one match for a plot to indexing 108 matches for a system.

The main data sources are:

• WhoScored: with more than 1,300+ events per match: passes, tackles, coordinates.

• Fotmob: source for more specific match data like xG, numbers of shots and shot quality.

Fotmob provides the shot as a number, whereas WhoScored only provides if the action was a shot (True) or not (False). They complement each other.

The first wall I hit in this Data Engineering process was: Entity Resolution.

Source A calls the team “R. Madrid,” Source B calls them “Real Madrid.” I needed to map them, so the RAG system wouldn’t think they are different teams.

Extracting the Data

The scrapers development evolved from a one-off scraping to more matches. In this case I used just 108 matches from the first leg of the Eredivisie league.

Why the Dutch league? It’s a league I’m really curious about, they are one of the best breeding talent leagues in Europe and it is always worth it looking at their emergent talents.

The scrapers followed a simple rule: the Raw information is immutable. I save the JSON exactly as it comes from the web into a “Raw Zone” (local for now). That way if I find a bug in my tactical metrics calculation later, I don’t need to scrape the web again. I just re-run it from the raw files.

Quick summary of how it works:

Scraper WhoScored --(JSON)--> [ Raw Zone /whoscored/ ]
                                            |
 Scraper Fotmob   --(JSON)--> [ Raw Zone /fotmob/   ]
                                            |
                              [ scrape_all_matches.py ]
                                            |
                               ( Orchestration & Logs )

• The Workers: Specialized scrapers (one for WhoScored, another for Fotmob) designed with a single responsibility: extracting raw data.

• The Storage: A local directory that serves as my immutable “Raw Zone.”

• The Orchestrator: A central script (scrape_all_matches.py) that acts as the conductor, identifying missing matches and triggering the workers accordingly.

# scripts/scrape_all_matches.py (A Simplified version of the Orchestrator)

def run_pipeline():
    # 1. Check what we already have (Incremental mode)
    existing_matches = get_local_raw_manifest()

    # 2. Run WhoScored Scraper
    print("🚀 Starting WhoScored extraction...")
    ws_data = scrape_whoscored_season(mode="incremental", exclude=existing_matches)
    save_to_raw_zone(ws_data, source="whoscored")

    # 3. Run Fotmob Scraper
    print("🚀 Starting Fotmob extraction...")
    fm_data = scrape_fotmob_eredivisie(mode="incremental", exclude=existing_matches)
    save_to_raw_zone(fm_data, source="fotmob")

    print("✅ Raw Zone updated. Ready for ETL.")

Pydantic Contracts: the “Airlock” Pattern

To safely store data in a vector database, I needed a Contract. It is a strict, machine-checkable definition of what your data must look like before it’s allowed to move downstream.

In my case, it’s the schema for a “valid match” (required fields, types, constraints). If the scraped payload doesn’t satisfy that contract—missing xG, null team IDs, wrong types—the pipeline fails fast and the match never gets stored in the vector database.

Pydantic is in charge to validate that match, working as an airlock. It defines exactly what a “valid match” looks like.

Pre-calculating +30 Metrics

Dumping 1,300 raw events into the LLM didn’t seem realistic nor cost-effective. It’s expensive in matters of tokens and slow latency, which ultimately confuses the model, making it prone to give back unreliable information.

Instead of the ETL just moving data, it acts as a Factory.

It processes raw, messy coordinates and distills them into Tactical Insights (or Actionable Metrics):

• Instead of 500 raw pass coordinates → Verticality: 0.65

• Instead of 20 defensive events → PPDA: 8.2

The logic is simple: I don’t want the LLM to waste its “brainpower” (and tokens) trying to do math on thousands of x,y points. I want it to focus on what it does best: reasoning over tactical concepts.

By pre-calculating these metrics, I’m handing the AI a “scout’s report” instead of raw notes.

This is the transformation step of the pipeline: where raw events, shots, and mappings are stitched together into a single, validated match profile.

# scripts/process_raw_data.py (simplified version of the transformation logic)

def process_matches():
    # 1. Load the "Glue": Match mappings and raw data
    mappings = load_json("data/match_mapping.json")
    
    for ws_id, mapping in mappings.items():
        # 2. Resolve IDs (The fix for the Home/Away swap bug)
        home_id, away_id = resolve_team_ids(mapping)
        
        # 3. Stitch data sources (WhoScored Events + Fotmob Shots)
        ws_data = load_json(f"raw/whoscored_matches/match_{ws_id}.json")
        fotmob_match = find_match_in_bulk(mapping['fotmob_id'])
        
        # 4. The "Factory": Distill 1,300+ events into 38 tactical metrics
        events_df = pd.DataFrame(ws_data['events'])
        raw_metrics = calculate_all_metrics(events_df, fotmob_match['shots'], home_id, away_id)
        
        # 5. The "Airlock": Validate everything with Pydantic
        match_profile = MatchProfile(
            metadata=MatchMetadata(match_id=ws_id, date=mapping['match_date']),
            home_team=TeamMatchStats(**map_metrics(raw_metrics, "home")),
            away_team=TeamMatchStats(**map_metrics(raw_metrics, "away")),
            home_score=calculate_score(fotmob_match['shots'], "home"),
            away_score=calculate_score(fotmob_match['shots'], "away")
        )
        
        # 6. Save to the Golden Dataset
        save_to_gold(match_profile)

In essence, it resolves team IDs, stitches two different data sources together, calculates tactical metrics, and finally passes everything through a Pydantic "airlock" to ensure the Golden Dataset is 100% reliable.

An issue I found at the beginning

Early in development, the system told me Zwolle dominated a game they actually lost 2-8 (https://www.sofascore.com/football/match/heracles-almelo-pec-zwolle/wjbsCjb)

The LLM was just reading the data I gave it and I thought it was hallucinating.

The ETL had a bug in the team ID mapping that swapped the Home and Away stats.

Something that made me understand that paying attention to the DE part is central.

The Golden Dataset & The Sniper Approach

The final output of the ETL is the matches_gold.json.

This file became the center of the system. Everything downstream: reports, evaluations, and rebuilds started here. That’s why I treat it as the Source of Truth, and not the vector database.

Once the data is in this shape, the next step was loading it into ChromaDB.

To do that, I used a simple 2-chunk architecture when indexing each match:

• Summary Chunk: Contains match metadata: teams, date, score, and competition. Its job is to make sure the system finds the right match.

• Tactical Chunk: Contains the pre-calculated metrics. This is what the LLM actually reads to generate the analysis.

I ended up calling this setup the “Sniper Approach.”

I wanted to avoid relying entirely on semantic search: embed the query, retrieve the closest vectors, and hope the correct match is somewhere near the top. That works, but it always felt a bit loose for this use case.

When a user asks about PSV vs Ajax, I don’t want the system to “kind of” get it right. I already know the exact match I’m looking for, so I use metadata filtering to narrow it down first. Once the match is identified, only then does the LLM see the tactical data.

This way, the vector database serves exactly what I ask for and retrieval becomes deterministic.

[SNIPPET F: scripts/rebuild_chromadb.py – Chunking & Metadata logic]

# scripts/rebuild_chromadb.py 

for match in matches:
    match_id = match['metadata']['match_id']
    home = match['home_team']
    away = match['away_team']
    
    # Chunk 1: Summary (for metadata filtering)
    summary_text = (
        f"{home['team_name']} vs {away['team_name']} "
        f"({match['home_score']}-{match['away_score']}). "
        f"Possession: {home['possession']}% vs {away['possession']}%. "
        f"xG: {home['xg']} vs {away['xg']}."
    )
    
    summary_meta = {
        "match_id": match_id,
        "chunk_type": "summary",
        "home_team": home['team_name'],
        "away_team": away['team_name'],
        "match_date": match['metadata']['match_date']
    }
    
    collection.add(
        documents=[summary_text],
        metadatas=[summary_meta],
        ids=[f"{match_id}_summary"]
    )
    
    # Chunk 2: Tactical Metrics (for LLM generation)
    tactical_meta = {
        "match_id": match_id,
        "chunk_type": "tactical_metrics",
        "home_ppda": home['ppda'],
        "home_verticality": home['verticality'],
        "home_xg": home['xg'],
        "away_ppda": away['ppda'],
        "away_verticality": away['verticality'],
        "away_xg": away['xg'],
        # ... (38 total metrics)
    }
    
    collection.add(
        documents=[f"Tactical metrics for {home['team_name']} vs {away['team_name']}"],
        metadatas=[tactical_meta],
        ids=[f"{match_id}_tactical_metrics"]
    )

Two chunks per match: one for finding it (metadata filtering), one for analyzing it (LLM generation). The vector database doesn't guess; it serves exactly what I ask for.

I also added a sanitize_metadata() function to prevent ChromaDB from crashing on None values. It saved me from silent failures during indexing.

Link to the repo so you can check all the code: Football RAG Intelligence

Bottom Line

At the end of the day, a football analyst needs to trust the numbers, and a developer needs to trust the pipeline.

By building a strict ETL with Pydantic and a Golden Dataset, I managed to reduce the “hallucination surface” before even writing a prompt. The idea was to make the data so clear that the AI didn’t have to guess.

What’s next?

Now that we’ve tackled the data preparation, we need to talk to it.

In the next article, I’ll dive into the Prompt Engineering side of the project.

I’ll show you why I spent a good amount of time designing a Tailored Prompt and how that decision helped me cut token costs by 80%.

If you're interested in the intersection of Data Engineering and Generative AI, subscribe to follow this series.

See you then,

Ricardo.

I won't take much of your time, but before it ends, I wanted to thank you for reading this newsletter during the year.

I wrote about football, AI, RAG systems, agentic IDEs, and a bunch of technical experiments, things I hope helped you apply them to your own work.

So thank you. It really means a lot that you share this space with me.

To wrap it up, I want to share one thing that changed my thinking this year and will serve as my compass for years to come.

It's about how I want to perform my work and develop my career.

I'm sure it can help you start 2026 with a different perspective.

The Book That Made Me Rethink About Purpose

I recently finished reading So Good They Can’t Ignore You by Cal Newport, a book recommended by on a brilliant X/Twitter thread about books every developer should read.

This was the book that really hit me this year.

Why? Cause all my life I’ve thought the popular advice “find your passion and the rest will follow” was real. Too many decisions made using this mantra.

Then, to my surprise, Newport argues the opposite in the chapters of this book.

Telling stories of people from each path and ultimately showing who developed more successful and satisfying lives.

Here’s the deal.

Passion Mindset vs. Craft Mindset

The central subject of the book is these two concepts.

The passion mindset is about finding work that matches a passion you supposedly already have. It’s asking “what can the world offer me?” and assuming passion comes first, then the work follows.

The craft mindset flips this. It’s about getting really good at something rare and valuable. Asking “what can I offer?” instead.

The key difference: passion comes after you develop mastery, not before.

This made me rethink how I approach my own career in tech. Since I pivoted from medicine I’ve been unknowingly following this path, trying to get better at managing data, programming and ultimately building AI systems.

I was lucky enough to apply it to football (which I love) and healthcare, my background.

But the true passion came from pushing through the work and wanting to get better each day.

How Chalamet Pursues Greatness Through Craft

In February, at the SAG Awards ceremony, Timothée Chalamet said something unusual: “I’m really in pursuit of greatness. I want to be one of the greats.”

I felt that quote was really honest because he was actually talking about becoming great through the work.

He mentioned being inspired by Daniel Day-Lewis, Marlon Brando, and Viola Davis, and spending 5.5 years of his life preparing for A Complete Unknown where he portrayed Bob Dylan.

That’s the craft mindset in action.

Greatness is something you build deliberately over years of committed work.

Career Capital: The Currency to Buy What You Want in Your Career

Career capital is the set of rare and valuable skills you’ve accumulated through the years.

Newport uses this economic metaphor deliberately: great jobs (those offering creativity, impact, and control) are scarce and valuable.

To get one, you need to offer something scarce and valuable in return.

Most people want autonomy, interesting projects, and meaningful work from day one (happened to me). But you need currency to buy those things. First you accumulate the capital, then you invest it to negotiate the career you actually want.

You build it by developing skills that are rare and valuable, ones others don’t have and the market needs.

This changed how I choose what to learn.

Before, I chased new technologies that sounded interesting but now I ask myself if it gives me the career capital I want to build. Or is it rare and valuable, more than a commodity.

For example: Python is valuable but not rare. Instead, using Python to create AI systems applied to a niche domain like football analytics or healthcare is a rare combination.

This lens shows if you're building capital or just chasing noise.

What This Means for 2026

For 2026, my plan is simple: keep accumulating capital, investing it by building projects that combine rare and valuable skills, sharing what I learn here, and iterating.

If there’s something you can take from this for your own 2026, let it be this:

Build mastery first. The passion will come on its own.

Have a great year.

Till next time,

Ricardo.

Long time no see

First of all, Merry Christmas 🎄

It’s been a while since I last send a post, but life happens. So, here I am before finishing the year.

I wanted to end 2025 with the same vibe I want to start 2026: building projects and sharing knowledge.

Lately, I’ve been working on something that mixes my interest in AI and my passion for football. I’m really excited to go over its details and how the idea came up.

When I started analyzing football data and creating post match reports, I had a problem that I think a lot of coaches, analysts, and football data practitioners can relate to.

Gathering free match data from various sources to build reports is tedious.

This makes it difficult to create a summarized report from any match without hopping from one web to another.

Say if you want to analyze PSV’s pressing patterns from last week’s Eredivisie match day, you need to go to WhoScored, then Fotmob for shot and xG values, Understat, BeSoccer etc, and obtaining the data manually.

That’s why I wanted to built this system:

One where I could ask “What was PSV’s pressing strategy against Ajax?” in natural language and get an instant tactical report—with real stats, context, and visualizations from multiple free data sources.

I want to show you how it works.

What I Built

This is the live demo hosted at Hugging Face Spaces: Football RAG Intelligence - Live Demo

It’s a RAG (Retrieval-Augmented Generation) system that ingests Eredivisie match data from WhoScored and Fotmob, stores it in a vector database, and generates tactical analysis grounded in actual statistics.

You ask questions in natural language. It retrieves the match data and then generates comprehensive rundowns thanks to the LLM text-generation capability.

Reduced hallucinations and instant visualizations at low cost.

Here’s what it handles:

• 108 Eredivisie matches indexed with event-level data (~1355 events per match).

• Dual-mode interface: Ask a question and get tactical commentary. Request a visualization and get instant plots.

• Multi-provider support: Works with Anthropic’s Claude, OpenAI, and Gemini models.

• $0.50 total cost to test everything.

The visualizations I used were already created using a prior code. I went through it in an earlier article, you can go check it here: Building Your Own Football Analytics Dashboards With Free Data

Why This Matters

Your match data lives in one place so you don’t have to hop around internet to get it. Ask questions in plain language, get answers backed by recent stats. Need a passing network or shot map? Type “show passing network for Feyenoord”.

Who can leverage this?

Coaches, scouts, and analysts at small/medium/big clubs, football fans, developers. Pretty much anyone involved in analyzing football with data.

How It Works

Here’s the high-level flow:

User Query → Router (classify intent)
             ↓
    ┌────────┴─────────┐
    ↓                  ↓
LLM Analysis      Visualization
(Tailored Prompt)     (Keyword-based)
    ↓                  ↓
ChromaDB          pre-built matplotlib
retrieval         plots
    ↓                  ↓
Grounded          $0 cost
Commentary        images

The system does five things:

1. Routes your query: Questions like “What was PSV’s pressing strategy?” go to the LLM pipeline. Commands like “Show shot map” trigger visualizations.

2. Retrieves match data: ChromaDB finds the exact match using team names and metadata filtering instead of semantic search guessing.

3. Generates analysis: The LLM gets the actual stats and writes tactical commentary using a carefully engineered prompt (which I’ll cover in Article 2).

4. Validates output: Every statistic cited in the response is checked against the golden dataset. If it’s not there, it doesn’t make it into the output.

5. Delivers instantly: Text analysis in 6-7 seconds or visualizations in under a second because they bypass the LLM entirely.

Hints on the key architectural decisions I made (I’ll dig deeper into these in future articles):

• Prompt-first design: I designed the Tailored Prompt before building the ChromaDB schema. I wanted to tackle the mismatch between what the LLM expected and what the database provided.

• 2-chunk architecture: Each match gets two documents in ChromaDB. One summary chunk (team names, score, date) for filtering. One tactical metrics chunk (38 pre-calculated features) for LLM generation.

• Pre-calculated metrics: All tactical metrics are computed during data ingestion. PPDA, progressive passes, field tilt, compactness, etc. The RAG pipeline doesn’t calculate anything, it just retrieves and interprets.

• Smart routing: Text questions go to the LLM. Visualization commands go straight to the plots generation with matplotlib. This was to reduce the cost for every viz request.

• Golden Dataset ETL: Raw data from WhoScored and Fotmob flows through a Pydantic validation pipeline. Only clean, validated data makes it into ChromaDB. This “airlock” pattern caught bugs before they could cause hallucinations.

The Results

In initial evaluation testing on 10 diverse matches, these were the obtained results:

Retrieval Accuracy: 100%

Every query found the correct match data. Metadata filtering (team names, dates) acts like a “sniper” approach versus pure semantic search, which only hit 70% accuracy.

Faithfulness: 99.4%

Generated analysis matched source statistics. Every number cited in the commentary exists in the golden dataset. One test case had a minor discrepancy due to rounding, hence 99.4% instead of 100%.

Tactical Insight: 95.0%

The commentary provided actual both tactical depth and data reporting.

I evaluated the system using an LLM-as-a-Judge methodology with specific rubrics and reference answers.

The cost: ~$0.0001 per query with Claude Haiku 4.5.

The system still occasionally generates erroneous team names or statistics, which is why continuous evaluation is important. I'll cover my evaluation approach in Article 4.

What’s Next: The Series Roadmap

This article gives a big picture of what I built and how it works.

In next articles I’ll go deeper into specific aspects of the journey:

• Crafting a Football ETL Pipeline with free event data for RAG: What sources I used, why, how I managed all this data to make it useful for the system, and what is RAG.

• Why Prompt Engineering Came before the vector database and how it helped optimize costs: Designing the Tailored Prompt to avoid retrieval-generation mismatch. I’ll show the many prompt iterations from V1.0 (1800 tokens, slow, vague) to V3.5 (360 tokens, fast, precise).

• Evaluating the system with the Evaluation Driven Development approach: The LLM-as-a-Judge methodology. How I built the three-metric evaluation framework. Creating test datasets that actually matter. Debugging false failures.

• Deploying the App: Hosting an initial version of the app in HF Spaces, a well-known place for AI/ML developers to deploy applications.

• Next steps to Production Scaling: Current MVP limitations. Production stack design following data, software, and AI engineering best practices (CID/CD, pipeline orchestration, LLM cloud hosting and inference, automated evaluations) to go from proof-of-concept to a system that obtains weekly matches and generates fully automated reports on demand hosted on premise.

Try It Yourself

Demo Link: Football RAG Intelligence

Pick a provider (Claude, GPT, or Gemini), paste your API key, and start asking questions.

Example queries to try:

Text analysis:

• “What was PSV’s pressing strategy against Ajax?”

• “How did Heracles build up play against PEC Zwolle?”

• “Explain the tactics in Feyenoord vs Ajax”

Visualizations:

• “Show dashboard for Heracles vs PEC Zwolle”

• “Show passing network for Feyenoord”

• “Show shot map for AZ vs Utrecht”

The code is fully open source: GitHub Repository

Clone it.

Run it locally.

Modify it for your own league or data sources.

I included all the documented architecture decisions to showcase the entire process and next steps.

Bottom Line

The goal of this project is to show that:

A RAG system and an LLM of your choice fed by your own clean data, clear architecture, and careful prompt engineering, helps you solve a real problem like automated post match analysis.

Leveraging AI to create systems or tools is one of the things that excites me the most. There's something incredible about going from idea to working system so fast.

AI helps blur that line between "I want to build this" and "I built this."

I would love to hear some thoughts on this on how useful is this to you.

Til next time,

Ricardo.

For example, you want ChatGPT to analyze files in your S3 bucket, or to help you manage your databases, but you end up copying and pasting data manually.

Every new data source requires its own custom connector same as every AI application needs its own integration code.

There’s a solution which has risen in popularity as new way of how we work with AI and data integration: Model Context Protocol (MCP).

What is an MCP and What is it Used For?

Model Context Protocol (MCP) is an open standard that allows AI models to securely connect to external data sources and tools through a unified interface.

MCP acts as an USB-C port for AI applications.

Just as USB-C provides a standardized way to connect any device to any peripheral without custom cables for each combination, MCP provides a standardized way to connect any AI model to any data source without writing custom integration code.

Before MCP, if you wanted Claude to access your MinIO storage, your GitHub repositories, or your database, you’d need three separate custom integrations. With MCP, you write one MCP server for each data source, and any MCP-compatible AI client (like Claude Desktop, Cursor, or your custom application) can instantly use all of them.

The key is the standardization. Instead of AI models needing to know the specific APIs of hundreds of different services, they just need to understand one protocol: MCP.

General Structure

MCP follows a client-server architecture that separates concerns in the following way:

MCP Host

The user-facing AI application (like Claude Desktop, Cursor, or your custom AI app) that coordinates everything.

MCP Client

Lives inside the host application and manages secure connections to MCP servers. Each server gets its own isolated client connection.

MCP Server

External programs that expose specific capabilities to AI models like connecting to databases, file systems, APIs, or any other data source.

The communication happens through JSON-RPC, a lightweight protocol that enables secure, two-way communication between clients and servers.

Three Core Primitives

MCP organizes functionality into three main types:

Resources: Read-only data that the AI can access (like files, database records, or API responses). We can call them “things the AI can read.”

Tools: Actions the AI can perform (like creating files, sending emails, or running queries). These are “functions the AI can call.”

Prompts: Reusable conversation templates or workflows that provide structured interactions.

The importance of this design is that the AI model doesn’t need to know anything about MinIO’s S3 API, your database schema, or any specific service. It just knows how to ask for resources, call tools, and use prompts through the MCP interface.

Practical Use Cases

MCP is useful in scenarios where you need AI models to work with real, live data:

Development Workflows: AI coding assistants that can read your codebase, access your Git history, and understand your project structure in real-time.

Data Analysis: Models that can query your databases, analyze your files, and generate insights from your actual business data.

Content Management: AI that can access your document repositories, and help you manage and organize content.

Business Intelligence: Models that connect to your analytics platforms, CRM systems, and help you make data-driven decisions.

Infrastructure Management: AI that can interact with your cloud storage, monitor your systems, and help with operational tasks.

The key advantage is real-time access. Instead of feeding static data to AI models, MCP enables dynamic, contextual interactions with live systems.

Practical Example: MinIO MCP Server

Now let’s see MCP in action with a real example: the MinIO MCP Server built in collaboration with my colleague Ginard, a brilliant senior software engineer (Rafa's GitHub and Rafa's LinkedIn) who came up with this idea of connecting your MinIO object storage with any host and client, even a local LLM.

What the MinIO MCP Server Does

The server exposes MinIO object storage operations as MCP tools, allowing any MCP-compatible AI client to manage buckets and objects through natural language.

Repository: https://github.com/Rafitis/minio-mcp-server

Key Features

7 MCP Tools organized by domain:

Bucket Operations:

• list_buckets: Get all available buckets with creation dates

• get_bucket_info: Detailed bucket metadata, policies, object count, and size

• create_bucket: Create new buckets with validation

• delete_bucket: Delete empty buckets or force delete with contents

Object Operations:

• list_objects: List objects with filtering and pagination

• get_object_info: Get detailed object metadata

• delete_object: Remove objects with version support

Architecture Highlights

Built on FastMCP: Uses the FastMCP framework for robust MCP protocol support

Async Architecture: Full async/await support for better performance

Comprehensive Validation: Input validation and error handling with proper HTTP status codes

Modular Design: Separated BucketTools and ObjectTools classes for clean organization

Quick Setup

The setup process demonstrates how streamlined MCP can be:

# Clone and install
git clone https://github.com/Rafitis/minio-mcp-server
cd minio-mcp-server
uv sync

# Configure your MinIO connection
cp .env.example .env
# Edit .env with your MinIO credentials

# Start the MCP server
uv run python src/minio_mcp/server.py

Claude Desktop Integration

To connect with Claude Desktop, you just add this configuration:

{
  “mcpServers”: {
    “minio-mcp-server”: {
      “command”: “/path/to/uv”,
      “args”: [
        “--directory”, “/path/to/minio-mcp-server”,
        “run”, “python”, “src/minio_mcp/server.py”
      ],
      “env”: {
        “MINIO_ENDPOINT”: “localhost:9000”,
        “MINIO_ACCESS_KEY”: “minioadmin”,
        “MINIO_SECRET_KEY”: “minioadmin”,
        “MINIO_SECURE”: “false”
      }
    }
  }
}

After restarting Claude Desktop, you can use natural language commands like:

• “List all buckets in MinIO”

• “Show me information about the ‘analytics-data’ bucket”

• “Delete ‘old-backup.zip’ from the ‘archives’ bucket”

The AI model automatically translates these requests into the appropriate MCP tool calls.

Connecting with Local LLMs and Optimal Prompts

One particular aspect of MCP is its model-agnostic design. You can use the same MCP server with cloud-based models like Claude or with local models like Mistral.

Local LLM Integration

The feature/llm-rest-api-integration branch of our repository shows how to connect MCP servers with local LLMs for maximum privacy and control.

Key Benefits of Local Integration:

• Privacy: Your data never leaves your infrastructure

• Cost Control: No per-token pricing from cloud providers

• Customization: Fine-tune models for your specific domain

• Offline Capability: Works without internet connectivity

Setting Up with Enterprise LLMs

Here’s how you can connect with your company’s enterprise LLM infrastructure:

Enterprise LLM Setup (OpenAI-compatible API):

import asyncio
from openai import OpenAI
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

class EnterpriseMinioMCPClient:
    def __init__(self):
        # Configure your enterprise LLM as an OpenAI-compatible client
        self.enterprise_llm = OpenAI(
            api_key=”your-enterprise-api-key”,  # Your company’s API key
            base_url=”https://llm-service.yourcompany.com/v1”  # Your company’s LLM endpoint
        )
        
    async def connect_to_minio_server(self, server_script_path: str):
        “”“Connect to MinIO MCP server”“”
        server_params = StdioServerParameters(
            command=”python”,
            args=[server_script_path],
            env=os.environ.copy()
        )
        
        # Establish connection to MCP server
        stdio_transport = await stdio_client(server_params)
        self.stdio, self.write = stdio_transport
        self.session = ClientSession(self.stdio, self.write)
        await self.session.initialize()
        
    async def process_query(self, query: str) -> str:
        “”“Process user query through Enterprise LLM + MinIO tools”“”
        
        # Get available MinIO tools
        tools_response = await self.session.list_tools()
        
        # Build tool descriptions for the LLM
        tools_info = “\n”.join([
            f”- {tool.name}: {tool.description}”
            for tool in tools_response.tools
        ])
        
        # Ask enterprise LLM which tool to use
        messages = [
            {
                “role”: “system”, 
                “content”: f”You are a MinIO assistant with these tools:\n{tools_info}\n”
                          “Respond with TOOL_CALL: {{\”tool_name\”: \”name\”, \”parameters\”: {{}}}} or answer directly.”
            },
            {”role”: “user”, “content”: query}
        ]
        
        response = self.enterprise_llm.chat.completions.create(
            model=”your-company-model”,  # Your enterprise model name
            messages=messages,
            max_tokens=500
        )
        
        llm_decision = response.choices[0].message.content.strip()
        
        # Execute tool if LLM decided to use one
        if llm_decision.startswith(”TOOL_CALL:”):
            tool_call = json.loads(llm_decision.replace(”TOOL_CALL:”, “”).strip())
            tool_result = await self.session.call_tool(
                tool_call[”tool_name”], 
                tool_call[”parameters”]
            )
            
            # Format result with enterprise LLM
            format_messages = [
                {
                    “role”: “system”, 
                    “content”: “Format this MinIO tool result into a natural language response.”
                },
                {
                    “role”: “user”, 
                    “content”: f”Query: {query}\nResult: {tool_result.content}”
                }
            ]
            
            final_response = self.enterprise_llm.chat.completions.create(
                model=”your-company-model”,
                messages=format_messages,
                max_tokens=1500
            )
            
            return final_response.choices[0].message.content
        
        return llm_decision

# Usage
client = EnterpriseMinioMCPClient()
await client.connect_to_minio_server(”src/minio_mcp/server.py”)
result = await client.process_query(”Show me all buckets and find the largest files in each one”)

Optimal Prompting Strategies

When working with MCP and local LLMs, these prompting techniques can help deliver a better result:

Be specific about the context:

“Using the MinIO tools, list all buckets and then show me 
the 5 largest objects in the ‘backups’ bucket”

Structure multi-step operations:

“First, check what buckets exist in MinIO. Then, for the 
bucket with the most objects, show me a summary of file 
types and total storage used.”

Provide clear constraints:

“List objects in the ‘logs’ bucket, but only show files 
from the last 7 days and limit results to 20 items”

Use domain-specific language:

“Check the health of our data lake by listing all buckets, 
showing their sizes, and identifying any empty buckets 
that might need cleanup”

The key: leveraging the AI’s natural language understanding while being precise about what data operations you want performed.

Performance Considerations

Local LLMs with MCP work best when you:

• Choose function or tool-calling capable models (Mistral, Llama 3.2, Qwen)

• Optimize context windows for your data size

• Use streaming responses for real-time feedback

• Implement proper error handling for network timeouts

Relevant Resources and Documentation

If you want to dive deeper into MCP, here are the essential resources:

Official Documentation: Model Context Protocol Specification - The complete technical specification

Anthropic’s MCP Guide: MCP Documentation - Practical guides and tutorials

MCP GitHub Organization: GitHub ModelContextProtocol - SDKs, examples, and community contributions

Awesome MCP Servers: A growing collection of community-built MCP servers for popular services

MCP.so: MCP.so - A web to “Find Awesome MCP Servers and Clients”

The ecosystem is expanding rapidly, with new MCP servers being built for everything from Slack and GitHub to specialized databases and custom APIs, even to write your own articles in Substack/Medium.

Key Takeaways

Model Context Protocol helps solving a big challenge in AI development: connecting models to real, live data in a standardized way, providing a universal interface that works across the entire ecosystem.

• For developers, it means more time building intelligent features using AI.

• For organizations, this means building AI applications that can actually work with the nuances of your data infrastructure.

• For the AI ecosystem, this means faster innovation as everyone builds on shared standards and sharing this servers as open source.

The goal of the MinIO MCP Server is to demonstrate how straightforward it can be to expose powerful data operations to AI models, by creating a bridge between your object store and an LLM with just a few hundred lines of code.

Whether you’re using cloud models like Claude or local models like Mistral, the same MCP server works seamlessly.

Besides improving models to make them smarter, the future of AI relies on making models seamlessly interact with the tools and data that power our workflows.

Check out the MinIO MCP Server repository and start building your own AI-data bridges today.

Til’ next time,

Ricardo.

We've all been there.

But fortunately there's a tool that can solve all of these problems in second.

uv is the Python package that's helps setting up and managing Python projects blazingly fast.

Subscribe now

What is uv?

Is a Python package manager built in Rust that promises to be "an extremely fast Python package installer and resolver."

uv was created by the team at Astral (the same people behind Ruff), and it's designed to replace not just pip, but also pipenv, poetry, pyenv, and conda in many use cases. It's a unified tool that handles:

• Package installation and resolution

• Virtual environment management

• Python version management

• Project scaffolding

Think of it as the Swiss Army knife for Python development, but one that actually works smoothly instead of having unstable tools.

Why uv Beats Everything Else

Speed

Where uv really shines. While pip can take minutes to install a complex set of dependencies, uv does it in seconds. We're talking about 10-100x faster installation times.

The first time you use it, you'll think something went wrong because it finished too quickly (happened to me).

Better Than pip

pip is the default, but it's also slow and doesn't handle dependency resolution as elegantly as it could.

uv uses a modern resolver that's both faster and more reliable. Plus, unlike pip, uv creates isolated environments by default.

Simpler Than Poetry

Poetry is great for dependency management, but it has its quirks. The configuration can be complex, and it sometimes feels like overkill for simple projects.

uv gives you the power of Poetry with the simplicity of pip.

More Reliable Than Conda

Conda has its place, it was the first package manager I used, especially for scientific computing and data science. But for pure Python projects, Conda environments can be heavy and sometimes unpredictable, they can easily break and sometimes trying to find the root of that error and fixing it is worse than creating a new environment from scratch.

uv keeps things lightweight and consistent.

What Makes uv Special: The Technical Bits

When you use uv, you get three key files that make your life easier:

1. pyproject.toml

This is your project's configuration file. It contains all your dependencies, project metadata, and build settings in a standardized format. Unlike requirements.txt, it separates development dependencies from production ones and includes version constraints clearly.

When you run uv pip install in a project with a pyproject.toml file, uv will:

1. Read Dependencies: Automatically detect and install the dependencies listed in the [project] and [project.optional-dependencies] sections.

2. Manage Environments: Create and sync a virtual environment with the exact dependencies specified in the uv.lock file (if present) or pyproject.toml.

3. Lock Dependencies: Generate a uv.lock file that pins the versions of all direct and transitive dependencies, ensuring fully reproducible builds.

This makes uv a powerful tool for managing complex projects without needing higher-level workflow managers.

2. uv.lock

It contains the exact versions of every package (and their dependencies) that your project uses. This means when someone else runs your project, they get the exact same package versions you used. Helps to avoid the "but it works on my machine" issues.

3. Automatic .venv Creation

uv automatically creates and manages virtual environments. No more remembering to activate environments or wondering which packages belong to which project.

uv streamlines virtual environment creation and management.

• Creating a virtual environment:

# Creates a .venv directory in the current folder
uv venv

This command automatically finds your system's Python and creates a virtual environment. To use a specific Python version, use the --python flag (e.g., uv venv --python 3.11).

• Activating the virtual environment:

Activation commands remain standard for your shell:

# For bash or zsh
source .venv/bin/activate

Once a virtual environment is active, uv commands like uv pip install will automatically use it.

The Modern Data Stack Connection

If you're working in data science or analytics (for example in football analytics), uv is particularly valuable regarding:

• Reproducible analyses: The lock file ensures your analysis can be reproduced exactly

• Faster iteration: Quick environment setup means less time waiting, more time analyzing

• Clean project structure: Clear separation between development and production dependencies

• Better collaboration: Team members can quickly get identical environments

Real Example: Setting Up My Football Analytics Project

Here’s an example on how to get started with my football analytics tutorials repository using uv.

Step 1: Install uv

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip if you prefer
pip install uv

Step 2: Clone and Set Up the Project

git clone https://github.com/ricardoheredia/football-analytics-tutorials.git
cd football-analytics-tutorials

Now, instead of dealing with virtual environments, requirements files, and all that complexity, you just run:

uv sync

And uv will:

• Create a virtual environment automatically

• Install all dependencies from the lock file

• Ensure everything is isolated

• Do it all in seconds

Step 3: Start Working

uv run jupyter notebook

This command runs Jupyter in the project's environment without you having to manually activate it.

The Files That Make It Work

In the repo, you'll see these key files:

pyproject.toml contains our project configuration:

[project]
name = "football-analytics-tutorials"
dependencies = [
    "pandas>=2.0.0",
    "matplotlib>=3.7.0",
    "seaborn>=0.12.0",
    "jupyter>=1.0.0",
    # ... more dependencies
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
]

uv.lock ensures everyone gets the exact same package versions (this file is quite long, but that's the point – it's comprehensive).

Why This Matters for Your Workflow

Using uv has changed how I approach new projects. Instead of spending minutes setting up environments and installing packages, I spend a few seconds. It helps removing the friction that often prevents us from starting new experiments or sharing our work.

Now, if I want to test a football analytics technique, I can:

1. Create a new project with uv init

2. Add dependencies with uv add pandas matplotlib

3. Start coding immediately

Getting Started Today

If you want to try this out with the example repository:

1. Install uv using one of the methods above

2. Clone the repo: git clone https://github.com/ricardoheredia/football-analytics-tutorials.git

3. Run uv sync

4. Start exploring: uv run jupyter notebook

Check the documentation from the website if you want to go deeper: uv documentation

You'll be up and running under a minute.

The Bottom Line

Python package management has been a pain point for too long.

uv solves the problem and makes the whole experience smooth. Fast installation, reliable dependency resolution, and automatic environment management mean less time fighting with tools.

For football analytics, data science, machine learning, or any Python project, uv is rapidly becoming the standard.

The combination of speed, reliability, and simplicity is hard to beat.

Let me know in the comments if you have already tried it before or what’s your preferred Python package manager.

Check out the tutorials repository and start building your own match analysis dashboards today

Till next time,

Ricardo.

When we think about writing we might believe that we have an inherent obligation of writing something ground breaking, a scientific article, an encyclopedia, etc.

But the reality is simpler.

Writing is a powerful tool that you can use pretty much for any purpose: writing short stories, listing things to remember them, or journaling, for example.

One of my favorite uses besides writing for this newsletter and sharing content online is: tracking my weekly knowledge.

A writing use case I’m sure will help you advance your learning progress, your projects, and your career in general.

Subscribe now

Using a Paper and Digital Notebook

Not so long ago, when I started in this world of technology, especially in data science, in my very first day of work, I was handed a laptop along with a small notebook and a pen. I immediately thought: “What’s the use of this? I’ll have everything inside my IDE, I don’t think I’ll forget anything.”

Boy, I was wrong.

At the same time I was advancing through projects and meetings, that notebook saved my life. It helped me:

• Organize my thoughts before presenting results in a meeting.

• Summarize key ideas from daily standup and sprints.

• Highlight key results and suggestions from my peers.

• Note down next steps.

• And one of my favorites: annotate new things to learn.

The importance of that notebook (and its content) grew more and more in my daily workflow.

Soon, I felt I needed a little “upgrade”, so I decided to expand my note taking to a digital format.

I chose Notion as my main notes storage. This helped me organized my notes in simple categories:

• Work Projects: meeting summaries, progress, next steps, deadlines, pain points.

• Personal Projects

• Learning (courses, new technologies, tools, etc.)

• Newsletter posts ideas

• Notes about books (technical and non-technical)

This way, every note was allocated in a specific category, helping me organize the mess I was accumulating in the physical notebook.

I then realized something: I was noting down things I learned and implemented during the week, but wasn’t actually reflecting about them nor documenting them with detail.

Here, documenting the process you go through when learning something new is important. It helps you be aware of what you’re putting into practice, the failed experiments, and the final success.

That’s why I created a specific category in my notes:

The Data Learning Diary

I fill this diary (a basic separate page in Notion) with the things I’ve learnt through the week.

What I do in 3 steps:

1. I see something I want to learn → note down the topic

2. Go over the topic and use the Feynman technique by writing a summary in simple words to see if I understood → note down that summary (depending on the case I later ask Claude or ChatGPT to help me understand difficult concepts).

3. If it’s relevant to the project, apply that knowledge immediately → document every single step in the way: the goal of the project, first implementation, failed experiments, what worked, what didn't.

I do this daily, so at the end of the week I have a list of all the things I've been going over.

This is an example of last week.

On Friday, I did the exercise of going over each of the things I learned from Monday to Friday. Checking what I documented and rereading it to recall it.

This took me about 20-30 minutes at the end of the day, and I felt it was a powerful way of fixing that knowledge.

Giving room for your mind to process everything it went through the week, may feel overwhelming at first, but it helps your brain settle the information you’ve been learning.

Creating your own note taking methodology can make wonders in the long term. It can make a compound effect and help you advance in areas you feel stuck, understand concepts better, apply them or discard them for others that might be more suitable for your project. It’s your choice.

Key Takeaways

• Whether you’re advancing on your data career or you’re more experienced, writing down and organizing your notes will help you retain the daily information better.

• Choose any tool you want, physical or digital, the important is to have one you feel comfortable with.

• Make the effort of writing things daily, just a few comprehensive lines of what you’ve learnt that day and put aside some minutes at the end of the week to go over it.

• Ask AI to help you ease the way, be it summarizing, understanding, or reframing ideas.

You’ll see the big picture at the end of the week and adjust your methodology for a next occasion.

Hope this idea is valuable to you, and if you have any suggestions on what other note-taking methods are helpful, feel free to comment!

See you next time,

Ricardo.

Writing code has changed in the last a couple of years. When ChatGPT appeared in the map, using a chat window and asking GPT to create something was a new way of interacting with AI.

This definitely changes the way that code and software is created.

According to the great Andrej Karpathy, who talked about this at the AI Startup School lecture in San Francisco called “Software Is Changing (Again)”1, by comparing an old vs. new paradigm on creating software:

“We now spend more time thinking, planning, and reviewing code generated by LLMs than memorizing syntax and programming from scratch”.

With time, LLMs market has risen, different AI labs have developed their own open and closed source ones. New tools have also been created to help developers improve their workflows by leveraging these models, practically embedding them inside development environments, which are known as: agentic IDEs.

What are Agentic IDEs?

They are development environments enhanced with AI that assists with code generation. They are also compared to Agentic CLIs (command line interfaces) like Claude Code and Gemini CLI, which can be used from both the terminal and as a chat window.

These tools offer capabilities like:

• A variety of LLMs from different providers to use.

• Capacity to index your codebase and libraries documentation

• Model Context Protocols (MCP) → open standard that connects AI models to external tools, execute actions, and read data sources, through structured interfaces with LLMs.

• Ability to edit files autonomously, providing tab completions and code suggestions.

• Help in projects from planning phase to execution phase, leveraging the use of contextual documentation to understand the nuances of the project.

• Adaptation to your workflows to help amplify your development in your own domain knowledge.

What are their main challenges?

For the last months I’ve been using Cursor and a couple weeks ago I started using Trae, one that looks like an affordable competitor.

These tools are intuitive at first and you can get proficient at using them them pretty quickly, especially if you come from VSCode.

But like Uncle Ben says:

“With great power comes great responsibility" 🕷️

Things can go sideways pretty fast if you are not on the steering wheel.

Some of the main challenges I’ve faced:

• Understanding how the different LLMs work, and which one excels at which task.

• Rate limit: tracking how much of your monthly quota are you consuming. This helps you understand how to prompt better to achieve results in less iterations.

• Testing different prompt formats, to see what helps to achieve better results with each model.

• Knowing how to leverage the context window of each model.

• Keeping the leash tight in Agent mode, trying not to let it go rogue and make extreme codebase changes without supervision.

• Integrating MCPs using them as extra tools that improves my workflow. Especially the ones that are suitable for my project.

You’'ll see how to tackle these challenges with a framework I used and how I applied it in two football-related use cases.

How can you leverage them for Football Analytics?

One of the things I like the most about AI is that it is here to augment our capabilities and help us create opportunities within our domain knowledge.

In this case, I followed a general framework that you can replicate for any project, it works for both Cursor and Trae.

1. As soon as you open your project, create three files:

   1. rules.mdc: this one sets the context of the rules2 that the agent must follow in each project when generating code. In any conversation, it will consider anything you want your project to have: role the AI must adopt, your Python version, the libraries you use, your coding style, design pattern, etc.

   2. project_context.md: you’ll entire context, this is the document where you set your project’s main idea goal, characteristics of the project, steps to achieve it, anything. It’s an opportunity to describe clearly and concisely what you’re working on.

   3. tasks.md: granular description of your project tasks. You can use it as a log so models understand what you’ve done and your progress.

2. Version Control initiating Git from the beginning of the project: commit changes before accepting the code suggestions from the Agent, if you’re satisfied then test and proceed.

3. Index only necessary folders, files, and libraries documentations at the beginning, this will help the Agent pay attention to your codebase structure and understand the last version of the documentation you’re using, for example the last version of Pandas or Matplotlib.

In summary:

Football Examples

Example 1: six‑plot match dashboard

For this I needed to do a bunch of stuff:

• Scraping match event data from different sources.

• Cleaning and unifying pitch coordinates and IDs

• Precalculating the metrics

• Generate the plotting functions.

You can refer the last article so see what the project is about: Building Your Own Football Analytics Dashboards With Free Data

And I needed to go over each step with a structure.

1. Files

   1. rules.mdc: emphasized the generation of the code in functions and simplified code, sometimes LLMs go way over their head and make up stuff.

      

   2. project_context.md: I went from broad to specific explanation of my project. Main goa, key components, steps to create it, plots characteristics, color and aesthetic I wanted to implement.

      

   3. project_log2025.md: this is the task document where I only set the specific task to accomplish and next steps.

   

2. Version control with Git

3. Index files and folders: in Trae, the context indexes automatically, in Cursor you need to indicating it at the beginning but then files are automatically synced.

From this point onwards, is a back and forth iteration, tweaking the documents, and adapting the prompts to obtain satisfactory outputs from the LLMs.

Some of the challenges: the model confused coordinate systems (0–100 vs 120×80), misnamed some columns, or repeated different Matplotlib functions. Had to pass the dimensions explicitly in a document to be used as context.

Example 2: on‑ball sequences with GPT‑5 in Cursor (Trae didn’t have it yet)

Sequence helps you not only analyze what happened in a match (player passed a ball in a specific direction and zone of the field) but also ‘how’ it happened before and after that, it adds context.

I asked GPT‑5 to find sequences based on my data from Salzburg vs. Real Madrid in the CWC, and gave it freedom to pick any event and any player. I did it in 3 steps:

• Asked it to adopt the role of a PhD Level Football Machine Learning Engineer and that it needed to understand my codebase and recent progress.

• Indexed my event data, so it could understand the type of events and specifications of the plots colors.

• I asked it to plot coordinates X and Y of any event and any player.

It chose a pass where Dean Huijsen receives deep on the left in his own half and carries into the attacking half on the same flank.

Then plotted two examples with a dark mplsoccer theme and label the player.

It filtered events, computed distance gained (about 39–43m in two cases), and drew the trajectory of the sequence.

The takeaway: when your instruction is specific and concrete, agentic IDEs translate it into working code quickly.

How to get reliable results from the models

• Be specific with inputs: a well-described tasks, specific code format (generate functions).

• Paste snippets of your information (e.g. rows of your data frame) and state plotting specifications.

• Index your context: point the Agent to the exact files or docs you want it to use.

• Have it explain the logic in plain language before you run anything.

Quick comparison between Cursor vs Trae based on my experience

Cursor

Is one of the most populars, I personally find these specs useful:

• Agent mode in Claude Sonnet 4: best model I’ve tested inside Cursor, it provides well structured code and understands the codebase when you give it the entire context.

• MCP integration: most of the MCPs have integration for Cursor, for example setting Supabase was easier here than in Trae which is newer.

• Haven’t tried but looks interesting: Background Agents → edit and run code in a remote environment.

• Broader range of models: for small tasks the Cursor small own model helped me for writing specifications for project and I also liked using Deepseek v3.1 for coding, it was pretty solid.

• Something I didn’t like: the rate limit. With pro plan ($20 a month), you were suppose to have unlimited requests but one day they changed it quietly and people started to hit rate limits all of a sudden.

Trae

• Is cheaper: first month $3, next bill $10.

• Has two modes:

  • Builder: to execute routine and end-to-end tasks.

  • Builder with MCP: use MCP servers to run tasks.

• MCP: setting them is easier than in Cursor and they have a marketplace where you can grab and the ones you need.

• Haven’t tried but looks interesting: Custom Agent → use MCP tools and built-in ones from Trae to use a specific Agent for specific tasks.

• Needs more popularity but they are clear with the limits you have 600 a month.

• Something I didn’t like: they have a SOLO builder mode which is more autonomous and you can see the development of your app during the whole process: backend and frontend, but you have to join a waitlist to get an invitation codes that hasn’t arrived yet.

To help you evaluate them deeply you can check these two sources to help you decide:

Trae AI: A Guide With Practical Examples

Cursor AI: A Guide With 10 Practical Examples

Final thoughts

Agentic IDEs can help you move fast from any question you have to working code.

Start small: aim for iteration and then repeatable workflows. Keep guardrails in place: index your documents, do sanity‑checks after every iteration, have the IDE generate simple tests, and ask models to state assumptions before coding.

As you polish prompts and set rules, you’ll see the improvements.

Is a comprehensive visual report that provides a quick-analytical overview of a football match.

If you missed a match or watched the 90+ minutes and you want to review the statistics quickly, a dashboard helps you get an overview of the tactical and performance insights in one place.

In case you're tracking a league as an analyst, as a scout to flag a player, or even as fan that wants to know how your favorite team performed this weekend, building them can make a difference in how fast you retrieve that information.

I built this dashboard using:

• Python 3.10

• Beautiful Soup

• Pandas

• NumPy

• Pandas

• Matplolib

• Mplsoccer

The goal was to build a template with just 6 key analytical plots:

• Passing Networks: Shows team shape, player positions, and passing combinations.

• Defensive Actions: Reveals pressing intensity, defensive positioning, and team compactness.

• Progressive Passes: Analyzes forward progression and attacking build-up patterns

• Shot Map: Comprehensive shooting analysis with xG, shot types, and quality assessment.

• xT Momentum: Tracks dangerous situation creation, goals, and match momentum shifts over time.

• Match Statistics: Side-by-side comparison of key performance metrics between teams.

Where to get the data from?

This is the most important part.

In this case I needed event data for only one match, using coordinates from different situations in the offensive and defensive phases like: Passes, Progressive Passes, Interceptions, Blocks, etc.

These coordinates are represented as X and Y, paired with its end_x and end_y. This helps understanding where and when a situation started, same as where it ended on the pitch.

WhoScored was my go to place to obtain the majority of them. But I was still missing the shots coordinates. Fotmob has them, though it’s a tricky place to obtain them.

I suggest you to visit the GitHub repo and give the scraping logic a look: https://github.com/ricardoherediaj/football-analytics tutorials/blob/main/notebooks/cwc_scraping_test.ipynb

Plotting the Dashboard

After obtaining the data sources, I transformed the raw match events into insights.

In this case I saved the data in CSV and JSON format, you’ll see it at: https://github.com/ricardoherediaj/football-analytics tutorials/blob/main/data

• df_events contains the main events and coordinates I used for the plotting

• match_events.json and matchdict.json contain players numbers and shirts

• shots_df includes the shots data from Fotmob in the match

• xT_grid.csv has the values to understand the highest and lowest threat actions a team makes during a match on the pitch.

Assisted by Claude Sonnet 4 inside the Cursor IDE, I designed this template around six plots that I found interesting for the dashboard.

I selected just six to try not to overcrowd the report. Each plot shows specific characteristics of team’s performances.

1. Passing Networks

Shows the team shape, players average positions, and passing combinations.

I also calculated measures for verticality, to see how direct a team's passing is. I'm also tracking the defensive line, forward line, and team median position to understand how compact or stretched a team's shape is.

When you visualize them size-by-size, Salzburg's network might show a compact, possession-based approach with short passing triangles, while Real Madrid could display a more vertical, counter-attacking structure with longer passing connections.

I converted WhoScored coordinates (0-100 scale) to StatsBomb format (0-120x0-80) for consistency across all visualizations.

The bidirectional pass combinations reveal which player partnerships are most active during the match.

2. Defensive Actions

This heat map shows where each team applies pressure and wins possession.

I tracked every tackle, interception, ball recovery, and blocked pass, then creating a KDE (kernel density estimation) heat map that shows the intensity of defensive actions across the pitch.

The Defensive Action Height metric tells you how high up the pitch a team typically wins the ball.

Combined with the compactness percentage, you can immediately see if a team is playing a high press or sitting deep.

3. Progressive Passes

Passes that significantly advance the ball toward the opponent's goal at least 30%.

The pitch is divided by zones where you can see if a team builds attacks primarily through the left flank, through the center, or via the right side.

Example: If Salzburg completed 23 progressive passes with 65% coming from the left side, you can deduct they're targeting Real Madrid's right defensive lane.

4. Shot Map

It shows where shots were taken and incorporates Expected Goals (xG), big chances, and different shot outcomes to give you a complete attacking picture.

Each shot is sized by its xG value and color-coded by outcome. Green circles are goals, hatched circles are saves, and larger markers indicate big chances. This shows you which team created better opportunities, regardless of the final score.

For example: a team with 8 shots worth 0.3 xG total had a very different performance than a team with 4 shots worth 1.2 xG total.

5. xT Momentum

Expected Threat (xT) momentum tracks which team is creating more dangerous situations throughout the match, smoothed over time to show momentum shifts.

I'm calculating the xT value for every successful pass and carry, then using a weighted rolling window to show how momentum builds and shifts. When you see the line spike upward, that team is creating dangerous situations. When it dips, they're losing control.

Momentum spikes often correlate with goals, substitutions, or tactical changes.

6. Match Statistics

The final central plot is a comparative view of key performance metrics.

Possession percentage, field tilt (percentage of touches in the attacking third), passing accuracy, defensive actions, and PPDA (Passes Per Defensive Action - a pressing intensity metric).

Notes on the Development Journey

I've left my experimental attempts visible in the notebook because I wanted to show the messy development process before the final dashboard code.

Experiment 1: data integration challenges, mixing WhoScored events and Fotmob shot coordinates. Since they’re different platforms they use different coordinate systems and player ID formats but still the plotting was poor.

Experiment 2: used the data preprocessing from experiment 1, builds the layout and makes the visualizations work as subplots rather than standalone plots. This required making three functions to be "subplot-friendly”.

Experiment 3: improved the “dual ID system” issue, since WhoScored uses different team IDs than Fotmob, so I needed to map between them correctly for the shot map while keeping everything else consistent.

Experiment 6: the final version I'm satisfied with (for now). It did the preprocessing process more straightforward and plotted all six plots into a meaningful dashboard.

Next Steps

This template is designed to be the foundation for a larger end-to-end football analytics pipeline. The next steps would be:

• Modularizing the code into separate Python scripts for easier maintenance

• Database integration in Supabase to store scraped data persistently

• Automated data collection and reports visualization using GitHub Actions or similar

• Individual players performance reports

• Obtaining data for more leagues and matches

Once you have the template working for one match, you can generate these reports for any match in any league, as long as you get the underlying event data.

The goal of this is to think it a systematic approach to football analysis that combines the best of data science with tactical understanding.

Each visualization answers specific questions that matter to different stakeholders:

• Coaches can see their team's tactical execution and identify areas for improvement

• Scouts can quickly assess player and team performance across multiple matches

• Analysts can spot patterns and trends that aren't visible from watching alone

• Developers/Fans can understand the tactical nuances of matches beyond just the final score

I invite you to grab a cup of coffee, subscribe to my newsletter, and give it a check to the repo: https://github.com/ricardoherediaj/football-analytics-tutorials/blob/main/notebooks/match_dashboard_template.ipynb

You might learn something new, discover something to improve, or ideas to make your own football plots!

Subscribe now

References

Special mention to the main reference I based on:

https://github.com/adnaaan433/Post-Match-Report-2.0/tree/main