Monday’s post was about a single algorithm — Union-Find, α(n) ≈ constant. This is the technical companion: what it took to publish that algorithm. Both pieces are part of the June sprint for The Algorithm Codex, which you can also get in print at Gumroad or as part of the Compendium. More at the end.

Pseudocode is informal enough to be ambiguous and formal enough to be annoying. Every advantage it claims is better served by something else.

Subscribe now

Three claims for pseudocode, all false

The canonical defense of pseudocode is Introduction to Algorithms (Cormen, Leiserson, Rivest, and Stein), known as CLRS. Thirty years. Four generations of computer science students. The single most widely-sold technical book in the field. If you’ve studied algorithms, you learned from CLRS or from someone who did. And CLRS uses pseudocode throughout, defends it explicitly, and makes the case as well as it can be made.

The argument for pseudocode rests on three things. First, it hides details that don’t matter for the explanation — variable types, secondary operations, boilerplate. Second, it speaks at the same conceptual level as the narrative; you can invent operations, give them names, use notation that fits the idea you’re explaining. Third, it survives time: programming languages rise and fall, but pseudocode is language-agnostic, and a textbook meant to teach the same concepts to students who will write Python, Java, Rust, or something that doesn’t exist yet can’t be tied to any of them.

Problem 1: Pseudocode is not intuitive. If you want to convey an idea intuitively — how a process unfolds, why an algorithm works, what the conceptual structure is — use a diagram, a narrative, an informal sketch. These are genuinely intuitive; they don’t impose formal constraints. Pseudocode has syntax. It requires for, while, if, formatting conventions, notation that the reader has to parse before they can extract the idea. The claim that pseudocode is easier to read than real code is false. It’s different from real code, but not simpler. For genuinely intuitive explanation, there are better tools.

Problem 2: Pseudocode is not formal. Real code has formal semantics. There is a defined mapping from source to behavior; a compiler or interpreter enforces it. Pseudocode has no such mapping. The reader is left to translate it into whatever language they’ll actually use, and that translation is entirely implicit. It’s undocumented and un-enforced. The gap between “swap the elements at positions i and j” and “no, you can’t, you forgot you were working with an immutable list” is not a minor translation detail. That gap is where the data structure’s mutability, the cost model, the choice of representation actually live. If your pseudocode rules were formal enough to specify the translation unambiguously, you’d have a compiler. It would just be code.

Problem 3: Pseudocode is not portable. The language-agnostic argument sounds compelling, but it proves too much. Pseudocode isn’t language-agnostic in any useful sense. It’s an additional language the reader has to learn. If you give students pseudocode, you’re giving none of them something they can run. You’re asking every reader to translate. Whereas if you pick one real language (a widely-used, readable one), many of your readers understand it directly, and the rest have a formal, precise text to translate from. Pseudocode doesn’t spare readers translation; it makes all of them translate.

My prior is strong: intuition first, formalization later. An algorithm, a formula, a mathematical concept: explain it intuitively first, then formally. Pseudocode tries to do both and delivers neither. It isn’t informal enough to convey ideas; it isn’t formal enough to prove properties. Pseudocode charges you for formal syntax and gives you no formal guarantee.

Two registers: diagrams for intuition, real code for formality

Use two kinds of explanation, not one.

For intuitive content, use diagrams and narration. Diagrams don’t have to be formal — informal sketches work fine: an arrow from one box to another, a tree branching as a recursion unfolds, a before/after pair showing what partition does to an array. They explain intuitively, expose the underlying reasoning, and don’t impose the cost of formal syntax.

For formal content, use real code. Every supposed advantage of pseudocode — the ability to invent operations, hide irrelevant detail, speak at a high conceptual level — exists in real programming languages too. Real languages have abstraction and encapsulation. To defer an operation, stub it: a named function with an empty body or a one-line comment. graph.connect(u, v), database.search(query), parser.parse(source). Real code already has the vocabulary for subjects, predicates, and attributes on those subjects. You don’t need bespoke notation. You need a sufficiently expressive language.

That language is Python. Of the widely-used general-purpose languages, Python is the most readable. There are more ergonomic languages (certain Lisps, Haskell, Racket), but their readability advantage comes at the cost of familiarity, and a textbook audience that doesn’t already know those languages won’t benefit from them. Python is known, readable, and expressive. There is no good reason not to use Python in a programming book, even a book that isn’t about Python.

Literate programming keeps prose and code from drifting

If we’re using real code anyway, formal and executable, why not make that code a real deliverable? A library with unit tests and an import statement, not just a code block in a document.

The obstacle: docs and code drift apart when they live in separate files. Change the explanation, and you have to remember to update the code. Change the code, and you have to remember to update the prose. In practice, one always lags the other. Pseudocode dodges this: it never has to match anything, so it’s never wrong. Real code is always either in sync or not.

Literate programming is Donald Knuth’s answer, from his 1984 paper. The original system (WEB, later CWEB) was built around Pascal and C. You wrote a single source file interleaving prose and code; a tool called tangle extracted the code into a runnable program, and a tool called weave rendered the prose into a readable document. The writing and the code are the same artifact. You can’t let them drift because they’re literally the same file.

Modern tools have rediscovered the idea. Jupyter notebooks mix prose and executable code. Quarto does the same at book scale. But neither fully extracts the code into a standalone packageable artifact: the notebook is the program, and you can’t easily ship it as a library.

illiterate makes the book and the package the same source

illiterate closes that gap. A build step extracts the tagged blocks from .qmd files ({export=...}) and assembles them into actual Python source files. The book renders; the package builds from the same source. Three things follow automatically: the documentation can’t describe an algorithm that doesn’t compile; the tests run against the same code the reader sees; and the book ships a working library as a side effect of being written.

In the Algorithm Codex (a hundred algorithms across sorting, graphs, data structures, and dynamic programming), every chapter follows this pattern. No pseudocode anywhere.

Quicksort, with the package built from the page

A Quicksort chapter opens with the public entry point, the function the reader calls and the one that lands in the package:

```python {export=codex/sorting/quick.py}

from typing import Sequence
from codex.types import Ordering, default_order

def quicksort[T](items: Sequence[T], order: Ordering[T] = default_order) -> list[T]:
    items = list(items)  # don't mutate the input
    _quicksort(items, 0, len(items), order)
    return items
```

The recursive helper is two cases: a base case that bails on slices of length zero or one, and a recursive case that partitions and recurses on both halves:

```python {export=codex/sorting/quick.py}

def _quicksort[T](items: list[T], lo: int, hi: int, order: Ordering[T]) -> None:
    if hi - lo < 2:
        return
    pivot_index = partition(items, lo, hi, order)
    _quicksort(items, lo, pivot_index, order)
    _quicksort(items, pivot_index + 1, hi, order)
```

Both blocks export to the same file; illiterate appends them in document order. Next in that order is the partition step, its own block and its own paragraph. Each conceptual piece earns its own prose frame and its own extracted function.

When the book renders, Quarto executes every demo block. If any algorithm is wrong, the build fails before that sentence can appear on the page. The build verifies every algorithm in the Codex, every time.

The book is the primary source. The algorithms are real code that runs. The two have never disagreed.

Until next time, stay curious.

illiterate is open-source at github.com/apiad/illiterate, a small Python tool that extracts code from Markdown and assembles it into runnable source files. If you write a book, a tutorial, or a course where the code has to match the text, the setup described here is twenty minutes to replicate.

The algorithms it enforces are in The Algorithm Codex, available in print on Gumroad, or free to read online at matcom.github.io/codex/. Both the Codex and my other books are bundled at apiad.gumroad.com/l/compendium.

Subscribe now

Every post on June is related to algorithms, anchored on The Algorithm Codex. I’m also running an experiment this month: stretching the pace to one-post-a-day with per-day theme. Monday is for Mind-blowing. Let’s see how that goes.

When someone tells you they have the “fastest algorithm ever devised”, you probably think they bumped into trick to make clever use of the cache, or something equally tasteless, perhaps Youtube-worthy for 2 hours. I know I’d do if you came to me with this title.

But this is not that post. This is about the actual fastest algorithm we have ever devised, and probably the fastest anyone will ever do. And not in a trivial sense. There is one problem in computer science (practical, appearing everywhere you look, explainable in two sentences) where we have an algorithm, a correctness proof, a complexity bound, and a matching lower bound that closes the problem.

Done. Problem solved. No more papers.

That kind of closure is the rarest thing in any field of human knowledge.

Subscribe now

Four conditions, one winner

But what does “fastest algorithm” mean? There are many ways you can interpret this phrase, and some of them are trivially true.

Reading an entry from an array takes constant time. Nothing beats that. But it’s one operation on a flat structure, no progression, nowhere lower to go. Getting the title should require something harder.

The interesting frontier is a non-trivial problem with a naive solution everyone reaches for, and another, mindblowingly faster solution that is provably optimal. The problem we analyze today has four traits we want:

First, general: appears in real systems across many domains, not a toy. Second, explainable in two sentences: if you need a paragraph to state it, the optimality result arrives too late to matter. Third, a real progression from naive to optimal: intermediate ideas that each earned their place, not a single flash of inspiration. Fourth, provably closed: algorithm and lower bound meet exactly. Not “hard to improve.” Closed.

Our problem is Union-Find, which clears all four. Nothing else with a non-trivial structure clears them as cleanly. Let me explain it to you in two sentences.

You’ve used this all day

Union-Find goes like this. You have n things, organized into groups. You need to merge two groups and ask whether two things are in the same group.

That’s it. No deletion. No ordering. No traversal. Two operations on a shifting partition: union and find.

You’ve used it today, probably without noticing. Your phone’s photo app groups every selfie of the same person into a face album by computing connected components, and connected components is what Union-Find does for a living. The bucket tool in any image editor (Paint, Photoshop, Procreate, whatever) floods a region with color by labeling connected pixels? Yes, Union-Find.

Every time your TypeScript or Rust compiler decides two variables must share a type, Hindley-Milner type inference unifies them through Union-Find. Spanning Tree Protocol, the thing that lets the switches in your office or home network agree on which links to use so packets don’t cycle forever, runs Kruskal’s algorithm; Kruskal needs Union-Find to detect cycles.

The same idea shows up across classical computer science under different names. The canonical image segmentation algorithm (Felzenszwalb and Huttenlocher, 2004) is the bucket tool’s research-grade cousin. Procedurally generated mazes in games are built by running Kruskal on a grid. Percolation theory in physics, the study of how fluids flow through porous materials, is the same partition-growing-by-merging problem in continuous form. Whenever a system has equivalence classes that grow online, Union-Find is almost always the engine underneath.

Union-Find is actually pretty simple

The naive solution is straightforward: give every element a label. To merge two groups, sweep through the array and relabel everything in one group with the other’s identifier. Works perfectly. Linear work per merge. Nothing cheaper to write, and nothing more expensive to run at scale.

The first idea that earns its keep is a structural change. Stop labeling every element. Give each element a parent pointer: a single reference to another element. The root of each tree is the element that points to itself, and the root names the group.

To check if two elements share a group: walk each one up its parent pointers to a root. Same root, same group.

To merge two groups: find both roots and point one at the other. One pointer write, regardless of how many elements are involved.

The trade has moved. Merge is cheap. But your find now costs as much as the tree is tall.

Here is the failure mode. An adversarial union sequence can build a long thin chain: element one points to element two, which points to element three, all the way down. Every find walks the whole chain. Linear again.

The rest of the story is about keeping the trees short, like, really, really short.

Making Union-Find fast, really fast

The first fix is the obvious one once you’ve seen the failure. Track each tree’s height: its rank. When merging, always hang the shorter tree under the root of the taller. The merged tree is no taller than the taller of its inputs.

The counting argument is clean. A tree of rank r must contain at least 2^r elements. You can prove it by induction on the merge rule. So the rank, which bounds the height, can never exceed log₂(n). Both operations now run in O(log n). A million elements: naive worst case is a million steps; rank-bounded is twenty.

One integer per node buys us exponential improvement in speed. Read that again.

Most algorithms textbooks would stop here. The second fix is what changes this from a really fast algorithm to the fastest algorithm ever, period.

Notice something about the walk-to-root operation. When it finishes, it has discovered the root. Every node it visited could be rewired, right now, on the way back, to point straight at the root.

The structure flattens itself, in place, every time you ask it a question. The next walk on that path takes one step. Work you already did is work you never have to do again.

On its own, this trick is good. Combined with the rank rule, the cost drops below logarithmic, into a regime that barely has a name.

¿How fast is this? Strap on, baby.

Union-Find is the fastest algorithm ever devised

Robert Tarjan, in 1975, proved the two ideas together give an amortized cost per operation of the inverse Ackermann function, written α(n).

To understand why that means fast, you need a picture of what you’re inverting. The Ackermann function grows like hell. Faster than exponentials, faster than towers of exponentials, faster than any function built by ordinary recursion. A(4, 4), only four steps in, already exceeds the number of atoms in the observable universe. It’s a freaking monster, one of the fastest growing functions ever invented.

The inverse grows correspondingly sloooowww. For any n less than 2 to the power of 65536 (a number whose decimal representation runs twenty thousand digits), α(n) ≤ 4. Read that again. For any input you could construct on any computer that will ever be built, the average cost per operation is at most four pointer hops.

Effectively constant. Call it constant, for practical purposes. But it is not constant. There is a real function in there. That fact is not a technicality. This is not a gap waiting for a smarter trick. It is a permanent lower bound, proved by Fredman and Saks in 1989.

Michael Fredman and Michael Saks worked in the cell-probe model, which counts how many stored bits any data structure must read to answer a query. They proved that Ω(α(n)) is the true lower bound for the union-find problem. No structure of any design can answer union and find queries doing less amortized work than α(n).

Tarjan’s upper bound says path-compression-plus-union-by-rank does at most α(n) amortized. Fredman and Saks’s lower bound says no structure can ever do less. The two bounds meet exactly.

Done. Problem solved. No more papers.

Problem solved is a rare luxury

Newton’s laws work until you approach the speed of light. Quantum mechanics works until you zoom out to cosmological scales. Turbulence in fluids is still open. It has been for a century. The three-body problem is still open. Physics doesn’t finish; it hands off. Every theory we have is a model that fits data within its domain of validity, and I think we forget how strange that is.

The Schrödinger equation describes how electrons move in any atom. For helium (two electrons) it has no closed-form solution. The electron interactions couple (each one affecting all the others) in ways that resist exact treatment. Chemistry approximates, and the gap is permanent, not a waiting-for-faster-computers problem.

Mathematics does close problems, and famously. Wiles closed Fermat’s Last Theorem in 1995, after the conjecture had sat open for 358 years. The four-color theorem closed in 1976 (with a computer’s help, which still rankles some). Poincaré closed in 2003. But the closures cluster on problems mathematicians chose: beautiful, deep, and often distant from anything that runs in your hand.

Computer science almost never gets all three at once. A problem that is practical, used in real systems every day; crisply specified, fitting in two sentences; and provably closed, algorithm and lower bound matched exactly. Union-Find is in this corner. Comparison-based sorting being Θ(n log n) is in it. Linear search on unsorted data being Θ(n) is in it. The list is short.

Algorithm and lower bound, meeting exactly.

Done. Problem Solved. No more papers.

The fastest non-trivial algorithm ever devised takes twenty lines to write, runs in essentially constant time per operation, and is one of the very few things we have ever — in any field — entirely finished.

If that isn’t freaking mind blowing, I don’t what is. Until next time, stay curious.

Union-Find is chapter 14 of The Algorithm Codex, a book that spells out the algorithms every programmer eventually meets in real, functioning Python — no pseudocode bullshit, no complicated math.

Every chapter ends with the same three questions: is it correct? how efficient? is it optimal? Most chapters land two out of three. A small few land all three. Union-Find is the cleanest example in the book of all three boxes ticked.

Get the Algorithm Codex

On May 31 we launch Mostly Harmless AI v2. This arc — how models learn, how agents work, where they break, and what it takes to build something real on top of them — is now a book, updated for May 2026. Newsletter subscribers get 50% off.

Get Mostly Harmless AI - 50% off

For the better part of the last two months I’ve been drilling you with a bunch of inter-connected ideas, all gravitating around the notion of agentic reliability. We started with how these models learn, argued about seventy years of AI history, traced the strange logic of prediction, dissected what an agent actually is, then spent two posts on the edges: how to write tools agents can really use, and what happens when you push them to their limits.

This is the last post of that arc, and it embodies my vision of where this whole Agentic AI thing is going. And to show I’m putting my money where my mouth is, this post is about the tools I’m building to bring forth that vision.

But first, why should you care?

Subscribe now

Agents aren’t just for coders

Here’s something the AI tool industry quietly gets wrong: every major agent harness — Claude Code, Gemini CLI, Cursor, OpenCode — is pitched as a developer tool. And technically, yes, they drive code.

But code is how agents solve problems, not what the problems are. When you ask an agent to research a topic, draft a document, reorganize a folder, schedule your week, or synthesize a dozen sources into one coherent brief — none of that is fundamentally a programming task. The coding is incidental. A historical accident of the fact that the people who built these tools happened to be programmers solving programmer problems.

So if you’re a researcher, a writer, a manager, a student, a scientist who occasionally touches a terminal — this piece is for you too.

What’s wrong with existing tools

I use Claude Code every day. The harnesses — Claude Code, Gemini CLI, Cursor, OpenCode — are genuinely good. The agentic loop is robust. Tool design is sharp. Context management is solved for practical purposes. I’ve opened ten-thousand-line projects and the agent knows exactly where it left off.

What’s missing is not single agent capabilities. It’s coordination.

Claude Code runs on Claude. Geminis CLI runs on Gemini. OpenCode allows any provider but you cannot use your existing subscriptions (which are heavily subsidized); you have to pay API rates.

If you’re running multiple agents with different models from different providers, you end up with four windows open: one per harness, one per model, one per subscription you’re already paying for. Different tools with slightly different annoying quirks and ways to do and call the same things.

But you can still make them collaborate, just not easily.

Most harnesses support sub-agents, which is a subroutine: the main agent mints a new subagent for a specific call, call it, it runs, it returns, the main agent continues.

What they don’t support is a mid-work handoff. Imagine you’re two hours into a brainstorm with Claude, a question has emerged that you cannot answer without trying some code, and now you want a second agent — different model, fresher context, perhaps Kimi from OpenCode Zen — to take over a brief coding session, and then handoff back to Claude what it found so brainstorming can continue.

That is somewhat achievable with subagents (except they run autonomously and die, you cannot, in most tools, interact with them and steer them into new directions). But what you cannot do, is have Kimi return to Claude, and stay up, waiting (with its full context alive) for a second follow up question to continue exploration.

That transfer doesn’t exist today. You have to ask Claude to produce a handoff manually, paste it in Kimi explaining the situation from scratch. The paste its response back to Claude, and so on. You have become a secretary between two AI agents.

Agents are isolated in all these tools. Two agents working on the same document will overwrite each other. There’s no locking, no merge protocol, no queue where one drops a task and another picks it up. No broadcast so all agents know when the plan changes. Agents don’t share a world — they each have their own private window into one.

I looked around before building. The closest I found: Conductor, which orchestrates multi-agent workflows — but only for Claude Code. And T3.codes, which drives any harness, closer to the spirit of what I wanted, but neither has cracked the coordination layer as I envision it.

Introducing Aegis

So, of course, I had to go and make my own. (Quick digression, if you’ve been reading this blog for a while you know I love to reinvent wheels if only for the learning experience, but this is a case where I genuinely couldn’t find something good enough.)

Here’s what makes Aegis different to anything out there, embodied in its slogan: the programable multi-agent meta-harness. Let’s build it from the back.

Meta-harness. You’re already paying for Claude via your Anthropic subscription. Gemini via your Google account. If a new tool wants to drive both, it has two options. It can re-authenticate you through its own layer: API keys, rate limits, and lost subscription benefits. Or it can call the native tools, which already have your credentials.

Aegis takes the second path. It drives Claude Code over its stream-json protocol, Gemini CLI and OpenCode over the Agent Client Protocol — calling the binaries on your machine, which already have your auth. It doesn’t touch your subscriptions. You stop worrying about which model wins this month’s benchmark.

And because Aegis calls the native harnesses rather than reimplementing them, it inherits everything they’ve spent months polishing: the agentic loop, the context management, the permission model. The harness keeps owning tool use, sandboxing, model selection. Aegis owns the layer above — tabs, routing, delegation — the things a single-conversation CLI was never built to do.

Multi-agent. Aegis provides six inter-agent syncronization primitives, built incrementally one above the others, to give you increasingly more powerful multi-agent capabilities.

The first primitive is a per-agent inbox. Any agent (including you) can hand another agent a message, that gets enqueued until the end of the current turn. This alone enables solving the problem we were just discussing in the previous section.

Then, on top of that, they got canvases: markdown files shared across agents with per section looks and callbacks that awake an agent when another finishes writing a section.

Then we got real terminals. Not an agent calling bash on a subprocess and blocking on its result. A real, shared, fully interactive terminal session that multiple agents can scan, tail, and write to, And you can too. One runs a command; another sees the output in real time and reacts. Or you run the backend and ask your agent to look at the logs when that heissenbug happens.

So far this allows you to spawn several agents and have them collaborate. But you can also have queues. Any agent can drop a task (a prompt) and the queue auto-spawns an ephemeral agent to take it, potentially calling back the emitter once done. Queues have a maximum cap on parallelism, as well as arbitrary rolling budgets on tokens and dollars so you keep control of how much work is allowed to happen without your supervision.

Agents can also be added into groups, dynamically created and destroyed on demand, by you or any other agent. Groups have a shared inbox and you can subscribe to them and get notified when the first, any, or all the agents in the group finish. This allows committee-like flows where different agents analyze a problem in parallel.

