AI Engineering: Agents and Applications › AI Coding Agents › Day 302

Hands-on lab — Day 302: The AI Coding Landscape

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/coding_agent_engine.py

Test

bash tests/run_tests.sh

File tree

examples/coding_agent_engine.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/run-output.txt
expected-output/starter-run.txt
expected-output/test-output.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/coding_agent_engine.py
tests/run_tests.sh
tests/test_coding_agent.py
troubleshooting.md

Lab README

Day 302 Lab: The AI Coding Landscape

Lesson

  • Lesson title: The AI Coding Landscape
  • Day number: 302 of 365
  • Lesson article: https://ai-roadmap-365.github.io/day-302-the-ai-coding-landscape
  • Lab files: everything you need is in this directory — follow “How to run” below.
  • Browse the course locally: from the repository root, this lab also appears in the course website at /labs/day-302-the-ai-coding-landscape when the site is running.

Purpose

Construct an AI Coding Agent Engine in Python featuring AST-based repository mapping, targeted search-and-replace patch application, and automated test verification.

Learning objectives

  • Build an AST-based repository structure generator.
  • Implement targeted search-and-replace file patch application.
  • Execute automated test verification harnesses and capture stdout/stderr diagnostics.
  • Handle missing files, target mismatches, and syntax validation.

Prerequisites

  • Python 3.10+ installed
  • pytest installed

Supported operating systems

  • macOS, Linux, Windows WSL2

Hardware requirements

  • Standard CPU, 512MB RAM

Required software

  • Python 3.10+, pytest

Free and open-source options

  • Python Standard Library, Pytest

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/coding_agent_engine.py: Starter implementation skeleton
  • examples/coding_agent_engine.py: Verified reference implementation
  • tests/test_coding_agent.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/coding_agent_engine.py

What the commands do

  • Generates repository structural map, applies search-and-replace patches, and runs test harness.

Expected output

Repo map preview:
 File: starter/coding_agent_engine.py
  class CodingAgentEngine:
  def __init__(self, workspace_root: str):
  def generate_repo_map(self) -> str:
  def apply_search_replace(self, file_rel_path: str, search_block: str, replace_block: str) -> str:
  def run_verification_tests(self, test_command: str = "python3 -m unittest discover") -> Dict[str, Any]:
File: examples/coding_agent_engine.py
  class CodingAgentEngine:
  def __init__(self, workspace_root: str):
  def generate_repo_map(self) -> str:
  def apply_search_replace(self, file_rel_path: str, search_block: str, replace_block: str) -> str:
  def run_verification_tests(self, test_command: str = "python3 -m unittest discover") -> Dict[str, Any]:

Validation steps

Run test runner:

bash tests/run_tests.sh

Tests

The test suite validates:

  • Repo map generation and class/def symbol extraction
  • Successful search-and-replace patch modification
  • Missing file and search block mismatch error handling
  • Subprocess test execution and stdout/stderr capture

Cleanup

rm -rf .pytest_cache __pycache__ .venv

Troubleshooting

Ensure workspace root is a valid directory path.

Security notes

Runs completely offline on local CPU.

Extension exercises

Add unified diff parsing support.

Day number: 302 of 365

Expected output

FIELDS.md

# Measured Values
- `repo_files_indexed`: 1
- `patches_applied`: 1

examples-run.txt

Repo map preview:
 File: starter/coding_agent_engine.py
  class CodingAgentEngine:
  def __init__(self, workspace_root: str):
  def generate_repo_map(self) -> str:
  def apply_search_replace(self, file_rel_path: str, search_block: str, replace_block: str) -> str:
  def run_verification_tests(self, test_command: str = "python3 -m unittest discover") -> Dict[str, Any]:
File: examples/coding_agent_engine.py
  class CodingAgentEngine:
  def __init__(self, workspace_root: str):
  def generate_repo_map(self) -> str:
  def apply_search_replace(self, file_rel_path: str, search_block: str, replace_block: str) -> str:
  def run_verification_tests(self, test_command: str = "python3 -m unittest discover") -> Dict[str, Any]:

measured-values.txt

repo_files_indexed=1
patches_applied=1

run-output.txt

Repo map preview:
 File: starter/coding_agent_engine.py
  class CodingAgentEngine:
  def __init__(self, workspace_root: str):
  def generate_repo_map(self) -> str:
  def apply_search_replace(self, file_rel_path: str, search_block: str, replace_block: str) -> str:
  def run_verification_tests(self, test_command: str = "python3 -m unittest discover") -> Dict[str, Any]:
