Functions, Modules & OOP

This block shows a big idea: in Python a function is itself a value, just like a number or a string. You can put it in a variable, store it in a dict, and pass it around — then call it later. It also shows returning several results at once.

1. fn = get_weather — no parentheses, so we are not calling the function; we are giving it a second name. fn("Paris") then runs the same function.
2. dispatch = {"weather": get_weather} stores the function under a name in a dictionary. dispatch["weather"]("Oslo") looks it up by that string and calls it. This "name → function" table is exactly how an agent picks which tool to run.
3. return "the reply", ["chunk1", "chunk2"] returns two things as a tuple. text, sources = answer("q") unpacks them into two variables in one line.
4. lambda city, unit="C": ... is a tiny nameless function written on one line — handy when a function is so small that giving it a full def would be overkill.

What the output means: Nothing prints on its own here; each line evaluates to a value (e.g. fn("Paris") is 'sunny in Paris'). In a notebook the last expression of a cell shows automatically.

Try this: Add a second entry to dispatch, like "echo": lambda s: s, then call dispatch["echo"]("hi"). You just extended a dispatch table without touching any of the existing code — that is the whole point of storing functions by name.

The ** operator "spreads" a dictionary into named arguments of a function. This is the single trick that lets an agent call any tool with whatever arguments the model chose — without knowing them in advance.

1. args = {"name": "web", "replicas": 3} is a plain dict of argument values.
2. scale(**args) is the magic: the ** unpacks the dict so it becomes scale(name="web", replicas=3). The dict keys must match the parameter names.
3. def complete(messages, **kw): does the reverse — the **kw collects any extra keyword arguments the caller passes into a dict named kw. So calling complete([], model="claude-opus-4-8", effort="high") makes kw == {'model': 'claude-opus-4-8', 'effort': 'high'}.

What the output means: print(kw) shows the collected extras as a dictionary: {'model': 'claude-opus-4-8', 'effort': 'high'}.

Try this: Add another argument, e.g. complete([], model="x", temperature=0.2), and watch temperature appear in the printed dict. This is why the agent's tool.run(**block.input) works no matter what fields a tool needs.

A module is just a .py file, and import lets one file borrow the functions and classes defined in another. This is how the capstone is split into agent/ and mock/ folders instead of one giant file.

1. import json brings in the whole module; you then reach inside it with a dot: json.load(f). The name stays prefixed, so it's obvious where load came from.
2. from anthropic import Anthropic pulls out just one name so you can write Anthropic directly instead of anthropic.Anthropic.
3. from agent.schemas import RiskClass imports from your own package. The dotted path agent.schemas means "the file schemas.py inside the folder agent/". A folder becomes an importable package when it contains an __init__.py file.

Try this: If you ever hit ModuleNotFoundError, it almost always means you ran Python from the wrong folder, or a package folder is missing its __init__.py. Check both before assuming the code is broken.

Type hints are labels that say what kind of value each variable or argument holds. Python does not enforce them at runtime — they are documentation for humans and fuel for tools like editors and Pydantic. They make a function's contract readable at a glance.

1. def get_logs(pod: str, lines: int = 20) -> str: reads as: pod should be a string, lines an integer (defaulting to 20), and the function returns a string (that's what -> str means).
2. names: list[str] means "a list whose items are strings"; counts: dict[str, int] means "a dict with string keys and integer values".
3. Optional[str] means "a string or None" — use it when a value might be missing. Literal["low", "high"] means the value must be exactly one of those spelled-out choices, nothing else.

Try this: Change level to "medium". Python won't complain when you run it (hints aren't enforced), but an editor or Pydantic model using that Literal would flag it — which is exactly how the course keeps structured LLM output valid.

A class is a blueprint that bundles data + behaviour together. You use one when a thing has state that changes over time — like an agent that remembers its conversation. Each object you build from the class (an instance) keeps its own private copy of that state.

1. def __init__(self): is the constructor — it runs automatically the moment you create an instance, and its job is to set up starting state. Here it makes an empty self.messages = [].
2. self means "this particular instance". Storing data on self is what lets one Agent remember things independently of any other Agent.
3. def chat(self, text): is a method — a function that belongs to the class and receives self so it can read and change that instance's state.
4. a = Agent() builds an instance (running __init__). Each call to a.chat(...) appends to a's own list, so the count grows across calls.

What the output means: a.chat("again") returns "(2 messages so far)" because the two messages accumulated on this one instance — the state persisted between calls.

Try this: Create a second agent b = Agent() and call b.chat("hi"). Its count starts at 1, proving each instance has its own messages list.

A dataclass is a shortcut for a class that mostly just holds a few fields. You list the fields with type hints and Python auto-writes the tedious __init__ (and a readable printout) for you. It's perfect for a plain "record" — like describing one tool.

