Functions, Modules & OOP

1 · Functions, deeper intermediate

Here's a moment every agent-builder hits. You've written five tools — get_weather, search_docs, scale_service, and two more. Now the model says "run search_docs." Your first instinct is a wall of if name == "get_weather": ... elif name == "search_docs": ..., growing one branch per tool forever. Then someone shows you that in Python a function is just a value you can drop into a dict, and the whole ladder collapses into one line: DISPATCH[name](...). That small shift — functions are things, not just actions — is the mental unlock this section is built on.

The everyday analogy is a restaurant's bell system. The kitchen doesn't memorise which cook makes which dish; it has a row of labelled bells, and ringing "table 4's dessert" summons whoever is assigned to dessert. The label (a string) is separate from the worker (the function). Swap the pastry chef and nobody re-learns the bells. In Python the "bells" are dictionary keys and the "workers" are functions stored as values — which is exactly how an agent routes the tool the model picked without hard-coding every possibility.

The reason this works is that def get_weather(...) does two things: it builds a function object and binds the name get_weather to it. The name is just a label; the object lives independently. So fn = get_weather (no parentheses!) hands the same object a second label — nothing runs yet. This is the single most common beginner mistake here: writing fn = get_weather() with parentheses, which calls the function immediately and stores its return value instead of the function itself. Parentheses mean "do it now"; no parentheses means "hold onto the recipe for later." Keep that distinction sharp and the rest of the chapter falls into place.

The other quiet workhorse is returning several values at once. Python lets you return "the reply", ["chunk1", "chunk2"] — that comma builds a tuple — and the caller unpacks it in one line with text, sources = answer(q). It reads like the function handed back two labelled things, which is precisely how RAG's answer() gives you both the generated text and the source chunks it used, so you can show citations. From P1 you already know def, parameters, defaults, and return. Two more essentials: functions are values (you can store and pass them), and they can return multiple things (as a tuple).

pythondef get_weather(city):
    return f"sunny in {city}"

# a function is a value — store it, pass it around
fn = get_weather
fn("Paris")                       # 'sunny in Paris'

dispatch = {"weather": get_weather}   # map a name -> a function
dispatch["weather"]("Oslo")         # call it by name

# return several values as a tuple
def answer(q):
    return "the reply", ["chunk1", "chunk2"]
text, sources = answer("q")          # unpack the two return values

# a lambda: a tiny one-line function (no name)
run = lambda city, unit="C": f"18°{unit} in {city}"

2 · *args, **kwargs & unpacking intermediate → essential

Picture the impossible situation this solves. An LLM returns a tool call: it wants scale run with {"name": "web", "replicas": 3}. Tomorrow it wants a different tool with completely different arguments — {"pod": "api-7", "lines": 50}. You cannot write your agent to know every tool's parameters in advance; the model decides those at runtime. So how do you call a function whose argument names you don't know until the moment you call it? The answer is a single operator, **, and once it clicks you'll see it as the hinge the whole tool-calling loop turns on.

Think of ** as an envelope-to-form translator. The model hands you a sealed envelope — a dict of name/value pairs. A function, meanwhile, is a paper form with labelled blanks: name, replicas, namespace. Writing scale(**args) tips the envelope out so each labelled slip drops into the matching blank on the form: {"name":"web","replicas":3} becomes scale(name="web", replicas=3). The keys have to match the blanks — that's the one rule. This is "unpacking": spreading a collection back out into individual arguments.

The mirror image is packing, and it's where **kwargs in a function definition comes in — and where the common confusion lives. People see ** in two places and assume it does one thing. It doesn't: at the call site ** spreads a dict out; in the parameter list **kwargs gathers leftover keyword arguments into a fresh dict. Same symbol, opposite direction — spreading versus collecting. Naming it kwargs is pure convention (short for "keyword arguments"); the ** is what actually matters, so **extras works identically. Getting the two directions straight is the whole skill.

Why does an agent care so much? Because it lets one line — tool.run(**block.input) — call any tool with whatever the model chose, and lets a wrapper like complete(messages, **kw) quietly forward extra options (model, temperature, whatever) down to the API without listing them all. The ** operator "spreads" a dict into keyword arguments. This is the exact mechanism the agent uses to call a tool with the arguments the model chose.

pythondef scale(name, replicas, namespace="staging"):
    return f"{namespace}/{name} -> {replicas}"

args = {"name": "web", "replicas": 3}
scale(**args)          # same as scale(name="web", replicas=3)