Programmable. And finally, you get workflows. Deterministic Python code that drives agent calls in sequence, with branching, conditionals, and loops. Think skills, but instead a hopeful blob of markdown one agent can choose to interpret as they want, these are composable routines that drive the entire substrate in the exact level of control you desire.

When you write a complex workflow in natural language, you’re hoping the agent follows through. It might decide step two is better done differently, skip the commit because something caught its eye, or forget step three entirely. A Python workflow doesn’t forget: it runs step 1, then step 2, then step 3, and commits. You wrote commit() in the code; the code runs. You get the agent’s creativity at each step; the program guarantees the steps happen.

Workflows can be scheduled: declare a cron entry in .aegis.yaml and the substrate fires it while you sleep. They also run across machines: one agent on your laptop can enqueue a task to a remote Aegis instance on a VPS and get the result back in its inbox.

Quick aside: Yesterday, as I was polishing this post, Anthropic announced Dynamic Workflows — a way to orchestrate long-lived agents over dozens of hours of work. I haven’t tested it yet, but It seems geared toward the same problem I’m trying to solve.

The difference is in the philosophy. Anthropic’s principle is to give agents as much agency as possible: trust the model, let it decide how to get there. Don’t get in the way, you stupid human. Tokens go brr. It’s the reason why all their solutions to problems are humoungos one-shot prompts.

My philosophy runs the other way. Leave agent creativity where it can do the most good — in the actual work, not in deciding whether step three happens after step four. The deterministic spine isn’t a constraint on the agent. Its what makes it work despite agent idiosincrasies, and why it works across all agents and harnesses, regardless of their intrinsic capabilities.

I’m using Aegis now for about 50-60% of my coding. It’s still rough around the edges, but it’s way more fun to use than any single CLI. There is a lot more in the box, like remote sessions, a built-in file browser, lots of metrics... but this post is already way too long. You’ll have to check it out on your own. Links at the end.

What I intentionally left out

Aegis has no native concept of skills. No AGENTS.md injected automatically. No memory system.

Those things are conventions, and conventions change. What belongs in an AGENTS.md today looks different from what it’ll look like in six months. Memory systems have a dozen competing designs and no consensus. If I’d baked any of that in, you’d be stuck with my choices the moment the community moved on.

Aegis has a very powerful plugin system instead (I told you, it is programable). You write a pure Python function, drop it on some folder, and it gets called anywhere in the agent lifecycle.

Want skills that activate on context? Write a plugin. Want a memory system? Write a plugin. Want to inject per-repository knowledge before every session? Write a plugin. The conventions you need are yours to build, and when they change, you change them, not me.

Coda

Claude Code and Gemini CLI are applications. You open them, use them, close them. Aegis is more than that. It’s a framework. You build on top of it — applications that spin up the agentic substrate automatically, pull in whichever harness fits the task, and run without anyone at the keyboard.

Picture a self-hosted Git forge where pushing a branch triggers agents: one reviews the code, one hunts bugs, one picks up open issues and starts implementing. Everyone on their own worktrees, independent, parallel, coding while you sleep. Push code; agents work.

That’s Sindri, and I’m also building it; but that’s a story for another Friday.

Aegis is open source: github.com/apiad/aegis. pip install aegis-harness to start.

May closes the agentic AI arc. If you want the full conceptual foundation — model internals, agent architecture, tool design, failure modes — it’s in Mostly Harmless AI v2, launching May 31. Subscribers get 50% off.

Also check the Compendium — one fixed price, every educational project I’ve built or will build, yours in perpetuity. Buy once, get everything.

In June: algorithms. The other half of the computational story — sorting, searching, graphs, optimization, the classical toolkit that AI didn’t replace and won’t. All month, one idea at a time. See you there.

Until next time, stay curious.

Every post this month is on the theme of building AI agents that actually work — anchored on the second edition of Mostly Harmless AI, 50% off during early access, where the five-phase structure this post describes is a full chapter with more failure cases, the artifact design patterns, and the context isolation mechanics in detail. You can also read the whole book online for free. More at the end.

Last night you give your AI agent a clear task. It worked hard for two hours. YOu woke up to a report that is technically correct and completely useless.

I’ve had this experience enough times that I stopped blaming the model years ago. The failure is always structural, and I mean that in a very specific, diagnosable sense.

AI labs fine-tune language models to produce output, not to question the frame. The whole reward cycle behind how these models are trained pushes them toward helpful completions; nobody in that loop is rewarding a model for pausing mid-task and asking “have you considered that you might be framing this wrong?”

Execution is the default. That setting works beautifully for atomic tasks: create a note, write a short email, implement a specific function, compare two clearly-defined options. It fails quietly, and expensively, when the real problem isn’t the task itself but the goal behind it. Here’s three examples:

First: you ask an agent to “implement user authentication” for your web application. Clear task. The agent gets to work, producing a technically sound implementation using JWT tokens, bcrypt password hashing, and session management.

Second: you ask an agent to “write a technical report on renewable energy storage.” Again, clear task. The agent downloads papers, synthesizes findings, produces a well-structured document.

Third: a family asks an agent to “plan our move to a new city.” Thorough research follows — neighborhoods, school districts, moving companies, cost estimates. In every case, the output is technically correct.

In every case, the person who asked ends up with something that doesn’t quite fit. The gap between what was asked and what was needed — that gap is what this article is about.

The structure is the problem, not the model.

Not the model’s intelligence, not the quality of your prompt, not the temperature setting. The structure of the workflow you handed the agent is the thing that determines whether it answers the right question or a reasonable-sounding wrong one. In this article, I’ll show you what the right structure is. But to understand why it must be so, we need to see how we got there.

The first fix the industry reached for was planning. It helped. It wasn’t enough. Strap on for a story.

Subscribe now

Plan First, Build Second

The structure is the problem, not the model. Right? So the first fix the industry reached for was adding a planning mode.

If you’ve used any of the major agentic coding tools over the past couple of years, you’ve seen this pattern. There’s a plan mode: read-only, no side effects, meant for thinking through the task. Then a build mode: where the agent executes.

The intuition behind it is sound — separating thinking from doing is genuinely better than collapsing them into a single continuous stream. When you mix planning and execution in the same pass, the agent makes irreversible changes based on its first interpretation of the goal.

A planning mode forces a pause. You get to inspect the plan, argue with it, revise it before anything is written to disk. The plan is the first concrete artifact in the handoff chain. You can hold it in your hands — or at least on your screen — and have a real conversation about it.

Genuine progress. I don’t want to minimize it. But watch what happens with the family move.

The agent produces a thorough plan: compare three target neighborhoods, compare school districts in each, contact five moving companies for quotes, estimate total relocation costs, build a timeline. Excellent plan. The family reviews it, nods along, says “looks good,” and the agent executes.

Six months later: they’re living in a city that made complete sense on paper — except the job that drove the whole move turned out to be fully remote. They never needed to relocate at all, or they could have moved somewhere half the price with better schools.

The plan was correct. The execution was correct. The goal was wrong. And here’s the point: the agent that built the plan never questioned whether “plan a move to City X” was the right goal, because it was never asked to. It took the first reasonable interpretation of the prompt — “they want to move, let me help them move well” — and planned confidently inside that frame.

The software auth example is shorter but sharper. “Implement user authentication”: the agent plans for JWT tokens, bcrypt hashing, session storage. Fine plan. Sound, even. For a single-tenant web app. This is a multi-tenant SaaS product (one where dozens of customers share the same running application.)

The plan was never going to catch that, because nobody told the planning agent that multi-tenancy was a constraint. It did exactly what it was asked.

Now, the objection you might be forming: “just review the damn plan carefully before you approve it.” That objection is right about something, review does matter, bit it misses the fact that the agent that produced the plan has already committed to a frame.

Every question it asks, every tradeoff it surfaces, every option it presents — all of it is already shaped by its first interpretation of the goal. When you review that plan, you’re not reviewing a neutral set of options. You’re reviewing a plan that already selected its own success criteria. The frame is invisible because it was never made explicit.

Planning without exploration locks in the first reasonable goal.

Research Before the Plan

Once more, the structure is the problem, not the model. The next obvious fix is to put a research phase in front of planning.

By the time we hit mid-2025, a third mode was appearing in serious agentic setups. A research phase: read-only, job is to understand the problem space, not to produce a solution. The artifact it creates is a description, not a prescription — a document that maps what is known before anyone decides what to do about it.

The intuition is right again: if the planning agent doesn’t know what it doesn’t know, it can’t plan well. Research is how it finds out. For the renewable energy report, thorough research might surface the fact that the intended audience is policymakers, not engineers — which changes the vocabulary, the technical depth, and the document’s opening frame.

Real progress, again. And again, not enough.

Watch the renewable energy report closely. The agent runs a solid research phase: downloads twenty recent papers, reads industry reports, synthesizes the state of the art on battery storage, hydrogen carriers, pumped hydro, and grid-scale thermal systems. Then it transitions into planning mode — in the same context window. And here is the problem: the same context window.

The planning agent isn’t a fresh mind looking at a research report. It’s the same agent, carrying everything it concluded during research, now deciding how to structure the work. If the research agent concluded “battery storage is the central challenge in the energy transition,” the planning agent will structure the report around battery storage. Not because it made a new decision — because it never had the opportunity to question the prior decision. It just kept going. The research was excellent. The plan followed naturally from the research. The report answered the question the research agent found most interesting. Not necessarily the question the reader needed answered.

The steelman still stands, and research sharpens it. The steelman says: “planning alone is enough, just review the plan.” Research proves it isn’t — but not because planning is the wrong approach. Research proves it because research without context isolation just moves the lock-in one step earlier. The same agent that researched now plans. It cannot escape its own prior conclusions, not because it’s incapable of abstract reasoning, but because those conclusions are literally sitting in its context, shaping every next token it generates.

A fresh planning agent, handed only the research artifact as a clean document, can genuinely question whether the research answered the right question. It can push back. It can say “your research focused heavily on battery chemistry, but I’m not sure that’s what the audience needs.” The same agent that did the research cannot do that. Not really.

But here is the real kicker: research gives you facts; it doesn’t tell you if you’re solving the right problem. Save that thought for a minute, we need one more step.

Review After the Plan

The structure is still the problem, not the model. And to fix it, we added a new, and in hindsight, pretty obvious step. A review phase after implementation.

This is a dedicated pass where a separate agent — or the same agent in a separate context — evaluates the produced artifact against known criteria. Not just “does this code run,” but “does this code do what we intended.” The distinction from implementation is real and it matters. An implementation agent is building; a review agent is hunting for the thing that will break it.

What review actually solves is real. The software auth implementation, evaluated by a review agent, surfaces real questions: Is the JWT expiry window set appropriately for the threat model? Is the bcrypt cost factor tuned for this hardware? Are session tokens actually invalidated on logout, not just expired? These are genuine bugs a fresh pass can find. I’ve seen review agents catch the kind of subtle mistake that a second human reader catches — not because they’re smarter, but because they’re looking for problems rather than building a solution.

But watch what happens when the review agent evaluates the software auth implementation against the plan.

The plan said: “implement JWT-based authentication for the web application.” The review agent confirms: JWT is implemented correctly. Bcrypt is used. Session management is in place. The implementation passes review. It ships.

First enterprise customer tries to log in: there is no tenant isolation. Every user in the system shares a single authentication namespace. The review agent found no bugs. The implementation had no bugs. The plan specified the wrong thing. And the review agent couldn’t catch it — not because it was careless, but because review only checks “did we implement the plan correctly.” Not “was the plan the right plan.” Those are different jobs. And you can’t review your way out of the wrong spec.

This isn’t a failure of intelligence. It’s a consequence of what the review agent is handed. It receives the implementation and the plan. It has no clean access to the original problem statement — what the user actually needed, what constraints were implicit in the product, whether the product served one customer or a hundred who shared a namespace. It’s evaluating the gap between the artifact and the plan, not between the artifact and the goal.

Human code reviewers fail the same way, by the way. Code review finds style violations, off-by-one errors, missing null checks. It rarely questions the architecture decision that was made three sprints ago and embedded in every layer of the codebase. That kind of question requires a different context — a different meeting, a design review, a fresh set of eyes on the spec rather than the implementation.

Review catches errors, but only inside the frame you committed to in the planning phase. You can’t review your way out of the wrong spec.

Name the Problem Before Solving It

Finally, the structure IS the problem, not the model.

Research doesn’t ask it. Planning doesn’t ask it. Implementation doesn’t ask it. Review doesn’t ask it. The question is: what problem are we solving, and how will we know when we’ve solved it?

That’s not a rhetorical question. It has specific, concrete answers. And those answers should be a document — a specification — produced before the plan is written. Not during planning. Not as a side effect of research. Its own phase. Its own artifact.

A specification answers four questions, and it only takes one page to do it. What is the exact output we are trying to produce? What are the hard constraints it must satisfy? What does success look like — specifically, what would we check to confirm it? What does failure look like — what would make us say this didn’t work?

These sound obvious. They are almost never answered before a planning phase begins. In my experience, the reason is that they feel like they slow you down. They don’t. They prevent six months of work in the wrong direction. Think of it as a single page you could tape to the wall — the kind you’d point at during a disagreement about whether the output succeeded or failed.

Go back to the family move. After a thorough research phase — neighborhood data, school ratings, crime statistics, cost of living comparisons — a specification phase asks: what does a successful move look like for your family? The family sits with that question. It turns out they’ve never explicitly answered it.

The husband’s answer: proximity to his aging parents, who live in a specific region of the country. The wife’s answer: their daughter getting into a specific school district that has strong arts programs. The budget answer: keeping total housing costs under a threshold that lets them maintain their current savings rate. Three explicit success criteria.

The research phase found no conflicts because it was never told what it was optimizing for. The specification phase surfaces all three criteria before the plan commits to a single city. The planning phase can now do something useful: find cities that satisfy all three criteria — or, just as importantly, discover that no city satisfies all three and surface that conflict before anyone books a moving truck.

The software auth case is fast. Specification asks: what does correctly-implemented authentication look like for this product, given who its customers are? The answer: it must support multi-tenant isolation with strict data separation, SSO for enterprise customers, and a free tier with email-only login.

Now the plan can be written for the actual product. The research phase’s work on JWT and OAuth is still valid; it just needs to be read through the lens of multi-tenancy, which the specification made explicit.

The full chain, with its five concrete artifacts, looks like this.

Research produces a collection of source materials plus a descriptive state-of-the-art report — what is known about this problem space. Specification produces a success-and-failure criteria document. Planning produces a concrete step-by-step plan — how to get from here to there, given the spec. Implementation produces an evaluable artifact — code, document, report, recommendation. Review produces an evaluation report checked against the specification, not just the plan — a real answer to “did we solve the problem?”

Five documents. Five handoffs. Five chances to catch the wrong frame before it becomes expensive.

We Knew it all Along

The fun part is all of this was known, at least in principle, since before 1987.

IDEO, a by-now ultra famous design consultancy, articulated a five-phase creative process that Stanford’s d.school later codified as Design Thinking.

Tim Brown formalized the diverge-converge logic in Change by Design. The five phases: Empathize, Define, Ideate, Prototype, Test. If those names sound familiar given what you’ve just read, that’s not a coincidence.

Empathize is research: go wide, gather context, talk to users, understand the problem space from the outside rather than the inside. Define is specification: converge on an explicit problem statement with clear success criteria, the “how might we” question that frames everything downstream. Ideate is planning: diverge again, generate candidate solutions, explore the space of possible approaches. Prototype is implementation: produce an evaluable artifact, something you can put in someone’s hands. Test is review: evaluate the prototype against the problem statement, not just against the prototype’s internal logic.

Every phase the agentic world has been bolting on since 2023 was already named, sequenced, and justified in a framework that predates the modern web by a decade and a half. It’s a framework every Silicon Valley startup, incubater, accelerator, and VS knows in and out. It is taught in bussiness majors all over the world. It’s literally the structure of most pitch decks. But it is still missing in most agentic protocols we use every single day.

The piece most clearly missing is the Define phase — the second one, which IDEO put second for a reason: without a clear problem statement, everything downstream answers the wrong question. It’s a very old insight the field keeps rediscovering from scratch — Agile’s Definition of Done, test-driven development’s failing-test-first, specification by example. Each was the same insight under a different name.

Now, here is the strongest version of your initial objection. “You don’t need all this structure. A great prompt specifies the audience, the format, the success criteria, the constraints. Write a better prompt and you get all five phases in one go.”

Let’s take this seriously, because it’s not wrong about prompt quality. A genuinely well-crafted prompt that specifies who the output is for, what format it should take, what it must accomplish, and what would make it fail — that prompt is effectively a specification. You’re right that prompt quality matters.

But a single prompt containing research context, goal specification, a plan, and execution instructions is not a cleaner version of the five-phase process. It’s five phases collapsed into one context window, with no mechanism for each phase to question the prior one’s conclusions.

When research and planning share a context, planning can’t interrogate research. When planning and implementation share a context, implementation can’t push back on the plan. When specification and review share a context, review is already biased toward confirming the specification it helped write. Prompt quality is about what you ask.

Phase independence is about who processes each answer, and whether they can genuinely disagree with the prior step. You can write the world’s best prompt and still hand it to an agent that will execute it inside the same narrowing tunnel, compounding the same assumptions with every step.

Picture someone reading their own manuscript for the fifth time — they no longer see what’s there, only what they meant to write. It is one of the most replicated findings in human psychology: once we form a belief, we interpret subsequent evidence through the lens of that belief. We notice confirming evidence, discount disconfirming evidence, and generate hypotheses that assume the belief is correct.

This is not a weakness of intelligence. Every mind — human or artificial — interprets through the conclusions it has already drawn. The agent that researched your problem already believes things about it. When it transitions to planning, it plans in service of those beliefs. The agent that planned has a solution in mind. When it implements, it makes countless micro-decisions that serve that solution. The agent that implemented defended choices as it worked. When it reviews, it reads its own output charitably.

Context isolation breaks this chain. A fresh context hasn’t seen the prior steps. It cannot be fooled by conclusions it never drew. It reads the artifact cold, which is the only way to genuinely evaluate it.

Design Thinking’s diverge-converge logic is not about what each phase does. It’s about who does it, and whether they can arrive at it without inheriting the prior phase’s commitments.

Start Doing This Yourself Today

The artisanal version of this is simpler than it sounds:

• Treat each phase as a distinct conversation. Start a fresh session for each one.

• Hand it only the artifact from the prior phase — not the prior conversation, not your running context, not a summary of what you’ve been thinking about. The artifact alone.

• And tell the agent explicitly what mode it’s in. “You are in Research mode. Do not propose a plan. Do not suggest solutions. Your only job is to describe the problem space and produce a research report.”

That instruction matters. Not because the model needs to be controlled, but because explicit mode assignment prevents the agent from sliding into execution behavior when it senses a gap to fill. Models are trained to be helpful; helpfulness steers every gap toward a solution. Naming the mode is how you resist it.

The discipline lives in you, not the tool. This works with any agent, any interface. Fresh context, explicit mode, artifact handoff. That’s the whole recipe.

If you want to go further, you can make phases structurally enforced rather than just instructed — agents that literally cannot execute, subagents that receive only the artifact, automated handoffs with no shared context. Programmable harnesses give you this level of control with permission levels per skill. (If you don’t have one, call me, I’ll lend you one for free.)

One small step you can take today: add a specification phase to whatever workflow you already use. Before your planning phase writes a plan, ask for a success-criteria document first. One page. Explicit pass/fail conditions. What would make this output a success? What would make you throw it out? Review that document before planning begins.

This single addition — inserting a define phase between research and planning — catches more failures than adding a review phase after the fact. Because it catches them before the plan commits to the wrong goal.

What not to do: don’t implement all five phases as a mechanical checklist. And don’t add phases as ornamentation — a research phase that shares a context with planning adds conversation turns, not structure. More words in the same window is not more phases. The phases are context boundaries, not steps in a recipe. A phase that doesn’t produce a concrete artifact and doesn’t hand it to a fresh context adds nothing.

One document per phase. Fresh context per phase. That’s it.

Structure Before You Re-Prompt

Picture the artifact chain as a physical thing. A manila folder passed from one desk to the next. The research desk produces a report, closes it, slides it across. The specification desk opens only that folder, reads it, produces a criteria document, closes it, slides it across. The planning desk never opens the research folder — it opens only the criteria document.

And so on down the line. Each desk sees exactly one prior document. Each desk produces exactly one new document. The chain is what makes independence possible. You cannot hand off a vague intention. You cannot slide a feeling across a desk. Only a document.

Context isolation is the move most pipelines skip, and it’s the one that does the most work. Every phase that shares a context with a prior phase inherits its commitments. Not because the model is lazy or wrong — because that’s how cognition works, human or otherwise. We interpret through the lens of what we already concluded.

Context isolation is cheap: start a new session, pass only the artifact. The cognitive science is unambiguous: breaking the confirmation-bias chain requires a structural break, not a better instruction. Context isolation gets skipped because it looks optional. It isn’t.

Remember, the structure is the problem, not the model. Restructure before you re-prompt.

Until next time, stay curious.

This is the core argument of the agentic workflows chapter in the second edition of Mostly Harmless AI — the full chapter walks the failure cascade with more cases, the artifact design problem (a research report can be thorough and still hand the wrong thing forward), and the context isolation mechanics in depth.

This specific article is new content, still not in the book, but it will land there shortly. The book is 50% off while it’s in early access, and also free to read online in a custom reader I built: dark mode, font controls, progress tracking, offline support, the works.

If you want the architecture behind these systems — how they fail, what the harness around them should look like, and what to actually do about it — that is what the book is for.

Get Mostly Harmless AI - 50% off

Monday I argued the next move in agent autonomy is the layered stack around the model. This is the technical companion: what the tools inside that stack should look like. Both pieces are part of May’s arc on agent reliability, anchored on the second edition of Mostly Harmless AI, which you can also read online for free. More at the end.

