{
"cells": [
{
"cell_type": "markdown",
"id": "0",
"metadata": {},
"source": [
"# Functions as Values\n",
"\n",
"**Agentic AI** · playground\n",
"\n",
"*A function in Python is an object: it can be stored in a variable or a dictionary, passed to another function and returned from one. The notebook covers `lambda`, closures and their late binding, `*args` / `**kwargs`, and the tool registry `dict[str, Callable]` on which every hand-written agent loop of the course rests.*"
]
},
{
"cell_type": "markdown",
"id": "1",
"metadata": {},
"source": [
"## First-Class Functions\n",
"\n",
"**A first-class function is a function that the language treats as an ordinary value:** it can be bound to a name, stored in a data structure, passed as an argument and returned as a result. Python functions have this property. The statement `def f(): ...` creates a function object and binds the name `f` to it; the call `f()` is a separate operation on that object.\n",
"\n",
"The property solves a problem that every agent has. A language model does not call a function. It emits **text** that names a tool and its arguments, for example `{\"name\": \"add\", \"arguments\": {\"a\": 2, \"b\": 3}}`. The program around the model has to convert the name `\"add\"` into the function to execute. With first-class functions, this conversion is one dictionary lookup."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2",
"metadata": {},
"outputs": [],
"source": [
"def add(a: float, b: float) -> float:\n",
" \"\"\"Return the sum of a and b.\"\"\"\n",
" return a + b\n",
"\n",
"\n",
"f = add # no parentheses: the function object itself, not a call\n",
"print(f) # a function object\n",
"print(f(2, 3)) # the same function, called through another name\n",
"print(f is add) # both names refer to one object"
]
},
{
"cell_type": "markdown",
"id": "3",
"metadata": {},
"source": [
"A function object carries data about itself. The attributes `__name__` and `__doc__` hold the name and the docstring (the string literal directly below the `def` line). A tool-calling agent sends exactly these two items to the model as the description of a tool."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4",
"metadata": {},
"outputs": [],
"source": [
"print(f.__name__)\n",
"print(f.__doc__)\n",
"print(f.__annotations__) # parameter and return annotations, as a dictionary"
]
},
{
"cell_type": "markdown",
"id": "5",
"metadata": {},
"source": [
"## Functions as Arguments\n",
"\n",
"**A higher-order function is a function that takes a function as an argument or returns one.** The built-in functions `sorted`, `max` and `min` are higher-order: their parameter `key` receives a function that maps an element to the value by which the elements are compared.\n",
"\n",
"The example ranks retrieved documents by a similarity score. This is the last step of every retriever in the course."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6",
"metadata": {},
"outputs": [],
"source": [
"hits = [(\"doc-a\", 0.31), (\"doc-b\", 0.87), (\"doc-c\", 0.55)]\n",
"\n",
"\n",
"def score(hit):\n",
" return hit[1]\n",
"\n",
"\n",
"print(sorted(hits, key=score, reverse=True))\n",
"print(max(hits, key=score))"
]
},
{
"cell_type": "markdown",
"id": "7",
"metadata": {},
"source": [
"## Lambda Expressions\n",
"\n",
"**A lambda expression creates a function without a name from a single expression:** `lambda hit: hit[1]` is the same function as `score` above. A lambda expression is used where a function is needed once and a `def` statement would only add a name. The body is restricted to one expression; a function with statements needs `def`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8",
"metadata": {},
"outputs": [],
"source": [
"print(sorted(hits, key=lambda hit: hit[1], reverse=True))\n",
"\n",
"square = lambda x: x * x # legal, but `def square(x): return x * x` is preferred\n",
"print(square(4), square.__name__) # a lambda has no name of its own"
]
},
{
"cell_type": "markdown",
"id": "9",
"metadata": {},
"source": [
"## Closures\n",
"\n",
"**A closure is a function together with the variables of the enclosing scope that the function uses.** When a function is defined inside another function and refers to a local variable of the outer function, the inner function keeps access to that variable after the outer function has returned.\n",
"\n",
"A closure solves the problem of giving a function data that the caller must not supply. In an agent, a tool often needs a resource — a database connection, a working directory, an API key — that the model must not choose. The closure fixes the resource when the tool is created, and the model supplies only the remaining arguments."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "10",
"metadata": {},
"outputs": [],
"source": [
"def make_reader(directory: str):\n",
" \"\"\"Return a tool that reads files, restricted to one directory.\"\"\"\n",
" def read_file(name: str) -> str:\n",
" return f\"(content of {directory}/{name})\" # `directory` comes from the enclosing scope\n",
" return read_file\n",
"\n",
"\n",
"read_notes = make_reader(\"/srv/notes\")\n",
"print(read_notes(\"todo.md\"))\n",
"print(read_notes.__closure__[0].cell_contents) # the captured variable is stored with the function"
]
},
{
"cell_type": "markdown",
"id": "11",
"metadata": {},
"source": [
"### Late Binding\n",
"\n",
"**A closure stores the variable, not the value the variable had at definition time.** The value is read when the inner function is called. The documentation states the rule for a lambda defined in a loop: the variable *\"is accessed when the lambda is called — not when it is defined\"* ([Python Software Foundation, 2023, *Programming FAQ*](https://docs.python.org/3.12/faq/programming.html#why-do-lambdas-defined-in-a-loop-with-different-values-all-return-the-same-result)).\n",
"\n",
"The rule is visible without a loop: the variable is reassigned after the function is defined, and the call reads the new value."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "12",
"metadata": {},
"outputs": [],
"source": [
"city = \"Berlin\"\n",
"report = lambda: f\"weather report for {city}\"\n",
"city = \"Paris\"\n",
"print(report()) # Paris: `city` is read at the time of the call"
]
},
{
"cell_type": "markdown",
"id": "12a",
"metadata": {},
"source": [
"The defect appears when tools are created in a loop. The key of each entry is evaluated when the entry is created, the body of the lambda only when the tool is called. All three functions share the one variable `city`, and after the loop its value is `\"Rome\"`.\n",
"\n",
"At module level, `city` is a global variable, so these lambdas have no closure at all (`__closure__` is `None`): each call looks up the global name `city`. The cause is the same as for a closure — one shared variable that changes after the function is defined."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "12b",
"metadata": {},
"outputs": [],
"source": [
"weather_tools = {}\n",
"for city in [\"Berlin\", \"Paris\", \"Rome\"]:\n",
" weather_tools[city] = lambda: f\"weather report for {city}\"\n",
"\n",
"for name, tool in weather_tools.items():\n",
" print(f\"{name:6} -> {tool()}\") # every key, the same report: Rome\n",
"print(weather_tools[\"Berlin\"].__closure__) # None: the lambda reads the global `city`"
]
},
{
"cell_type": "markdown",
"id": "13",
"metadata": {},
"source": [
"#### Factory Function\n",
"\n",
"**A factory function is a function that creates and returns a new object; it is called for the object it builds, not for a computed result.** `make_weather_tool` below is a factory function: each call returns a new tool function.\n",
"\n",
"A factory function repairs the defect by giving each tool a variable of its own. A call of `make_weather_tool` creates a new local scope, and in it a new parameter `place`, bound to the argument when the call begins and never reassigned afterwards. The lambda created in that call captures this `place`. Three calls create three separate variables with the values `\"Berlin\"`, `\"Paris\"` and `\"Rome\"`. The closure still reads its variable at the time of the call — late binding remains — but no other code changes that variable.\n",
"\n",
"The loop variable `city` and the parameter `place` are different variables; the lambda inside the factory refers only to `place`. The cell shows the three captured cells: three distinct objects with three values."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "13a",
"metadata": {},
"outputs": [],
"source": [
"def make_weather_tool(place):\n",
" return lambda: f\"weather report for {place}\"\n",
"\n",
"fixed_factory = {city: make_weather_tool(city) for city in [\"Berlin\", \"Paris\", \"Rome\"]} \n",
"\n",
"for name, tool in fixed_factory.items():\n",
" cell = tool.__closure__[0]\n",
" print(f\"{name:6} -> {tool()} cell id {id(cell)}, contents {cell.cell_contents!r}\")"
]
},
{
"cell_type": "markdown",
"id": "13b",
"metadata": {},
"source": [
"#### Default Argument\n",
"\n",
"**A default argument also repairs the defect:** a default value is evaluated once, when the function is defined. In `lambda city=city: ...` the name `city` occurs twice and denotes two variables — on the left of `=` the lambda's own parameter, on the right the loop variable of the comprehension in the cell below, read once, when the lambda is created.\n",
"\n",
"The parameter is, however, part of the signature: `inspect.signature` returns `()` for the factory-made tool and `(city='Berlin')` for the default-argument tool. A registry that builds the tool description from the signature describes `city` to the model as an argument, and the model may then pass a city of its own choice. For tools, the factory function is the correct repair."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "14",
"metadata": {},
"outputs": [],
"source": [
"import inspect\n",
"\n",
"fixed_default = {city: lambda city=city: f\"weather report for {city}\" for city in [\"Berlin\", \"Paris\", \"Rome\"]}\n",
"\n",
"print(fixed_factory[\"Berlin\"](), inspect.signature(fixed_factory[\"Berlin\"]))\n",
"print(fixed_default[\"Berlin\"](), inspect.signature(fixed_default[\"Berlin\"]))\n",
"print(fixed_default[\"Berlin\"](city=\"Tokyo\")) # the caller can override the captured value"
]
},
{
"cell_type": "markdown",
"id": "15",
"metadata": {},
"source": [
"## Argument Packing and Unpacking\n",
"\n",
"**The operators `*` and `**` convert between a collection and the arguments of a call.** In a call, `f(*seq)` passes the elements of a sequence as positional arguments, and `f(**d)` passes the items of a dictionary as keyword arguments. In a definition, `*args` collects the surplus positional arguments into a tuple and `**kwargs` collects the surplus keyword arguments into a dictionary.\n",
"\n",
"`**` is the step that connects a model's tool call to a Python function: the model emits the arguments as a JSON object, `json.loads` converts the object to a dictionary, and `tool(**arguments)` calls the function with them."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "16",
"metadata": {},
"outputs": [],
"source": [
"arguments = {\"a\": 2, \"b\": 3}\n",
"print(add(**arguments)) # the same call as add(a=2, b=3)\n",
"\n",
"\n",
"def describe(*args, **kwargs):\n",
" return f\"positional: {args}, keyword: {kwargs}\"\n",
"\n",
"\n",
"print(describe(1, 2, unit=\"km\"))"
]
},
{
"cell_type": "markdown",
"id": "17",
"metadata": {},
"source": [
"A call with a wrong or missing argument name raises `TypeError`. An agent loop converts this exception to an **observation** — the text that the model receives as the result of its action — so that the model can correct the call."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "18",
"metadata": {},
"outputs": [],
"source": [
"try:\n",
" add(**{\"a\": 2, \"c\": 3})\n",
"except TypeError as e:\n",
" print(\"TypeError:\", e)"
]
},
{
"cell_type": "markdown",
"id": "19",
"metadata": {},
"source": [
"## Tool Registry\n",
"\n",
"**A tool registry is a dictionary that maps the name of a tool to the function that implements it.** The agent loop receives a name and arguments from the model, finds the function in the registry and calls it. This procedure is called **dispatch**: the selection of the code to execute from a value known only at run time.\n",
"\n",
""
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "20",
"metadata": {},
"outputs": [],
"source": [
"from typing import Callable\n",
"\n",
"\n",
"def multiply(a: float, b: float) -> float:\n",
" \"\"\"Return the product of a and b.\"\"\"\n",
" return a * b\n",
"\n",
"\n",
"TOOLS: dict[str, Callable] = {\"add\": add, \"multiply\": multiply}\n",
"\n",
"\n",
"def dispatch(name: str, arguments: dict) -> str:\n",
" \"\"\"Execute one tool call and return the observation as text.\"\"\"\n",
" if name not in TOOLS:\n",
" return f\"error: unknown tool {name!r}; available: {sorted(TOOLS)}\"\n",
" try:\n",
" return str(TOOLS[name](**arguments))\n",
" except TypeError as e:\n",
" return f\"error: {e}\"\n",
"\n",
"\n",
"print(dispatch(\"multiply\", {\"a\": 4, \"b\": 2.5}))\n",
"print(dispatch(\"divide\", {\"a\": 4, \"b\": 2}))\n",
"print(dispatch(\"add\", {\"a\": 4}))"
]
},
{
"cell_type": "markdown",
"id": "21",
"metadata": {},
"source": [
"The description of the tools that the model receives is computed from the same registry, from `__name__` and `__doc__`. Registry and description therefore cannot diverge: a tool that is registered is described, and a tool that is described can be called.\n",
"\n",
"The handler in `dispatch` has one weakness: `except TypeError` also handles a `TypeError` raised **inside** the tool and reports it as a wrong call. `07-json-and-schemas.ipynb` separates the two cases by checking the arguments against the signature before the call."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "22",
"metadata": {},
"outputs": [],
"source": [
"def tool_descriptions(tools: dict[str, Callable]) -> str:\n",
" return \"\\n\".join(f\"- {fn.__name__}: {fn.__doc__}\" for fn in tools.values())\n",
"\n",
"\n",
"print(tool_descriptions(TOOLS))"
]
},
{
"cell_type": "markdown",
"id": "23",
"metadata": {},
"source": [
"## Summary\n",
"\n",
"| Construct | Meaning |\n",
"|---|---|\n",
"| `f = add` | the function object, bound to a second name; `f(2, 3)` calls it |\n",
"| `fn.__name__`, `fn.__doc__` | name and docstring, the description of a tool |\n",
"| `key=lambda hit: hit[1]` | a function without a name, passed as an argument |\n",
"| closure | an inner function with the variables of the enclosing scope; the variable is read at the time of the call |\n",
"| `f(**arguments)` | a dictionary passed as keyword arguments |\n",
"| `TOOLS[name](**arguments)` | dispatch: the function is selected by a value known only at run time |\n",
"\n",
"## Use in the Course\n",
"\n",
"| Construct | Notebooks |\n",
"|---|---|\n",
"| tool registry and dispatch | `course/lecture-ReAct/lecture-ReAct.ipynb` and its exercises; `course/lecture-Gateway/lecture-Gateway-exercises.ipynb`; `playground/SWE-Agent/build-a-swe-agent.ipynb`; `playground/memory/06-write-paths.ipynb` |\n",
"| `lambda` as `key=` or as a small callback | the exercises of `lecture-Decomp`, `lecture-ToT`, `lecture-RAG`, `lecture-Eval`; `playground/langgraph/01-langgraph-basics.ipynb` (routing functions) |\n",
"| a function passed as a parameter (`ask=input`, `ask=lambda prompt: \"y\"`) | `playground/pydantic-ai/01-pydantic-ai-basics.ipynb`, `playground/pydantic-ai/02-swe-agent-as-a-graph.ipynb` |\n",
"\n",
"The next notebook, `02-decorators.ipynb`, fills the registry with the `@tool` syntax instead of a dictionary literal."
]
},
{
"cell_type": "markdown",
"id": "24",
"metadata": {},
"source": [
"## Tasks\n",
"\n",
"**Task 1.** Sort the list `hits` by the length of the document name, the longest name first, with a lambda expression.\n",
"\n",
"**Task 2.** Write `make_counter()`, which returns a function without parameters. Each call of the returned function returns the number of calls so far: 1, 2, 3, … Two counters created by two calls of `make_counter` count independently. (The statement `nonlocal n` permits an inner function to assign to a variable of the enclosing function.)\n",
"\n",
"**Task 3.** Extend `dispatch` so that it limits the number of calls: `make_dispatch(tools, max_calls)` returns a dispatch function that returns `\"error: call limit reached\"` after `max_calls` calls."
]
},
{
"cell_type": "markdown",
"id": "25",
"metadata": {},
"source": [
"### Solutions"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "26",
"metadata": {},
"outputs": [],
"source": [
"# Task 1\n",
"print(sorted(hits + [(\"document-d\", 0.1)], key=lambda hit: len(hit[0]), reverse=True))\n",
"\n",
"\n",
"# Task 2\n",
"def make_counter():\n",
" n = 0\n",
" def count():\n",
" nonlocal n\n",
" n += 1\n",
" return n\n",
" return count\n",
"\n",
"\n",
"c1, c2 = make_counter(), make_counter()\n",
"print(c1(), c1(), c1(), c2())\n",
"\n",
"\n",
"# Task 3\n",
"def make_dispatch(tools, max_calls):\n",
" calls = 0\n",
" def limited(name, arguments):\n",
" nonlocal calls\n",
" if calls >= max_calls:\n",
" return \"error: call limit reached\"\n",
" calls += 1\n",
" return str(tools[name](**arguments))\n",
" return limited\n",
"\n",
"\n",
"d = make_dispatch(TOOLS, max_calls=2)\n",
"print([d(\"add\", {\"a\": 1, \"b\": i}) for i in range(3)])"
]
},
{
"cell_type": "markdown",
"id": "27",
"metadata": {},
"source": [
"## References\n",
"\n",
"- Python Software Foundation. \"Programming FAQ.\" Python 3.12 documentation. 2023. "
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}