Stage 1 · Theory & Documentation

Foundations· 2 of 3

Check your setup

What the toolchain is, how an exercise is graded, and how to read a unittest failure. Then an easy exercise whose only job is to break loudly now rather than confusingly in module 4.

15 minute read

⚡

For the best experience: Download the native Atlas Desktop app for instant test running, native IDE sync, and 100% offline practice.

Download Desktop App→

Every exercise in this course runs the same way. Taking ten minutes to verify your local environment now prevents tooling issues in later modules. The introductory exercise verifies that Python, the editor, the test runner, and the mock client interact properly on your machine.

The minimal toolchain

The runtime requires three components:

Python 3.10 or newer.
unittest, which ships in the Python standard library.
mockllm, a single-file test mock with zero external dependencies, copied into each exercise workspace.

This design avoids external package managers, virtual environments, and API credentials, keeping tests self-contained and reproducible. The skills required to read unittest outputs translate directly to pytest and other test frameworks.

unittest tests the Python standard library itself. Its output format maps directly to the test reports generated by broader Python testing tools.

How grading works

When an exercise opens, the workspace copies scaffold.py to solution.py. The file solution.py stores your code and persists across editor restarts.

The test file test.py imports directly from solution.py:

from solution import (
    count_words,
    first_reply,
    last_user_message,
    role_counts,
    summarise_messages,
)

The test runner tests both user solutions and reference solutions against the identical test suite. The build pipeline runs reference.py against test.py in continuous integration; if reference code fails any assertion, the lesson cannot build.

Because test.py imports functions by name, preserving function signatures is mandatory. Renaming count_words to word_count triggers an immediate ImportError:

ImportError: cannot import name 'count_words' from 'solution' (/.../solution.py)

Modify function bodies freely, but keep function names and parameter lists intact.

Reading a test failure

Consider a test failure caused by using content.split(" ") instead of content.split():

test_an_empty_string_is_zero (__main__.TestCountingWords.test_an_empty_string_is_zero) ... FAIL
test_collapses_runs_of_whitespace (__main__.TestCountingWords.test_collapses_runs_of_whitespace) ... FAIL
test_counts_words (__main__.TestCountingWords.test_counts_words) ... ok

======================================================================
FAIL: test_an_empty_string_is_zero (__main__.TestCountingWords.test_an_empty_string_is_zero)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/Users/you/exercises/check-your-setup/test.py", line 34, in test_an_empty_string_is_zero
    self.assertEqual(count_words(""), 0)
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
AssertionError: 1 != 0

----------------------------------------------------------------------
Ran 16 tests in 0.001s

FAILED (failures=3)

Read the traceback from the bottom:

FAILED (failures=3) indicates the total failure count.
AssertionError: 1 != 0 shows the mismatch. The left value is the output returned by your code; the right value is the expected output.
The lines above the assertion show the test file location and the specific call under test (count_words("")).
The test name test_an_empty_string_is_zero describes the specific behavior being checked.

Custom assertion messages provide additional context:

AssertionError: 1 != 0 : content is None on a turn that only calls a tool, so this has to return a number rather than raise

Text following the colon explains the rationale for the test case.

FAIL indicates an unmet assertion where code executed but returned an unexpected value. ERROR indicates an unhandled exception during test execution, pointing to an exception in solution.py. Resolve ERROR tracebacks first, as fixing exceptions often clears multiple assertion failures.

Running tests from the command line

Run tests from the terminal in the exercise directory:

python3 test.py                                        # run all tests
python3 test.py TestCountingWords                      # run one test class
python3 test.py TestCountingWords.test_none_is_zero    # run one specific test

Isolating a single test case speeds up debugging. When a single logic error fails multiple tests within a class, running the simplest failing test provides the cleanest debugging signal.

unittest executes test methods in alphabetical order. Rather than debugging whichever test appears first in the terminal output, select the test case with the minimal input, such as empty or zero-length arguments.

Troubleshooting Python versions

Verify your installed interpreter version:

python3 --version

If the command prints Python 3.10.x or newer, the setup is complete.

On Windows systems, use the Python launcher py:

py -3 --version
py -3 test.py

If your system has Python 3.9 or older, upgrade to 3.10 or higher. The exercises rely on standard library features introduced in 3.10, including union type annotations (str | None) and sys.stdlib_module_names.

On macOS, install Python via python.org or Homebrew to run alongside the default system interpreter.

Exercise specification

Implement five utility functions for processing chat message sequences:

count_words: count words in a message body.
role_counts: tally message counts per role.
last_user_message: locate the most recent message with role user.
summarise_messages: generate a single-line summary string.
first_reply: execute a single completion call via MockClient.

Pay attention to edge cases:

str.split() without arguments collapses consecutive whitespace and returns an empty list for empty strings (""), whereas str.split(" ") returns [""].
To find the last user message in multi-turn dialogues, iterate through the message list in reverse order.

Foundations

Check your setup

What the toolchain is, how an exercise is graded, and how to read a unittest failure. Then an easy exercise whose only job is to break loudly now rather than confusingly in module 4.

15 minute read

⚡

For the best experience: Download the native Atlas Desktop app for instant test running, native IDE sync, and 100% offline practice.

Download Desktop App→

Coding Objective

Implement your solution in the editor on the right or work in your local IDE. All unit tests run against your code in real-time.

Language: Python 3.10+Runner: Local / Pyodide

Exercise

check-your-setup

16 tests, graded on your machine in about a second. Stuck for 10 minutes? The desktop app will offer you the reference solution.

solution.py

"""
Check your setup.

Five small functions over the one data structure this whole course is built on:
a list of chat messages. Nothing here is hard. It is here so that when something
in your toolchain is broken you find out in the first ten minutes rather than in
module four.

Run `python3 test.py` when you want to see how you are doing.
"""

from __future__ import annotations

def count_words(content: str | None) -> int:
    """
    Count the whitespace separated words in one message's content.

Args:
        content: the text of a message, or None. None is not an error here. An
            assistant turn that only calls a tool carries no text at all, and
            you meet that in the next lesson, so every function that touches
            content has to survive it.

Returns:
        The number of words. Runs of spaces, tabs and newlines count as a single
        separator, which is what str.split() with no argument already does for
        you. Both None and "" count zero.
    """
    raise NotImplementedError

def role_counts(messages: list[dict]) -> dict[str, int]:
    """
    How many messages each role sent.

Args:
        messages: dicts shaped like {"role": "user", "content": "hello there"}.

Returns:
        A dict mapping role to count, holding only the roles that actually
        appear. An empty list gives an empty dict.

Do not pre-seed the roles you expect. A conversation can carry "system",
        "user", "assistant" and "tool" turns, and reporting {"tool": 0} for a
        conversation that never called a tool is a claim your caller will read
        as fact.
    """
    raise NotImplementedError

def last_user_message(messages: list[dict]) -> str | None:
    """
    The content of the most recent message whose role is "user".

Search from the end of the list, not the start. By the time you are running
    an agent the list holds several user turns, the model's replies, and the
    results of every tool it called, and the question you are answering is the
    last one, never the first.

Returns:
        The content of that message, or None when no message has role "user".
        Those two cases are deliberately not distinguished here, which is fine
        for a helper this size and would not be fine in an agent: a caller that
        needs to tell "nobody has asked anything yet" from "the last question
        arrived empty" has to be given the message, not its content.
    """
    raise NotImplementedError

def summarise_messages(messages: list[dict]) -> str:
    """
    One line describing a whole conversation.

Returns:
        "N messages, M words", where N is the number of messages and M is the
        total word count across every message's content.

Nothing is pluralised: a single message gives "1 messages, 4 words".
        Read that format twice. Matching a string exactly is most of what a test
        suite ever asks of you, and a wrong comma is a red test.

Examples:
        >>> summarise_messages([{"role": "user", "content": "hello there"}])
        '1 messages, 2 words'
        >>> summarise_messages([])
        '0 messages, 0 words'
    """
    raise NotImplementedError

def first_reply(client) -> str:
    """
    Send one message to the model and return the text that comes back.

Send a single user message with the content "Hello." and model="mock", then
    dig the assistant's text out of the response:

response = client.chat.completions.create(
            model="mock",
            messages=[{"role": "user", "content": "Hello."}],
        )
        response.choices[0].message.content

Both arguments have to be named. create() takes keyword arguments only, so
    passing the message list positionally raises TypeError before anything else
    happens. Real provider clients are the same, for the same reason: a call with
    a dozen optional parameters is unreadable when they are positional.

The nesting on the way out is deep for a one line answer. That is not the
    mock being awkward. It is the shape every OpenAI compatible provider returns,
    and the next lesson is about why each layer exists.

Args:
        client: a mockllm.MockClient. Call it exactly once.

Returns:
        The assistant's reply text.
    """
    raise NotImplementedError

Or use the desktop app