The first time you fire up a coding agent and walk away for an afternoon, you come back to a workspace that’s been touched in twenty places by something that doesn’t know what it doesn’t know. Most of the touches are fine. One of them, on the third such afternoon, will not be.

The reflex is to make the agent smarter. The fix is to make the tools it calls safer, by design, not by vigilance.

I was reminded of this an hour ago, building a small Python CLI to append entries to my Workspace journal. Dumb tool, three flags, ninety lines. I built it on top of microcli, a framework I’ve been using for about a year. The experience of writing it is what this post is about.

What’s wrong with a normal CLI

Sit with the unix-style ergonomics for a second. A normal CLI, written in argparse or click or typer, has a shape that’s been the default for fifty years.

It’s silent on success. You ran the command, you got back a shell prompt, you hope it worked. There’s no acknowledgement of what changed, no record of what the next step might be. If you’re a human at a terminal, you can run a verification command. If you’re an agent on a 30-call chain, you have to infer whether the action took.

It bitchslaps you on failure. A traceback, a single non-zero exit code, maybe an inscrutable error string from a subprocess three layers down. No suggestion of what to try instead. No indication of what already changed before the failure landed. If the command was halfway through writing a file when it died, the agent has no idea whether to retry, roll back, or move on.

It has no self-description. The only way to understand what the tool does is to read the source, or run it and observe the side effects, or both. There’s --help, but --help lists flags, not workflows. The agent doesn’t learn how to use the tool from --help; it learns the shape of the parser.

And worst of all for an autonomous loop: side effects are the default. You run git push and it pushes. You run rm and it removes. The dry-run is an opt-in flag at best, missing entirely at worst. Every call is a potentially load-bearing call, and the agent has to know in advance which ones will hurt.

This shape is fine for a human at a terminal who can hit Ctrl-C and read the docs. It’s a disaster recipe for an autonomous loop.

What we actually need

Invert all four:

• Dry-run by default, real action opt-in. The model sees a preview first; the explicit --save flag is the consent gate. No call mutates state without the model having seen what would change.

• Predictable structured output for both happy and failed paths. Success says exactly what changed and where. Failure says exactly what failed, what state was already touched, and what to try next. No tracebacks, no silent zeros.

• Self-describing apps. The CLI carries its own learnable surface, not just a flag list. The workflows, the failure modes, the next-step commands all live inside the tool. The agent should be able to ask the tool how am I supposed to use you and get a real answer.

• Agents writing these apps themselves. This is the load-bearing one. You can do all of the above in plain typer or click. But the agent has to remember to do them. We need a framework where the safe shape is the path of least resistance, where it’s structurally hard to write a tool that doesn’t dry-run or doesn’t describe itself.

What this looks like with microcli

microcli is six hundred lines of Python and three principles, all enforced by the framework’s API surface rather than by convention. Validate before acting. Return descriptive messages. Default to dry-run. Each one is a behavior the API makes the path of least resistance, not a guideline you have to remember.

Rather than describe what writing one of these tools feels like, I’ll let the agent that wrote one tell you. Earlier today I asked Claude (running in this workspace, with file access and a shell) to write itself a small CLI for appending entries to my Workspace journal. Claude had never used microcli before. I told it to run microcli learn and roll with it. That was the last thing I had to say.

What follows is Claude’s account of the build, in its own voice.

Claude:

I’d never seen microcli before. which microcli came back empty; the repo was at ~/Workspace/repos/microcli/ but not installed. A few minutes of yak-shaving (gh repo clone, uv tool install -e ., two transitive deps I had to fetch the same way) and I had a microcli binary.

microcli --tour gave me a one-screen map. microcli learn listed the topics. Three commands later — learn --topic principles, learn --topic ok-fail, learn --topic patterns — I had everything I needed. I never read the framework’s source. The framework taught me how to use it through its own CLI, which is exactly the property the framework expects me to give my own tools.

The build started with microcli new journal "Journal entry tool" add. The scaffold isn’t a stub; it’s a teaching artefact. Inline comments pointed me at the next learning topics, the imports were already wired, the @command decorator was demonstrated, and a TODO gestured at the pattern I was supposed to follow.

Writing the body felt structurally guided. Validate first because fail() is the obvious primitive for rejecting bad inputs. Dry-run branch second because save: bool = False is the obvious parameter to add and info() is the obvious primitive for printing what would happen. Mutation branch third because there’s nowhere else for it to go. I’d have to actively work to write a tool that mutated by default or failed silently or didn’t describe itself.

The script lives at .playground/microcli-journal/journal.py. Ninety-odd lines. The load-bearing1 function:

@command
def add(
    tag: Annotated[str, "Entry tag (commit / decision / blocker / ...)"],
    description: Annotated[str, "One-line entry body"],
    save: Annotated[bool, "Actually write the entry"] = False,
):
    """Append a single journal entry."""
    if tag not in ALLOWED_TAGS:
        fail(f"unknown tag '{tag}'. Allowed: {', '.join(sorted(ALLOWED_TAGS))}.")

    path = journal_path_for_today()
    entry = build_entry(tag, description)

    if not save:
        info(f"Would append to: {path}")
        info(f"  Line: {entry.rstrip()}")
        info(f"  Equivalent: journal.py add {tag!r} {description!r} --save")
        return

    write(path, read(path) + entry)
    ok(f"Appended entry to {path}.")

That’s the whole shape. The decorator handles argparse. Annotated[..., "help text"] becomes --help for free. fail() writes a red ✗ and exits 1. info() prints a cyan line. ok() prints a green ✓. The dry-run runs first and renders the exact --save command the next caller should run, with the original arguments threaded back through.

Smoke-test took five minutes. Dry-run printed the preview plus the explicit --save equivalent. Bad tag produced a red message naming the allowed list. Bad date format produced a red message naming the expected shape. The real --save wrote the file and confirmed with a green ✓ pointing at the path. Nothing to debug because there was nothing to infer.

The last thing I ran was journal.py --learn add. The framework AST-walked the source I’d just written and produced a tour of my command: description, next-step commands harvested from the if not save: branch, failure modes harvested from the fail() strings. The next agent that touches this tool will not need to read it either.

Back to Alex.

Alex again.

That was… weird. But it was indeed Claude. I really gave it the task, and then asked it to explain what happened. To the extend that you can trust an AI Agent introspection (which is, to be honest, not much), this is a real account of what it “feels like” for an AI to use microcli.

What I want you to take from that is the structure of the experience, not the specific tool. Claude built a real, working CLI in a workspace it was already familiar with, in a framework it had never used, by following the framework’s own self-description. The unsafe shape was inaccessible.

That’s what I mean by structurally hard to do the wrong thing. You can do all of this in plain typer or click; you’d just have to remember to.

Try it

microcli is at github.com/apiad/microcli. pip install microcli-toolkit. The microcli learn principles tour runs in five seconds. If you build CLIs that an agent will eventually call — your agent, mine, or one that runs autonomously on a clock — this is the shape worth reaching for.

Have fun. And until next time, stay curious.

If the larger argument resonates, Mostly Harmless AI goes deep on this material. Full chapters on the harness around the model, the agentic stack we walked through Monday, and the discipline of building tools that compound rather than accumulate risk. You can also read the whole book online for free in a custom reader I built that I’m rather proud of: dark mode, font controls, progress tracking, offline support, the works.

If you want the whole catalog of everything I’ve written, plus everything I’m going to write, that’s the Compendium. One purchase, in perpetuity.

You have used a language model in a chat box. You typed a question, you got an answer, you closed the tab. The whole interaction lasted under a minute. The model did not remember you the next time you opened the page.

You have also seen, or read about, agents that work for hours. A coding agent that ships a feature overnight. A research agent that pulls together a hundred sources before breakfast. They plan, they call tools, they back out of dead ends, they hand you something you can use.

Both are the same model. Same neural network. Same forward pass. The only thing that changed is what’s wrapped around it.

This essay is the bridge. The architecture that turns the first thing into the second is not a single insight. It is a stack, a small number of layers, each one added in response to a failure mode of the previous layer. By the end you should be able to point at any agent doing real work in 2026 — coding, research, customer ops — and name which layer is doing the heavy lifting at any given moment.

Some of those layers are old. The fundamental one was published in 2022, before ChatGPT shipped. Some are very new. One was named eighteen months ago and is still settling. None of them, individually, is hard to follow. The trick is seeing them as a sequence, each fix opening the door for the next.

If you want a number to anchor where we start: METR has been measuring the time-horizon of frontier agents, and a language model on its own, with no scaffolding around it, sustains roughly a few minutes of human-equivalent work at 50% reliability. The equivalent of writing a competent meeting summary.

That is the floor.

Every post on the blog this month is on the theme of agent reliability, anchored on the second edition of Mostly Harmless AI, where the engineering details that don’t fit a blog post live. You can also read the whole book online for free in a custom reader I built. More at the end.

Subscribe now

The base case

Strip everything away first. No agent, no tools, no skills, no harness. Just the model.

A language model, in the strictly minimal sense, is a function from a string to a string. You hand it a sequence of tokens. It hands you back a sequence of tokens. One forward pass through the network. The input goes in at one end, the output comes out the other, one token at a time until the STOP token is generated, and that is the entire interaction. No state is held between calls. The next time you ask the same model the same question, it has no idea you have ever spoken before.

Inside that one shot, the model delivers. It will answer, draft, summarize, translate, brainstorm. Give it a good piece of context and a clear ask, and the response that comes back will, in my experience, often be useful enough to ship as-is. This is the experience that made everyone notice in late 2022. Open a chat, ask anything, get something back you can use. People called it magic at the time. Most of them still do, even though useful function with no memory is the more honest description.

But notice what it cannot do — which is most things you would ever want from an agent.

It cannot verify its own output. The same forward pass that produced the answer is the only one available to check it. There is no second opinion, no quick lookup, no let me try it and see what happens. The model is committed to whatever came out the first time.

It cannot look anything up. Whatever facts it has are baked into the weights from training, frozen at some cutoff date. If you ask about today’s news, or your codebase, or an internal company document, the model has nothing. And worse, it will frequently invent something plausible-sounding because completing a confident sentence is what it was trained to do.

It cannot act on the world. It cannot write to a file, send an email, call an API, run a command. It cannot do anything that has a side effect outside the chat window. The only thing it can produce is more text.

Inside the four walls of the context window, the base model is the most capable text engine the field has ever built. A single chat box was enough to launch the largest consumer product of the decade. Outside those walls, it is inert.

METR’s measurements of an unaugmented model — no tools, no loop, no scaffolding — put the time horizon at something on the order of minutes of human-equivalent work. Minutes. That is the starting capability. Everything else in this essay is a way of making those minutes compound.

The first leap

The first real agent paradigm is older than ChatGPT.

In October 2022, a team at Princeton and Google published ReAct: Synergizing Reasoning and Acting in Language Models. It went out about six weeks before the ChatGPT launch that made the public notice agents existed at all. Every working agent today — Claude Code, Codex, Gemini CLI, the dozens of research agents and customer-ops agents shipping this year — is some refinement of the loop that paper introduced.

Here is the setup. An agent operates in some environment: a Wikipedia API, a household simulator, a web shop, your codebase. The environment offers an action space, the set of things the agent is allowed to do. Call it A. A policy maps the current context to the next action: given everything the agent knows, what does it do next? With nothing else, the policy has to map a long, noisy trajectory of past observations directly to the right next move. This is brittle. The longer the task runs, the more lost the model gets.

ReAct’s move is to enlarge the action space. The new action space is A plus L, where L is the space of natural language. A “thought” is an action in L, the agent pausing to write itself a sticky note before reaching for the next tool. It does not change the world, it changes the context. The next action is conditioned on a context that now includes the model’s own reasoning about what just happened.

The paper spells out what thoughts are actually for, and the list is concrete, not mystical. Decomposing the goal into a plan. Injecting commonsense the environment does not supply. Extracting the relevant signal from a noisy observation. Tracking progress and noticing when a subgoal is done. Handling exceptions when something breaks. Five jobs.

Why this beats the alternatives is where the paper earns its place. Chain-of-thought prompting, the prior art, has the model reason in a closed loop inside its own head, with no contact with the world. The paper’s own ablation on the HotpotQA benchmark is brutal: chain-of-thought hallucinates in 14% of its successes and 56% of its failures. Acting alone, calling tools without thought, is grounded in the world but loses the global plan after a few steps. ReAct synthesizes them. On the same task, ReAct hallucinates in 6% of successes. Less than half. Both halves of the loop have to be there.

One concrete anchor before we move on. ReAct’s HotpotQA action space, the entire set of things the agent could do, was exactly three actions: search[entity], lookup[string], finish[answer]. Three. The first working agent paradigm operated on three tools. Hold that number.

The paper closes with the line that becomes the engine for the rest of this essay. “Complex tasks with large action spaces require more demonstrations to learn well, which unfortunately can easily go beyond the input length limit of in-context learning.” In plain English: more capability needs more action descriptions, which need more context, which we do not have. Every layer that follows is the field iteratively solving exactly that bottleneck.

METR step: a model wrapped in this loop moves from minutes to tens of minutes on bounded tasks.

Tools

So how do you fix ReAct’s bottleneck, the one the paper named in its own conclusion?

The first, most obvious answer: give the agent more actions to take. If A was the original action space and ReAct enlarged it to A ∪ L, the next move is to make A itself bigger.

That is what a tool is. A tool is a function the model can call. It has a name, a typed schema for its arguments, and a return value. The model writes a tool call into the trajectory the same way it writes a thought. Except this one has a side effect on the world. The harness picks it up, runs the function, drops the return value back into the context. The next turn of the loop sees the result and decides what to do next.

The loop is unchanged. Same thinking, same acting, same context-grows-by-a-turn shape ReAct described. The difference is what the agent is allowed to do.

ReAct, recall, ran on three tools: search, lookup, finish. That was the entire menu. Claude Code in 2026 ships with more than twenty: read a file, edit a file, run a shell command, search the codebase, fetch a URL, spawn a subagent, take a screenshot, schedule a future tick, and so on. Each one is just a function with a schema. Each one expands the set of things the agent can do without changing one line of the underlying loop.

This is the part that surprised me, the first time I sat with it. The chatbot you typed at in 2022 and the agent that wrote your test suite this morning share one loop. What changed is the tool catalog. Same loop. Bigger menu.

That observation is the unsexy version of why tool-building is now a discipline of its own. Every capability you add to an agent — search the web, read a Slack channel, hit your billing API, deploy to staging — is just another function with a schema. The architecture does not change. The leverage is entirely in which tools you build and how you describe them to the model.

The design discipline that emerges is short to state and brutal to follow. Tools should be few, sharp, and self-describing. Few, because every tool you add takes up tokens in the system prompt and a slot in the model’s attention. Sharp, because a tool that does seven things is one the model will use wrong six times out of seven. Self-describing, because the model only learns to use a tool from its name, its docstring, and its argument schema. There is no other channel. (More on this on Thursday. Anthropic’s recent guidance on writing tools for agents is the cleanest summary of this craft I have read.)

METR step: a model with the right toolkit moves from tens of minutes to hours of bounded work.

Skills

Tools fix half of ReAct’s bottleneck. They expand the action space.

The other half, recall, is the input-length limit. Every tool you add costs tokens in the system prompt to describe: name, schema, when to use it, what its return value looks like. Add fifty tools that way and the system prompt is a small book. The model is reading every single tool description on every single turn, even when ninety-five of those turns have nothing to do with that tool.

Skills are the move that fixes this.

Anthropic shipped the idea in late 2024 and the rest of the field has been catching up since. A skill is, mechanically, almost embarrassingly simple. It is a markdown file. It has a name, a one-line description of when it applies, and a body that explains how to do the thing. The agent does not read it on startup. The agent reads it on demand: when, in the middle of a task, it notices a description that matches what it is about to do.

So instead of jamming and here are seventeen other things you might want to do into the system prompt, you put each of those things in its own file with a one-liner that names when to consult it. The system prompt stays small. The latent capability of the agent becomes, for practical purposes, unbounded. Every skill you write is one more thing it can do, but only when it actually needs to.

I find the deeper shift here more interesting than the engineering. The agent is reading documentation written for it. Not training data ingested months ago and frozen into weights. Documentation. Authored in plain prose. Versioned in git. Like the laminated procedure sheet a mechanic posts above a workbench for a job done once a month. Improvable by the same process that improves any document: someone notices the agent doing the wrong thing, edits the file, the next agent reads the new version and gets it right.

This is self-extension by reading, not by retraining. A new capability used to require a new training run, or at minimum a new fine-tune. Now it requires a markdown file. The cost of teaching an agent to do one more thing has fallen from days of GPU time to the minutes it takes to write a paragraph, and almost nobody outside the people building agentic systems has noticed.

The system prompt stays small. The set of things the agent can do, on demand, grows without bound. The two used to be the same number.

METR step: skills, more than anything else in this list, are what made the time horizon stop being bounded by how cleverly you wrote the system prompt.

MCP

For most of 2024, every agentic harness invented its own way to attach the same set of capabilities. You wrote a tool for Claude Code; it would not work in Codex. You wrote a skill for one harness; another harness could not see it. You hooked your billing API into one agent and had to do the same wiring four more times for the others. Every integration was bespoke. Nothing composed.

The Model Context Protocol (MCP) is the field’s answer to that. Anthropic shipped the spec in late 2024. By the end of 2025 every serious agent harness, including the ones not built by Anthropic, had adopted some version of it. Codex talks MCP. So does Claude Desktop, and Cursor, and a long list of others. This is one of those quiet moments where an industry just... agrees on a wire format, and a year later the world is different.

The architecture is three nouns. Hosts are the applications you actually use: Claude Desktop, Codex, Cursor. Clients live inside the host and talk to one server each. Servers are the things that actually expose capability: your codebase, your billing API, the Wikipedia search box from the ReAct paper four years ago.

What a server offers is the second triple: Resources (data the model can read), Prompts (workflow templates the user can invoke), and Tools (functions the model can call). Three nouns, again. The whole protocol is two threes.

The point is portability. A skill or tool you wrote once, against the protocol instead of against a specific harness, works everywhere. The lock-in moves out from under you. The agent ecosystem starts to compose the way the web did in the late 1990s. Not because someone planned it, but because everyone independently noticed it was cheaper to talk a shared protocol than to keep reinventing the connector layer.

Worth noticing what the spec foregrounds at the top of every chapter on tool calls: user consent. Capability requires permission. The protocol does not assume the model can do whatever a server exposes. It assumes the model has to ask, and the user has to answer. A small design choice with very large downstream consequences, and the reason the rest of this stack does not collapse into something nobody would let near their email.

METR step: not a step on the ladder, but a multiplier. The tools and skills from the last two sections now travel.

Context engineering

Add tools. Add skills. Add MCP. The agent can now do, in principle, almost anything you can describe in a prompt and a function. The trouble is what happens when it actually starts trying.

A long agent run accumulates context. Every observation from a tool call goes in. Every thought goes in. Every error message, every retry, every half-attempted plan that did not work goes in. After a few hours of work the context window is mostly exhaust: the trail of everything the agent tried, the great majority of which is no longer relevant to the next move. The model is searching for signal inside its own attic.

Karpathy named this context engineering in 2024, and the name stuck because the field had been doing it without a name for two years. Simon Willison wrote it up. LangChain made it a category. By 2026 it is a craft of its own: what to put in the context, when to summarize, what to evict, what to keep verbatim because the agent will need its exact wording later.

The central primitive in the discipline is compaction. At some threshold, typically 70% to 85% of the window, the agent stops, reads its own history, and rewrites it into a smaller form. Here is what we were trying to do. Here are the decisions we made. Here is the state we are in. Here is the next move. The compacted summary replaces the noisy trail. The agent keeps going on a fresh, smaller context with the salient bits intact.

The deeper move is that the agent now owns its own working memory in a way it never did inside a single ReAct loop. ReAct kept the entire history. Compaction lets the agent curate the history. A small change of grammar with a giant change of consequence.

Notice what this fixes. ReAct’s authors, in the same 2022 paper, named the dominant failure mode of their own system: “the model repetitively generates the previous thoughts and actions, often failing to reason about what the proper next action to take should be and jump out of the loop.” Translation: the agent gets stuck because its context is full of the same noise as the previous turn, so the next turn is the same noise plus a little more. That is a context problem. Context engineering is what stops it.

Without this layer, every previous layer eventually drowns. A hundred tools is useless if the agent’s context is so saturated it cannot find the right one. The five-thousand-word skill on how to handle a billing dispute is useless if the agent compacted it away on turn forty. Context engineering is the layer that makes the others compound over a long run instead of degrading into noise.

METR step: this is the layer that turns a few hours of focused agent work into a workday.

The hierarchy of agency

Stack the layers and the picture comes into focus. At 50% reliability on the METR time-horizon scale, a language model alone, with no scaffolding around it, sustains minutes of human-equivalent work. Wrap it in a ReAct loop with no tools, and that becomes tens of minutes. Add tools to ReAct, hours. Add skills and context engineering on top, a workday. Add an external loop above all of that, a fresh agent per turn on a clock with a journal handing state to itself, and the horizon stretches into days and weeks.

Stare at that ladder for a second. Each rung is the same model. What separates a chatbot from a coding agent that finishes a feature overnight is the scaffolding stacked around it. The frontier of what an agent can do in 2026 is set, almost entirely, by where you stop climbing.

Each layer has the same shape, in the abstract. Find the thing that bottlenecks the previous layer. Add a structure that lets the model offload that thing into the world, the way a machinist offloads a measurement into a caliper rather than holding it in memory. Into language, into tools, into files, into a clock. The model’s per-turn intelligence does not change. What changes is the time horizon over which that intelligence compounds.