# a function that accepts any keyword args
def complete(messages, **kw):     # kw is a dict of the extras
    print(kw)                     # {'model': 'claude-opus-4-8', 'effort': 'high'}
complete([], model="claude-opus-4-8", effort="high")

3 · Modules & imports essential

Every project starts the same way and ends the same way. Day one, everything lives in one heroic agent.py — the tools, the prompts, the loop, the safety rules, all of it. It feels fast. Then it hits 800 lines, two changes in different places start colliding, and you can't find the function you wrote last week. The fix isn't discipline, it's modules: you cut the monolith into named files, and suddenly the capstone reads as agent/ and mock/ folders whose names tell you where things live. This section is about how one file borrows from another.

The analogy is a kitchen with labelled drawers. You don't keep every utensil in one giant bin; you have a drawer for knives, one for spoons, one for spices. A module is a drawer, and import is you opening the right one to grab exactly the tool you need. import json is "open the whole json drawer" — you then reach in with a dot, json.load(f), and it's always obvious where load came from. from anthropic import Anthropic is "just take the one thing out" so you can use Anthropic bare. Both are fine; the dotted form keeps origins visible, the from form keeps call sites short.

A package is the next step up: a folder of related modules that Python treats as one importable unit, marked (historically) by an __init__.py file sitting inside it. That's why from agent.schemas import RiskClass reads as a little filesystem path — "the file schemas.py, inside the folder agent/." The dots are folder separators for code.

Now the mistake that will cost you an hour if nobody warns you: ModuleNotFoundError. Nine times out of ten it does not mean your code is broken. It means Python was launched from the wrong directory, so it's looking for agent/ in a place where agent/ isn't — or the folder is missing its __init__.py and so isn't a package Python will import from. Before you doubt a single line of logic, check where you ran python from and whether the __init__.py exists. A module is just a .py file. import lets one file use another's functions/classes. A folder with an __init__.py is a package.

python# import a whole module, use dotted names
import json
json.load(f)

# import specific names from a module
from anthropic import Anthropic
from pydantic import BaseModel, Field

# import from your OWN package (the capstone does this)
from agent.schemas import RiskClass    # from agent/schemas.py
from mock import cluster, actions    # from mock/cluster.py, mock/actions.py

4 · Type hints intermediate

You will inherit code you didn't write — from a teammate, from an SDK, from yourself six months ago. You open a function called process(data, opts) and stare. What is data? A list? A dict? A string of JSON? What does it hand back? The only way to know is to read the entire body, or run it and see what explodes. Now imagine the signature had read process(data: list[str], opts: dict[str, int]) -> Sentiment. You'd know the contract at a glance without reading a line of the body. That glance is what type hints buy you, and it's why this course sprinkles them everywhere.

Think of a type hint as the label on a shipping box: "Fragile — glassware," "This end up." The label doesn't physically stop you from dropping the box — and this is the part that surprises people — Python does not enforce type hints at runtime. You can annotate lines: int and still pass a string; Python shrugs and runs it. The hints are for humans reading the code and for tools — your editor's autocomplete, a type-checker like mypy, and especially Pydantic, which reads the hints and actually does validate against them. So the honest framing is: hints are documentation that some tools choose to enforce.

That non-enforcement is the classic beginner trap. Someone annotates carefully, sees no error when they pass the wrong type, and concludes "type hints do nothing." They're half right — hints do nothing on their own at runtime; their whole payoff comes from the tooling that reads them. A few pieces of vocabulary you'll lean on: list[str] is "a list of strings," dict[str, int] is "string keys, integer values," Optional[str] means "a string or None" (for a value that might be missing), and Literal["low", "high"] means the value must be exactly one of those spelled-out choices.

That last one, Literal, is quietly the star of an AI course: it's how you pin an LLM's structured output to a closed set of allowed values so a stray "kinda high" can't slip through and corrupt downstream logic. Type hints annotate what a function takes and returns. Python doesn't enforce them, but they make code readable and power tools like Pydantic. This course uses them throughout.

pythonfrom typing import Optional, Literal

def get_logs(pod: str, lines: int = 20) -> str:
    # pod is a str, lines is an int (default 20), returns a str
    return "..."

names: list[str] = ["a", "b"]          # a list of strings
counts: dict[str, int] = {"a": 1}       # dict: str keys, int values
ref: Optional[str] = None              # str OR None
level: Literal["low", "high"] = "low"   # only these exact values

5 · Classes (OOP) intermediate

Try building a chatbot with only functions and you'll feel the pain immediately. Each turn needs the whole conversation so far, so you end up threading a history list through every single call — respond(text, history), then respond(next_text, history), carrying that list by hand like a hot plate you can't put down. Lose track of it once and the bot forgets everything. A class is the moment you get to set the plate down: the conversation lives inside the object, and the object remembers it for you between calls. That's what "state" means, and it's why the agent is a class.

The analogy that makes classes click is a cookie cutter and its cookies. The class is the cutter — the shape, the blueprint. Each object you stamp out (an instance) is a separate cookie made from that shape but living its own life. Two Agent() instances share the design (same methods, same structure) but each has its own messages list, so one user's conversation never bleeds into another's. A class bundles two things the cutter analogy captures: the data each cookie carries (its state) and the behaviour the shape defines (its methods).

Two words trip up nearly every newcomer. __init__ is the constructor — it runs automatically the instant you write Agent(), and its only job is to set up the starting state (self.messages = []). You never call it by hand; creating the object calls it for you. And self is simply "this particular cookie" — the specific instance a method is working on. When you write self.messages.append(...), you're saying "add to this instance's own list." The common mistake is forgetting self. and writing a bare messages = [] inside a method: that makes a throwaway local variable that vanishes when the method returns, and the object remembers nothing. If it should survive between calls, it lives on self.

The rule of thumb for when to reach for a class: use one when a thing has state that changes over time and behaviour that acts on that state. A one-shot calculation is a function; a conversation, a growing index, a connection you open and reuse — those are objects. A class bundles data + behavior. Use one when something has state that changes over time — like an agent that remembers a conversation, or a vector store that holds indexed chunks.

pythonclass Agent:
    def __init__(self):        # runs when you create one
        self.messages = []      # state: this instance's history

    def chat(self, text):      # a method — self is "this instance"
        self.messages.append({"role": "user", "content": text})
        return f"({len(self.messages)} messages so far)"

a = Agent()          # create an instance (__init__ runs)
a.chat("hi")          # call a method
a.chat("again")       # state persists on 'a'

__init__ is the setup method; self refers to the specific instance so each object keeps its own state.

6 · Dataclasses intermediate

Here's the tedium a dataclass abolishes. You want a small record — a Tool with a name, a description, a risk level, and a function to run. Written by hand, that's a class where you type every field name three times: once in __init__'s parameters, once as self.name = name, and again for the next field, and the next. Then, when you print() it to debug, you get the useless <Tool object at 0x10f3a2b80> and have to hand-write a __repr__ too. It's pure boilerplate, and boilerplate is where typos hide. The @dataclass decorator writes all of it for you.

Think of it as a form template. Instead of drafting a new paper form from scratch — drawing every box and label — you tick "I need fields: name, description, risk, run" and the office prints a ready-to-fill form with the boxes, the labelling, and a tidy summary printout already done. In code, you just list the fields with type hints under @dataclass, and Python auto-generates the constructor (so Tool("get_pods", "list pods", "read_only", fn) just works, in field order) plus a readable __repr__ and sensible equality.

The one gotcha that bites everyone eventually: fields with defaults must come after fields without them. Just like function arguments, you can't have a required field sitting after an optional one — name: str then enabled: bool = True is fine, but flip them and Python raises an error at class-definition time. (There's a subtler trap too, inherited from section 8: never use a mutable default like [] directly; dataclasses make you use field(default_factory=list) instead, for exactly the shared-state reason you'll meet shortly.)

Why does the course lean on dataclasses so hard? Because a tool is fundamentally a record that happens to carry a callable — its behaviour (the run function) sits right next to its metadata (name, risk). That co-location is what lets the safety gate look up a tool and instantly know its risk before deciding whether to run it. A dataclass is a class that's mostly just fields — Python writes the boilerplate __init__ for you. Perfect for a "record" like a Tool.

pythonfrom dataclasses import dataclass
from typing import Callable

@dataclass
class Tool:
    name: str
    description: str
    risk: str
    run: Callable            # a function is a valid field!

t = Tool("kubectl_get", "list pods", "read_only", lambda: "pods...")
t.name        # 'kubectl_get'
t.run()       # 'pods...'

7 · Enums intermediate