File: examples/coding_agent_engine.py
  class CodingAgentEngine:
  def __init__(self, workspace_root: str):
  def generate_repo_map(self) -> str:
  def apply_search_replace(self, file_rel_path: str, search_block: str, replace_block: str) -> str:
  def run_verification_tests(self, test_command: str = "python3 -m unittest discover") -> Dict[str, Any]:

starter-run.txt

An untouched starter fails the suite. Captured from a real run:


self = <examples.coding_agent_engine.CodingAgentEngine object at 0x10770e8b0>
test_command = 'python3 -c \'print("Tests OK")\''

    def run_verification_tests(self, test_command: str='python3 -m unittest discover') -> Dict[str, Any]:
>       raise NotImplementedError('TASK 3: implement run_verification_tests.')
E       NotImplementedError: TASK 3: implement run_verification_tests.

examples/coding_agent_engine.py:24: NotImplementedError
=========================== short test summary info ============================
FAILED tests/test_coding_agent.py::test_generate_repo_map - NotImplementedErr...
FAILED tests/test_coding_agent.py::test_apply_search_replace_success - NotImp...
FAILED tests/test_coding_agent.py::test_apply_search_replace_missing_file - N...
FAILED tests/test_coding_agent.py::test_apply_search_replace_target_not_found
FAILED tests/test_coding_agent.py::test_run_verification_tests - NotImplement...
============================== 5 failed in 0.04s ===============================

Implement each TASK in starter/, copy it over examples/, and the same
suite goes green.

test-output.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-302-the-ai-coding-landscape
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_coding_agent.py::test_generate_repo_map PASSED                [ 20%]
tests/test_coding_agent.py::test_apply_search_replace_success PASSED     [ 40%]
tests/test_coding_agent.py::test_apply_search_replace_missing_file PASSED [ 60%]
tests/test_coding_agent.py::test_apply_search_replace_target_not_found PASSED [ 80%]
tests/test_coding_agent.py::test_run_verification_tests PASSED           [100%]

============================== 5 passed in 0.05s ===============================

test-run.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-302-the-ai-coding-landscape
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_coding_agent.py::test_generate_repo_map PASSED                [ 20%]
tests/test_coding_agent.py::test_apply_search_replace_success PASSED     [ 40%]
tests/test_coding_agent.py::test_apply_search_replace_missing_file PASSED [ 60%]
tests/test_coding_agent.py::test_apply_search_replace_target_not_found PASSED [ 80%]
tests/test_coding_agent.py::test_run_verification_tests PASSED           [100%]

============================== 5 passed in 0.05s ===============================

Source files

examples/coding_agent_engine.py (2332 bytes)
import os
import subprocess
from typing import Dict, Any, List

class CodingAgentEngine:
    def __init__(self, workspace_root: str):
        self.workspace_root = os.path.realpath(workspace_root)
        
    def generate_repo_map(self) -> str:
        repo_map_lines = []
        for root, _, files in os.walk(self.workspace_root):
            for file in sorted(files):
                if file.endswith(".py") and not file.startswith("test_"):
                    rel_path = os.path.relpath(os.path.join(root, file), self.workspace_root)
                    repo_map_lines.append(f"File: {rel_path}")
                    with open(os.path.join(root, file), "r", encoding="utf-8") as f:
                        for line in f:
                            if line.strip().startswith("def ") or line.strip().startswith("class "):
                                repo_map_lines.append(f"  {line.strip()}")
        return "\n".join(repo_map_lines)
        
    def apply_search_replace(self, file_rel_path: str, search_block: str, replace_block: str) -> str:
        abs_path = os.path.join(self.workspace_root, file_rel_path)
        if not os.path.exists(abs_path):
            raise FileNotFoundError(f"File not found: {file_rel_path}")
            
        with open(abs_path, "r", encoding="utf-8") as f:
            content = f.read()
            
        if search_block not in content:
            raise ValueError(f"Target search block not found in {file_rel_path}")
            
        new_content = content.replace(search_block, replace_block, 1)
        with open(abs_path, "w", encoding="utf-8") as f:
            f.write(new_content)
            
        return f"Successfully updated {file_rel_path}."
        
    def run_verification_tests(self, test_command: str = "python3 -m unittest discover") -> Dict[str, Any]:
        result = subprocess.run(
            test_command,
            shell=True,
            cwd=self.workspace_root,
            capture_output=True,
            text=True
        )
        return {
            "exit_code": result.returncode,
            "passed": result.returncode == 0,
            "stdout": result.stdout,
            "stderr": result.stderr
        }