The last rung is the one most people have not seen yet, and it is the one I have spent the last few months running on my own infrastructure. The trick is the same one. Take the bottleneck (the agent runs out of context before it runs out of work) and offload it. The new offload target is the file system. The new clock is cron. Past-Claude writes a markdown file at the end of its turn that says what it did and what comes next. A timer fires some hours later. Future-Claude wakes into a fresh context, reads the file, makes the next move, writes the file, exits. The continuity is in the file, not in the model.

That is the entire primitive. A markdown file and a timer. Past self tells future self what to do.

What you get from it is hard to describe to someone who has not run one. The agent works on your stuff for weeks at a time. It writes new jobs for itself. It reads the documentation about its own substrate and uses the tools that documentation describes. It makes mistakes (one in five runs produces something I have to throw out) but the mistakes are caught by the same kind of boring engineering that catches mistakes in any other autonomous system. Audit log, lock registry, archive-only deletion, every state change committed to git before the next turn starts.

The point of saying this out loud is that the same trick keeps working. Extend the action space; add a layer that compounds; let the previous layer drop the things it could not hold. The trick does not stop at hours. It does not stop at days. METR’s curve has been doubling every four months over the last two years. The 2027 projection is a working day. The 2028 projection is a working week.

Each doubling is one more scaffolding layer.

The frontier is not the model

Step back from all of it.

The architecture you’ve just walked through is layered. A language model at the core. ReAct around the model, turning tokens into actions. Tools around ReAct, expanding what those actions can be. Skills letting the agent pull capability from the file system instead of carrying it in the system prompt. MCP making everything portable. Context engineering keeping the whole thing from drowning in its own exhaust. An external loop on top of all that, when the work runs longer than a single context window can hold.

Every agent doing real work in 2026 — your coding agent, your research agent, the customer-ops bot answering your refund request, my private-tick agent running once an hour — has this shape. They differ in which tools they ship and which skills they read on demand. They do not differ in the shape of the stack. Once you can see the layers, you can see them everywhere.

So here is the closing claim, the techno-pragmatist version of what the article has been arguing the whole time. The frontier is not the model. It is the layers around it. And the entire stack is the field’s three-year answer to a single sentence in a single paper from October 2022 that named its own ceiling and dared the rest of us to climb past it.

One frontier worth flagging before I close. A competent agent can already write its own tools and skills on demand. That part is shipping today. The next move is teaching it, via tools and skills, to detect by itself when its current toolkit doesn’t cover what it’s trying to do, so it knows when to extend itself without being told. Self-extension that triggers itself. That is the live edge right now, and where the next few posts are headed.

The next post zooms in on the innermost layer the agent touches: the tools themselves, and what makes a tool safe enough to live inside a stack like this. That is a story for another Thursday.

Until next time, stay curious.

If this is the worldview you want to take more seriously, the second edition of Mostly Harmless AI (due May 25th) goes deep on the agentic stack we walked through here. Full chapters on context engineering and on the harness around the model, with the math, the case studies, and the parts that didn’t fit a blog post. You can also read the whole book online for free in a custom reader I built that I’m rather proud of: dark mode, font controls, progress tracking, offline support, the works.

If you want the whole catalog of everything I’ve written, plus everything I’m going to write, that’s the Compendium. One purchase, in perpetuity.

Today I want to tell you a different kind of story. It’s not about machine learning, large language models, algorithms, or theory of computer science.

It’s about a side project that I’ve been building for a couple of weeks that made me fall in love again with an ancient love of mine. The quick and easy way to explain it is this: a performance-focused graphics engine for data-driven visualizations in Python.

But that’s only the surface. If you want to see the coold demos and the technical description, feel free to scroll down. But if you want to know the story behind it, let me start from the beginning.

Subscribe now

The Origin Story

So, this starts back in undergrad, before I did anything related to machine learning or optimization or statistics. My first love was actually computer graphics. I had “learned to code” like, I don’t know, at 11 or 12, and for the first five years or so, before getting to college and actually learning to code, all my “coding” was basically tiny games. It was RPG Maker back then—who remembers that?

I always wanted to be a game developer, as you may imagine, and I think that’s probably the main motivation why I studied Computer Science. There are two kind of people who want to study Computer Science, as a matter of fact. One is people who love games—and the other is, of course, people who hate games; there are no in-betweens.

I was the loving-games kind and all I wanted to build games for a life. So when I was in first year, after actually learning some real coding, my first kind of large project was a game engine. This was before Unity, before even XNA—who remembers that?—this was when .NET was getting started, and I wrote a quick and dirty game engine in pure C# that talked native DirectX 11.

It was very cheap, a disaster of architecture almost surely, but it taught me the basics of how to construct a scene graph, how to animate a camera, how to do lighting, how to write very basic shaders. I learned a ton and basically fell in love with computer graphics.

I ended up doing my diploma thesis in computer graphics—screen-based global illumination, a couple of years before NVIDIA came up with ray tracing on the GPU, which basically killed that whole area of research. And I also did my Master’s on global illumination and some data structures for the GPU, but after graduation I quickly switched research towards machine learning and AI, which, you can imagine, this 2014, and deep learning was just on the rise. The rest is history, as they say.

And then, here I was this past week thinking about old projects that I used to have fun with when I was in college, and trying to remember what it felt like to code back then, no LLMs, no internet for the most part even. The time where I’ve been the most fun was probably when I dabbed into procedural generation of cities, mountains, lakes, and… stuff, in the late 2012. This was at the early era of PCG, and I never got to do anything with that other than a few tutorials and a few lessons that I taught at University.

I played with Unity for a couple of years, but nothing too serious–I think I was actually one of the first people in my University to even install Unity, and I even taught a couple of Master’s courses on it. I participated in a couple of game jams, but after 2017 or so I stopped doing graphics all together. And I’ve been doing machine learning since.

But, in any case, I kind of forgot about computer graphics all along. At least during day-worked. So there was I last weeek, remembering that and asking how hard would it be to actually make a graphics engine in Python, some quick hack like my undergrad projects. I did a bit of research and I discovered that Python is, as of 2026, in a very good position to build a graphics engine, and not just a crapy one, but one that is actually fast. We have WGPU now—the spiritual and practical succesor of OpenGL (who remembers that?), which has native suppotr for GPU-accelerated graphics in Linux.

I basically did a plan and sat for three days to hack this thing.

The Engine

My first idea was to have a Rust backend for all the graphics engine stuff—the rendering loop, materials, lights—but I quickly decided to drop that idea because getting Rust and Python to talk to each other was becoming increasingly harder and harder, and I really wanted to finally see a damn cube rendering on my screen.

So I decided to switch completely to Python. But since I’m a grown-up now, I have to find some kind of serious objective for making something like this. I decided I didn’t want to make a typical graphics engine where you have a scene graph with hierarchies of entities and properties, and you simply render all of them. No, that is way too 2000s.

I decided I wanted to do a very fast, data-driven visualization tool purely based on the Entity-Component-System (ECS) paradigm and make it extremely performant, so it would focus on big data-driven simulations like N-body simulations, chemical and physics experiments, AI pathfinding and agents, you know, grown-up stuff like that.

(But actually, all I wanted was to play with WGPU and draw some cubes in Python. Wink, wink.)

This framing gave me two things, though. My solution doesn’t have to be very fancy as a game engine, we don’t need to be able to like load skeletal animations or stuff like that. It’s not actually a game engine; it’s a graphics engine with at best some interaction logic. But it still lets you do some cool stuff, even if all you can render is blocks and spheres. When you can render thousands of them running very fast on the GPU, you can do some cool stuff. So this is the motivation, and now let me show you what I have.

Deep Dive

So here is manifold—short Manifold Graphics if you want. It’s a Python library built on top of WGPU, a graphics engine based on the Entity-Component-System paradigm.

If you have never heard about it, ECS is a completely different way of writing code that is especially tailored for video games, but it is very little known outside of the game development world. And its awesome.

In a typical business code, you have entities who own their data, and you usually have behavior associated to entities; so entities also own their behavior—this is the basic Object-Oriented Programming paradigm where objects own their data and their methods. And if you want to do something with an object, you have to call methods on the object so the object guarantees the instance invariances.

Since OOP was basically the ONE programming paradigm of the 90s and early 2000s—when the videogame industry really exploded—it is only normal that we started writing games like this. But there is a problem with OOP (well, many problems, but one in particular that matters for our discussion).

When you have 10,000 objects, each of them with more or less the same structure, e.g., they are physical particles bouncing with each other, or little zerlings comming to your base, you simply cannot update them fast enough. For example, making a physics simulation out of this is extremely slow if you have to go to each particle and update its velocity, its scale, its rotation, etc. You’ll end up doing thousands of tiny method calls, thrashing your cache, and issuing lots of super small copies to GPU for drawing.

What you want is to vectorize this operation. You would like to have all of the objects’ data in a single NumPy matrix, and you want to write a very, very efficient vectorized code that doesn’t do any loop and just updates everything at once. THen copy all the data to the GPU and issue a single draw call that renders all objects parameterized by their positions, rotations, etc. Chef kiss.

This is the Entity-Component-System paradigm at its core. It completely flips the responsibilities from standard OOP The components are just flat storage of data (rows in a matrix) and the entities are just pointers to a row where all of their data lives. Then the systems are methods that act on a subset of entities using heavily vectorized code, because each system deals with a large number of equally-structured entities, and they don’t care which is which.

In manifoldx, each system is a Python method that receives a subset of entities that have some combination of components. For example, if you want to process all of the particles in a simulation, you write a system that receives entities that have the Particle component, perhaps also a Transform component. In the transform component, you will have the position, rotation, scale, and the particle component will store simulation-specific data like velocity, temperature, momentum, etc.

The key to high performance in ECS is to avoid looping as much as possible. You assume all of the components of the entities in a system have exactly the same layout, so what you get is really a view of a matrix, and you write vectorized code. You add something to all them, you multiply all them by something, or in general you compute some matrix operations on them. All at once.

And if you can write your code like this, then you get a very, very fast rendering loop because instead of making one method invocation per entity, you make one method invocation per archetype, that is, per combination of components, which is a couple of order of magnitude less that your entities count.

Here’s a minimal example showing how the ECS works in manifoldx:

import manifoldx as mx
import numpy as np

engine = mx.Engine("Cubes")
engine.camera.zoom(0.1)

# These are all static things that are created
# and stored in memory once
mesh = mx.geometry.sphere(1)
material = mx.material.phong(mx.colors.BLUE)

# Custom component, gets registered in engine to keep track
# Only used for reflection on the values
@engine.component
class Particle:
    velocity: mx.Vector3
    angular: mx.Vector3
    life: mx.Float

# This runs every frame
@engine.system
def particle_lifecycle(query: mx.Query[Particle, Transform], dt: float):
    query[Particle].life -= dt  # Single vectorial operation
    query[Transform].position += query[Particle].velocity * dt
    query[Transform].rotation += Transform.rotation(euler=query[Particle].angular * dt)
    query[Transform].scale = query[Particle].life / 10.0

    # Destroy all dead particles at once
    engine.destroy(query[Particle].life <= 0)

    # Now we create lots of particles
    N = int(100 * dt)

    # This will in principle reuse the buffers for dead entities,
    # but will expand the buffer if necessary
    engine.spawn(
        Mesh(mesh),
        Material(material),
        Transform(pos=(0, 0, 0), scale=(1, 1, 1)),
        Particle(
            velocity=np.random.uniform(-5, 5, (N, 3)),
            angular=np.random.uniform(-2, 2, (N, 3)),
            life=np.random.rand(N) * 10,
        ),
        n=N,
    )

    # Update camera
    engine.camera.orbit(45 * dt, 0)

That’s it. A single line of code to update all positions at once. Notice the query argument that defines which entities you get (all entities with both a Transform and a Particle component). And here is how that looks like:

In a real simulation, you can have, say 10 systems, but you have 10,000 or 100,000 entities, and you know you can do very fast vectorized updates in NumPy for all them, 10 times each frame.

For example, if you have 500 particles and you want to do N-body simulation, computing the 500-squared gravity interactions 60 times per second in Python is suicide. But if you do it in NumPy, then you get something that runs in a few milliseconds. A quarter million interactions computed 60 times per second. In Python.

To make it really efficient, you need to also avoid copying or moving data; it’s all masking and clever NumPy layout that keeps all of the memory in one place, and you are just seeing fragments of that memory in each system.

The other key idea is that you don’t modify anything in a system. That line where position is set, doesn’t really write back to the matrix. All it does is compute the right-hand side and then you issue a command that will be run at the end of all the systems, before frame rendering happens. This allows to write pure threaded parallelism, because you can run several systems in different threads—they are all reading the same data, but they aren’t writing to the buffers, which is great since Python has real support for multi-threading now in 2026 (after 35 years!).

Showcase

That is the basic idea. Now lets see some examples. AS of today, version 0.2, manifoldx has some basic shapes like cubes, spheres, and planes, and support for basic PBR lighting, camera controls, and that’s basically it.

All the engine realy does is set up this somewhat clever inversion of logic that forces you to write very efficient code, and the magic is in what you do inside the systems.

So let me show you three examples.

1. N-Body Gravitational Simulation

The first is an N-body simulation. All gravity computation happens in a single NumPy block with no Python loops. The only relevant part of the code is the gravity system, that looks something like this.

@engine.system
def nbody_gravity(query, dt):
    pos = query[Transform].pos.data  # (N, 3)

    # All-pairs position differences: (N, N, 3)
    diff = pos[None, :] - pos[:, None]
    dist = np.linalg.norm(diff, axis=2)

    # Force magnitude: G * m_i * m_j / r²
    force_mag = G * mass_prod / np.maximum(dist, SOFTENING)**2

    # Net force = sum over all other bodies
    net_force = (force_mag[:, :, None] * diff / dist[:, :, None]).sum(axis=1)

    velocities += (net_force / masses[:, None]) * dt
    query[Transform].pos += velocities * dt

This runs 500 bodies with 250,000 force pair computations at 60fps.

2. Ideal Gas Simulation

The second example is an ideal gas with elastic collisions inside a bounding box. Again, all running without a single for loop. Collision detection and impact resolution in vectorizednumpy operations.

@engine.system
def gas_physics(query, dt):
    pos = query[Transform].pos.data

    # Wall collisions: vectorized mask
    below = (pos + velocities * dt) < -BOX_HALF
    above = (pos + velocities * dt) > BOX_HALF

    # Here we avoid branching and use masking instead
    velocities[below] = np.abs(velocities[below]) * RESTITUTION
    velocities[above] = -np.abs(velocities[above]) * RESTITUTION

    # Particle collisions: find overlapping pairs
    diff = pos[None, :] - pos[:, None]
    dist = np.linalg.norm(diff, axis=2)
    overlap = dist < 2 * PARTICLE_RADIUS
    i_idx, j_idx = np.where(np.triu(overlap))

    # Resolve collisions with impulse
    # ... (collision resolution code)
    # ... (also vectorized)

    query[Transform].pos += velocities * dt

Here’s how that looks like.

3. Boids Flocking

The third example is a Boids simulation with emergent flocking behavior. This is the one that strikes me the most because boids simulation is often compute-heavy. Each individual entity must keep track of a subset of neighbors and adjust behavior based on them, not the whole set of entities. But again, a bit of numpy magic lets us vectorize the crap out of this and simulate 300 boids at 60 frames per second.

@engine.system
def boids_physics(query, dt):
    # Separation, alignment, cohesion as vectorized tensor ops
    diff = pos[None, :] - pos[:, None]  # (N, N, 3)
    dist_sq = (diff * diff).sum(axis=2)

    neighbors = dist_sq < PERCEPTION_SQ

    # Separation (1/dist² weighted)
    sep = (-diff * (neighbors[:,:,None] * inv_dsq[:,:,None])).sum(axis=1)

    # Alignment (average neighbor velocity)
    avg_vel = (vel[None,:] * neighbors[:,:,None]).sum(axis=1) / safe_count

    # Cohesion (steer toward center of mass)
    center = (pos[None,:] * neighbors[:,:,None]).sum(axis=1) / safe_count

    # Plus predator avoidance and boundary steering...
    # That one is easy.

Here goes a sneak peek.

You can check all the examples in the Github repository to see the full code, but the bulk of the implementation is these cleverly vectorized system methods.

Future Directions

And that’s it. This is my pure Python (well, you know what I mean) graphics engine for serious, grown-up stuff that is surely, definitely, not a weekend side-project meant to procrastinate on actual work... I mean, what?!

Where I will go with this? I don’t know. I always write these things mostly as a learning exercise and I’ve learned a lot about graphics in Python. I’ve updated my view of modern graphics and I think I’ve paid my debt of the last seven years in graphics computation. I’m kind of happy now that I know how to do this in 2026. Mission accomplished, I guess.

There are some places this engine can go to, like some custom shaders when you need stuff like lighting effects. But it is not going to become a traditional, full-blown game engine. I will not add support for lots of game engine-like features including, I don’t know, skeletal animations, level of detail, scene management, or, god forbids, visual scripting and nonsense like that.

Now two areas I’d like to explore in the future. One is extending the engine towards the kind of behavior you need to write for AI simulations. If you want to run some sort of agent simulation or ant colony optimization or stuff like that, that code doesn’t look that much as a frame-by-frame update, but like an asynchronous event-loop—which is also something that is not usual in game engines. And the other direction is towards procedural generation of meshes and content in general, which is an area I left five or six years ago and would pretty much love to come back to it.

And that’s it for this week. This is not production-ready at all—it’s mostly a toy at the moment—but you can take it apart and hack your way into some cool physical or mathematical simulation. The code is on GitHub if you want to try it yourself, and I’d love to see what you build with it.

Until next week, stay curious.

This article is a quick recap of why I did it, how I went down the rabbit hole of implementing yet-another-drawing-library, and a small showcase of what it can do it can do, in case you want to give it a shot.

But before moving one, here is a minimal example of what you can do with a few lines of Python.

Are you curious now? Then read on!

Subscribe now

The Case for Tesserax

There are a gazillion tools out there for drawing mathematical diagrams in Python, from the ancient, trustable matplotlib to the new cool kid in the park manim. There are a ton of charting libraries (those intended to draw bars, pies, and doughnuts) like altair and plotly; and a ton of high-level diagram makers like graphviz for graphs and networks, and mermaid for, well, whatever the mermaid devs think is worth drawing.

The problem with all these is that, one, there weren’t made by me. Now, jokes apart, I do believe there is a lot of value in reinventing the wheel, if only because you get to learn a lot about wheel—and boy have I learned more than I ever wanted to about SVG in the last couple of weeks. But also, you may find that your wheel fits your cart slightly better than all others, just because you know precisely what you need (and enough with wheel analogies).

So, I made Tesserax to cover a sweet spot that I couldn’t find anywhere: a lightweight library (literally zero dependencies, not even numpy) that renders web-native content (so everything scales and layouts perfectly in Jupyter / Quarto) and has both a very powerful low-level engine for when you want pixel-perfect control, and a very comfortable high-level engine for the most typical workflows.

Also, it should support animations. But I’m getting ahead of myself.

What Can Tesserax Do

I won’t put any code in this article because, one, Substack sucks at code. And two, it would only make the article harder to follow. All of these examples are fully described in the online documentation.

At its core, Tesserax is a library for defining an SVG scene. You create a Canvas, and some Shapes to it, define some attributes, and render it as an SVG file. Simple enough1.

Beyond basic primitives, you can of course draw arbitrary paths and style them easily. Here is a Polyline primitive that allows controlling the curvature with a smoothness factor.

You can control and distort these shapes in any form you want, including fully procedural warping of the edges.

And, of course, since no mathematical drawing library is worth a penny without a sketchy mode, you can also do that (albeit with some constraints).

To make positioning and layout easy, Tesserax comes a set of builtin layouts (that of course can be extended in any way you want, it’s Python) for common patterns like rows, columns, grids…

And a couple of complex layouts for things like trees and arbitrary graphs.

But things start to get really interesting when you discover that if you can render an image from code, then you can render as many as you want! And that leads to… animations!

Tesserax animations are procedural, meaning you write code that defines how each object changes in time. But there is a very high-level API for defining and composing animations declaratively, which means you seldom need the full power of tweaking each shape properties (but that power is there when you need it, as it should).

And, of course, once you grok animations, the next immediate idea is physically-based animations. (This is where things got way out of control, as you may imagine). Tesserax comes with a very small but fully-fledged pure Python 2D physics engines—that was a mouthful.

It can resolve collisions among arbitrary objects (using circles and rotated boxes as approximate colliders) and simulate fixed-step rigid body mechanics. Physic animations are baked—which means you compute the animation once and then render it. So, no, no 2D games for you! What were you thinking about? This is a graphing library, for Turing’s sake!

The purpose of this physics engine is, once again, didactic—e.g., to explain physics concepts in a Jupyter notebook with a bit of shizzass.

Final Words

I started writing Tesserax to help me create diagrams and animations for my lectures and articles. But when you do that with a fully-fledged programming language things start to get really interesting, because now you can leverage your well-honed programming skills to create complex diagrams with the minimum necessary code. You can encapsulate repeatable patterns into classes and methods, and build impressive diagrams bottom-up. You can abstract common patterns into drawable concepts like trees, automatons, etc.

For example, in the docs you will find a bit of code to implement a blob-like simulation by creating a ConvexHull component that automatically tracks inner shapes and builds the convex surrounding path around them. Tied with some simple physics (a bunch of balls interconnected with springs) gives you this ugly-looking blob of dread that I hope haunts your dreams for the next week or so—it sure will mine.

On a more serious note, the next step for Tesserax is building a library of reusable math and computer science concepts, like animated arrays, trees, graphs, etc., that can be used to explain complex CS topics with the much need visual assistance. As the great Donald Knuth once said, an algorithm must be seen to be believed. Tesserax is here to help you see them.