Somewhere in every codebase a bug like this is waiting. A tool's risk is stored as the string "read_only". The safety check reads if risk == "readonly": — no underscore. It compiles, it runs, it never matches, and a write action that should have been blocked sails straight through. No error, no crash, just a silent hole in your safety gate discovered the hard way. The whole class of bug comes from using free-text strings for values that should be a fixed, known set. An enum closes that hole.

An enum is like the gear selector in a car: P, R, N, D. There is no "kinda-drive" or "drive-ish" — the lever physically only stops at defined positions. You reference RiskClass.READ_ONLY, a real named thing the editor autocompletes and Python can verify, instead of a loose string you might fat-finger. Misspell the member name and you get an immediate, loud AttributeError at the point of the mistake — not a quiet wrong-answer three functions downstream. That's the trade: enums move typos from silent runtime bugs to obvious, early failures.

Two flavours matter here, and mixing them up is the common confusion. A plain Enum gives you identity — members are distinct, comparable with ==, but have no order (asking A < B raises a TypeError). An IntEnum also makes each member an integer, so members can be ordered and compared with < and >. The rule: use a plain Enum when you just need distinct labels ("is this the irreversible one?"), and an IntEnum when the values form a ranking you'll compare ("is this rung more powerful than that one?"). Inheriting from str as well (class RiskClass(str, Enum)) is a handy extra: each member also behaves like its string value, which keeps JSON serialization and equality clean.

In this course the two enums RiskClass and Rung are the literal backbone of the capstone's safety model — the gate is a table indexed _MATRIX[rung][risk], enums used as dict keys. An enum is a fixed set of named values. Use one when a value must be one of a known list — like risk levels. Typo-proof and readable.

class _Any:
    '''stands in for any undefined demo value; supports call/attr/index/
    iteration and basic arithmetic (as 0.7) so demo snippets run.'''
    def __call__(self, *a, **k): return _Any()
    def __getattr__(self, k): return _Any()
    def __getitem__(self, k): return _Any()
    def __iter__(self): return iter([])
    def __len__(self): return 0
    def __contains__(self, o): return True
    def __enter__(self, *a): return _Any()
    def __exit__(self, *a): return False
    def __float__(self): return 0.7
    def __int__(self): return 1
    def __lt__(self, o): return True
    def __gt__(self, o): return False
    def __le__(self, o): return True
    def __ge__(self, o): return False
    def __add__(self, o): return o
    def __radd__(self, o): return o
    def __bool__(self): return True
    def __repr__(self): return 'demo'
    def __str__(self): return 'demo'
risk = _Any()

pythonfrom enum import Enum, IntEnum

class RiskClass(str, Enum):
    READ_ONLY = "read_only"
    IRREVERSIBLE = "irreversible"

RiskClass.READ_ONLY            # the member
RiskClass.READ_ONLY.value      # 'read_only'
risk == RiskClass.IRREVERSIBLE # safe comparison — no typos possible

# IntEnum members are ordered — useful for "rungs"
class Rung(IntEnum):
    OBSERVE = 1
    ACT = 3
Rung.ACT > Rung.OBSERVE        # True

8 · The mutable-default trap must-know gotcha

This is the bug that makes you doubt your sanity. You write def add_message(msg, history=[]), test it once, get ['a'] — perfect. You ship it. Days later, users report messages from other people's conversations appearing in their chat. You re-read the function ten times; the logic is obviously correct. Nothing looks wrong. The horror of this trap is that the code is readable and reasonable and still broken, and it's the number-one confusing bug for people building stateful agents. Learn it once here and you'll spot it forever.

The cause hides in a Python rule that's actually consistent, just surprising: a default argument is evaluated exactly once, when the function is defined — not fresh on each call. So that [] is created a single time and quietly reused by every call that doesn't supply its own list. The mental model most people carry ("a new empty list each call") is simply wrong; the truth is "one list, born at definition, shared forever."

An analogy: imagine a form that's supposed to give each visitor a blank notepad, but the office only ever bought one notepad and hands that same dog-eared pad to everyone. Visitor A jots "a." Visitor B gets the pad — and sees A's note still on it, then adds "b," so it now reads "a, b." Nobody erased anything between visitors because there was never a second pad. For a value type like a number the trap doesn't bite (you can't scribble on the number 5), which is exactly why beginners get away with it until the first list or dict default.