1. @dataclass is a decorator: a line above the class that rewrites it, adding the constructor automatically from the fields below.
2. name: str, description: str, risk: str, run: Callable declare four fields. Callable means "a function" — so a field can literally hold a function you'll call later.
3. t = Tool("kubectl_get", "list pods", "read_only", lambda: "pods...") creates one in the order the fields were declared — no __init__ written by hand.
4. t.run() calls the stored function. Bundling the behaviour (run) together with its metadata (name, risk) in one object is what makes a tool registry tidy.

What the output means: t.name is 'kubectl_get' and t.run() returns 'pods...' — the lambda we stored gets executed on demand.

Try this: Add a field enabled: bool = True after run (fields with defaults must come last) and create a tool without passing it. The dataclass fills in the default for you.

An enum (enumeration) is a fixed, named set of allowed values. Reach for one when a value must be one of a known short list — like a risk level. It's typo-proof: you refer to RiskClass.READ_ONLY, not the loose string "read_only" that's easy to misspell.

1. class RiskClass(str, Enum): defines the set. Inheriting from str too means each member also behaves like its string value, which is handy for JSON and comparisons.
2. READ_ONLY = "read_only" defines one member. RiskClass.READ_ONLY is the member object; RiskClass.READ_ONLY.value is its underlying string 'read_only'.
3. risk == RiskClass.IRREVERSIBLE is a safe comparison — if you fat-finger the name, Python raises an error instead of silently comparing against a wrong string.
4. class Rung(IntEnum): makes members that are also integers, so they can be ordered. Rung.ACT > Rung.OBSERVE is True because 3 > 1 — useful for ranking permission levels.

What the output means: Rung.ACT > Rung.OBSERVE evaluates to True; enums as ordered rungs let the safety gate compare "how powerful is this action" numerically.

Try this: Compare two RiskClass members with < — you'll get a TypeError, because a plain Enum has no order. That's exactly why the ordered levels use IntEnum instead.

This is one of Python's most famous traps, and it bites people building agents. A default argument is created only once — when the function is first defined — not fresh on each call. So a mutable default like [] is secretly shared by every call that relies on it.

1. def add_message(msg, history=[]): looks innocent, but that [] is built a single time. Every call that doesn't pass its own history reuses the same list.
2. So add_message("a") gives ['a'], but the next call add_message("b") gives ['a', 'b'] — the earlier 'a' leaked in because it was never a fresh list.
3. The fix: use history=None as the default, then if history is None: history = [] inside the function. Now a brand-new list is created on every call that needs one.

What the output means: The wrong version accumulates across calls (['a'] then ['a', 'b']); the fixed version returns a clean ['a'] then ['b'].

Try this: Run the wrong version three times in a row and watch the list keep growing. This is the exact reason the course's agent sets self.messages = [] inside __init__ (runs per instance) rather than as a shared default.

This rounds out packing and unpacking. * deals with positional values (order matters, no names), and ** deals with keyword values (name=value). Collecting is "packing"; spreading them back into a call is "unpacking".

1. def combine(*blocks): — the * packs any number of positional arguments into a single tuple named blocks. combine("a","b","c") makes blocks == ("a","b","c").
2. NewUserMessage(*results) would unpack a list back out: each item becomes a separate positional argument — how the agent sends several tool results in one message.
3. {**base, "max_tokens": 4096} builds a new dict from base and then overrides one key. This is the clean way to make a request variant without mutating the original.
4. def complete(messages, **kw): then client.messages.create(messages=messages, **kw) shows pass-through: collect extra kwargs, then forward them onward unchanged.

What the output means: combine("a","b","c") is ['a','b','c']; the merged dict is {'model': 'claude-opus-4-8', 'max_tokens': 4096} — same model, bigger token budget.

Try this: Build {**base, "model": "claude-haiku"} and confirm base itself is unchanged afterward. Spreading always makes a copy, which is why it's safe for overrides.

Inheritance lets one class build on another instead of copying code. The child (subclass) automatically gets the parent's methods, and can add new ones or tweak existing ones. Read it as an "is-a" relationship: a VectorStore is a Store with extra powers.

1. class VectorStore(Store): — the (Store) means "inherit everything from Store". Without writing them, VectorStore already has Store's attributes and methods.
2. super().__init__(name) calls the parent's constructor first, so the shared setup (self.name, self.items = []) still happens. Then the child adds its own state: self.model = model.
3. def add(self, x): overrides the parent's add. Inside, super().add(x) reuses the parent's version (append to the list), and then the child extends it with an extra print.

What the output means: vs.add("chunk1") both stores the item (parent behaviour) and prints embedded & stored chunk1 (the child's addition) — reuse plus extension.

Try this: Comment out the super().__init__(name) line and create a VectorStore. You'll get an error the first time self.items is used, because the parent's setup never ran. That's what super() was doing for you.

Four small class features that make your objects nice to use and debug. "Dunder" methods (named with double underscores like __repr__) are hooks Python calls for you at special moments.

1. def __repr__(self): defines what shows when you print the object or view it in a REPL. Without it you'd get an unhelpful <Diagnosis object at 0x...>; with it you get a readable summary. {self.confidence:.2f} formats the number to 2 decimals.
2. @property turns a method into something you read like a plain attribute — d.is_confident with no parentheses. It's computed on the fly and read-only, great for derived values like "is this confident enough?".
3. @staticmethod marks a function that lives under the class for tidiness but takes no self — it doesn't use instance state. Diagnosis.from_dict(d) is a common pattern: a helper that builds an instance from raw data.

What the output means: print(d) shows Diagnosis(cause='db auth', conf=0.91) thanks to __repr__; d.is_confident is True and is accessed without () because it's a property.

Try this: Add () after d.is_confident and run it — you'll get a TypeError because a property returns the value directly, not a callable. Properties look like data, not methods.

An abstract base class (ABC) defines a contract: it lists methods that any subclass is required to implement, but provides no working body itself. It's how an SDK hands you a shape to fill in — you supply the storage, the SDK calls your methods.

1. class MemoryBackend(ABC): inherits from ABC, marking it abstract — a template, not something you use directly.
2. @abstractmethod above def read(...) and def write(...) means "every subclass must provide these". The ... body is just a placeholder; there's no real implementation here.
3. class FileMemory(MemoryBackend): is a concrete subclass that actually implements read and write using real files.
4. Trying MemoryBackend() directly raises TypeError: can't instantiate abstract class — Python enforces the contract. FileMemory() works because it filled in both required methods.

What the output means: mem = FileMemory() succeeds; instantiating the abstract MemoryBackend itself would fail with a TypeError.

Try this: Delete FileMemory's write method and try to create one. Python refuses, listing write as still abstract — the ABC guarantees you can't forget part of the interface.

This is everything in P3 working together: a dataclass, an enum, type hints, a registry dict, **kwargs, and __repr__ — a runnable miniature of the capstone's tool system. It answers "which tools exist, and may I run this one right now?"

1. class Risk(str, Enum) fixes the allowed risk levels; @dataclass class Tool bundles a tool's name, its risk, and the run function into one record (with a friendly __repr__).
2. REGISTRY: dict[str, Tool] = {} is the lookup table, and register(tool) adds a tool under its name. Two tools get registered — a read-only one and a write one.
3. def call(name, allow_writes=False, **kwargs): is the policy gate. It finds the tool, and if the tool is a WRITE while allow_writes is off, it returns a BLOCKED message instead of running it.
4. return tool.run(**kwargs) is the payoff line: the **kwargs unpacks whatever arguments were passed straight into the stored function — the same generic-call trick from section 2, now inside a real gate.
5. if __name__ == "__main__": runs the demo only when you execute this file directly, so importing it elsewhere stays quiet.

What the output means: The four prints show: the tool's __repr__; a successful read (pods in prod); a blocked write (BLOCKED: scale ...); and finally the same write allowed through with allow_writes=True giving scaled web to 3.

Try this: Add a third tool with Risk.READ_ONLY and call it through call(...) with no allow_writes — it runs freely because only writes are gated. You've just rebuilt the shape of the capstone's safety policy.

An LRU (Least Recently Used) cache keeps a fixed number of items and, when full, throws away the one untouched for the longest. This is the classic object-oriented design interview question; OrderedDict makes it clean because it remembers insertion/access order.

1. self.d = OrderedDict() stores the items in an order-aware dict; self.cap is the maximum size.
2. get: if the key is missing, return -1. Otherwise self.d.move_to_end(key) bumps it to the "most recently used" end, then returns its value. Touching an item makes it recent — that's the whole idea.
3. put: if the key already exists, move it to the recent end; then set the value.
4. if len(self.d) > self.cap: means we just overflowed, so self.d.popitem(last=False) evicts from the front — the least-recently-used item.

What the output means: After exceeding capacity, the item you accessed or added least recently is the one dropped. Both get and put run in O(1) average time.

Try this: Create c = LRUCache(2), then put(1,1), put(2,2), get(1), put(3,3). Key 2 is evicted, because get(1) made 1 more recent than 2.

"Design the classes for X" is a staple of low-level-design interviews. A deck of cards is the friendly version: it shows off enums for fixed categories, a frozen dataclass for an immutable value, and a normal class to hold the collection.

1. class Suit(Enum): SPADE=1; HEART=2; ... — an enum is the right tool because there are exactly four suits and no others should ever exist.
2. @dataclass(frozen=True) on Card makes each card immutable — once created, its rank and suit can't change. Frozen dataclasses are also hashable, so cards can live in sets or act as dict keys.
3. rank: int with the comment # 2..14 means 2 through 14 (11-14 being Jack/Queen/King/Ace); suit: Suit reuses the enum as the field's type.
4. self.cards = [Card(r, s) for s in Suit for r in range(2, 15)] is a nested comprehension: for each suit, for each rank 2..14, build a card — producing all 52 cards in one line.

What the output means: A fresh Deck() holds 52 unique Card objects (4 suits × 13 ranks). Because cards are frozen, two Card(14, Suit.SPADE) values are interchangeable.

Try this: Add a deal(self, n) method that pops n cards off self.cards and returns them. Notice you never need to guard suits against typos — the Suit enum already made that impossible.