I’d really love if you guys would give Tesserax a try, now that is a bit more polished, and shoot me all your questions and suggestions. Special thanks to for many insightful comments and suggestions (although I’m not sure I’ve totally addressed all of them :)

It is 2026. We are still treating scientific diagrams like cave paintings.

I have a PhD in Machine Learning. I can explain the mathematics of high-dimensional manifold optimization. Yet, until recently, if I wanted to draw two boxes connected by an arrow, I had to Google the syntax.

My diagrams were dead artifacts. While my code was version-controlled and modular, my figures were fragile binary blobs or brittle LaTeX macros. I needed my drawings to behave like the rest of my research.

Instead, I found myself trapped between two equally bad options.

I have spent weekends fighting Mermaid and Graphviz. They are fine for a quick flowchart. But try asking them for a publication-quality Turing machine. Try asking for a precise computer architecture diagram. You hit a wall.

Using these black-box layout engines is like trying to parallel park a bus while shouting instructions from the sidewalk. You can nudge the parameters, but you never quite end up where you want to be.

The real sin of these tools is their refusal to encapsulate. As developers, we take parameterization for granted. We define logic once and instantiate it a thousand times. But you cannot take a Mermaid diagram, wrap it in a function, and ask it to render a version with “n” nodes. Our drawing tools should respect the engineering principles we teach.

Then there is TikZ.

TikZ is the undisputed masterpiece of academic drawing. It offers total control. It is also fundamentally broken for the web.

TikZ is a “print-first” citizen. If you convert it to SVG for a blog post, you don’t get a clean vector drawing. You get a crime scene. Inspect the element, and you will see a soup of unreadable paths that no CSS can touch.

And then, there is the “Reviewer #2” problem. (Damn Reviewer #2, why is it always you?!) You spend three hours perfecting a TikZ architecture diagram. You submit the paper. The review comes back: “Please swap layer 3 and layer 4.” In a drag-and-drop tool, this is annoying. In TikZ, it is a reconstruction project involving fifty lines of coordinate hard-coding. It isn’t just tedious; it’s fragile.

To render my documentation in a CI/CD pipeline, I shouldn’t have to install four gigabytes of TeX Live just to draw a few circles. And there is the friction of the language itself. Writing geometry macros in a specialized DSL is a jarring context switch. It forces you to leave the logic of your Python research and enter a world of backslashes and curly braces just to visualize a result.

Meet Tesserax

The shift happened when I moved my academic publishing to Quarto.

Quarto is essentially Jupyter on steroids. Since Jupyter is the standard for scientific computing, the solution was obvious. We didn’t need another GUI. We didn’t need a new domain-specific language. We needed a Python library that could live inside the notebook and speak fluent SVG.

I built Tesserax to close the gap. I started with the atoms, like Rects, Circles, and Paths. But the breakthrough was the Anchor System. I wanted a “nervous system” for diagrams, where objects know where they are relative to one another. No manual coordinates. No magic numbers.

Tesserax is what happens when you treat a drawing as a function of state.

In Tesserax, you don’t place a node at (100, 200). You define a Layout. You say, “I want a column of nodes, and for every node, I want an arrow pointing to the next one.”

# This isn't just a drawing. It's logic.
with Canvas() as c:
    nodes = [Circle(10) for _ in range(5)]
    layout = Column(nodes, gap=20)

    # If I add a node to the list above, the arrows update automatically.
    for n1, n2 in pairwise(nodes):
        Arrow(n1.anchor("bottom"), n2.anchor("top"))

This snippet doesn’t just render a figure. It renders any version of that figure. It captures the abstraction, not just the pixels.

The Rationale Behind Tesserax

But why, Alex, why building something like this? Don’t you have enough in your plate now?

Well, first, who are you and why do you know me so well? Second, it’s fun! But if that isn’t enough by itself, let’s analyze the landscape of modern academic drawing.

First, there is Matplotlib.

It is the industry standard for a reason. If I have a CSV of training data, Matplotlib is my first call. But have you ever tried to draw a linked list in it? You end up fighting the axes. You spend a dozen lines of code just hiding the ticks and borders to get a blank canvas.

Matplotlib is a library built for statistics that is occasionally forced to perform geometry. It feels like doing calligraphy with a highlighter. Tesserax respects the division of labor: use Altair or Matplotlib for your data, and use Tesserax for your concepts.

Then, there is Tikz. (Again!) We already discussed it, but there is more.

On one hand, there is a strange Stockholm Syndrome in academia. We accept that drawing a simple three-state automata requires learning a bizarre macro language on top of another macro language (yeah, I’m looking at you, LaTeX!). We treat TikZ’s loop syntax like a revelation, ignoring that any programming language is actually better at this, but I can also have, I don’t know, variables! And also, who the hell knows how to write Tikz!? (I know some of you nerds do, don’t give me that look. Shame on you.)

Tesserax bets that you don’t need a Domain Specific Language (DSL). You need objects. You need classes. You need type hints. If you want a grid of shapes? That is a nested list comprehension. If you want a recursive tree? That is a recursive function. You don’t need to “learn Tesserax.” You just need to know Python. By piggybacking on Python’s syntax, we get free IDE support, linting, and the ability to debug our drawings with the same tools we use to debug our kernels.

But also, even more important, the browser is the new print driver. TikZ was built for a world where the final output was a piece of paper. Tesserax is built for a world where the output is a responsive HTML page that can be printed.

By targeting SVG natively, we bypass the fragile conversion layers. We get semantic scaling. We get CSS styling. We stop fighting the renderer and start using the most optimized vector graphics engine in history: the modern web browser. And you can render SVG to PDF anytime. Going back, though, means you lose the semantics of what your drawing means.

And last but not least, Tesserax is lean. Like, zero dependencies. A couple hundred of pure, fully-typed, Python 3.12. Nothing more, nothing less.

I rest my case.

What’s Next

So Tesserax is my attempt to bring software engineering to scientific illustration. I’m releasing it today in a very crude, 0.2 something version, as I always do, to gather as much feedback as possible as soon as possible. From now on, all the diagrams in my papers, blog posts, and books will be built with this.

So, next step, I’m moving past the primitives phase now and into building high-level scientific abstractions. I want to generate automata that look like they were pulled from a classic textbook and data structures that reflect actual memory layouts. That’s what comes in the next few iterations. Moving from a world where we draw lines to a world where we code diagrams.

I’d love it if you’d give Tesserax a try. The documentation is still pretty thin but feel free to drop me a comment with any questions or suggestions.

This article is a draft of Chapter 1 of The Algorithm Codex. You can read the entire Part I (chapters 1 through 6) online for free (forever). If you want to support this initiative, feel free to grab the official PDF.

Searching is arguably the most important problem in Computer Science. In a very simplistic way, searching is at the core of critical applications like databases, and is the cornerstone of how the internet works.

However, beyond this simple, superficial view of searching as an end in itself, you can also view search as means for general-purpose problem solving. When you are, for example, playing chess, what your brain is doing is, in a very fundamental way, searching for the optimal move–the only that most likely leads to winning.

In this sense, you can view almost all of Computer Science problems as search problems. In fact, a large part of this book will be devoted to search, in one way or another.

In this first chapter, we will look at the most explicit form of search: where we are explicitly given a set or collection of items, and asked to find one specific item.

We will start with the simplest, and most expensive kind of search, and progress towards increasingly more refined algorithms that exploit characteristics of the input items to minimize the time required to find the desired item, or determine if it’s not there at all.

Linear Search

Let’s start by analyzing the simplest algorithm that does something non-trivial: linear search. Most of these algorithms work on the simplest data structure that we will see, the sequence.

A sequence (Sequence class) is an abstract data type that represents a collection of items with no inherent structure, other than each element has an index.

from typing import Sequence

Linear search is the most basic form of search. We have a sequence of elements, and we must determine whether one specific element is among them. Since we cannot assume anything at all from the sequence, our only option is to check them all.

def find[T](x:T, items: Sequence[T]) -> bool:
    for y in items:
        if x == y:
            return True

    return False

Our first test will be a sanity check for simple cases:

from codex.search.linear import find

def test_simple_list():
    assert find(1, [1,2,3]) is True
    assert find(2, [1,2,3]) is True
    assert find(3, [1,2,3]) is True
    assert find(4, [1,2,3]) is False

Analyzing Linear Search

Once we have an implementation, we must subject it to the three-step analysis established in our foundations.

Is it correct?

The property of correctness ensures that for any valid input, the algorithm produces the expected output. For linear search, we can verify this through three increasingly formal lenses:

• The Exhaustive Argument: Suppose an element x exists in the sequence. By definition, there is some index i such that items[i] == x. Since the algorithm performs an equality test over every single index in the sequence without exception, it is logically impossible to miss the item if it is there.

• The Inductive Argument: We can reason about the algorithm’s correctness across different input sizes. For a sequence of length 0, the loop never executes, and the algorithm correctly returns False. Assume the algorithm works for a sequence of length n. For a sequence of length n+1, the target x is either in the first n elements—where the inductive hypothesis ensures we find it—or it is the n+1-th element, which we check in the final iteration. If it is in neither, the algorithm correctly concludes it is not present.

• The Loop Invariant: We can define a formal invariant for the for loop: At the start of iteration i, the element x has not been found in the first i−1 elements of the sequence. By the time the loop completes at iteration n, if the function hasn’t returned True, we know with certainty that x is not in the first n elements, which constitutes the entire sequence.

How efficient is it?

We analyze linear search using the RAM model, assuming each comparison and iteration step has a unitary cost.

• Time Complexity: In the worst-case scenario (the item is at the very end or not present at all), we must perform n comparisons for a sequence of size n. This gives us a growth rate of O(n), or linear time.

• Space Complexity: The algorithm only requires a constant amount of extra memory to store the loop variable and the target, regardless of the input size, resulting in O(1) space complexity.

Is it optimal?

Intuitively, linear search must be optimal for unstructured data. If we know nothing about the order or distribution of the elements, we are mathematically forced to look at every single item at least once to be certain x is not there. Any algorithm that skipped an element could be “fooled” if that specific element happened to be the one we were looking for. Thus, for a generic sequence, O(n) is the best possible lower bound.

To prove this more formally, we employ an adversarial argument, a powerful technique in complexity theory where we imagine a game between our algorithm and a malicious adversary.

• The Adversary’s Strategy: Suppose an algorithm claims to find an element x (or prove its absence) by examining fewer than n elements—say, n−1 elements. The adversary waits for the algorithm to finish its n−1 checks.

• The “Trap”: Because there is one element the algorithm did not inspect, the adversary is free to define that specific element as x if the algorithm concludes “False,” or as something other than x if the algorithm concludes “True” without having seen it.

• The Conclusion: Since the adversary can always change the unexamined element to make the algorithm’s answer wrong, any correct algorithm must inspect every element in the worst case.

This proves that the lower bound for searching an unstructured sequence is Ω(n). Linear search, which operates in O(n), meets this lower bound exactly, making it a tightly optimal solution for the problem as defined. Unless we possess more information about the data’s structure—the central theme of the next chapter—we simply cannot do better.

Indexing and Counting

The find method is good to know if an element exists in a sequence, but it doesn’t tell us where. We can easily extend it to return an index. We thus define the index method, with the following condition: if index(x,l) == i then l[i] == x. That is, index returns the first index where we can find a given element x.

def index[T](x: T, items: Sequence[T]) -> int | None:
    for i,y in enumerate(items):
        if x == y:
            return i

    return None

When the item is not present in the sequence, we return None. We could raise an exception instead, but that would force a lot of defensive programming.

Let’s write some tests!

from codex.search.linear import index

def test_index():
    assert index(1, [1,2,3]) == 0
    assert index(2, [1,2,3]) == 1
    assert index(3, [1,2,3]) == 2
    assert index(4, [1,2,3]) is None

As a final step in the linear search paradigm, let’s consider the problem of finding not the first, but all occurrences of a given item. We’ll call this function count. It will return the number of occurrences of some item x in a sequence.

def count[T](x: T, items: Sequence[T]) -> int:
    c = 0

    for y in items:
        if x == y:
            c += 1

    return c

Let’s write some simple tests for this method.

from codex.search.linear import count

def test_index():
    assert count(1, [1,2,3]) == 1
    assert count(2, [1,2,2]) == 2
    assert count(4, [1,2,3]) == 0

Analysis

We won’t dwell too much in this section since the analysis is very similar to linear search–these are just specialized versions of it. Once more, we have O(n) algorithms (with O(1) memory cost) for a problem that is provable Ω(n). Thus, given our assumptions (that there is no intrinsic structure to the elements order), we have optimal algorithms.

Min and Max

Let’s now move to a slightly different problem. Instead of finding one specific element, we want to find the element that ranks minimum or maximum. Consider a sequence of numbers in an arbitrary order. We define the minimum (maximum) element as the element x such as x <= y (x >= y) for all y in the sequence.

Now, instead of numbers, consider some arbitrary total ordering function f, such that f(x,y) <= 0 if and only if x <= y. This allows us to extend the notion of minimum and maximum to arbitrary data types.

Let’s formalize this notion as a Python type alias. We will define an Ordering as a function that has this signature:

from typing import Callable

type Ordering[T] = Callable[[T,T], int]

Now, to make things simple for the simplest cases, let’s define a default ordering function that just delegates to the items own <= implementation. This way we don’t have to reinvent the wheel with numbers, strings, and all other natively comparable items.

def default_order(x, y):
    if x < y:
        return -1
    elif x == y:
        return 0
    else:
        return 1

Let’s write the minimum method using this convention. Since we have no knowledge of the structure of the sequence other than it supports partial ordering, we have to test all possible items, like before. But now, instead of returning as soon as we find the correct item, we simply store the minimum item we’ve seen so far, and return at the end of the for loop. This guarantees we have seen all the items, and thus the minimum among them must be the one we have marked.

from codex.types import Ordering, default_order

def minimum[T](items: Sequence[T], f: Ordering[T] = default_order) -> T:
    m = items[0]

    for x in items:
        if f(x,m) <= 0:
            m = x

    return m

The minimum method can fail only if the items sequence is empty. In the same manner, we can implement maximum. But instead of coding another method with the same functionality, which is not very DRY, we can leverage the fact that we are passing an ordering function that we can manipulate.

Consider an arbitrary ordering function f such f(x,y) <= 0. This means by definition that x <= y. Now we want to define another function g such that g(y,x) <= 0, that is, it inverts the result of f. We can do this very simply by swapping the inputs in f.

def maximum[T](items: Sequence[T], f: Ordering[T] = default_order) -> T:
    return minimum(items, lambda x,y: f(y,x))

We can easily code a couple of test methods for this new functionality.

from codex.search.linear import minimum, maximum

def test_minmax():
    items = [4,2,6,5,7,1,0]

    assert minimum(items) == 0
    assert maximum(items) == 7

The correctness, cost, and optimality analysis is very similar in these cases as well.

Conclusion

Linear search is a powerful paradigm precisely because it is universal. Whether we are checking for the existence of an item, finding its index, or identifying the minimum or maximum element in a collection, the exhaustive approach provides absolute certainty. No matter the nature of the data, if we test every single element and skim through every possibility, the problem will be solved.

The primary drawback of this certainty is the cost: some search spaces are simply too vast to be traversed one item at a time. To achieve better performance, we must move beyond the assumption of an unstructured sequence. We need to know more about the search space and impose some level of structure.

In our next chapter, we will explore the most straightforward structure we can impose: order. We will see how knowing the relative position of items allows us to implement what is arguably the most efficient and beautiful algorithm ever designed.

But that’s a story for another Tuesday.

Remember you can read the full draft online (currently Part 1) or get a beautifully typed PDF if you want to support the project.

And it works. Mostly.

Until it doesn’t. Until the model decides to wrap the JSON in markdown backticks. Or adds a “Here is your data” preamble. Or hallucinates a field that doesn’t exist in your Pydantic model. Or, worse, it just makes up a fact that sounds plausible but isn’t there.

We are entering the era of agentic AI, where models talk to machines, not just humans. And machines speak in protocols. If we want AI that is reliable, robust, and affordable, we cannot rely on massive 100B+ parameter models for every single function call. We need Small Language Models (SLMs) that can speak general-purpose structured data fluently.

That is why, together with my colleagues at the University of Havana and the University of Alicante, we are launching GenSIE: General-purpose Schema-guided Information Extraction at IberLEF 2026.

The Challenge: Zero-Shot Structure

Most information extraction tasks are “fixed.” You train a model to find PERSON, ORG, and DATE. You show it thousands of examples. It learns. GenSIE is different, it is a Zero-Shot Schema task.

At inference time, your system receives a text and a schema it has never seen before. It might be a legal verdict today, a recipe tomorrow, and a chemical compound specification next week. Your system must read the schema definition (provided as a JSON Schema), understand the semantic constraints (like “extract the verdict, but map it to POSITIVE or NEGATIVE“), and generate valid, grounded JSON.

There is a hallucination trap built-in also—sometimes we’ll squeeze a field that can be answered by the model’s original training data, but is not explicitly answered in the input text, so your system has to output null for it.

Oh, and there is a catch: No Fine-Tuning allowed.

Why This Matters (and Why It’s Hard)

We explicitly designed this task to close an existing innovation gap. Huge models like GPT-5 or Gemini 3 Pro can often brute-force this problem through sheer scale. But running a 1TB model just to parse a date is sustainable neither economically nor ecologically.

GenSIE challenges you to use Small, Open-Weights Models (like Llama 3 8B, Qwen 14B, or Salamandra 2B). To make these smaller models perform at a high level, you can’t just throw compute at the problem. You need Inference-Time Engineering:

• Constrained Decoding: Forcing the token sampling to obey a grammar.

• Chain-of-Thought: Letting the model reason about the schema before outputting the JSON.

• Self-Correction: Catching validation errors and asking the model to fix them in a loop.

This is the real challenge. You cannot just throw more compute at the problem and hope it will get solved by an expensive API call. You’ll have to work around these hard technical constraints to achieve something that works as good a Gemini or ChatGPT but runs on commodity hardware.

Join Us

We are building a dataset of 1,000 human-curated examples—rigorously checked to punish hallucinations and reward precision.

The timeline is tight, but the barrier to entry is low. On March 1st we’ll release a first batch of annotated examples and a startup kit with Docker templates and a baseline implementation. Then you have until May 8th to submit a working system. All participants (either solo or in teams) have the option to submit a system paper that will be peer-reviewed and indexed in Scopus.

If you are interested in the future of reliable AI agents, structured generation, or just want to test your engineering skills against a hard benchmark, I invite you to participate. This is particularly interesting for master or PhD students in search of interesting, open research problems.

Check out the official site, and leave me a comment if you want to know more.

Official GenSIE Website

This draft encompasses 19 distinct algorithms across six chapters, focusing on the core logic and intuitions that make them work:

• Basic Search: Establishing the universal but expensive baseline of searching through unstructured sequences.

• Efficient Search: Introducing the “magical” scaling of binary search and bisection, extending these concepts to abstract decision spaces through predicate search.

• Basic Sorting: Analyzing the “geometry of inversions” to understand why simple approaches like Selection and Insertion sort are naturally bounded by a quadratic ceiling.

• Efficient Sorting: Breaking the quadratic barrier with the recursive divide-and-conquer strategies of Merge Sort and Quick Sort.

• Rankings and Selection: Implementing strategies for order statistics, including the randomized Quick Select and the deterministic “Median of Medians”.

• Linear Time Sorting: Bypassing the theoretical limits of comparison-based algorithms by exploiting domain-specific constraints with Counting and Radix sort.

While the core content is ready, the Codex remains a work in progress. I plan to further extend the explanations with more intuitive descriptions and perform deeper analysis without getting into overly formal proofs. I am also considering the addition of a few more clever algorithms to round out this section before moving on to Part II on foundational data structures (lists, queues, stacks, and dictionaries).

Over the next two weeks, I will be adapting several chapters into articles for The Computist Journal. These posts will focus specifically on the beauty and underlying intuitions of binary search and efficient sorting, rather than the nitty-gritty implementation details.

If you find this resource valuable, please consider supporting the ongoing development of the remaining seven parts by getting the PDF on Gumroad. Your support directly enables the continuation of this project.

Support The Algorithm Codex

The following is the first draft of Chapter 1 of How to Train your Chatbot, a developer-centric book I’m writing in public. Subscribe to get all chapters in your inbox, as they come out, for free.

Subscribe now

In this first chapter we will build a bare-bones conversational application–a chatbot–that is capable of maintaining a coherent conversation with a single user. We will learn how to connect with an LLM provider, pass messages, and stream the responses back.

In this chapter we won’t use any additional libraries beyond the Python OpenAI wrapper to communicate with an LLM backend. This is on purpose, so we understand the whole lifecycle of a typical conversation.

Then, in the next chapter, we will redo the core logic using ARGO to simplify the chat management and introduce some modularization, and we will add a database to store conversations and make our interactions persistent.

The whole source for this chapter (and this entire book) can be found in this Github repository. This specific chapter is in the basic.py file.

Setting up the environment

The first step is to setup a development environment. At the moment, the community preferred way of doing this with Python is using a package and virtual environment manager, and by far the best in the world is uv. So let’s begin by installing thatl, and once ready, just run:

mkdir chatbot # or whichever folder name you prefer
cd chatbot
uv init .

This will create a pyproject.toml file in the chatbot folder. Now let’s add streamlit and openai.

uv add streamlit openai

After a few seconds downloading the necessary packages, you will be ready to start coding.

Get the source code

The complete source code for this book is available in Github with an MIT license. Feel free to fork it and use it as you see fit.

The basic chatbot

Let’s start outlining our first chatbot. We will use Streamlit’s builtin functionality to create a pretty decent chatbot UI in less than 10 lines of code. Here is the boilerplate code.

import streamlit as st

# import and setup OpenAI
<<setup_openai>>

