Modules

A module is a Python file you can import. import means “load that file and use its names.” Real agents are several files, not one giant script. This editor cannot make sibling files, so you will import stdlib modules here. Stdlib means the modules that come with Python. Then you will plan how to split an agent on paper.

Without modules, every example lives in one box. With modules, tools.py can be tested without starting the loop. That split is how agents stay editable.

What you will learn

• import, from, and as
• if __name__ == "__main__": in plain words
• How you would split an agent into files
• Practice with math, json, and datetime

Three ways to import

import math
import json as js
from datetime import date

• import math loads the module. You write math.sqrt. The prefix shows where the name came from.
• import json as js loads it under a short name. as means “call it this instead.” Use this when the module name is long, not to hide it.
• from datetime import date pulls one name out. You write date, not datetime.date.

Do not write from math import *. That dumps many names into your file. You will not know where sqrt came from. You might overwrite your own pow.

Python runs a module the first time you import it. Keep the top of a file thin. Put work in functions. If you connect to a database at import time, every test pays that cost. If you append to a global list at import time, tests share that list.

Import the same module twice in one program: the second time is cheap. Python reuses the already loaded module. Side effects at import still happened once. That is why side effects at import are painful.

Only run this when this file is the program

Every module has a name flag called __name__.

• When you run this file as the program, __name__ is "__main__".
• When another file imports this file, __name__ is the module’s name, not "__main__".

So this block means: only run this when this file is the program.

def main():
    print(class="tok-s">"start the agent")

if __name__ == class="tok-s">"__main__":
    main()

Tests can import your functions without starting the agent. That is the whole reason. If main() sat naked at the bottom of loop.py, then import loop would launch the agent in the middle of a test.

Put almost nothing else at the top besides imports, constants, and def. The if __name__ block calls main. main calls the loop. Tests call smaller functions.

How you would split an agent into files

Imagine three files:

loop.py would import tools. tools.py would not import loop.py. That keeps a one-way line. If two files import each other, you get a circular import. Python may hand you a half-loaded module and a confusing error.

Add tests/test_loop.py later. Tests import loop functions. They do not run the __main__ block.

On your computer you save those files next to each other. Here, we only describe the split and import stdlib modules instead.

If import fails with ModuleNotFoundError, you typed a wrong name, or that package is not installed. json and math are always there. httpx is not, until you install it on a real machine. This site cannot install it.

A package in Python can also mean a folder of modules with an __init__.py. You do not need that for a three-file agent. Three modules in one folder, imported by name, is enough. If you name a file json.py, you hide the stdlib json. The error looks like dumps is missing. Rename your file. Never shadow stdlib names.

import tools looks for tools.py on sys.path, which includes the current directory when you run a file. From a tests folder the path can differ. Running python -m pytest from the project root is the usual fix on a laptop. Here, you only import stdlib, so the path lesson is for later. Still: one-way imports, thin tops, main behind a name check.

Common mistakes

• from math import *.
• Work at import time: opening files, launching loops.
• Circular imports: loop imports tools imports loop.
• Naming your file json.py so it hides the stdlib module.
• Forgetting that this editor has no sibling files.

Run to execute this in your browser. Nothing is sent to a server.

In this editor, __name__ is usually "__main__", so the extra line prints. On a real import, that line would stay quiet.

How agents use this

Treat the agent as a few files from day one. The loop imports tools. Tests import the loop. Only a main block starts the program. When you add a tool, you add a function in tools.py, not another hundred lines in one file. Import is how that split stays clean.

Prompts as a module let you change text without touching the loop. Tools as a module let you stub search in tests by passing a fake registry. The loop should accept a tool dict and a model function. if __name__ == "__main__": is where you wire the real ones.

Joeven lessons stay in one box. Your laptop should not. Copy the layout table into a folder when you leave the browser. The language feature you practiced is import. The design feature is one-way dependencies.