Setup, Schema & the Mock Cluster

Before writing any logic you lay down the folder structure. These terminal commands create the project inside the course starter kit so it reuses the same virtualenv and .env file you set up in earlier chapters — no new setup.

1. cd llm-course-starter then source .venv/bin/activate moves into the starter kit and turns on its virtual environment — an isolated Python with the course's libraries already installed.
2. pip install pytest adds the test runner you'll use in Step 5.
3. mkdir -p devops-agent/{agent,mock,runbooks,tests,evals} creates the project folder and its five sub-folders in one line. The {...} is shell shorthand that expands to five separate mkdirs.
4. touch agent/__init__.py mock/__init__.py creates empty __init__.py files. That one detail is what makes agent and mock real Python packages you can import from — without them, from mock import cluster later would fail.

What the output means: No visible output — success is silent. Afterwards the tree shown below exists: agent/ (the brain), mock/ (the fake cluster), runbooks/, tests/, and evals/.

Try this: Run ls devops-agent to confirm the five folders exist. If a later step says No module named 'mock', the missing __init__.py is the usual culprit — check it's there.

This file defines the two data shapes the whole project is built around, using Pydantic — a library that lets you declare exactly what fields a piece of data has and what type each one is, then checks the data matches. Think of it as a typed form the rest of the code must fill in correctly.

1. class RiskClass(str, Enum) is an enum: a fixed set of allowed values. An action is exactly one of READ_ONLY, REVERSIBLE, SIGNIFICANT, or IRREVERSIBLE — the four risk levels, from 'just looking' (🟢) to 'delete / apply in prod' (🔴).
2. class Diagnosis(BaseModel) is the structured answer the agent must produce. BaseModel means Pydantic will validate every field.
3. The fields spell out a complete diagnosis: likely_cause (a sentence), evidence (a list[str] — the facts it cites), suggested_fix, and fix_risk which is a RiskClass — so the fix is tagged with its danger level.
4. confidence: float = Field(ge=0.0, le=1.0) forces the number to sit between 0 and 1 (ge = greater-or-equal, le = less-or-equal). runbook_ref: Optional[str] = None is an optional pointer to a doc, defaulting to nothing.

What the output means: Nothing runs — this is a definition. But now anywhere in the code, a Diagnosis is guaranteed to have these fields with these types, or Pydantic raises an error before the bad data can spread.

Try this: Later the safety gate will read fix_risk to decide what's allowed. Because it's an enum, a typo like "irreversable" is impossible — that is the whole point of using an enum instead of a plain string.

The mock cluster is a fake Kubernetes cluster that lives entirely in a JSON file. It lets you develop something dangerous safely: it's deterministic (same answer every time), free, and physically cannot break anything real. Two files make it up — the data (fixtures.json) and the reader (cluster.py).

1. fixtures.json is just the cluster's state written down: a list of pods and deploys. One pod is stuck in CrashLoopBackOff with real error logs, and a deploy 18 minutes ago changed the DATABASE_URL secret — that's a deliberate story the agent should piece together.
2. In cluster.py, _STATE = json.load(open(...)) reads that JSON once into memory. The os.path.dirname(__file__) part means it finds the file next to the module, no matter which folder you run from.
3. get_pods(namespace="staging") returns the pods in a namespace — a plain list comprehension that filters _STATE["pods"].
4. get_logs(pod, ...) looks the pod up, and if it isn't found returns a friendly "Error: pod '...' not found" string instead of crashing. Otherwise it joins the last lines log entries with newlines.

What the output means: Every function only reads — it hands back data and changes nothing. get_logs("checkout-api-7d9f"), for example, returns the three log lines including the password authentication failed error.

Try this: Because it's all read-only, this is exactly the surface the read-only diagnostician in Lab 8b needs. Actions that change things live in a separate file (Step 4) so the safety gate can be tested without any risk.

These are the actions the agent might eventually take — restart a rollout, open a pull request, delete a pod. While you're building, they are simulated: each just returns a string describing what it would do and changes nothing at all.

1. Every function returns an f-string like f"[mock] restarted rollout {namespace}/{name}". The [mock] prefix is a constant reminder that nothing real happened.
2. The functions span the risk range on purpose: rollout_restart and open_pr are reversible, while delete_pod is irreversible — the dangerous kind the safety gate must guard.
3. Because they only return text, you can wire them into the full safety gate in Lab 8c and watch it allow, block, or ask-for-approval on each one — with zero chance of touching real infrastructure.

What the output means: Calling any of these just gives you a [mock] ... sentence. delete_pod("x") returns "[mock] DELETED pod staging/x" and the real cluster is untouched.

Try this: Splitting reads (cluster.py) from writes (actions.py) is the key design move: it means the diagnostician literally has no function that can change anything, which is a much stronger safety guarantee than 'we promise not to'.

This is your first test file. Tests are small functions that check your code does what you expect, automatically. These need no API key and cost nothing — they just poke the mock cluster and assert the answers are right.

1. The two sys.path.insert(...) / from mock import cluster lines at the top make the mock package importable when pytest runs the file.
2. Each def test_...() is one test. pytest finds every function whose name starts with test_ and runs it. Inside, assert checks a condition — if it's false, the test fails and pytest tells you exactly where.
3. test_mock_finds_crashloop_pod proves the fixtures load and lookup works. test_mock_logs_contain_root_cause proves the real error is present in the logs (so the agent will have genuine evidence). test_missing_pod_is_handled asks for "does-not-exist" and checks the reply starts with "Error" — proving bad input doesn't crash anything.
4. You run them with python -m pytest tests/ -v from inside devops-agent.

What the output means: pytest prints one line per test with PASSED, then a summary: 3 passed in 0.04s. Green here means the foundation is solid — with no API key and no cost. That's the mock-first payoff.

Try this: Break a test on purpose: change "CrashLoopBackOff" in the assert to "Running" and re-run. pytest will show a FAILED with the expected-vs-actual values — that's the feedback loop tests give you.