if __name__ == "__main__":
    engine = CodingAgentEngine(".")
    print("Repo map preview:\n", engine.generate_repo_map())
metadata.yml (406 bytes)
lesson_id: D302
day: 302
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/coding_agent_engine.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (14 bytes)
pytest>=7.0.0
starter/coding_agent_engine.py (1080 bytes)
"""STARTER -- implement each TASK below, then run the tests.

Every function that raises NotImplementedError is yours to write. The
imports, constants and data structures are given; the logic is not.
Run `bash tests/run_tests.sh` to see which tasks are still outstanding.
"""

import os
import subprocess
from typing import Dict, Any, List

class CodingAgentEngine:

    def __init__(self, workspace_root: str):
        self.workspace_root = os.path.realpath(workspace_root)

    def generate_repo_map(self) -> str:
        raise NotImplementedError('TASK 1: implement generate_repo_map.')

    def apply_search_replace(self, file_rel_path: str, search_block: str, replace_block: str) -> str:
        raise NotImplementedError('TASK 2: implement apply_search_replace.')

    def run_verification_tests(self, test_command: str='python3 -m unittest discover') -> Dict[str, Any]:
        raise NotImplementedError('TASK 3: implement run_verification_tests.')
if __name__ == '__main__':
    engine = CodingAgentEngine('.')
    print('Repo map preview:\n', engine.generate_repo_map())
tests/run_tests.sh (253 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
if [ -n "$PYTEST" ]; then
    $PYTEST tests/test_*.py -v
elif command -v pytest &> /dev/null; then
    pytest tests/test_*.py -v
else
    python3 -m unittest discover -s tests -p 'test_*.py' -v
fi
tests/test_coding_agent.py (2384 bytes)
import pytest
import tempfile
import os
from examples.coding_agent_engine import CodingAgentEngine

def test_generate_repo_map():
    with tempfile.TemporaryDirectory() as tmpdir:
        sample_file = os.path.join(tmpdir, "calculator.py")
        with open(sample_file, "w", encoding="utf-8") as f:
            f.write("class Calculator:\n    def add(self, a, b):\n        return a + b\n")
            
        engine = CodingAgentEngine(tmpdir)
        repo_map = engine.generate_repo_map()
        assert "File: calculator.py" in repo_map
        assert "class Calculator:" in repo_map
        assert "def add(self, a, b):" in repo_map

def test_apply_search_replace_success():
    with tempfile.TemporaryDirectory() as tmpdir:
        sample_file = os.path.join(tmpdir, "math_ops.py")
        with open(sample_file, "w", encoding="utf-8") as f:
            f.write("def divide(a, b):\n    return a / b\n")
            
        engine = CodingAgentEngine(tmpdir)
        search_block = "    return a / b"
        replace_block = "    if b == 0:\n        return 0\n    return a / b"
        
        msg = engine.apply_search_replace("math_ops.py", search_block, replace_block)
        assert "Successfully updated math_ops.py" in msg
        
        with open(sample_file, "r", encoding="utf-8") as f:
            updated = f.read()
        assert "if b == 0:" in updated

def test_apply_search_replace_missing_file():
    with tempfile.TemporaryDirectory() as tmpdir:
        engine = CodingAgentEngine(tmpdir)
        with pytest.raises(FileNotFoundError):
            engine.apply_search_replace("nonexistent.py", "a", "b")

def test_apply_search_replace_target_not_found():
    with tempfile.TemporaryDirectory() as tmpdir:
        sample_file = os.path.join(tmpdir, "app.py")
        with open(sample_file, "w", encoding="utf-8") as f:
            f.write("x = 10\n")
            
        engine = CodingAgentEngine(tmpdir)
        with pytest.raises(ValueError) as exc:
            engine.apply_search_replace("app.py", "y = 20", "y = 30")
        assert "not found" in str(exc.value)

def test_run_verification_tests():
    with tempfile.TemporaryDirectory() as tmpdir:
        engine = CodingAgentEngine(tmpdir)
        res = engine.run_verification_tests("python3 -c 'print(\"Tests OK\")'")
        assert res["passed"] is True
        assert "Tests OK" in res["stdout"]

Troubleshooting

Troubleshooting - Day 302

Ensure search block indentation matches file content exactly.

Security notes

Security - Day 302

Execute test commands in isolated sandboxed temporary directories.