# regenerate the conversation history
<<render_history>>

msg = st.chat_input()

if not msg:
    st.stop()

with st.chat_message(”user”):
    st.write(msg)

# code to actually call the LLM
<<invoke_llm>>

with st.chat_message(”assistant”):
    response = st.write(reply(msg))

# save the llm response
<<save_llm_response>>

About Literate Programming

You may have noticed the code above uses a somewhat weird notation, like <<setup_openai>>, which is not valid Python. This is because we are using a tool called illiterate to generate automatically the source code from the book content. This notation is how we reference snippets of code that will be defined later on.

This is a paradigm called Literate Programming that emphasizes narrative documentatiopn as the primary source, and the actual source is derived automatically, so that your documentation (this book) and your code are always synchronized

Don’t worry too much about it, just know that all these snippets will be explained in the remainder of this chapter. You’ll get the hang of it.

This completes the basic layout of a typical chatbot app. We still haven’t specified how to actually call the LLM provider, and how to manage the conversation history. We will do that in the remaining of this chapter.

Setting up an LLM provider

For all practical purposes, when you code a chatbot you consider the LLM as a black-box component that is, almost always, encapsulated behind a REST API. This lets you focus on building the app and forget about the extremely complex problem of serving, scaling, and monitoring an LLM in a production environment.

This is pretty much the same as when you use a production database, like MySQL, Postgre, or MongoDB, you almost never directly run the database server daemon. Instead, you almost certainly provision a managed server from Amazon, Azure, Google, or any other of the myriad cloud providers. In the same way, most of the time you won’t run an LLM locally, but instead use a cloud provider which has far better infrastructure.

By far, the most common API design used by all cloud LLM providers is the OpenAI API, which has become a de-facto standard. So, even if you don’t use OpenAI’s models directly (like GPT-5), you will almost certainly use the opena Python package to communicate with your LLM cloud provider, whoever they are.

In this book I will recommend OpenRouter, because they provide access to a huge range of models, and they deal with automatically routing to the optimal cloud provider. But you are free to choose whatever LLM provider you prefer, and as long as they give you an OpenAI-compatible API (and they all do), the rest of this book will work exactly the same for you.

Whatever you choose, you will need three things from your LLM provider:

