Architecture & Codebase Exploration

# Colab cell — pure Python, no key needed. Builds a tiny sandbox repo on
# disk so the three tools actually run against real files.
import subprocess, pathlib

REPO = pathlib.Path("sandbox/repo").resolve()   # absolute so containment checks work
REPO.mkdir(parents=True, exist_ok=True)
(REPO / "pricing.py").write_text(
    "def calculate_discount(price, pct):\n"
    "    return price * (pct / 100)\n")
(REPO / "utils.py").write_text(
    "def clamp(x, lo, hi):\n    return max(lo, min(x, hi))\n")

def search_symbol(pattern: str, max_results: int = 40) -> str:
    """Grep the repo for a symbol or error string. Ripgrep if available."""
    try:
        out = subprocess.run(
            ["rg", "-n", "--max-count", "3", pattern, str(REPO)],
            capture_output=True, text=True, timeout=20,
        ).stdout
    except FileNotFoundError:
        out = subprocess.run(
            ["grep", "-rn", pattern, str(REPO)],
            capture_output=True, text=True, timeout=20,
        ).stdout
    lines = out.splitlines()[:max_results]
    return "\n".join(lines) or "no matches"

def list_dir(rel: str = ".") -> str:
    target = (REPO / rel).resolve()
    # Constrain to the repo — never let the agent wander the filesystem.
    if REPO not in target.parents and target != REPO:
        return "error: path escapes the repo"
    entries = sorted(p.name + ("/" if p.is_dir() else "") for p in target.iterdir())
    return "\n".join(entries)

def read_file(rel: str, start: int = 1, end: int = 400) -> str:
    target = (REPO / rel).resolve()
    if REPO not in target.parents and target != REPO:
        return "error: path escapes the repo"
    if not target.is_file():
        return f"error: {rel} is not a file"
    text = target.read_text(errors="replace").splitlines()
    window = text[start - 1:end]
    # Line numbers help the model reference and later edit precisely.
    return "\n".join(f"{i + start:>5}  {ln}" for i, ln in enumerate(window))


# drive the agent's three "eyes" against the sandbox repo:
print("search_symbol('calculate_discount'):\n" + search_symbol("calculate_discount"))
print("\nlist_dir('.'):\n" + list_dir("."))
print("\nread_file('pricing.py'):\n" + read_file("pricing.py"))

# Colab cell — run once. Set your key in the 🔑 panel (name it
# ANTHROPIC_API_KEY) or paste it. This is the assembled agent loop: it needs
# the tools from the previous cell wired into EXPLORE_TOOLS (schemas) and a
# run_explore_tool dispatcher, plus a real repo — it's here to read and adapt.
!pip install -q anthropic

import os
try:
    from google.colab import userdata
    os.environ["ANTHROPIC_API_KEY"] = userdata.get("ANTHROPIC_API_KEY")
except Exception:
    from getpass import getpass
    os.environ.setdefault("ANTHROPIC_API_KEY", getpass("Anthropic API key: "))

import json, pathlib
import anthropic

client = anthropic.Anthropic()
PLAN_PATH = pathlib.Path("sandbox/plan.json")

def explore_and_plan(issue_text: str) -> dict:
    system = (
        "You are a senior engineer triaging a bug. Use search_symbol, "
        "list_dir, and read_file to locate the relevant code. Do NOT guess "
        "at file contents — read them. When confident, call record_plan with "
        "the files you will edit, your understanding of the bug, and the fix "
        "approach. Read only what you need; the repo is large."
    )
    messages = [{"role": "user", "content": f"Issue:\n{issue_text}"}]
    while True:
        resp = client.messages.create(
            model="claude-sonnet-5", max_tokens=4096,
            system=system, tools=EXPLORE_TOOLS,   # search/list/read/record_plan
            messages=messages,
        )
        if resp.stop_reason != "tool_use":
            continue
        messages.append({"role": "assistant", "content": resp.content})
        results = []
        plan = None
        for block in resp.content:
            if block.type != "tool_use":
                continue
            if block.name == "record_plan":
                plan = block.input          # {"files":[...], "bug":"...", "fix":"..."}
            else:
                results.append(run_explore_tool(block))
        if plan is not None:
            # Checkpoint: survives a crash so W22's implement stage can resume.
            PLAN_PATH.write_text(json.dumps(plan, indent=2))
            return plan
        messages.append({"role": "user", "content": results})