The fix is a fixed idiom worth memorising: default the argument to None, then create the real object inside the function — if history is None: history = []. Now every call that needs one gets a genuinely fresh list. This is the same reason the course's agent sets self.messages = [] inside __init__ (which runs per instance) rather than as a shared class-level default — otherwise every agent would scribble on the same notepad. One Python quirk bites nearly everyone building agents: a mutable default argument (like [] or {}) is created once and shared across all calls. This causes conversation histories to leak between agent instances — a nasty, confusing bug.

python# ✗ WRONG — the default list is shared across every call!
def add_message(msg, history=[]):    # created ONCE, reused
    history.append(msg)
    return history

add_message("a")      # ['a']
add_message("b")      # ['a', 'b']  ← 'a' leaked in! not a fresh list

# ✓ RIGHT — use None as the default, create inside
def add_message(msg, history=None):
    if history is None:
        history = []             # a fresh list every call
    history.append(msg)
    return history

9 · *args and packing/unpacking, in full intermediate

Section 2 gave you half a superpower; here's the other half. You met ** for keyword arguments — the dict-to-form trick. But the model might ask you to run three tools in one turn, and your agent has to bundle all three results back into a single user message. Or you're building a request from a shared base config plus a couple of overrides. These are the moments where knowing both the * (single-star) and ** (double-star) forms, in both directions, turns clumsy code into one clean line. This section completes the picture.

Hold two axes in your head and everything sorts itself out. The first axis is one star vs two: * deals with positional values (order matters, no names — like items in a list), while ** deals with keyword values (name=value pairs — like a dict). The second axis is direction: in a function's parameter list, a star packs loose arguments into a collection; at a call site, a star unpacks a collection back out into loose arguments. Four combinations, but really just two ideas crossed together.

The everyday image is a suitcase. Packing (def combine(*blocks)) is zipping many loose items into one bag — combine("a","b","c") arrives inside the function as the tuple ("a","b","c"). Unpacking (func(*mylist)) is opening the bag at the destination so each item comes out as its own separate argument again. The confusion to avoid: a star in a def line is the "close the suitcase" side; a star at the call is the "open the suitcase" side. Same symbol, opposite ends of the trip.