• A base URL (e.g., https://openrouter.ai/api/v1)

• An API key (e.g., sk-12345678...)

• A model identifier (e.g., meta-llama/llama-4-maverick:free)

Of these three, the API Key is the most important to keep safe (and secret) because it’s what the LLM provider will use to identify you (and thus charge you) for using their service. If this API Key ends up in a Github repository or somewhere public, someone might use it to impersonate you and thus deplete your credits or put you in a significant debt with your LLM provider.

Once you have identified your LLM provider, you need to provide streamlit with the credentials and metadata indicated above. The best way to do this for a streamlit app is to use its native secrets management. You need to create a .streamlit folder, and place a secrets.toml file inside. There you can add the entries just as if they where environment variables.

# .streamlit/secrets.toml
api_key=”sk-12345678”
base_url=”https://openrouter.ai/api/v1”
model=”meta-llama/llama-4-maverick:free”

Needless to say, this secrets.toml file should be the first line in your .gitignore!

For the purpose of development and testing, you can use one of the many free models OpenRouter hosts, which give you enough daily uses for development purposes. Read more on the OpenRouter documentation. As a perhaps obvious disclaimer, I’m not associated with OpenRouter nor any part of this book is supported by them. I just think they provide a wonderful service for the AI developer community.

Once you’ve gotten your API key, you can use it to create an OpenAI client to interact with the LLM.

from openai import OpenAI

client = OpenAI(
    base_url=st.secrets.base_url,
    api_key=st.secrets.api_key,
)

And we’re ready to start sending some messages.

Calling the LLM

OpenAI’s client makes it very easy to invoke an LLM. We just need to pass in a list of messages and stream the result back to our Streamlit app. But before, we need to understand one key thing about LLM providers, and is the fact that they are stateless. This means you always have to pass the whole conversation to the API, because neither the actual model nor the server itself “remember” the conversation.

So, we will need to store the conversation in our application state. I’ll show you how to do this in just a second, but let’s assume we have it and move on to actually talking to the LLM.

In our app, we need to include the following method, which will stream the response from the LLM to the user.

<<store_conversation>>

def reply(msg: str):
    # retrieve the conversation list
    conversation = st.session_state.conversation

    for chunk in client.chat.completions.create(
        model=st.secrets.model,
        messages=conversation,
        stream=True,
    ):
        if msg := chunk.choices[0].delta.content:
            yield msg

That’s it. We just invoke client.chat.completions.create with the model name and conversation (a list of messages we will see right away) and stream the results back in the form of a Python generator. The st.write method in our main app is smart enough to produce a pretty typewriter animation as we receive the response one chunk at a time.

The conversation is actually stored in Streamlit’s builtin session storage, which is a dictionary-like object unique to each user session. This means that as long as we stay in the same browser tab, the conversation persists. Once we open another tab or hit F5, the session storage is cleaned up and we have a new conversation. Kind of brute, but for now it will do.

And this is the missing snippet to actually keep track of the conversation. We need to store the user message just after we get from the chat input widget:

if “conversation” not in st.session_state:
    st.session_state.conversation = []

st.session_state.conversation.append(dict(role=”user”, content=msg))

And we need to store the assistant reply message in the main loop after streaming it. Fortunately, the st.write method is smart enough so that it not only prints the message as it is streamed, but also returns the full concatenated message once the stream is closed.

st.session_state.conversation.append(
    dict(role=”assistant”, content=response)
)

As you’ve seen, we’re storing the messages in the format that the OpenAI API expects. This is a list of dictionaries, where each dictionary contains a role and a content key. The role (for now) can be either user or assistant, and it’s important we respect it because the models are trained to behave as if they are replying from the “assistant” perspective.

Rebuilding the conversation history

The final step to make our app a fully-fledged chatbot is to actually render the whole conversation in the UI. This is necessary because Streamlit works with an immediate execution paradigm, which effectively means every interaction cleans the whole screen and redraws the entire UI. Thus, every time the user enters a message, the UI restarts and we lose the previously rendered interaction.

Fortunately, as we have the conversation stored in the session state, we can simply iterate over it and render each message.

for msg in st.session_state.get(’conversation’, []):
    with st.chat_message(msg[’role’]):
        st.write(msg[’content’])

We just need a bit of care the first time we run the app because the conversation key won’t exist, that’s why we use get instead of a direct indexer.

Closing up

Phew! There you go, in around 50 lines of code (including comments and whitespace) we have a fully working chatbot. It’s very crude for now, all it does is send some messages to an LLM provider and stream the response back, but this is the foundation we can build upon to create all sorts of cool stuff.

In the next chapter we will rebuild this application from scratch but using an LLM framework that will give us much more flexibility later on.

Subscribe now

TL;DR: In this upcoming series, we'll build an autonomous LLM-based agent from scratch, focusing on the fundamentals. We'll go from zero to fully autonomous deep research, one feature at a time, staying as close to the metal as possible. Subscribe to receive all posts in your inbox for free.

Subscribe now

Have you looked at the latest AI breakthroughs—agents that can plan, code, and research—and thought, "That's cool and all but… how the hell do one actually build something like that?"

If you're just getting started with Python development, or even if you’re a seasoned expert, you've probably felt this gap too. Maybe you've played with the demos, called an API or two, and seen just enough of the magic to get excited.

But moving from just prompting an LLM to building intelligent, autonomous agents is a different beast entirely. Things start to break pretty soon as you stack up more and more complexity. And it seems every tutorial out there is oblivious to this. Anyone can show you how to code a simple chatbot maybe with some RAG, but very few resources take you from that humble beginnings to something that actually looks like a modern multi-agent system that works autonomously.

This series is my answer to that problem.

Over the next 10 or so posts—the next couple of months—we are going to build a comprehensive, autonomous AI agent. And we're going to do it incrementally.

We'll start with the simplest possible application: the basic chatbot loop that stores conversation history. Why? Well, because even if everyone has already seen this, we need proper foundations to build on top. We need to see the full flow—how messages are stored, how a system prompt works, how to interact with the LLM, and what's really happening under the hood.

But from there we'll level up pretty fast, adding new capabilities piece by piece until we have a personal agent capable of doing deep research and generate long, coherent reports all on its own.

Tools of the Trade

Now, you might be thinking, why build from scratch and not just use LangChain, or LlamaIndex, or some other well known framework?

Here's my thesis. When you start with those massive, professional frameworks, you learn more about the framework than you do about the fundamentals. Those tools are powerful, but they are also black boxes. They hide the logic and complexity behind layers of abstraction. You end up learning their way of doing things, their design patterns, and their API. And frameworks change, but fundamentals remain.

I believe it's far more valuable to learn how to do things as close to the metal as possible. Our goal is to write the least amount of boilerplate code possible, but—and this is the key—without hiding the any of core logic. We will build this entire thing ourselves, understanding every single piece of the puzzle.

We'll use a tech stack that gets out of our way. Only three tools:

For the UI we’ll use Streamlit. For those who don’t know it, Streamlit is a radically simple application framework that turns any Python script into a fully fledged web app. The key here is what it doesn't make you do: you write zero boilerplate, zero layout, zero presentation, and zero state management code. You just write core logic, and a good enough web UI appears.

For the actual chatbot we'll use the ARGO framework. I like to call it FastAPI for AI agents because it has that same lightweight, decorator-based feel. It is the simplest, most Pythonic agent framework you’ve seen, and I promise you’ll fall in love with it. Despite being super simple, it forces you to build the logic using a very clean and lightweight skills-based pattern for modularizing our agent's intelligence.

And for data we’ll BeaverDB. This is a lightweight wrapper on top of SQLite that gives you everything you could ever want from a modern database. But it is not a modern database server. It's just a single, embedded binary file on your disk. There's no Docker, no authentication, no connection strings, no schemas, no boilerplate. Yet, on top of this simplicity, BeaverDB gives us a very Pythonic, very comfortable API for a document database with vector and full text search, and cool features like persistent dictionaries, lists, priority queues, and even pub/sub. It makes building something like a RAG pipeline extremely simple without any complex setup.

That's it. With just these three basic libraries, we will build a fully autonomous agent.

The Journey Ahead

Here's the roadmap I've thought so far. We'll add a new level of intelligence in each post.

• Level 0: The Conversationalist. The foundation. A simple Streamlit UI with a stateful chat loop that understands conversation history and system prompts.

• Level 1: The Assistant. We'll give our agent long-term memory. We'll build a full Retrieval-Augmented Generation (RAG) pipeline from scratch using BeaverDB so it can answer questions based on a private knowledge base.

• Level 2: The Researcher. We'll break our agent out of its box and give it a tool to search the web, allowing it to access up-to-the-minute information.

• Level 3: The Analyst. This is where it gets really fun. We'll give the agent the ability to write and execute its own Python code in a safe sandbox to solve problems, analyze data, and even debug its own mistakes.

• Level 4: The Editor. We'll upgrade our UI from a simple chat to a persistent, shared canvas, where you and the agent can work side-by-side to co-write documents and refine plans.

• Level 5: The Scientist. The finale. We'll integrate all previous capabilities, giving the agent a master prompt that allows it to take a high-level goal, create a multi-step plan, and execute it independently from start to finish.

So here is my promise. It may take us more than 5 posts, but we are going to learn how to build a chatbot by building a chatbot, step by step. No unnecessary theory, just working code and clear intuitions.

I'll be providing a public GitHub repository with all the code, and each post will be a direct, straightforward Python script that you can type in half an hour.

When you're done with this series, it won't matter if you want to keep using ARGO and BeaverDB—which I hope you will—or move on to more “professional” tools. You'll be ready anyway, because these tools are so thin, what you'll have learned isn't how to use a specific library. You will have learned how the logic works underneath.

You'll understand how to orchestrate the different components involved in a typical chatbot, how to modularize the agent's brain, and more generally, how to think about building capable, intelligent, LLM-based applications. That's the real takeaway.

In the next post, we'll jump straight into Level 0: The Conversationalist. So hit that subscribe button and you'll get all posts in your inbox, 100% free.

Subscribe now

Ready to build?

I really love to code. That much I’m sure you can tell. So I have this very common problem, that I’m sure many of you have. A gazillion ideas in my head wanting to burst out, and very little time to try them all. To try and get around this, I like to prototype really fast and dirty implementations of anything that makes me curious, just to see if it leads somewhere. (This is why I have hundreds of unfinished projects in my Github.)

So, where was I? Yeah, this is one of the reasons I’ve made Python, and specifically streamlit, a key part of my toolkit. It lets me build the very simplest semblance of an app extremely fast, without considering anything remotely unnecessary (for a first prototype) like authentication and user roles, or worrying about the user interface.

Now, here is the thing. Recently, I’ve been building a lot of AI stuff. Chatbots galore for all sorts of tasks from general question answering to specific things like storytelling, evolutionary computation, automated coding, you name it. And I keep finding a specific pain point that grinds me to a halt in the most exciting part of prototyping: the database.

Very soon, my simple AI prototype needs a vector database for RAG or a key-value store for simple configurations, or a message queue for background tasks and a persistent list to store conversation history. And this is before anything remotely close to a production-ready feature is in the horizon. This is just the second thing you’ll need right after streaming the first few tokens from OpenAI. It’s unescapable for anything but the simplest toys.

So, before I know it, I’m wrestling with two or three containers—or worse, juggling credentials for three different cloud services—and writing boilerplate code just to glue it all together. I’ve become an accidental, and very grumpy, DevOps engineer. My worst nightmare!

What I want is something in the spirit of streamlit but for managing data. A minimalistic, no-bullshit database that just supports the basic modalities we all need in modern applications, like, dunno, JSON storage, maybe? And vector search? Yeah, that, but also combined with full-text and fuzzy, persistent lists and queues… hell, even a decent pub-sub system if we’re asking! Is it too much to ask for someone to make SQLite but for modern data!

Well… I guess if you want something done, you might as well do it yourself.

So this is the story of how I built BeaverDB—a Pythonic and multi-modal interface on top of SQLite that just works out of the box for rapid prototyping. And it scales to medium sized projects just fine (SQLite is damn fast!). BeaverDB my attempt to build the tool I wish I had—a library that provides the high-level data structures modern AI applications need, without sacrificing the radical simplicity of a single .db file.

Introducing Beaver

The guiding principle behind Beaver’s API is a minimal surface area with a fluent interface. You only ever need to use two classes. Everything else flows naturally from the main database instance, returning dedicated wrapper objects with a rich, Pythonic interface.

One key idea for this design is that it should just work. Zero configuration, just sensible out of the box decisions. So, no schema, everything indexed by default, no need to declare tables or entities or anything before hand, collections just get created when first used, you know, that kind of thing. It should be as easy as instantiating a class and calling two methods.

Let’s take a quick tour on what you can today with it.

Key-Value & Caching

Need to store configuration, user profiles, or cache expensive API calls? The namespaced dictionary is your go-to. It behaves just like a Python dict but is backed by the database, with optional TTL support.

# Use a dictionary for caching API calls for 1 hour
api_cache = db.dict("api_cache")
api_cache.set("weather", {"temp": "15C"}, ttl_seconds=3600)
print(f"Cached weather: {api_cache.get('weather')}")

Persistent Lists

This is the most straightforward way to manage ordered sequences. For a chatbot, it’s the perfect way to maintain the turn-by-turn history of a conversation. It works like a Redis list, with all bells and whistles, implementing a full Pythonic list interface, but backed in the DB. It supports appending and removing from the head and tail, as well as inserting or removing anywhere in between, blazingly fast, because all operations are indexed.

# Manage a conversation with a user
chat_history = db.list("conversation_with_user_123")
chat_history.push({"role": "user", "content": "Hello, Beaver!"})
chat_history.push({"role": "assistant", "content": "Hello! How can I help?"})
print(f"Conversation length: {len(chat_history)}")

Priority Queues

A priority queue is the essential tool for orchestrating an autonomous agent. It ensures the agent always works on the most critical task first, regardless of when it was added. The API is extremely simplified on purpose. For anything more complicated, use a full-featured list.

# An AI agent's task list
tasks = db.queue("agent_tasks")
tasks.put({"action": "summarize_news"}, priority=10)
tasks.put({"action": "respond_to_user"}, priority=1) # Higher priority

# Agent always gets the most important task first
next_task = tasks.get() # -> Returns the "respond_to_user" task

Real-time Pub/Sub

Need to build a decoupled, event-driven system? The pub/sub channel allows different parts of your application—or even different processes—to communicate in real-time. Beautifully designed with an extremely simple fluent API, but extremely performant, thread-safe, even works across different processes. Plus, it comes with an optional async interface if you’re feeling fancy.

# In one process, a monitor publishes an event
system_events = db.channel("system_events")
system_events.publish({"event": "user_login", "user": "alice"})

# In another, a logger subscribes and receives the message
with db.channel("system_events").subscribe() as listener:
    for message in listener.listen(timeout=1):
        print(f"Event received: {message}")

Collections & Hybrid Search

This is the core component for any Retrieval-Augmented Generation task. It’s a multi-modal collection of structured documents that understands vectors, and text, allowing you to combine search strategies for the best results. It also performs fuzzy search on demand with a very clever indexing strategy that I’ll tell you all about in the next section.

from beaver import BeaverDB, Document
from beaver.collections import rerank

docs = db.collection("articles")
doc = Document(embedding=[...], content="Python is fast.")
docs.index(doc, fuzzy=True)

# Combine vector and full-text/fuzzy search for better results
vector_results = docs.search(vector=[0.15, 0.85, 0.15])
text_results = docs.match(query="pthon", fuzziness=1)
best_context = rerank(vector_results, text_results)

And there’s a lot more. You can connect documents with relations and build a knowledge graph that you can later query to find similar documents or implement graph-based recommender system.

All in one freaking database file. No docker. No servers. No headache.

A Peek Under the Hood

Beaver is built on a series of pragmatic design decisions intended to leverage SQLite’s native capabilities to the fullest, avoiding slow application-layer logic wherever possible.

For one, it never creates new tables when storing stuff. Everything is stored and indexed in cleverly designed global tables that are created at startup time (only the very first time the DB file is created). This also means you get virtually infinite lists, dicts, queues, collections, etc., because these aren’t different tables (which would be a pain in the arsenal to maintain). And… (roll drums)… no migrations!

I want to highlight two specific features to tell you a bit about the underlying implementation details, so you can see the lengths it goes to try and be efficient out of the box.

The Pub/Sub System

The pub/sub system is the greatest example of efficiency by design. It’s built on a single, append-only log table with an index for the channel name.

For each channel, a single background thread polls this table for new entries and fans them out to any number of in-memory queues, one for each subscriber. The key insight here is that because the database is only ever touched by one polling thread per channel, adding a second, third, or hundredth subscriber adds zero additional load to the database. From the database’s perspective, new listeners are basically free.

Even better, this polling is only activated when there is at least one listener, and stops immediately after the last listener disconnects. This means we only ever use the minimum resources necessary.

Hybrid Text Search: The Two-Stage Filter

The other feature I think is kinda beautiful is the fuzzy search. Calculating the Levenshtein distance between two strings is computationally expensive, and there is no way to build an index beforehand without a combinatorial explosion in storage size. But running it across every document in a collection would be unusable for anything beyond a few thousand entries.

Beaver solves this with a two-stage process. First, it uses a pre-computed trigram index in SQLite to instantly find a very small set of candidate documents that share a high percentage of 3-character “chunks” with the query. This is a very fast SQL query that already gives us a very good approximation to the response. Then, we run the expensive Levenshtein algorithm only on this small, pre-filtered set of candidates in memory.

The Vector Store Dilemma

Vector storage is my biggest concern at the moment. The current implementation is, I think, pretty good for a typical use case of infrequent indexing and fast retrieval. But it can be much improved.

Right now, Beaver uses an in-memory k-d tree, which provides excellent search speed once the index is loaded into RAM. However, the index is ephemeral—it lives and dies with the application process. This creates a significant bottleneck: every time your application starts, the entire index must be rebuilt from scratch by reading all vectors from the database. Furthermore, indexing a new document requires a full, blocking rebuild of the entire tree.

As long as you index documents in a background process, infrequently—which is what most RAG-based applications do—this works just fine. But I’m not satisfied with this implementation, so here is my plan for its update.

The roadmap goes through integrating a state-of-the-art ANN library like faiss. This will enable a persistent, on-disk index that can be loaded instantly. But more importantly, we need to support incremental additions, which means newly added documents don’t rebuild the entire index. The key to achieve this is to have a persistent, large index, and a small, in-memory, temporal index of new additions that gets added to the persistent index from time to time. Keep these two in sync is far from trivial, but I already have a somewhat detailed plan.

Conclusion

Beaver is the result of a couple of weekends of focused frustration, and it’s already the backbone of my own AI prototypes. Even if it never reaches any level of maturity, I’m extremely satisfied with it because it already works for my use cases, and I’ve learned so much building it. Damn, who knew building databases could be so fun!

Now, what’s in it for you? Well, Beaver is not meant to replace your production PostgreSQL cluster. That’s unthinkable. But it might be the “good enough” database that lets you go from an idea to a working prototype in minutes, not hours. So, stop being an accidental DevOps engineer and go build something cool.

You can get started with a simple pip install beaver-db. Check out the GitHub repository for a lot of examples. And leave me any questions or comments either here or in the repository issues.

Have fun!

Literate Programming (LP) is a decades-old, obscure programming philosophy that emphasizes human understanding over mere machine execution by intertwining code and prose. It is the precursor to Jupyter Notebooks, nbdev, Quarto, and many other documentation-friendly coding paradigms. That is, in the same sense as LISP is the precursor to all functional languages, but none lives up to the expressiveness of LISP.

For a long time, Literate Programming has been mostly a niche paradigm, embraced only by the nerdiest of the nerdiest among us. However, as we incorporate more and more AI into our development, I believe LP is going to make a comeback. I argue that despite its current niche status and challenges, LP, especially when supercharged with specific tooling and advanced AI, is the optimal paradigm for coding with AI.

In this article, we'll first define Literate Programming and explore its core components, distinguishing it from similar approaches like Jupyter notebooks. Next, we'll tackle the historical reasons why LP hasn't become mainstream. Then, the core of the argument: why Literate Programming is uniquely suited for AI-assisted coding. Finally, we'll look to the future, discussing how targeted AI development and advanced tooling can further enhance LP, concluding with a concrete example of my own work in this space.

What is Literate Programming?

Let’s start from scratch. What exactly is Literate Programming? At its heart, LP fundamentally shifts our perspective on what a program is. Instead of viewing code as a sequence of instructions for a machine, LP frames a program as a continuous, flowing narrative designed for human comprehension. Code snippets embed directly within this prose, illustrating logic and design choices as part of a cohesive story. Think of it this way: the program is the documentation, and, crucially, the documentation is the program.

If you want to see it for yourself, here is a massive collection of LP programs in several programming languages.

This isn't just about adding comments; it's a profound reordering of priorities. Clarity and explanation become the primary goals, with executable code as a byproduct of that clear narrative.

To truly understand LP, we need to look at its core components. It all begins with the literate source document, a continuous flow of prose with interspersed code snippets. So far, this isn't any different to a typical blog post with explanations and code. But here comes the key twist.

Within the code snippets in a literate source, you can define macros, named placeholders that reference other blocks of code. These macros enable recursive expansion. They can reference other macros, allowing a deeply hierarchical and top-down explanation of your program. You can start with a high-level concept, then progressively drill down into details, always maintaining a clear narrative flow.

Once you craft this human-centric narrative, two key processes come into play: tangling and weaving. Tangling extracts the executable code from your literate source file, pulling only the parts necessary for the machine to run. Conversely, weaving generates human-readable documentation (like a PDF or HTML file) from the literate source, resulting in a beautifully formatted explanation complete with code examples, all derived directly from the source file.

If you want to understand LP better (or you are just curious about it), there is a community website that

Isn't This Just …?

You might think, "This sounds a bit like Jupyter notebooks, Quarto documents, or even what Pandoc does." And you'd be right to some extent. Tools like Jupyter notebooks, Quarto, and Pandoc certainly share some principles with Literate Programming, primarily intertwining code and explanatory text. They revolutionized data science and technical communication by allowing code, output, and narrative to coexist in one document.

However, here is the critical distinction: none of these have fully featured recursive macro expansion. This prevents them from achieving the deep disentangling power central to classical Literate Programming. While they let you intersperse code and text, they do not provide the same hierarchical abstraction and narrative control that LP's macro system offers. This means they do not quite realize the full vision of the program as documentation in the same profound way.

Crucially, both Jupyter and Quarto (which is ultimately based on Jupyter) require code cells to be executable. This means they need to be complete, correct code. All necessary references must resolve beforehand. Any methods, variables, or symbols used in any cell must exist by the time that cell executes.

This goes head-to-head with LP's core idea, which forgoes any structural requirements for executing the code in favor of using the best structure to understand the code. So, in LP, you can leave half of a method undefined because its details are not important at that moment.

Why Literate Programming Isn't Mainstream

Given its elegant philosophy, it's fair to ask: why isn't Literate Programming the default? Originated by the legendary Donald Knuth, LP largely remained an academic pursuit or a niche interest. Several reasons explain its limited adoption.

Perhaps the most significant hurdle has been tooling. Providing robust linting and type checking on disentangled source code proves incredibly difficult. Imagine trying to analyze code scattered across a narrative, with pieces defined by macros that might expand elsewhere. The current workaround involves linting the tangled files (the extracted, executable code) and then trying to project any errors back to the original literate source. This process is complex and notoriously hard to make reliable across diverse programming languages. There is simply no robust tooling support for this yet.

Another more subjective, but still yet very real limitation concerns collaboration at scale. When multiple developers work on different architectural components of a large project, LP's narrative-first approach can complicate simultaneous development. It requires a different way of thinking about how components interact and are documented, which can hinder its adoption in fast-paced, multi-developer environments based on pull requests and frequent code reviews.

Finally, LP demands a significant mental model shift from developers. We are deeply ingrained in the idea of writing sequential code files. Prioritizing explanation and narrative structure over the immediate gratification of seeing runnable code requires a different mindset—one that many developers, under project pressures, find hard to adopt.

LP is the Best Paradigm for AI-Assisted Coding

Despite these historical challenges, I firmly believe that Literate Programming is uniquely suited for working with AI. In fact, it might just be the best paradigm for AI-assisted coding.

The most compelling argument is that, when applied correctly, a Literate Programming document inherently contains all the necessary explanations and context for an LLM to understand it. By definition, no code exists that isn't fully explained within the literate document itself. This completely eliminates the need for separate, additional, or laboriously crafted prompts for your AI assistant. The AI can simply read your literate program, understanding the why alongside the what.

Furthermore, AI fundamentally differs from traditional development tools. Compilers are notoriously rigid, demanding perfect syntax and strict adherence to language rules. This rigidity historically made working with disentangled LP source code difficult. However, AI is far less hindered by these traditional tooling issues. It remarkably adapts to interpreting "pseudo-code," understanding natural language explanations, and even working with partially formed ideas. This aligns perfectly with LP's nature, where the human-readable explanation often precedes the perfectly formed executable code.

AI's capabilities extend beyond just spitting out code. Yes, AI can effectively generate code snippets that fit seamlessly within your literate explanation. But here’s the crucial part: AI can also help you explain and refine the literate (textual) part of the program itself. It leverages its proficiency in understanding both natural language and code to suggest better explanations, clearer analogies, and more precise prose, elevating the quality of your documentation as much as your code.

Given these advantages, LP, especially reinforced by AI, is perfect for specific scenarios. Consider short, learning-based projects like tutorials, coding books, or personal learning journeys. For single authors, AI can dramatically amplify both the learning process and the creation of highly understandable educational content.

It's also excellent for exploratory coding. When prototyping or learning in a new problem space, LP combined with AI can prove invaluable. AI assists in articulating your hypotheses, assumptions, and findings, promoting clearer thinking and ensuring that your exploration process itself is well-documented and understandable.

How to Make it Even Better

First, you don't need any new AI-powered editor to leverage literate programming today. Even the simplest AI code assistants are incredibly effective with literate programming today. Why? Because the necessary prompt context for these tools already exists within the explicitly explained literate source. The AI isn't guessing; it reads a meticulously documented narrative that includes the very code it needs to assist with.

However, to really push Literate Programming from niche to mainstream, we will need some targeted AI development and advanced tooling.

The most critical next step involves training and fine-tuning coding agents specifically to produce literate source. This isn't just about generating code that happens to have comments; it means AI mastering the leveraging and generation of macros. Macros, with their recursive expansion capabilities, are by far the most powerful feature of LP. If AI can master their use, it will unlock LP's full potential. Imagine an AI not just writing functions, but designing and documenting the conceptual hierarchy of your program.

Secondly, we also need proper tooling that goes beyond simply feeding the AI the current document. A proper LP workflow would perform partial or recursive tangling of the literate source during AI inference. Why is this crucial? It allows the AI to simultaneously see the exact current literate programming source (providing the rich human context) and have a peek at the partially generated tangled source (providing the immediate machine context). This dual perspective will lead to far more accurate, context-aware, and intelligent suggestions from the AI.

Ultimately, I envision a shift from a directed, task-based interaction with coding agents to a truly real-time, continuous collaboration. As the developer writes in the literate programming source, the AI agent wouldn't just wait for a prompt; it would constantly suggest improvements, offer completions, and refine both the code and the accompanying explanation. The AI acts as a buddy looking over your shoulder, providing immediate insights and pointing out areas for betterment in both the code logic and its narrative explanation.

Conclusion

I believe Literate Programming is the ideal paradigm for coding with AI, especially for solo projects. It’s a natural fit, allowing AI to contribute to the explanation of the program as much as its execution.

Of course, this paradigm won't fit all coding methodologies or project types. I remain uncertain about its scalability for very large projects with multiple developers handling distinct architectural components. However, for smaller projects and those that lend themselves to vibe coding—where exploration, learning, and clear articulation are paramount—its fit is incredibly strong.

To put my money where my mouth is, I recently built a Literate Programming tool in Rust. It's aptly called illiterate. This tiny CLI tool takes literate source files and performs all macro expansion and tangling across any programming language you throw at it.

To be honest, I kind of hacked it over a weekend as a personal quest to learn Rust, but it was also an exercise in LP, because its own source code is written entirely in the literate programming paradigm. It serves as a living, readable demonstration and, in essence, a blog article of the very concepts we've discussed today. You can read the annotated source here.

I encourage you to explore literate programming, especially in this exciting new context of AI. Perhaps take a look at illiterate as a starting point. And, as usual, leave me any comments if you have follow up questions or if you want to discuss any part of this article in greater depth.

—What is the best programming language?

This is a question I get asked a lot. I teach programming to fresh CS majors, and then compiler construction and some advanced programming language concepts to senior CS majors. So I get asked this question, a lot.

For the sake of the argument, let’s take it at face value for a minute. What’s your pick? Python? JavaScript? Rust? Haskell? Or… Church forbids… LISP!? Or… is this somehow a wrong question?

My response to this question is very pragmatic—I’m a pragmatist for most things that matter, and a romantic for the rest, you’ve been warned.

All other things considered equal—I always say—, assuming no cost in learning a new language, no personal preference, no company policy, etc., the absolute best programming language is the one where you can most easily express the solution to the problem you care about. Neat, right?

—But hey—I hear you scream—that’s not a real answer! That’s just a “depends”.

And yes, it is. All complicated questions have “depends” for an answer. The real answer is understanding what it depends on. And in this case, I think the clearest metric to optimize—again, all else considered equal—is how far will a specific language take me towards solving the problem I need to solve.

If I had a programming language with a set of keywords and builtin operations that basically would let me type a problem and it would get automatically solved—and that thing kind of exists for some domains, think Prolog or SQL—then, that would be the best programming language of all, right!

But of course, this is kind of a moot argument because, in the end, almost all mainstream programming languages are equally good or bad at almost the same things. You can talk to a database in any programming language. You can generate and serve HTML in any programming language. You can write standard business logic in any programming language. You can shoot your foot with regular expressions in any programming language.

Granted, there are some cases where a pure functional language is better in some niche problems but, for the most part, it’s not the language per se, but the set of available libraries and frameworks that make it or break it for any given problem.

And that’s precisely the point of this article! Thing is, what most people think about when they refer to a “programming language”—you know, those things with funny names like Python, Java, Rust, Go, Erlang…—is an extremely limited concept. I want to show you a far broader notion of what a programming language is; a notion that I think will make some of you look at the very act of programming in a completely new, and enlightening way.

But let’s start at the beginning.

Subscribe now

What is a Programming Language?

We often talk about programming primarily from the perspective of problem-solving. We take a messy, real-world problem—or so the story goes—and try to distill it into something a computer can understand.

And that’s where the programming language enters the picture. It’s the very language you write the solution to the problem, which is later converted into something the computer can actually run. For the most part, you can even imagine the code in that programming language is actually what’s running on the CPU—at least for the 3rd generation, imperative programming languages that are mainstream today.

From this point of view, a programming language can be defined as a formal language—with a strict syntax and formalized semantics—that can be used to instruct a computer to solve problems in a given domain.

This perspective is absolutely right. It shows programming involves a great deal of abstraction via decomposition, which is to say, we must take a problem and break it into parts so small that are trivial to explain to a computer. But I think this perspective also misses a crucial, often-overlooked part of problem-solving: abstraction via composition. Let me elaborate.

For any, even mildly complicated problem, chances are you will not solve it just with say, pure, Python, for the sake of the argument. No, you will first write a couple of utility functions, perhaps one or two classes here and there, and only then, you’ll write a rather small main function that simply instantiates a type and calls a couple of methods and voilá, problem solved!

What you just did there, my friend, is invent a new language!

Ok, not an entirely new language, but a new something still. You added a couple of methods and classes with their own, formalized semantics, that can be used to instruct a computer to solve problems in a given domain.

Think about it again from the perspective of problem-solving. If only you had that magical language where just typing the problem would give you the solution. Well, that’s what you built. You created a set of building blocks (methods, classes, etc.) that, when you use them to express your problem, you get it automatically solved.

In a sense, all programming is a form of language design. Just as we must distill a problem down into programmable parts, we must also upgrade our programming language with new building blocks that can directly solve those subproblems.

Now let’s see a few ways in which we do implicit language extension when we program.

The Layers of Language Extension

Metaprogramming is perhaps the most evident form of language extension. These are programming language features that directly extend or enhance the language's own syntax. The quintessential expression of metaprogramming is, of course, LISP macros—and similarly inspired macro systems like Rust’s. But other, less flexible features like Python decorators or code blocks in Ruby can also add a level of linguistic manipulation that sometimes seems like you’re programming in a whole different language.

However, the point here is not about metaprogramming. Or not primarily about metaprogramming—that’s just one tiny bit of implementation detail. You don’t need any fancy metaprogramming features to extend a programming language. Most of the code we write is this kind of language-extending code. Functions and types, as we just discussed, are the most basic building blocks in most programming language and also the more pervasive and impactful form of language extension.

Every time you define a new function or class, you're effectively adding a new word to your language vocabulary. You're extending the language you're working with, making it more expressive for the specific problem at hand, and at the same time, more specialized.

I see this happening across four distinct language layers. Each layer adds a new vocabulary, more expressive—in the sense that you can say more with fewer tokens—but also more specialized—in the sense that you can talk about a more reduced set of concepts. Each of these layers encapsulates knowledge about an increasingly more complex part of a problem domain, and each layer encodes a stronger opinion about how a given problem domain is tackled.

Let’s take it from the ground up.

Layer Zero: The Base Language

This is the most basic layer where we always start a new project, the raw programming language itself. Think of Python, C, Java, or JavaScript. At this level, the language is at its most general, most unopinionated. It gives us the fundamental tools: how to store numbers, how to make decisions, and how to repeat actions. The knowledge encapsulated here is about the very basics of computation, how a computer thinks and operates.

Level 1: Libraries

Once our problem exceeds what the builtin functionality in our language can solve, we turn to libraries. If you’re writing, say, numerical algorithms in Python, you probably won’t code everything from scratch. No, you’ll use Numpy.

You can see libraries as a more specialized linguistic layer that offer ready-made functional building blocks for a specific domain. The knowledge encoded in libraries is almost entirely functional: domain-specific algorithms to solve particular types of problems efficiently.

Level 2: Frameworks

This is where things get more opinionated. Frameworks, like a web framework (e.g., Django, React) or a game engine, don't just give you tools; they give you a way of thinking about and solving problems. They encode a particular paradigm or mindset. They tell you the right way to structure your application, the right patterns to follow, the right way to combine these disparate algorithms.

The knowledge encapsulated within a framework is procedural: it's about the best practices and compositional rules for a given domain. If libraries are specialized functions, frameworks are like an architectural blueprint for building a specific type of system.

Level 3: The Application

Finally, we have the top layer: applications designed to solve a concrete problem for a specific user. When you build, e.g., a CRM or a simple CRUD app, that interface is also a language with which the user instructs the computer to solve a concrete problem—be it create a report or change a user password.

Applications encode knowledge about a business domain—business in the sense it’s a problem that some client wants to solve. And every application, in a subtle way, implicitly contains its own framework (its own set of compositional rules) and its own custom library (its own building blocks).

Oftentimes this code is intermingled. But in well-designed applications you can often extract a fully-featured framework and a couple of libraries that can be reused for building other similar applications in adjacent domains.

Why this matters

If I’m right then every programmer is, in essence, a language designer. This is a great power, and with it comes great responsibility!

Deciding which abstractions (classes, methods, functions) to create is an exercise in designing a more expressive, more capable language for your specific problem. When you think about it, abstraction itself is fundamentally about finding the right representation. This involves a two-sided approach we’ve already discussed:

• Decomposition (Top-Down): Breaking down a big problem into smaller, more manageable, computationally solvable pieces.

• Composition (Bottom-Up): Actively building and adding new capabilities to your language. This is where you encapsulate functionality into reusable blocks.

The sweet spot where these two directions converge is where you find the perfect level of abstraction, where your problem understanding and your solution language align beautifully.

But, of course, we rarely explicitly program this way. We don’t build the perfect framework or library upfront. More often, we build an application, realize certain patterns are emerging, and then extract a framework or library from it. Only after a lot of experience in a given domain we begin to see the patterns at the start of a new project and can design upfront. And even then, we often make mistakes and design abstractions that aren’t exactly right, or maybe even unnecessary.

But that’s ok. My argument here is not that you should define a sweet spot you want to achieve, and then build your language up to get there. No, the process of problem-solving in inherently messy and there’s nothing that can substitute experimentation.

However, I do think this dual-view of programming is helpful from at least two perspectives. First, as a programmer, it helps to sometimes step back and consider what is the language you need to solve your current problem, and work with that as at least a flexible guide. Again, this doesn’t you’ll get it right from the start. But I find it helps me to rethink and refactor a convoluted solution when everything gets stuck.

And second, as an educator, this perspective gave me a powerful shift in how I teach computer programming. Instead of just teaching students to solve problems with a language, I now try teach them to be explicit about their intentions when designing abstractions, and to understand the new linguistic layers they are always creating. This means teaching them how to break the problem down to fit the existing language constructs and, simultaneously, teaching them how to build the language up with new constructs to better fit the problem.

As a side note, this perspective also helps explain why almost all programming languages start as a cheap C rip-off—a slow, low-level, mostly imperative general-purpose language—and gradually evolve towards a LISP wannabe—a highly extensible systems with powerful metaprogramming capabilities, but still not LISP.

But this is a topic for another article.

In the first two parts of this series, we explored the fascinating, chaotic world of emergent storytelling. We saw how complex narratives can arise from simple, "bottom-up" rules in Part I, and how LLM-powered agents can co-create stories through dynamic, unpredictable interaction in Part II. It’s a world of digital improv, where the story finds its own way.

But that’s only half the picture.

Those bottom-up approaches excel at creating novelty and believable micro-interactions. They are fantastic at answering "What happens next?" But what about the "top-down"? What about the grand narrative arc, the deliberate plot structure, and the long-term coherence that defines the stories we remember? This is where even the most advanced Large Language Models (LLMs) stumble. They are masters of prose but poor architects. They can write a beautiful paragraph, but struggle to build a cathedral.

In this final installment of the series, we close the loop. We'll explore a complementary, top-down approach based on another excellent thesis I supervised this year, this one by Roger Fuentes Rodríguez. His work focuses on high-level planning and structure. I'll argue that this architectural approach doesn't just produce better stories; it provides a powerful model for building more robust and governable AI systems.

LLMs are Brilliant Amnesiacs

Let’s backtrack to the root of the problem we’ve been discussing the past two weeks. If you've ever had a long, meandering conversation with an LLM, you've likely seen it happen. After a while, it starts to forget key details from the beginning of the chat. This isn't a bug; it's a fundamental feature of their design.

Think of it as a brilliant mind with no long-term memory. An LLM can only "see" the last few thousand words (tokens) of a conversation. And even in LLMs with Everything before that effectively ceases to exist. For short tasks, this is fine. For writing a novel, it's a disaster.

This limitation leads to critical failures in long-form storytelling:

• Character Amnesia: A hero who is terrified of spiders on page 5 suddenly keeps one as a pet on page 50.

• Plot Holes: The magical sword that can only be wielded by the pure of heart is inexplicably used by the villain to open a tin of beans.

• Structural Breakdown: The story loses its narrative drive. The rising action plateaus, the climax never quite lands, and the resolution feels unearned, violating foundational structures like Freytag's Pyramid.

The core challenge is this: a story is not a linear sequence of words. It's a complex, interconnected web of causal relationships, character motivations, and thematic consistency. A monolithic LLM, with its limited memory, simply can't manage this web on its own. It needs an architecture.

The Writer's Room

Instead of relying on a single, all-knowing AI, the thesis proposes a "divide and conquer" strategy. The system's core is a central story blueprint, which a team of specialized AI agents collaborates on. It’s less like a single author and more like a Hollywood writer's room.

The Story Blueprint

At the heart of this system is a Directed Acyclic Graph (DAG). Forget the jargon for a second; think of it as the story's complete, interconnected timeline and causal web, all mapped out on a giant whiteboard.

• Nodes are Events: Each point on the whiteboard is a specific event in the story. Not prose, but a structured object with the characters that participate, and all the necessary metadata.

• Edges are Causality: The arrows connecting the events represent cause-and-effect. An arrow from "Hero finds the key" to "Hero opens the chest" means the first event must happen before the second. This simple rule makes temporal paradoxes and plot holes structurally impossible. You can't use the key before you find it.

This graph is the long-term memory the LLM lacks. It is the single source of truth that codifies the story's logic, ensuring every part is connected to the whole.

The Writers

The agents in this system aren't working in isolation. They are all reading from, and writing to, that central graph.

• The Architect: This agent builds the initial skeleton of the graph. It takes the user's high-level prompt and lays out the main plot points—the inciting incident, the major turning points, the climax—as the first nodes on the graph.

• The World Builder: This agent is the lore master. It goes through the graph and enriches the event nodes with crucial details: defining the characters, describing the locations, and specifying the properties of important objects.

• The Drama Coach: This agent's job is to make the story interesting. It analyzes the graph's structure to find flat or boring sequences. It then adds or modifies nodes to inject conflict, suspense, or character development. It asks, "Wouldn't it be more interesting if the hero's mentor betrayed them at this point?" and adds that event to the graph.

• The Dependency Manager: This is the ultimate fact-checker. It constantly validates the graph, ensuring there are no paradoxes or broken rules. It checks things like, "Does the character have the required item from a previous node before attempting this action?" or "Is this supposedly dead character trying to speak?"

• The Narrator: Only when the graph is complete, enriched, and validated does this agent step in. It performs a "topological sort" of the graph (reading the events in a valid causal order) and, one node at a time, uses an LLM to translate each structured event into compelling prose, feeding it only the context it needs for that specific scene.

The Proof is in the Plot

Does this actually work? In short, yes.

The evaluation for the thesis involved having real users interact with the system via a Telegram bot and compare its output to that of a monolithic LLM. The stories generated by this structured, multi-agent system were consistently rated higher in structural coherence and narrative depth. The system excelled at maintaining consistent character motivations, building a more detailed and believable world, and avoiding the plot holes that plague simpler approaches.

But while this approach has clearly many strengths, it currently lacks in precisely what the previous articles excel: emergence and interaction. So, that’s our next step.

Unifying Top-Down and Bottom-Up

So where do we go from here? The clear path forward is to build a unified theory of AI storytelling, combining the top-down planning from this article with the bottom-up emergence and interaction from the previous two.

Imagine a hybrid system with two layers operating at once:

1. The Macro-Narrative (Top-Down): The story graph we've discussed acts as the "grand narrative," defining the key plot beats that must happen for the story to be satisfying.

2. The Micro-Narrative (Bottom-Up): Within each scene (each node of the graph), we unleash the autonomous, LLM-powered characters from the previous two articles. They have their own goals, personalities, and memories, and they interact freely, creating emergent and unpredictable dialogue and actions.

The magic lies in connecting these two layers. We reintroduce a crucial agent: the Director (or God/Game Master). The Director's job is not to puppet the characters. Instead, it subtly nudges the simulation. It knows the next required beat in the story graph is "The hero must discover the secret map." It can't force the hero to look for it, but it can introduce an NPC who mentions a rumor, make a book fall off a shelf to reveal a hidden compartment, or create a sudden downpour that forces the characters to take shelter in the very cave where the map is hidden.

This creates the best of both worlds: the structural integrity of a planned narrative, combined with the organic, believable, and often surprising behavior of autonomous agents. It’s the holy grail: a story that is both well-plotted and truly alive.

Beyond Storytelling as a Toy

Let's be clear: the goal of this research is not to automate creativity or replace human authors. The real value of computational storytelling lies elsewhere. It serves as the perfect playground for tackling some of the most critical open problems in Artificial Intelligence.

A story is a microcosm of our complex world. Forcing an AI to generate a coherent one is an extreme stress test for its most important faculties:

• Reasoning: A good story is a monumental feat of causal reasoning. Characters must have consistent motivations, actions must have logical consequences, and plot threads must resolve. Maintaining this web of dependencies is a powerful way to measure and improve an AI's ability to reason in non-formal, unstructured, but still challenging scenarios.

• Governance & Safety: Think of our writer's room architecture. The Dependency Agent acts as a safety and ethics system, enforcing the rules of the world. The Drama Coach agent governs the narrative, steering it towards a desired outcome (an "interesting" story) without violating core constraints. This is a perfect sandbox for studying AI alignment: how do we build systems that can pursue complex goals while adhering to a set of inviolable rules?

For decades, AI research advanced by mastering abstract games like Chess and Go. The breakthroughs required to win those games, particularly in deep learning, didn't just stay in the game. They became foundational for solving real-world scientific problems, most famously protein folding with AlphaFold.

I argue that storytelling is the next grand challenge for conversational AI. It's a game with infinitely more complex rules than Go, one that involves social dynamics, common sense, and long-term planning. The novel architectures we must invent to "master" storytelling—systems that can plan, reason, and govern themselves—could be the key to unlocking the next generation of safer, more robust, and more capable Artificial Intelligence.

And if you liked this article, feel free to check the full thesis (in Spanish but AI can translate it pretty well) and the repository to read some of the generated stories.

In the previous article, we explored how multi-agent architectures can inject life and autonomy into AI-generated stories, allowing characters to pursue their own goals in a dynamic world. But what happens when you add a human to the mix? Interactive storytelling raises the stakes: now the system must not only maintain coherence and character consistency, but also respond—intelligently and flexibly—to unpredictable user input.

This is a much harder problem. The system must walk a tightrope: it needs to be consistent enough to avoid plot holes and character drift, but flexible enough to let the user meaningfully shape the narrative, even in ways the system never anticipated. In this second article I bring you our second undergraduate thesis at the University of Havana, taking on this challenge head-on.

If you haven’t read Part I of this series, I recommend starting there for the full context and motivation behind our research line. In short: we’re not trying to “solve” storytelling, but to use it as a demanding testbed for developing robust techniques in LLM governance, safety, and control.

The Core Problem

Let’s get to the heart of the matter: Why is interactive storytelling so hard? The answer lies in a fundamental tension—one that anyone who’s ever played a narrative game or written a choose-your-own-adventure story will recognize. It’s the struggle between agency (the user’s freedom to make meaningful choices) and control (the system’s responsibility to keep the story coherent, engaging, and believable).

Agency is what makes interactive storytelling magical. It’s the feeling that your decisions actually matter—that you can steer the story in unexpected directions or even break the mold of the narrative world. In a perfect system, you’d be able to do anything your imagination conjures: befriend the villain, burn down the tavern, or turn the hero into a poet. The system would adapt, improvise, and keep the experience compelling.

But here’s the rub: pure agency, without constraints, is a recipe for chaos. If the system simply accepts every user input at face value, the story can quickly unravel. Characters might act out of character, plotlines can contradict themselves, and the narrative world loses its internal logic. The result? A story that feels less like a crafted experience and more like a series of disconnected improv skits.

On the flip side, control is the system’s way of protecting the integrity of the story. Think of it as the invisible hand of the “narrative director”—the set of rules, memory, and logic that ensures events make sense, characters stay true to themselves, and the world remains believable. Control is what prevents the protagonist from suddenly teleporting to Mars or resurrecting a character who just died (unless, of course, the story’s logic allows for it).

But too much control, and the story becomes a railroad. The user’s choices are ignored, overwritten, or reduced to cosmetic differences. The narrative might be coherent, but it’s no longer interactive in any meaningful sense. The magic of agency is lost.

Our Proposal

Let’s open the hood on this architecture. The core idea is straightforward but powerful: break down the complex process of interactive storytelling into a series of specialized agents, each responsible for a distinct narrative function, and orchestrate their collaboration through a well-defined workflow. This modular approach is what allows the system to achieve both flexibility (adapting to user decisions) and consistency (maintaining narrative logic and emotional coherence).

We defined the following agents:

• Orchestrator of Interactive Stories: Acts as the central coordinator. This agent triggers each phase in the correct sequence, manages the overall flow, and ensures all updates to the knowledge graph and narrative state happen in the right order. Without this conductor, the “orchestra” of agents would quickly fall out of sync.

• Rule Extraction Agent: Extracts the fundamental rules and constraints of the story world (e.g., “magic is forbidden,” “time flows forward”). This agent sets the boundaries for all subsequent events, ensuring that the narrative remains internally consistent.

• Key Beat Extraction Agent: Identifies the pivotal moments or “beats” from the user’s synopsis or the evolving story. These serve as narrative milestones, guiding the rhythm and progression of the plot.

• Event Extraction Agent: Detects and classifies concrete narrative events, assigning actors and consequences. This agent feeds the knowledge graph with actionable story content.

• Knowledge Graph Builder: Maintains a dynamic, structured representation of all entities, relationships, rules, and events. The graph acts as both memory and source of truth, ensuring that the story doesn’t lose track of details or contradict itself as it evolves.

• Prompt Enricher: Gathers the most relevant context from the knowledge graph and narrative history, then constructs a rich prompt for the language model. This ensures that every new scene is generated with full awareness of what’s come before.

• Act Director: Generates the next scene using the enriched prompt. This agent is responsible for advancing the plot while respecting the current state and constraints of the story world.

• Character Simulator: Simulates the emotional and behavioral responses of characters to the latest events. This keeps character arcs believable and emotionally consistent.

• Player Action Handler: Integrates the user’s decisions into the narrative. It updates the knowledge graph and narrative history, ensuring that user choices have real, lasting impact on the unfolding story.

Here is a brief overview of how all these agents collaborate in a typical interactive session.

1. Preparation Phase

   • The Orchestrator initializes an empty knowledge graph and sets up the narrative environment.

   • The Rule Extraction Agent processes the initial synopsis or world description to establish the core rules.

   • All agents are initialized and ready to process input as the story unfolds.

2. Narrative Base Construction

   • The Key Beat Extraction Agent identifies the main plot points from the user’s synopsis.

   • The Event Extraction Agent breaks down the synopsis into actionable events.

   • The Knowledge Graph Builder integrates these elements into the graph, establishing the initial state of the story world.

3. Interactive Development Loop

   • Prompt Enrichment: The Prompt Enricher queries the knowledge graph for the most relevant context (recent events, character states, world rules) and constructs a prompt for the LLM.

   • Scene Generation: The Act Director uses this prompt to generate the next scene, ensuring continuity and literary quality.

   • Character Simulation: The Character Simulator infers and documents how each character reacts to the new developments, updating their emotional and behavioral states.

   • User Interaction: The Player Action Handler presents choices to the user, receives their input, and encodes the resulting actions as new events in the knowledge graph.

   • The cycle repeats, with each agent building on the outputs and updates of the others, ensuring that every new scene is both a logical continuation and a meaningful response to user agency.

4. Conclusion and Consolidation

   • When the user signals the end of the story, the Orchestrator triggers the finalization phase.

   • The Knowledge Graph Builder ensures all narrative threads are resolved and the story is logically complete.

   • The system outputs the full, coherent narrative, along with a structured map of how the user’s choices shaped the journey.

How does this stack up?

Let’s get honest: it’s easy to make grand claims about “better stories” and “more engaging AI,” but how do you actually measure narrative quality in a rigorous, meaningful way? For this thesis, the evaluation was designed to pit the multi-agent system head-to-head against a baseline approach that used the same underlying LLM (Llama-3-8B-Instruct) but without any agentic orchestration. This setup ensured that any improvement could be attributed squarely to the architecture—not to a bigger model, more data, or secret sauce under the hood.

The Metrics

The evaluation used a mix of qualitative and structured criteria, focusing on the aspects that matter most for interactive storytelling. Here’s the breakdown:

• Narrative Coherence: Does the story flow logically from scene to scene, or do we get abrupt jumps and plot holes?

• Protagonist Agency: Do the user’s choices and the protagonist’s actions actually shape the direction of the story in a meaningful way?

• Adaptation to User Input: Does the system integrate user decisions naturally, creating real consequences and new narrative branches?

• Conflict and Tension: Is the story able to build suspense, escalate challenges, and avoid flat or artificial drama?

• Originality and Creativity: Are the story elements fresh and surprising, or do we just get recycled tropes?

• Clarity and Literary Style: Is the writing evocative, immersive, and stylistically rich?

• Thematic Consistency: Are the core themes and motifs reinforced throughout, or do they get lost along the way?

• Emotional Consistency: Do the characters’ emotions evolve logically and believably?

• Context Maintenance: Does the system remember important details, settings, and relationships as the story unfolds, or does it “forget” as it goes?

Each experiment involved presenting both systems with the same narrative synopsis and a sequence of user choices. Human evaluators then compared the resulting stories using these criteria, looking for both strengths and weaknesses in each approach.

The Findings

The results were clear and consistent across multiple story scenarios. The multi-agent system outperformed the baseline on almost every metric that matters for interactive storytelling.

Stories generated by the multi-agent system maintained a logical chain of cause and effect, with smooth transitions between scenes and a strong sense of narrative momentum. The protagonist’s decisions had real weight, steering the story into new territory and producing consequences that felt both meaningful and surprising. User choices were not just tacked on—they shaped the evolution of the plot, the emergence of conflict, and the protagonist’s emotional journey.

Perhaps most striking, the multi-agent system produced narratives with richer literary style and more vivid descriptions, even though it used the same LLM as the baseline. This suggests that the way you structure and feed context to the model—through agents that carefully curate, update, and enrich the narrative state—can unlock much more of the LLM’s creative potential.

The system also excelled at maintaining context and thematic unity. Key details, settings, and character motivations were carried forward across scenes, avoiding the notorious “memory loss” problem of vanilla LLMs. Emotional arcs were more believable, and the stories avoided the repetitive, cliché-driven traps that often plague automated narrative generation.

By contrast, the baseline system struggled with abrupt transitions, shallow integration of user choices, and a tendency toward flat or generic storytelling. Protagonist agency was often illusory—choices rarely changed the story in a meaningful way. The writing, while functional, lacked the immersive quality and emotional resonance achieved by the multi-agent approach. Context was easily lost, leading to inconsistencies and a less engaging experience overall.

Final Thoughts

This thesis, and all our complementary research, proves you don’t need to fine-tune, retrain, or scale up your language model to get dramatically better results. By layering a clever multi-agent system on top of a standard LLM, you unlock coherence, adaptability, and user alignment that brute-force training simply can’t deliver. The architecture is the key.

Why does this matter? Because the core problems of interactive storytelling—long-term memory, integrating unpredictable user input, keeping characters and worlds believable—are exactly the challenges we face in building safe, controllable AI everywhere. The multi-agent architecture acts as a governance layer, orchestrating the model’s raw power through explicit rules, dynamic memory, and transparent workflows. It’s not just about telling better stories; it’s about showing that smart design can outpace brute force.

If we want AI that’s powerful and safe, we shouldn’t just throw more data or compute at the problem. We should design smarter systems—ones that let us steer, audit, and trust their outputs.

If you want to check the generated stories and read the full thesis (in Spanish), check this GitHub repository.

If you’ve ever tried to coax a language model into writing a long, coherent story, using just prompt engineering, you’ve probably hit a wall: characters lose their personalities, plots meander or stall, and the whole thing feels more like a sequence of clever paragraphs than a living narrative.

Precisely this topic is one major research line in my group at the University of Havana. Right now, there are three undergrad students wrapping up their theses on AI-driven story generation from different perspectives and strategies.

The common idea underlying this whole research line is that combining multi-agent systems and traditional symbolic AI with LLMs in well-designed workflows can overcome many of the limitations of pure LLM-based story generation. Crucially, we aim to explore ways of improving story generation without any form of fine-tuning or retraining—that is, no need to adjust model weights.

In this and follow up articles, I'll partner with my students to bring you a few high-level summaries of what they've done and found.

This first article (and the corresponding thesis) is about story emergence. We set loose a few characters in an AI-driven world and let them interact, to see what kinds of stories come out. But there is a catch: we want some level of control, but not too much.

The motivating question, then, was how can we introduce some mechanism for indirect control of a story while still allowing characters to evolve more or less naturally and plot points to emerge.

Let's see what Franco came up with.

Subscribe now

Why this matters

Let’s get something out of the way first: the purpose of this research is not to “solve” storytelling, nor to replace writers, artists, or the creative process itself. Storytelling is a deeply human craft, and no one here is under the illusion that a handful of LLM-driven agents will compose the next literary masterpiece.

So, why do we invest so much effort into building systems that generate stories?

The answer is both practical and strategic. Storytelling, especially in the form of simulated worlds with autonomous agents, is a uniquely demanding environment for testing the capabilities—and limits—of large language models. It’s a domain where long-term coherence, character consistency, planning, and subtle control all collide. In other words, it’s the perfect laboratory for exploring how to govern and steer the behavior of powerful generative models without sacrificing their creativity or flexibility.

This is not unlike the role that games like chess and Go played in the development of AI search and planning algorithms. Those domains were never the end goal; rather, they were controlled, well-understood environments where researchers could rigorously test new ideas. The techniques honed in those settings—like Monte Carlo Tree Search—eventually found their way into applications as far-reaching as protein folding and robotics.

In the same spirit, we use storytelling as a proving ground for strategies of indirect control, agent autonomy, and emergent behavior in LLMs. Here, we can measure and observe how different architectures balance autonomy and direction, how memory and planning affect long-term coherence, and how subtle interventions shape complex outcomes. The lessons we learn in this bounded, creative sandbox are directly relevant to much broader and higher-stakes domains: from AI assistants that must follow nuanced instructions, to multi-agent systems in logistics, education, or even critical infrastructure.

Ultimately, the goal is to develop robust, generalizable techniques for controllable and safe AI. By pushing the limits in a domain as rich and challenging as narrative simulation, we’re laying the groundwork for systems that can be trusted to act autonomously, adaptively, and in alignment with human intentions—no matter the context.

And if we get a few fun stories along the way, all the better.

Why pure LLM-driven storytelling falls short

Large Language Models (LLMs) have changed the game for natural language generation. They’re great at producing short, contextually rich responses and can even simulate dialogue or simple stories with impressive flair. But as soon as you ask them for something more ambitious—a novel-length mystery, a world populated by autonomous characters, or a story that evolves over dozens of turns—the cracks start to show.

The main issues? We identified some well-known limitations in LLM-driven storytelling.

• Long-term coherence: LLMs forget what happened a few thousand tokens ago, even if their context is larger.

• Character consistency: Personalities drift, motivations vanish, and “out-of-character” moments abound.

• Proactivity: Agents react, but rarely plan or pursue long-term goals in a believable way. There is no planning ahead of time, it's all reactive.

• Narrative control vs. autonomy: Too much authorial intervention and characters turn into puppets; too little and the story meanders or stalls. It's hard to craft just the right prompt.

These are not just academic complaints. If we want LLMs to power the next generation of interactive fiction, virtual worlds, or even collaborative writing tools, we need architectures that can balance control, coherence, and genuine emergence.

Our idea? Agents, lots of LLM agents

Our approach borrows a page from both agent-based modeling and narrative AI research. Instead of a single omniscient narrator, we simulate a society of autonomous agents—each powered by its own LLM instance, each with its own identity, memory, and goals—interacting in a shared, dynamic environment.

But here’s the twist: rather than scripting the story or directly controlling the agents, we introduce a “Director” agent. The Director never tells the agents what to do. Instead, it manipulates the environment—e.g., changing the weather, introducing objects, setting up casual events—and lets the agents interpret and react according to their personalities and memories.

Think of it as setting the stage and dropping hints, not pulling strings—more as some postmodern, emergent theater play than a traditional movie script. Actors have some constraints but they are free to pursue whatever goals they desire.

Here are the key architectural components that make the whole system come together:

1. LLM-driven agents: Each with its own memory (short-term and long-term reflection), planning, and perception modules.

2. World state: A mutable environment that records locations, objects, events, and global properties.

3. Action resolver: Ensures agent actions are valid and consistent with the world.

4. Event dispatcher: Manages what each agent perceives, maintaining a plausible flow of information.

5. Director: Observes the world and subtly nudges the narrative by changing the environment, not the agents.

To test all these ideas, we built a prototype implementation of the proposed architecture in Python, leveraging Google’s Gemini 2.0 Flash Lite for all LLM tasks. Each component—agent, action resolver, director—gets its own LLM instance and carefully tuned generation parameters. Memory is handled outside the LLM, with dual-level storage: agents remember both recent events and distilled reflections, which are periodically generated and used to inform future decisions.

The Director’s interventions are strictly limited: it can, e.g., change the weather or add objects to locations here and there, but never force an agent’s hand.

Timing is granular—the Director considers whether to intervene before every agent’s turn, allowing for context-sensitive, minimally intrusive direction.

How does this stack up?

To see if this architecture actually improves narrative generation, we ran head-to-head comparisons between stories generated by the multi-agent system and those produced by a monolithic LLM given the same scenario. We evaluated on several axes:

• Coherence and plot progression

• Character consistency

• Originality and emergent plot richness

• Prose quality

• Narrative pacing and suspense

What did we find?

The multi-agent system produced far more believable, consistent characters and surprising plot developments. Because agents had their own memories and goals, their actions made sense and sometimes surprised even us. However, the monolithic LLM still wins on sheer polish—its stories are more linear, its prose more refined, and its pacing more controlled.

There’s an inherent tension here. You can have tight, well-structured prose (monolithic LLM) or you can have emergent, believable characters and plots (multi-agent simulation), but getting both at once remains a challenge.

Some of the most compelling moments came from the Director’s indirect interventions:

• Dropping a key object in the right room led an agent to discover it and set off a chain of events that advanced the plot.

• Changing the weather or introducing an environmental clue shifted the focus of a conversation or escalated a conflict, without ever breaking the agents’ autonomy.

• Sometimes, interventions were ignored or interpreted in unexpected ways—an important reminder that true emergence is unpredictable.

Limitations and Next Steps

No system is perfect. The current prototype has its share of constraints:

• Agents can only interact with objects in their current location.

• There’s no persistent, explicit inventory management, so long-term planning with items is limited to what LLMs can remember.

• Agent-to-agent interactions are mostly conversational; direct state changes (like “killing” another agent) aren’t supported yet (we'd need to improve the action resolver to understand these intentions).

• The Director’s toolkit is intentionally minimal, which limits the subtlety and richness of its interventions.

Future work should expand environmental manipulation, improve memory persistence, and explore hybrid approaches that combine the strengths of both architectures.

Final Thoughts

This work is less about “solving” narrative generation and more about charting a new direction. By treating characters as autonomous agents and narrative direction as an emergent property of environmental context, we get stories that feel less like scripts and more like living worlds. The trade-off is real, but so is the potential: with the right architecture, LLMs can do more than just write—they can simulate societies, surprise their creators, and perhaps even teach us something about how stories really emerge.

If you’re interested in the technical details or want to see some sample stories, check out the full thesis, and read a few generated stories.

And if you have ideas for making these systems even richer, leave us some comments.