One more move you'll use constantly: {**base, "max_tokens": 4096} spreads an existing dict into a new one and overrides a key — the clean, non-destructive way to make a request variant. Crucially it copies, so the original base is never mutated (a fact worth verifying yourself, and a common source of "why did my shared config change?" bugs when people mutate instead of spread). P2 showed **kwargs for calling tools. Here's the complete picture — *args collects positional arguments, and */** unpack collections into calls. This is how the agent passes "all tool results in one message" and how variadic helpers work.

python# *args: accept any number of positional arguments (collected into a tuple)
def combine(*blocks):
    return list(blocks)
combine("a", "b", "c")          # ['a', 'b', 'c']

# unpack a list INTO positional args with *
results = [{"type":"tool_result"}, {"type":"tool_result"}]
# NewUserMessage(*results) would pass each result as a separate argument

# merge dicts with ** (build a request from a base + overrides)
base = {"model": "claude-opus-4-8", "max_tokens": 1024}
call = {**base, "max_tokens": 4096}   # override just one key
# {'model': 'claude-opus-4-8', 'max_tokens': 4096}

# combine: forward extra kwargs to another function
def complete(messages, **kw):
    return client.messages.create(messages=messages, **kw)   # pass-through

10 · Inheritance & super() intermediate → advanced

You'll bump into inheritance the day you use somebody else's SDK. The Anthropic tools docs hand you a class called BetaAbstractMemoryTool and say "subclass this and fill in view, create, and friends." Or you want a custom error and Python says "subclass Exception." You didn't write those parents, and you don't want to — you want to build on them, keeping everything they already do and adding your own twist. That "build on top of, don't rewrite" move is inheritance, and it's why the concept matters even if you never design a class hierarchy yourself.

The cleanest way to feel it is the phrase "is-a." A VectorStore is a Store that also knows how to embed things. A savings account is a bank account with interest. When the child genuinely is a kind of the parent, inheritance fits; when it merely uses the other thing (a car has an engine, it isn't one), you'd reach for plain composition instead. Getting that "is-a vs has-a" instinct right is most of good object design, and mixing them up is the classic beginner over-reach — inheriting just to borrow a couple of methods you could have simply called.

The one piece of machinery to understand is super(). When a child overrides a parent's method — writes its own __init__ or its own add — it usually still wants the parent's version to run as well, not be thrown away. super().__init__(name) means "run the parent's setup first," so the shared state (self.name, self.items = []) still gets created before the child adds its own. Then the child layers on its extras. The single most common inheritance bug is forgetting that super().__init__() call in the child's constructor: the parent's setup never runs, and the first time you touch an attribute the parent was supposed to create — self.items — you get an AttributeError that looks baffling until you remember the parent never got to initialise.

The payoff is "reuse the parent, add specifics": call super().add(x) to get the parent's behaviour, then extend it. A subclass reuses and extends a parent class. You'll meet this when the SDK gives you a base class to subclass — like the memory-tool handler or a custom exception.

pythonclass Store:
    def __init__(self, name):
        self.name = name
        self.items = []
    def add(self, x):
        self.items.append(x)

# VectorStore IS-A Store, plus embedding behavior
class VectorStore(Store):
    def __init__(self, name, model):
        super().__init__(name)      # run the parent's __init__ first
        self.model = model          # then add our own state
    def add(self, x):
        super().add(x)              # reuse parent behavior…
        print(f"embedded & stored {x}")   # …and extend it

vs = VectorStore("docs", "minilm")
vs.add("chunk1")                   # uses both

11 · __repr__, @property, static & class methods intermediate

Every developer has had this exact frustrating debugging session. You've got a list of diagnosis objects, you print() it to see what's inside, and you get back a row of <Diagnosis object at 0x10f3a2b80>. Useless. You have no idea which is which. So you start bolting on print(d.cause, d.confidence) everywhere, cluttering your code just to see your data. That papercut — objects that won't tell you who they are — is exactly what the small class features in this section fix. They're not glamorous, but they're the difference between an object that's pleasant to live with and one that fights you.

Start with __repr__, the most immediately useful. It's a dunder method — "double underscore," Python's naming for hooks it calls on your behalf at special moments. Define __repr__ and you decide what shows when the object is printed or inspected: instead of the hex-address gibberish you get a readable Diagnosis(cause='db auth', conf=0.91). Think of it as your object's name tag at a conference — without one, everybody's a faceless silhouette; with one, you can tell them apart at a glance.

Next, @property — and here's the subtlety people miss. A property is a method dressed up to look like an attribute. You define is_confident as a function, but you access it as d.is_confident with no parentheses, and it computes fresh each time. The trap is exactly that missing-parens confusion, in both directions: add () to a property and you get a TypeError (you're trying to call a plain value); forget () on a real method and you get back the function object instead of its result. The rule of thumb: use a property for a lightweight derived value ("is this confident enough?") that feels like data, and a normal method for an action or anything expensive.

Finally, @staticmethod marks a function that lives under a class for tidy grouping but takes no self because it doesn't touch instance state — commonly a factory like from_dict(d) that builds an instance from raw data. Four class features that make your objects pleasant to use and debug.

pythonclass Diagnosis:
    def __init__(self, cause, confidence):
        self.cause = cause
        self.confidence = confidence

    # __repr__: what you see when you print the object (great for debugging)
    def __repr__(self):
        return f"Diagnosis(cause={self.cause!r}, conf={self.confidence:.2f})"

    # @property: a method you access like an attribute (computed, read-only)
    @property
    def is_confident(self):
        return self.confidence >= 0.8

    # @staticmethod: a plain function grouped under the class (no self)
    @staticmethod
    def from_dict(d):
        return Diagnosis(d["cause"], d["confidence"])

d = Diagnosis("db auth", 0.91)
print(d)              # Diagnosis(cause='db auth', conf=0.91)  ← thanks to __repr__
d.is_confident        # True   ← accessed like an attribute, no ()

12 · Abstract base classes — defining an interface advanced

Imagine handing a teammate a job with a checklist — and them quietly skipping half of it. You tell everyone building a storage backend "you must provide a read and a write." Someone implements read, forgets write, and ships it. It imports fine, constructs fine, and only blows up in production the first time anything calls the missing write. An abstract base class (ABC) is Python's way of making that mistake impossible: it turns "please implement these methods" from a hopeful comment into an enforced contract, checked the moment someone tries to create the object.

The analogy is a blank government form with required fields. The form defines the shape — name here, signature there — but is not itself a valid submission; you can't file the empty template. Only once every required field is filled does it become a usable document. An ABC works the same way: class MemoryBackend(ABC) with @abstractmethod on read and write declares the shape, and Python refuses to instantiate it directly (MemoryBackend() raises TypeError: can't instantiate abstract class). Only a concrete subclass that fills in every abstract method — like a FileMemory that actually reads and writes files — can be created.

The distinction beginners blur is "abstract vs concrete." An abstract method has no real body (just ... or a raise); it exists only to say "you must supply this." A concrete method has a working body. A class is abstract if any of its methods are still abstract, and the beauty is when the enforcement fires: not vaguely at some future call, but immediately at construction, with an error message that names exactly which method you forgot. That early, precise failure is the entire value proposition — you can't accidentally ship an incomplete implementation.

Why an AI engineer meets this: SDKs use ABCs to hand you a slot to fill. The memory tool is exactly this shape — you subclass an abstract base and implement view/create/str_replace, and the SDK's runner drives your methods. You supply the storage; the framework owns the flow. An ABC declares "any subclass must implement these methods." It's how SDKs give you a contract to fill in — like a memory backend where you supply the storage but the SDK drives the calls.

pythonfrom abc import ABC, abstractmethod

class MemoryBackend(ABC):
    @abstractmethod
    def read(self, path): ...     # subclasses MUST implement
    @abstractmethod
    def write(self, path, data): ...

# a concrete file-based implementation
class FileMemory(MemoryBackend):
    def read(self, path):
        with open(path) as f: return f.read()
    def write(self, path, data):
        with open(path, "w") as f: f.write(data)

# MemoryBackend()  -> TypeError: can't instantiate abstract class
mem = FileMemory()          # OK — it implements both methods

Worked example · a mini tool registry putting it together

Individually, the last twelve sections can feel like a bag of loose parts. A dataclass here, an enum there, **kwargs off in section 2 — each one sensible on its own, but you're entitled to ask "so what do they actually build together?" This worked example is the answer: every piece snapping into one small, runnable system that answers the two questions a real agent asks on every turn — which tools exist, and am I allowed to run this one right now? If the pieces felt abstract, watching them cohere here is where it clicks.

The mental model is an office with a tool cupboard and a supervisor. The cupboard is the registry — a dict mapping each tool's name to its record. Each tool (a dataclass) is a labelled box carrying its name, its enum risk level, and the run function that does the work. The supervisor is the call() policy gate: you ask for a tool by name, and before handing it over the supervisor checks the risk tag — a read-only tool goes through freely, but a write tool is refused unless you've explicitly shown the "writes allowed" permit. That refusal-by-default is the entire spirit of a safety gate.

Watch specifically for the payoff line, return tool.run(**kwargs). That single statement is the whole chapter in miniature: a function stored as a value (section 1), fetched from a dict by name (dispatch), and called with the caller's arguments spread in via ** (section 2) — all guarded by an enum comparison (section 7) inside a gate. Nothing here is new; it's the same moves you've already met, now load-bearing. Dataclass + enum + type hints + dispatch + **kwargs + __repr__ — a runnable miniature of the capstone's tool system, safe to run with no API key.

mini_registry.pyfrom dataclasses import dataclass
from enum import Enum
from typing import Callable

class Risk(str, Enum):
    READ_ONLY = "read_only"
    WRITE = "write"

@dataclass
class Tool:
    name: str
    risk: Risk
    run: Callable
    def __repr__(self):
        return f"Tool({self.name}, {self.risk.value})"

REGISTRY: dict[str, Tool] = {}
def register(tool): REGISTRY[tool.name] = tool

register(Tool("get_pods", Risk.READ_ONLY, lambda ns="staging": f"pods in {ns}"))
register(Tool("scale", Risk.WRITE, lambda name, n: f"scaled {name} to {n}"))

def call(name, allow_writes=False, **kwargs):     # a tiny policy gate
    tool = REGISTRY[name]
    if tool.risk == Risk.WRITE and not allow_writes:
        return f"BLOCKED: {tool.name} is a write and writes are off"
    return tool.run(**kwargs)                     # unpack args into the tool

if __name__ == "__main__":
    print(REGISTRY["get_pods"])                    # Tool(get_pods, read_only)
    print(call("get_pods", ns="prod"))          # pods in prod
    print(call("scale", name="web", n=3))         # BLOCKED (writes off)
    print(call("scale", allow_writes=True, name="web", n=3))   # scaled web to 3

Tool(get_pods, read_only)
pods in prod
BLOCKED: scale is a write and writes are off
scaled web to 3

Exercises expert

ops = {"add": lambda a,b: a+b, "mul": lambda a,b: a*b}
ops["add"](2, 3)   # 5

class _RiskClass_t:
    _ = None
    def __getattr__(self, k): return 'demo'
RiskClass = _RiskClass_t()

def is_dangerous(risk):
    return risk == RiskClass.IRREVERSIBLE

🎯 Interview practice interview

The interview questions this topic gets asked — worked, with code. For the full pattern catalog see A9 · Big Tech AI-engineering patterns.

pythonfrom collections import OrderedDict
class LRUCache:
    def __init__(self, cap):
        self.cap = cap
        self.d = OrderedDict()
    def get(self, key):
        if key not in self.d: return -1
        self.d.move_to_end(key)      # mark most-recent
        return self.d[key]
    def put(self, key, val):
        if key in self.d: self.d.move_to_end(key)
        self.d[key] = val
        if len(self.d) > self.cap:
            self.d.popitem(last=False)   # evict least-recent

pythonfrom dataclasses import dataclass
from enum import Enum
class Suit(Enum): SPADE=1; HEART=2; DIAMOND=3; CLUB=4
@dataclass(frozen=True)
class Card:
    rank: int      # 2..14
    suit: Suit
class Deck:
    def __init__(self):
        self.cards = [Card(r, s) for s in Suit for r in range(2, 15)]

from dataclasses import dataclass

@dataclass
class Tool:
    name: str
    risk: str

t = Tool("get_pods", "read_only")
print(t)   # Tool(name='get_pods', risk='read_only')

from enum import Enum
from dataclasses import dataclass

class Risk(str, Enum):
    READ_ONLY = "read_only"
    WRITE = "write"

@dataclass
class Tool:
    name: str
    risk: Risk

t = Tool("scale", Risk.WRITE)
print(t.name, t.risk.value)   # scale write

from dataclasses import dataclass
from enum import Enum
from typing import Callable

class Risk(str, Enum):
    READ_ONLY = "read_only"; WRITE = "write"

@dataclass
class Tool:
    name: str; risk: Risk; run: Callable

REGISTRY: dict[str, Tool] = {}
def register(tool): REGISTRY[tool.name] = tool

register(Tool("get_pods", Risk.READ_ONLY, lambda ns="staging": f"pods in {ns}"))
register(Tool("scale", Risk.WRITE, lambda dep, n: f"scaled {dep} to {n}"))

def call(tool_name, allow_writes=False, **kwargs):
    tool = REGISTRY[tool_name]
    if tool.risk == Risk.WRITE and not allow_writes:
        return f"BLOCKED: {tool.name} is a write and writes are off"
    return tool.run(**kwargs)

print(call("get_pods", ns="prod"))
print(call("scale", dep="web", n=3))
print(call("scale", allow_writes=True, dep="web", n=3))

def register_all(tools, into=None):
    if into is None:          # fresh list per call, NOT a shared default
        into = []
    into.extend(tools)
    return into

a = register_all(["get_pods"])
b = register_all(["scale"])
print(a)   # ['get_pods']  -- not polluted by b
print(b)   # ['scale']

from abc import ABC, abstractmethod

class Tool(ABC):
    name: str
    @abstractmethod
    def run(self, **kwargs) -> str: ...

class GetPods(Tool):
    name = "get_pods"
    def run(self, ns="staging"): return f"pods in {ns}"

print(GetPods().run(ns="prod"))
try:
    class Broken(Tool):
        name = "broken"          # forgot run()
    Broken()
except TypeError as e:
    print("cannot instantiate:", type(e).__name__)

from dataclasses import dataclass
from enum import Enum
from typing import Callable

class Risk(str, Enum):
    READ_ONLY = "read_only"; WRITE = "write"

@dataclass
class Tool:
    name: str; risk: Risk; run: Callable

class Registry:
    def __init__(self): self._tools: dict[str, Tool] = {}
    def register(self, tool): self._tools[tool.name] = tool
    def run(self, tool_name, allow_writes=False, **kwargs):
        tool = self._tools[tool_name]
        if tool.risk == Risk.WRITE and not allow_writes:
            return {"tool": tool_name, "allowed": False, "result": None}
        return {"tool": tool_name, "allowed": True, "result": tool.run(**kwargs)}

reg = Registry()
reg.register(Tool("scale", Risk.WRITE, lambda dep, n: f"scaled {dep} to {n}"))
blocked = reg.run("scale", dep="web", n=3)
assert blocked["allowed"] is False
print(blocked)
print(reg.run("scale", allow_writes=True, dep="web", n=3))

Knowledge check check yourself