patchpilot 0.1.0__py3-none-any.whl

patchpilot/__init__.py

@@ -0,0 +1,3 @@
+"""patchpilot: an AI agent that upgrades dependencies and fixes what breaks."""
+
+__version__ = "0.1.0"

patchpilot/agent.py

@@ -0,0 +1,90 @@
+"""The agent loop: send the conversation to Claude, run the tools it asks for, repeat."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import anthropic
+
+from patchpilot.tools import TOOL_FUNCTIONS, ToolError, Workspace
+
+MODEL = "claude-opus-5-5"
+
+# Anthropic-hosted tool: Claude fetches URLs (like changelogs) itself, no code needed on our side.
+# It only fetches URLs that already appear in the conversation, e.g. from get_latest_version.
+WEB_FETCH_TOOL = {"type": "web_fetch_20260209", "name": "web_fetch", "max_uses": 8}
+
+
+def execute_tool(ws: Workspace, name: str, tool_input: dict) -> tuple[str, bool]:
+    """Run one tool. Returns (result_text, is_error)."""
+    func = TOOL_FUNCTIONS.get(name)
+    if func is None:
+        return f"Unknown tool '{name}'.", True
+    try:
+        return func(ws, **tool_input), False
+    except ToolError as e:
+        return str(e), True
+    except TypeError as e:
+        return f"Invalid arguments for '{name}': {e}", True
+
+
+def run_agent(
+    ws: Workspace,
+    system: str,
+    task: str,
+    tools: list[dict],
+    max_turns: int = 30,
+    client: anthropic.Anthropic | None = None,
+    on_tool_call: Callable[[str, dict], None] | None = None,
+) -> str:
+    """Run the agent until it finishes and return its final text."""
+    client = client or anthropic.Anthropic()
+    allowed = {t["name"] for t in tools if "input_schema" in t}
+    messages: list[dict] = [{"role": "user", "content": task}]
+
+    for _ in range(max_turns):
+        response = client.beta.messages.create(
+            model=MODEL,
+            max_tokens=16000,
+            system=system,
+            tools=tools,
+            messages=messages,
+            output_config={"effort": "high"},
+            # If a request is declined by a safety classifier, retry on the server's default
+            # fallback model instead of failing outright.
+            betas=["server-side-fallback-2026-07-01"],
+            fallbacks="default",
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason == "refusal":
+            raise RuntimeError("Claude declined this request.")
+        if response.stop_reason == "max_tokens":
+            raise RuntimeError("Response hit max_tokens before finishing.")
+        if response.stop_reason == "pause_turn":
+            continue
+
+        tool_uses = [b for b in response.content if b.type == "tool_use"]
+        if not tool_uses:
+            return "\n".join(b.text for b in response.content if b.type == "text")
+
+        tool_results = []
+        for block in tool_uses:
+            if on_tool_call:
+                on_tool_call(block.name, block.input)
+            if block.name in allowed:
+                result, is_error = execute_tool(ws, block.name, block.input)
+            else:
+                result, is_error = f"Tool '{block.name}' is not available here.", True
+            tool_results.append(
+                {
+                    "type": "tool_result",
+                    "tool_use_id": block.id,
+                    "content": result,
+                    "is_error": is_error,
+                }
+            )
+        # All results for one turn go back in a single user message.
+        messages.append({"role": "user", "content": tool_results})
+
+    raise RuntimeError(f"Agent did not finish within {max_turns} turns.")

patchpilot/analyze.py

@@ -0,0 +1,36 @@
+"""`patchpilot analyze`: a read-only report of what could be upgraded."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from patchpilot.agent import run_agent
+from patchpilot.tools import READ_TOOL_SCHEMAS, Workspace
+
+SYSTEM_PROMPT = """\
+You are patchpilot, an agent that keeps a Python project's dependencies up to date.
+
+Your job right now is to produce an upgrade report. Use the tools to:
+1. Read the project's declared dependencies.
+2. Look up the latest version of each one on PyPI.
+3. Run the test suite to establish a baseline.
+
+Then finish with a concise report in Markdown:
+- A table of dependencies: name, current specifier, latest version, and whether the
+  current specifier already allows the latest version.
+- Which upgrades look like major-version jumps that are likely to need code changes.
+- The baseline test result.
+- A recommended order to upgrade in, with one line of reasoning each.
+
+You can only read and run tests in this phase; do not suggest that you changed any files.\
+"""
+
+
+def analyze(ws: Workspace, on_tool_call: Callable[[str, dict], None] | None = None) -> str:
+    return run_agent(
+        ws,
+        system=SYSTEM_PROMPT,
+        task=f"Analyze the project at {ws.root} and write the report.",
+        tools=READ_TOOL_SCHEMAS,
+        on_tool_call=on_tool_call,
+    )

patchpilot/cli.py

@@ -0,0 +1,151 @@
+"""Command-line entry point.
+
+patchpilot analyze <project>            read-only upgrade report
+patchpilot upgrade <project> <package>  upgrade one package and fix what breaks
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shlex
+import sys
+from pathlib import Path
+
+import anthropic
+from dotenv import find_dotenv, load_dotenv
+
+from patchpilot.agent import MODEL
+from patchpilot.analyze import analyze
+from patchpilot.github import GitHubError
+from patchpilot.sandbox import DEFAULT_IMAGE, SandboxError
+from patchpilot.tools import Workspace
+from patchpilot.upgrade import UpgradeError, upgrade
+
+
+def log_tool_call(name: str, tool_input: dict) -> None:
+    # File contents can be long; show just the path for writes.
+    shown = {k: v for k, v in tool_input.items() if k not in ("content", "old_text", "new_text")}
+    print(f"  → {name} {json.dumps(shown)}", file=sys.stderr)
+
+
+def explain_api_error(e: anthropic.AnthropicError) -> str:
+    """Turn an Anthropic SDK error into one sentence the user can act on."""
+    detail = str(e)
+    if isinstance(e, anthropic.APIStatusError) and isinstance(e.body, dict):
+        detail = e.body.get("error", {}).get("message", detail)
+
+    if isinstance(e, anthropic.BadRequestError) and "credit balance" in detail:
+        return (
+            "Your Anthropic account is out of credit. Add some at "
+            "https://console.anthropic.com/settings/billing and run patchpilot again."
+        )
+    if isinstance(e, anthropic.AuthenticationError):
+        return (
+            "Your Anthropic API key was rejected. Check ANTHROPIC_API_KEY in your .env file "
+            "(keys are at https://console.anthropic.com/settings/keys)."
+        )
+    if isinstance(e, anthropic.PermissionDeniedError):
+        return f"Your API key doesn't have access to {MODEL}: {detail}"
+    if isinstance(e, anthropic.RateLimitError):
+        return "The Anthropic API is rate-limiting this key. Wait a minute and try again."
+    if isinstance(e, anthropic.APIConnectionError):
+        return "Couldn't reach the Anthropic API. Check your internet connection and try again."
+    if isinstance(e, anthropic.APIStatusError):
+        return f"The Anthropic API returned an error ({e.status_code}): {detail}"
+    # e.g. no API key configured at all
+    return f"Couldn't call the Anthropic API: {detail}"
+
+
+def log_status(message: str) -> None:
+    print(f"• {message}", file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="patchpilot",
+        description="An AI agent that upgrades your dependencies and fixes what breaks.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    analyze_p = sub.add_parser("analyze", help="Report what could be upgraded (changes nothing).")
+    analyze_p.add_argument("project", type=Path, help="Path to the project.")
+
+    upgrade_p = sub.add_parser(
+        "upgrade", help="Upgrade one package, fix the code, and commit it to a new branch."
+    )
+    upgrade_p.add_argument("project", type=Path, help="Path to the project (inside a git repo).")
+    upgrade_p.add_argument("package", help="Name of the package to upgrade, e.g. pydantic.")
+    upgrade_p.add_argument(
+        "--image",
+        default=DEFAULT_IMAGE,
+        help="Docker image to run the project in; pick one matching your Python version "
+        "(default: %(default)s).",
+    )
+    upgrade_p.add_argument(
+        "--pr",
+        action="store_true",
+        help="Push the branch and open a GitHub pull request (needs the gh CLI, logged in).",
+    )
+    upgrade_p.add_argument(
+        "--no-docker",
+        action="store_true",
+        help="Run in a local virtualenv instead of Docker. Faster, but the project's code "
+        "runs directly on your machine.",
+    )
+
+    for p in (analyze_p, upgrade_p):
+        p.add_argument(
+            "--test-command",
+            default="python -m pytest -q",
+            help="Command that runs the project's tests (default: %(default)s).",
+        )
+
+    args = parser.parse_args(argv)
+    project = args.project.expanduser().resolve()
+    if not project.is_dir():
+        parser.error(f"{project} is not a directory")
+    test_command = shlex.split(args.test_command)
+
+    # Look for .env in the directory patchpilot is run from, not where it's installed.
+    load_dotenv(find_dotenv(usecwd=True))
+
+    try:
+        if args.command == "analyze":
+            ws = Workspace(root=project, test_command=test_command)
+            print(analyze(ws, on_tool_call=log_tool_call))
+            return 0
+
+        result = upgrade(
+            project,
+            args.package,
+            test_command=test_command,
+            on_status=log_status,
+            on_tool_call=log_tool_call,
+            use_docker=not args.no_docker,
+            image=args.image,
+            open_pr=args.pr,
+        )
+    except (RuntimeError, UpgradeError, SandboxError, GitHubError) as e:
+        print(f"patchpilot: {e}", file=sys.stderr)
+        return 1
+    except anthropic.AnthropicError as e:
+        print(f"patchpilot: {explain_api_error(e)}", file=sys.stderr)
+        return 1
+
+    print(result.report)
+    print(file=sys.stderr)
+    if not result.committed:
+        log_status("The agent didn't change any files, so no branch was created.")
+        return 1
+    verdict = "✅ tests pass" if result.tests_passed else "❌ tests still failing"
+    log_status(f"Committed to branch {result.branch} ({verdict})")
+    if result.pr_url:
+        log_status(f"Pull request: {result.pr_url}")
+    else:
+        log_status(f"Review it with: git diff HEAD...{result.branch}")
+    return 0 if result.tests_passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

patchpilot/github.py

@@ -0,0 +1,83 @@
+"""Push the upgrade branch and open a pull request, using the GitHub CLI (`gh`).
+
+Going through `gh` means patchpilot never handles a GitHub token itself: it uses
+whatever account the user already logged in with (`gh auth login`).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class GitHubError(Exception):
+    """Pushing or opening the PR failed; the message is meant for the user."""
+
+
+def _run(cmd: list[str], cwd: Path) -> str:
+    proc = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise GitHubError(f"`{' '.join(cmd[:3])}` failed:\n{proc.stderr.strip()}")
+    return proc.stdout.strip()
+
+
+def check_ready(repo_root: Path, branch: str, remote: str = "origin") -> str:
+    """Check everything a PR needs before any work starts. Returns the base branch."""
+    if shutil.which("gh") is None:
+        raise GitHubError(
+            "--pr needs the GitHub CLI. Install it (brew install gh) and run: gh auth login"
+        )
+    if subprocess.run(["gh", "auth", "status"], capture_output=True).returncode != 0:
+        raise GitHubError("You're not logged in to the GitHub CLI. Run: gh auth login")
+
+    remotes = _run(["git", "remote"], repo_root).split()
+    if remote not in remotes:
+        raise GitHubError(
+            f"This repo has no '{remote}' remote, so there's nowhere to open a PR. "
+            "Push it to GitHub first."
+        )
+
+    base = _run(["git", "rev-parse", "--abbrev-ref", "HEAD"], repo_root)
+    if base == "HEAD":
+        raise GitHubError("You're in 'detached HEAD' state. Check out a branch first.")
+    on_remote = subprocess.run(
+        ["git", "ls-remote", "--exit-code", "--heads", remote, base],
+        cwd=repo_root,
+        capture_output=True,
+    )
+    if on_remote.returncode != 0:
+        raise GitHubError(
+            f"Branch '{base}' isn't on GitHub yet, so a PR can't target it. "
+            f"Push it first: git push -u {remote} {base}"
+        )
+    taken = subprocess.run(
+        ["git", "ls-remote", "--exit-code", "--heads", remote, branch],
+        cwd=repo_root,
+        capture_output=True,
+    )
+    if taken.returncode == 0:
+        raise GitHubError(
+            f"Branch '{branch}' already exists on GitHub (probably an earlier patchpilot PR). "
+            f"Merge or close that PR and delete the branch first."
+        )
+    return base
+
+
+def open_pull_request(
+    repo_root: Path,
+    branch: str,
+    base: str,
+    title: str,
+    body: str,
+    draft: bool,
+    remote: str = "origin",
+) -> str:
+    """Push the branch and open a PR. Returns the PR's URL."""
+    _run(["git", "push", "--quiet", "--set-upstream", remote, branch], repo_root)
+    cmd = ["gh", "pr", "create", "--head", branch, "--base", base, "--title", title]
+    cmd += ["--body", body]
+    if draft:
+        cmd.append("--draft")
+    # gh prints the new PR's URL as the last line of its output.
+    return _run(cmd, repo_root).splitlines()[-1]

patchpilot/sandbox.py

@@ -0,0 +1,114 @@
+"""Where the project's own code runs: a Docker container (default) or a local virtualenv.
+
+Only commands run here: installing packages and running the test suite. File reads and
+edits happen on the host, inside the temporary worktree, and the agent loop (with the API
+key) never enters the sandbox.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+
+DEFAULT_IMAGE = "python:3.13-slim"
+CONTAINER_ROOT = "/workspace"
+CONTAINER_VENV = "/tmp/venv"
+
+
+class SandboxError(Exception):
+    """The sandbox couldn't be created; the message is meant for the user."""
+
+
+class LocalSandbox:
+    """A fresh virtualenv on the host. No isolation beyond Python packages."""
+
+    def __init__(self, project: Path, venv_dir: Path):
+        self.project = project
+        self.venv_dir = venv_dir
+        self.python = str(venv_dir / "bin" / "python")
+
+    def __enter__(self) -> LocalSandbox:
+        subprocess.run([sys.executable, "-m", "venv", str(self.venv_dir)], check=True)
+        return self
+
+    def __exit__(self, *exc) -> None:
+        shutil.rmtree(self.venv_dir, ignore_errors=True)
+
+    def run(self, cmd: list[str], timeout: int) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            cmd, cwd=self.project, capture_output=True, text=True, timeout=timeout
+        )
+
+
+class DockerSandbox:
+    """A locked-down container that can see only the temporary worktree.
+
+    - mounts the worktree at /workspace and nothing else from the host
+    - runs as the host user (not root), with all Linux capabilities dropped
+    - caps memory, CPU and process count so runaway tests can't take down the machine
+    """
+
+    def __init__(self, worktree: Path, project_rel: Path, image: str = DEFAULT_IMAGE):
+        self.worktree = worktree
+        rel = project_rel.as_posix()
+        self.workdir = CONTAINER_ROOT if rel == "." else f"{CONTAINER_ROOT}/{rel}"
+        self.image = image
+        self.name = f"patchpilot-{uuid.uuid4().hex[:12]}"
+        self.python = f"{CONTAINER_VENV}/bin/python"
+
+    @staticmethod
+    def check_available() -> None:
+        if shutil.which("docker") is None:
+            raise SandboxError(
+                "Docker isn't installed. Install Docker Desktop, or run with --no-docker "
+                "to use a local virtualenv instead (less isolated)."
+            )
+        info = subprocess.run(["docker", "info"], capture_output=True, text=True)
+        if info.returncode != 0:
+            raise SandboxError(
+                "Docker is installed but not running. Start Docker Desktop and try again."
+            )
+
+    def __enter__(self) -> DockerSandbox:
+        self.check_available()
+        cmd = [
+            "docker", "run", "--detach", "--rm",
+            "--name", self.name,
+            "--volume", f"{self.worktree}:{CONTAINER_ROOT}",
+            "--workdir", self.workdir,
+            "--user", f"{os.getuid()}:{os.getgid()}",
+            "--env", "HOME=/tmp",
+            "--env", "PIP_DISABLE_PIP_VERSION_CHECK=1",
+            "--cap-drop", "ALL",
+            "--security-opt", "no-new-privileges",
+            "--memory", "2g",
+            "--cpus", "2",
+            "--pids-limit", "512",
+            self.image,
+            "sleep", "infinity",
+        ]  # fmt: skip
+        proc = subprocess.run(cmd, capture_output=True, text=True)
+        if proc.returncode != 0:
+            raise SandboxError(f"Couldn't start the Docker sandbox:\n{proc.stderr.strip()}")
+        venv = self.run(["python", "-m", "venv", CONTAINER_VENV], timeout=120)
+        if venv.returncode != 0:
+            self.__exit__()
+            raise SandboxError(f"Couldn't create a virtualenv in the sandbox:\n{venv.stderr}")
+        return self
+
+    def __exit__(self, *exc) -> None:
+        subprocess.run(["docker", "rm", "--force", self.name], capture_output=True)
+
+    def run(self, cmd: list[str], timeout: int) -> subprocess.CompletedProcess[str]:
+        # `timeout` inside the container kills the command itself; killing only the
+        # `docker exec` client would leave it running in the container.
+        return subprocess.run(
+            ["docker", "exec", self.name, "timeout", str(timeout), *cmd],
+            capture_output=True,
+            text=True,
+            timeout=timeout + 30,
+        )

patchpilot/tools.py

@@ -0,0 +1,331 @@
+"""Tools the agent can call, plus the JSON schemas that describe them to Claude.
+
+Every tool works inside a single project directory (the "workspace"). Paths the
+model sends are resolved against that directory and rejected if they escape it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import tomllib
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+MAX_OUTPUT_CHARS = 20_000
+IGNORED_DIRS = {".git", ".venv", "venv", "__pycache__", "node_modules", ".pytest_cache"}
+
+# Matches "name", "name==1.2", "name[extra]>=1.0,<2", etc. Group 1 is the name, group 3 the spec.
+REQUIREMENT_RE = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(\[[^\]]*\])?\s*([^;#]*)")
+# What pip_install accepts: a name, optional extras, optional version specifier. No flags or URLs.
+INSTALLABLE_RE = re.compile(
+    r"[A-Za-z0-9][A-Za-z0-9._-]*(\[[A-Za-z0-9._,-]+\])?([<>=!~]=?[0-9A-Za-z.*,<>=!~]+)?"
+)
+
+
+class ToolError(Exception):
+    """A tool failed in a way the model should hear about and can recover from."""
+
+
+class Sandbox(Protocol):
+    """Somewhere to run the project's commands (see patchpilot.sandbox)."""
+
+    python: str
+
+    def run(self, cmd: list[str], timeout: int) -> subprocess.CompletedProcess[str]: ...
+
+
+@dataclass
+class Workspace:
+    root: Path
+    test_command: list[str]
+    # Where commands run in upgrade mode. None runs them directly in `root`, using whatever
+    # Python is on PATH (analyze mode, which never installs anything).
+    sandbox: Sandbox | None = None
+    changed_files: set[str] = field(default_factory=set)
+
+    def resolve(self, relative_path: str) -> Path:
+        path = (self.root / relative_path).resolve()
+        if not path.is_relative_to(self.root.resolve()):
+            raise ToolError(f"Path '{relative_path}' is outside the project directory.")
+        return path
+
+    def command(self, cmd: list[str]) -> list[str]:
+        """Point a leading `python` at the sandbox's own interpreter."""
+        if self.sandbox and cmd and cmd[0] in ("python", "python3"):
+            return [self.sandbox.python, *cmd[1:]]
+        return cmd
+
+    def run(self, cmd: list[str], timeout: int) -> subprocess.CompletedProcess[str]:
+        cmd = self.command(cmd)
+        try:
+            if self.sandbox:
+                proc = self.sandbox.run(cmd, timeout)
+            else:
+                proc = subprocess.run(
+                    cmd, cwd=self.root, capture_output=True, text=True, timeout=timeout
+                )
+        except FileNotFoundError as e:
+            raise ToolError(f"Command not found: {cmd[0]}") from e
+        except subprocess.TimeoutExpired as e:
+            raise ToolError(f"Command timed out after {timeout} seconds.") from e
+        if self.sandbox and proc.returncode == 124:  # exit code of coreutils `timeout`
+            raise ToolError(f"Command timed out after {timeout} seconds.")
+        return proc
+
+
+def _truncate(text: str) -> str:
+    if len(text) <= MAX_OUTPUT_CHARS:
+        return text
+    # Test failures usually matter most at the end of the output, so keep the tail.
+    dropped = len(text) - MAX_OUTPUT_CHARS
+    return f"[... {dropped} characters truncated ...]\n" + text[-MAX_OUTPUT_CHARS:]
+
+
+def _format_result(proc: subprocess.CompletedProcess[str]) -> str:
+    status = "PASSED" if proc.returncode == 0 else f"FAILED (exit code {proc.returncode})"
+    return _truncate(f"{status}\n\n--- stdout ---\n{proc.stdout}\n--- stderr ---\n{proc.stderr}")
+
+
+def list_files(ws: Workspace, directory: str = ".") -> str:
+    base = ws.resolve(directory)
+    if not base.is_dir():
+        raise ToolError(f"'{directory}' is not a directory.")
+    files = []
+    for path in sorted(base.rglob("*")):
+        rel = path.relative_to(ws.root.resolve())
+        if any(part in IGNORED_DIRS for part in rel.parts) or not path.is_file():
+            continue
+        files.append(str(rel))
+    return "\n".join(files) if files else "(no files)"
+
+
+def read_file(ws: Workspace, path: str) -> str:
+    target = ws.resolve(path)
+    if not target.is_file():
+        raise ToolError(f"File '{path}' does not exist.")
+    return _truncate(target.read_text(errors="replace"))
+
+
+def _writable(ws: Workspace, path: str) -> Path:
+    target = ws.resolve(path)
+    rel = target.relative_to(ws.root.resolve())
+    if any(part in IGNORED_DIRS for part in rel.parts):
+        raise ToolError(f"Refusing to write inside '{rel.parts[0]}'.")
+    return target
+
+
+def write_file(ws: Workspace, path: str, content: str) -> str:
+    target = _writable(ws, path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content)
+    ws.changed_files.add(path)
+    return f"Wrote {len(content)} characters to {path}."
+
+
+def edit_file(ws: Workspace, path: str, old_text: str, new_text: str) -> str:
+    target = _writable(ws, path)
+    if not target.is_file():
+        raise ToolError(f"File '{path}' does not exist. Use write_file to create it.")
+    text = target.read_text()
+    count = text.count(old_text)
+    if count == 0:
+        raise ToolError(f"old_text was not found in {path}. Read the file and copy it exactly.")
+    if count > 1:
+        raise ToolError(f"old_text appears {count} times in {path}. Include more context.")
+    target.write_text(text.replace(old_text, new_text))
+    ws.changed_files.add(path)
+    return f"Edited {path}."
+
+
+def parse_requirements(text: str) -> list[dict[str, str]]:
+    deps = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith(("#", "-")):
+            continue
+        match = REQUIREMENT_RE.match(line)
+        if match:
+            deps.append({"name": match.group(1), "spec": match.group(3).strip()})
+    return deps
+
+
+def normalize_name(name: str) -> str:
+    """PyPI treats 'Foo_Bar', 'foo-bar' and 'foo.bar' as the same package (PEP 503)."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def collect_dependencies(root: Path) -> dict[str, list[dict[str, str]]]:
+    """Declared dependencies from requirements*.txt and pyproject.toml, keyed by source."""
+    found: dict[str, list[dict[str, str]]] = {}
+    root = root.resolve()
+
+    for req_file in sorted(root.glob("requirements*.txt")):
+        found[req_file.name] = parse_requirements(req_file.read_text())
+
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_file():
+        data = tomllib.loads(pyproject.read_text())
+        project = data.get("project", {})
+        found["pyproject.toml [project.dependencies]"] = parse_requirements(
+            "\n".join(project.get("dependencies", []))
+        )
+        for group, reqs in project.get("optional-dependencies", {}).items():
+            found[f"pyproject.toml [optional-dependencies.{group}]"] = parse_requirements(
+                "\n".join(reqs)
+            )
+    return found
+
+
+def read_dependencies(ws: Workspace) -> str:
+    found = collect_dependencies(ws.root)
+    if not found:
+        raise ToolError("No requirements*.txt or pyproject.toml found in the project.")
+    return json.dumps(found, indent=2)
+
+
+def get_latest_version(ws: Workspace, package: str) -> str:
+    """Look up the newest release of a package on PyPI."""
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", package):
+        raise ToolError(f"'{package}' is not a valid package name.")
+    url = f"https://pypi.org/pypi/{package}/json"
+    try:
+        with urllib.request.urlopen(url, timeout=15) as resp:
+            info = json.load(resp)["info"]
+    except urllib.error.HTTPError as e:
+        raise ToolError(f"PyPI returned {e.code} for '{package}'.") from e
+    except urllib.error.URLError as e:
+        raise ToolError(f"Could not reach PyPI: {e.reason}") from e
+    return json.dumps(
+        {
+            "name": info["name"],
+            "latest_version": info["version"],
+            "requires_python": info.get("requires_python"),
+            "project_urls": info.get("project_urls"),
+        },
+        indent=2,
+    )
+
+
+def pip_install(ws: Workspace, requirement: str) -> str:
+    """Install one requirement (e.g. 'pydantic==2.9.2') into the sandbox's environment."""
+    if ws.sandbox is None:
+        raise ToolError("Installing packages is only available in upgrade mode.")
+    if not INSTALLABLE_RE.fullmatch(requirement):
+        raise ToolError(
+            f"'{requirement}' is not allowed. Pass a single requirement like 'name==1.2.3'."
+        )
+    return _format_result(ws.run(["python", "-m", "pip", "install", requirement], timeout=600))
+
+
+def run_tests(ws: Workspace) -> str:
+    return _format_result(ws.run(ws.test_command, timeout=600))
+
+
+TOOL_FUNCTIONS = {
+    "list_files": list_files,
+    "read_file": read_file,
+    "write_file": write_file,
+    "edit_file": edit_file,
+    "read_dependencies": read_dependencies,
+    "get_latest_version": get_latest_version,
+    "pip_install": pip_install,
+    "run_tests": run_tests,
+}
+
+
+def _schema(properties: dict, required: list[str]) -> dict:
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+        "additionalProperties": False,
+    }
+
+
+_PATH = {"type": "string", "description": "Path relative to the project root."}
+
+READ_TOOL_SCHEMAS = [
+    {
+        "name": "list_files",
+        "description": "List project files recursively, skipping .git, virtualenvs and caches.",
+        "input_schema": _schema(
+            {
+                "directory": {
+                    "type": "string",
+                    "description": "Directory relative to the project root. Defaults to '.'.",
+                }
+            },
+            [],
+        ),
+    },
+    {
+        "name": "read_file",
+        "description": "Read a text file from the project.",
+        "input_schema": _schema({"path": _PATH}, ["path"]),
+    },
+    {
+        "name": "read_dependencies",
+        "description": (
+            "Return the project's declared dependencies and version specifiers from "
+            "requirements*.txt and pyproject.toml, grouped by source file."
+        ),
+        "input_schema": _schema({}, []),
+    },
+    {
+        "name": "get_latest_version",
+        "description": (
+            "Look up the latest released version of a package on PyPI, plus its project URLs "
+            "(often including a changelog link)."
+        ),
+        "input_schema": _schema(
+            {"package": {"type": "string", "description": "PyPI package name."}}, ["package"]
+        ),
+    },
+    {
+        "name": "run_tests",
+        "description": "Run the project's test suite and return pass/fail status plus output.",
+        "input_schema": _schema({}, []),
+    },
+]
+
+WRITE_TOOL_SCHEMAS = [
+    {
+        "name": "edit_file",
+        "description": (
+            "Replace one exact occurrence of old_text with new_text in a file. old_text must "
+            "match the file exactly (including indentation) and appear only once."
+        ),
+        "input_schema": _schema(
+            {
+                "path": _PATH,
+                "old_text": {"type": "string", "description": "Exact text to replace."},
+                "new_text": {"type": "string", "description": "Replacement text."},
+            },
+            ["path", "old_text", "new_text"],
+        ),
+    },
+    {
+        "name": "write_file",
+        "description": "Create a file, or overwrite one completely. Prefer edit_file for changes.",
+        "input_schema": _schema(
+            {"path": _PATH, "content": {"type": "string", "description": "Full file content."}},
+            ["path", "content"],
+        ),
+    },
+    {
+        "name": "pip_install",
+        "description": (
+            "Install a single requirement into the project's isolated environment, "
+            "e.g. 'pydantic==2.9.2' or 'pydantic-settings'."
+        ),
+        "input_schema": _schema(
+            {"requirement": {"type": "string", "description": "One requirement specifier."}},
+            ["requirement"],
+        ),
+    },
+]

patchpilot/upgrade.py

@@ -0,0 +1,287 @@
+"""`patchpilot upgrade`: upgrade one package, fix what breaks, commit the result to a branch.
+
+The user's own checkout is never modified. All work happens in a temporary git worktree
+(a second checkout of the same repo), and the project's code only ever runs inside a
+sandbox (see patchpilot.sandbox). Only the finished commit, on a new
+`patchpilot/upgrade-<package>` branch, is left behind.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+import tomllib
+from collections.abc import Callable
+from contextlib import ExitStack
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from patchpilot import github
+from patchpilot.agent import WEB_FETCH_TOOL, run_agent
+from patchpilot.sandbox import DEFAULT_IMAGE, DockerSandbox, LocalSandbox
+from patchpilot.tools import (
+    IGNORED_DIRS,
+    READ_TOOL_SCHEMAS,
+    WRITE_TOOL_SCHEMAS,
+    Workspace,
+    collect_dependencies,
+    normalize_name,
+    run_tests,
+)
+
+DEFAULT_TEST_COMMAND = ["python", "-m", "pytest", "-q"]
+
+SYSTEM_PROMPT = """\
+You are patchpilot, an agent that upgrades one dependency in a Python project and fixes
+the code that breaks because of it.
+
+You are working in an isolated copy of the project with its own virtualenv. The test
+suite passed before you started. Your job:
+1. Find out the latest version of the package and install it with pip_install.
+2. Update the declared version specifier in requirements*.txt or pyproject.toml so it
+   requires the new version.
+3. Run the tests. If they fail, work out why: read the failing code, and read the package's
+   changelog or migration guide with web_fetch (use URLs from get_latest_version).
+4. Fix the project's code with small, targeted edits, then run the tests again. Repeat
+   until they pass.
+
+Rules:
+- Only upgrade the requested package. If the new version moved features into a separate
+  package (for example pydantic-settings), install it and add it to the declared
+  dependencies too.
+- Never delete, skip or weaken tests to make them pass. Change a test only when the test
+  itself uses an API that was removed, and keep what it checks the same.
+- Keep changes minimal and in the existing code style.
+- If you can't get the tests passing, stop and explain what's left.
+
+When you're done, reply with only this Markdown report (it becomes the commit message and
+the pull request description):
+
+## Summary
+One or two sentences: what was upgraded, from which version to which.
+
+## Breaking changes
+Each breaking change in the new version that affected this project, and how it was fixed.
+
+## Files changed
+A bullet per file with a short description of the change.
+
+## Needs your attention
+Anything you couldn't fix or a human should double-check. Write "Nothing." if none.\
+"""
+
+
+class UpgradeError(Exception):
+    """Upgrade could not start or finish; the message is meant for the user."""
+
+
+@dataclass
+class UpgradeResult:
+    branch: str
+    tests_passed: bool
+    report: str
+    changed_files: list[str] = field(default_factory=list)
+    committed: bool = False
+    pr_url: str | None = None
+
+
+def _git(*args: str, cwd: Path) -> str:
+    proc = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise UpgradeError(f"git {' '.join(args)} failed:\n{proc.stderr.strip()}")
+    return proc.stdout.strip()
+
+
+def _pip(ws: Workspace, args: list[str]) -> None:
+    proc = ws.run(["python", "-m", "pip", "install", "-q", *args], timeout=900)
+    if proc.returncode != 0:
+        raise UpgradeError(f"Installing the project failed:\n{proc.stderr.strip()[-3000:]}")
+
+
+def install_project(ws: Workspace) -> None:
+    """Install the project and its declared dependencies into the workspace's sandbox."""
+    project = ws.root
+    for req_file in sorted(project.glob("requirements*.txt")):
+        _pip(ws, ["-r", req_file.name])
+
+    pyproject = project / "pyproject.toml"
+    if pyproject.is_file() and "project" in tomllib.loads(pyproject.read_text()):
+        extras = tomllib.loads(pyproject.read_text())["project"].get("optional-dependencies", {})
+        target = f".[{','.join(extras)}]" if extras else "."
+        _pip(ws, ["-e", target])
+
+    if ws.test_command == DEFAULT_TEST_COMMAND:
+        if ws.run(["python", "-m", "pytest", "--version"], timeout=60).returncode != 0:
+            _pip(ws, ["pytest"])
+
+
+def _declares(directory: Path, package: str) -> list[str]:
+    """Which of the directory's dependency files declare the package."""
+    wanted = normalize_name(package)
+    return [
+        source
+        for source, deps in collect_dependencies(directory).items()
+        if any(normalize_name(d["name"]) == wanted for d in deps)
+    ]
+
+
+def check_declared(project: Path, package: str, repo_root: Path) -> None:
+    """Fail early, with a hint, if the package isn't a dependency of this project.
+
+    Otherwise the agent would run against a test suite that never exercises the package,
+    and "tests pass" would mean nothing.
+    """
+    if _declares(project, package):
+        return
+    elsewhere = []
+    for dep_file in sorted(
+        [*repo_root.rglob("requirements*.txt"), *repo_root.rglob("pyproject.toml")]
+    ):
+        rel = dep_file.relative_to(repo_root)
+        if any(part in IGNORED_DIRS for part in rel.parts) or dep_file.parent == project:
+            continue
+        if dep_file.parent not in elsewhere and _declares(dep_file.parent, package):
+            elsewhere.append(dep_file.parent)
+
+    message = f"{package} isn't a dependency of {project}."
+    if elsewhere:
+        dirs = [os.path.relpath(d) for d in elsewhere]
+        message += "\nIt's declared in: " + ", ".join(dirs)
+        message += f"\nTry: patchpilot upgrade {dirs[0]} {package}"
+    raise UpgradeError(message)
+
+
+def upgrade(
+    project: Path,
+    package: str,
+    test_command: list[str] | None = None,
+    on_status: Callable[[str], None] = lambda _: None,
+    on_tool_call: Callable[[str, dict], None] | None = None,
+    use_docker: bool = True,
+    image: str = DEFAULT_IMAGE,
+    open_pr: bool = False,
+) -> UpgradeResult:
+    test_command = test_command or DEFAULT_TEST_COMMAND
+    project = project.resolve()
+    repo_root = Path(_git("rev-parse", "--show-toplevel", cwd=project)).resolve()
+    project_rel = project.relative_to(repo_root)
+    check_declared(project, package, repo_root)
+    branch = f"patchpilot/upgrade-{package.lower()}"
+
+    exists = subprocess.run(
+        ["git", "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"], cwd=repo_root
+    )
+    if exists.returncode == 0:
+        raise UpgradeError(
+            f"Branch '{branch}' already exists. Delete it first: git branch -D {branch}"
+        )
+    if use_docker:
+        DockerSandbox.check_available()
+    # Check GitHub before spending anything on the agent, not after.
+    base = github.check_ready(repo_root, branch) if open_pr else None
+
+    tmp = Path(tempfile.mkdtemp(prefix="patchpilot-"))
+    worktree = tmp / "repo"
+    committed = False
+    with ExitStack() as cleanup:
+        cleanup.callback(_remove_worktree, repo_root, worktree, branch, lambda: committed, tmp)
+
+        on_status(f"Creating an isolated copy of the repo on branch {branch}")
+        _git("worktree", "add", "-q", "-b", branch, str(worktree), "HEAD", cwd=repo_root)
+        work_project = worktree / project_rel
+
+        if use_docker:
+            on_status(f"Starting a Docker sandbox ({image}) and installing the project")
+            sandbox = DockerSandbox(worktree, project_rel, image)
+        else:
+            on_status("Creating a local virtualenv and installing the project (no Docker)")
+            sandbox = LocalSandbox(work_project, tmp / "venv")
+        cleanup.enter_context(sandbox)
+
+        ws = Workspace(root=work_project, test_command=test_command, sandbox=sandbox)
+        install_project(ws)
+        on_status("Running the tests before upgrading")
+        baseline = run_tests(ws)
+        if not baseline.startswith("PASSED"):
+            raise UpgradeError(
+                "The tests fail before any upgrade, so patchpilot can't tell what the upgrade "
+                f"breaks. Fix them first.\n\n{baseline[-3000:]}"
+            )
+
+        on_status(f"Agent is upgrading {package}")
+        report = run_agent(
+            ws,
+            system=SYSTEM_PROMPT,
+            task=f"Upgrade '{package}' to its latest version in the project at {work_project}.",
+            tools=[*READ_TOOL_SCHEMAS, *WRITE_TOOL_SCHEMAS, WEB_FETCH_TOOL],
+            max_turns=60,
+            on_tool_call=on_tool_call,
+        )
+
+        on_status("Re-running the tests to verify the agent's work")
+        tests_passed = run_tests(ws).startswith("PASSED")
+        version = installed_version(ws, package)
+        result = UpgradeResult(
+            branch=branch,
+            tests_passed=tests_passed,
+            report=report,
+            changed_files=sorted(ws.changed_files),
+        )
+
+        if result.changed_files:
+            paths = [str(project_rel / p) for p in result.changed_files]
+            _git("add", "--", *paths, cwd=worktree)
+            title = f"Upgrade {package}" + (f" to {version}" if version else "")
+            title += "" if tests_passed else " (tests still failing)"
+            _git("commit", "-q", "-m", title, "-m", report, cwd=worktree)
+            result.committed = committed = True
+
+        if open_pr and result.committed:
+            on_status("Pushing the branch and opening a pull request")
+            where = f"in the Docker sandbox, {image}" if use_docker else "in a local virtualenv"
+            result.pr_url = github.open_pull_request(
+                repo_root,
+                branch,
+                base,
+                title,
+                pr_body(report, tests_passed, where),
+                draft=not tests_passed,
+            )
+        return result
+
+
+def installed_version(ws: Workspace, package: str) -> str | None:
+    proc = ws.run(["python", "-m", "pip", "show", package], timeout=60)
+    for line in proc.stdout.splitlines():
+        if line.startswith("Version:"):
+            return line.split(":", 1)[1].strip()
+    return None
+
+
+def pr_body(report: str, tests_passed: bool, sandbox: str) -> str:
+    verdict = (
+        "✅ The test suite passes."
+        if tests_passed
+        else "❌ The test suite still fails. This PR is a draft; see *Needs your attention*."
+    )
+    return (
+        f"{report}\n\n---\n\n"
+        f"**Verified by patchpilot:** after the agent finished, patchpilot re-ran the tests "
+        f"itself ({sandbox}). {verdict}\n\n"
+        "<sub>Opened by [patchpilot](https://github.com/ilmeedesilva/patchpilot), an AI agent "
+        "that upgrades dependencies and fixes what breaks. Review it like any other PR.</sub>"
+    )
+
+
+def _remove_worktree(
+    repo_root: Path, worktree: Path, branch: str, committed: Callable[[], bool], tmp: Path
+) -> None:
+    subprocess.run(
+        ["git", "worktree", "remove", "--force", str(worktree)], cwd=repo_root, capture_output=True
+    )
+    # No commit means nothing worth reviewing, so don't leave an empty branch behind.
+    if not committed():
+        subprocess.run(["git", "branch", "-D", branch], cwd=repo_root, capture_output=True)
+    shutil.rmtree(tmp, ignore_errors=True)

patchpilot-0.1.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: patchpilot
+Version: 0.1.0
+Summary: An AI agent that upgrades your dependencies, fixes what breaks, and opens a PR
+Project-URL: Homepage, https://github.com/ilmeedesilva/patchpilot
+Project-URL: Issues, https://github.com/ilmeedesilva/patchpilot/issues
+Project-URL: Demo, https://github.com/ilmeedesilva/patchpilot-demo
+Author: Ilmee De Silva
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,claude,dependencies,developer-tools,llm,upgrade
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=2.3.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=9; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# patchpilot
+
+[![CI](https://github.com/ilmeedesilva/patchpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/ilmeedesilva/patchpilot/actions/workflows/ci.yml)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/ilmeedesilva/patchpilot/blob/main/LICENSE)
+
+**An AI agent that upgrades a dependency, fixes the code that breaks, and opens a pull request explaining what changed and why.**
+
+Dependabot and Renovate bump version numbers. When the new version breaks your build, the fix is still on you. patchpilot does that part: it upgrades the package inside a sandbox, runs your tests, reads the failures and the changelog, edits your code until the tests pass, and hands you a reviewable PR.
+
+<!-- TODO: demo GIF here: `patchpilot upgrade . pydantic --pr` → PR appears -->
+
+```console
+$ patchpilot upgrade . pydantic --pr
+• Creating an isolated copy of the repo on branch patchpilot/upgrade-pydantic
+• Starting a Docker sandbox (python:3.13-slim) and installing the project
+• Running the tests before upgrading
+• Agent is upgrading pydantic
+  → read_dependencies {}
+  → get_latest_version {"package": "pydantic"}
+  → pip_install {"requirement": "pydantic==2.14.1"}
+  → run_tests {}                      # fails: BaseSettings moved out of pydantic
+  → pip_install {"requirement": "pydantic-settings==2.16.2"}
+  → write_file {"path": "app/config.py"}
+  → write_file {"path": "app/models.py"}
+  → run_tests {}                      # passes
+• Re-running the tests to verify the agent's work
+• Pull request: https://github.com/<you>/<repo>/pull/1
+```
+
+The PR description is written by the agent, and includes:
+
+> **Breaking changes**
+> - **`BaseSettings` moved to `pydantic-settings`**: importing it from `pydantic` now fails. Installed `pydantic-settings`, added it to `requirements.txt`, and now import from `pydantic_settings`.
+> - **`@root_validator` without `skip_on_failure=True` is an error in v2**: replaced with `@model_validator(mode="after")`.
+> - …
+>
+> **Needs your attention**
+> - In v1 the password check ran even when another field had failed; in v2 it only runs once all fields are valid, so a bad email plus mismatched passwords now reports only the email error.
+
+*(Trimmed output and report from a real run on [`examples/pydantic-demo`](https://github.com/ilmeedesilva/patchpilot/tree/main/examples/pydantic-demo).)*
+
+## Quick start
+
+You need Python 3.11+, [Docker Desktop](https://www.docker.com/products/docker-desktop/) running, and an [Anthropic API key](https://console.anthropic.com/settings/keys).
+
+```bash
+pipx install git+https://github.com/ilmeedesilva/patchpilot.git   # soon: pipx install patchpilot
+export ANTHROPIC_API_KEY=sk-ant-...      # or put it in a .env file where you run patchpilot
+
+cd your-project                          # a git repo with a test suite
+patchpilot analyze .                     # read-only report: what's outdated, what's risky
+patchpilot upgrade . pydantic            # upgrade + fix, committed to a new branch
+patchpilot upgrade . pydantic --pr       # ...and open a pull request
+```
+
+Each run uses Anthropic API credit. The amount depends on the size of the project and how much breaks.
+
+## Usage
+
+### `patchpilot analyze <project>`
+
+Reads your dependency files, checks PyPI for the latest versions and runs your tests once, then prints a Markdown report. It covers what's outdated, which upgrades are major-version jumps likely to need code changes, and a suggested order. It changes nothing.
+
+### `patchpilot upgrade <project> <package>`
+
+1. Checks that `<package>` really is a dependency of `<project>`. If it's declared in a subfolder instead, it tells you which one.
+2. Makes a separate checkout of your repo (a git worktree) on a new branch, `patchpilot/upgrade-<package>`. **Your working copy is never touched.**
+3. Starts a Docker sandbox, installs your project into it, and checks that the tests pass *before* changing anything.
+4. Lets the agent work: upgrade the package, run the tests, read the failures and changelog, edit the code, and repeat.
+5. **Re-runs the tests itself** instead of trusting the agent's word, then commits to the branch with the agent's report as the commit message.
+
+Review the result with `git diff HEAD...patchpilot/upgrade-<package>`, then merge it or delete it.
+
+| Option | |
+|---|---|
+| `--pr` | Push the branch and open a GitHub pull request. If the tests still fail, it's opened as a **draft**. Uses the [GitHub CLI](https://cli.github.com/), so patchpilot never handles a GitHub token. |
+| `--test-command "..."` | How to run your tests (default: `python -m pytest -q`). |
+| `--image python:3.11-slim` | Docker image to run in. Match it to your project's Python version (default: `python:3.13-slim`). |
+| `--no-docker` | Use a local virtualenv instead of Docker. Faster, but your project's code runs directly on your machine. |
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph host["Your machine"]
+        CLI["patchpilot CLI"] --> Loop["Agent loop"]
+        Loop <-->|"tool calls ⇄ results"| Claude["Claude API"]
+        Loop --> Files["Read / edit files<br/>in a temporary worktree"]
+    end
+    subgraph sandbox["Docker sandbox: sees only the worktree"]
+        Pip["pip install &lt;one package&gt;"]
+        Tests["your test suite"]
+    end
+    Loop --> Pip
+    Loop --> Tests
+    Loop -->|"verify, commit"| Branch["patchpilot/upgrade-&lt;pkg&gt;"]
+    Branch -->|"--pr"| PR["GitHub pull request"]
+```
+
+At the centre is a hand-written [tool-use loop](https://github.com/ilmeedesilva/patchpilot/blob/main/src/patchpilot/agent.py). patchpilot sends Claude the task and a list of tools. Claude replies with the tool it wants to call, patchpilot runs it and sends back the result, and this repeats until Claude writes its final report. Claude decides *what* to do next; patchpilot's code is the only thing that *does* anything.
+
+| Tool | Runs where | What it does |
+|---|---|---|
+| `read_dependencies` | host | Parses `requirements*.txt` and `pyproject.toml` |
+| `get_latest_version` | host | Queries PyPI, including changelog URLs |
+| `list_files`, `read_file` | host | Read-only, confined to the project folder |
+| `edit_file`, `write_file` | host | Exact-match edits; refuses `.git/` and virtualenvs |
+| `pip_install` | **sandbox** | One requirement at a time; flags, URLs and file paths are rejected |
+| `run_tests` | **sandbox** | Your test command, with a timeout |
+| `web_fetch` | Anthropic | Reads changelogs and migration guides |
+
+### Safety
+
+Upgrading means running code that isn't yours: your tests, and whatever a package runs when it installs. So that code runs inside a Docker container that:
+
+- mounts **only the temporary worktree**, not your home folder, SSH keys or other projects
+- runs as your user, not root, with all Linux capabilities dropped and `no-new-privileges`
+- is capped at 2 CPUs, 2 GB of memory and 512 processes
+- is deleted when the run ends, even if the run fails
+
+The agent loop and your API key never enter the container. These properties are checked by [integration tests](https://github.com/ilmeedesilva/patchpilot/blob/main/tests/test_sandbox.py), not just described here.
+
+### Design decisions
+
+- **Verify, don't trust.** The agent says when it's done, but patchpilot re-runs the tests itself before committing. The ✅ in the output is patchpilot's verdict, not the model's.
+- **Refuse to run when "tests pass" would mean nothing.** patchpilot stops if the tests already fail before the upgrade, or if the package isn't a dependency of the folder you pointed it at. Otherwise a green result could be meaningless.
+- **Fail before spending, not after.** Docker, GitHub login, remotes and branch names are all checked before the first API call.
+- **Leave nothing behind.** The worktree, container and virtualenv are cleaned up on success, failure or Ctrl-C. A branch only survives if it has a commit worth reviewing.
+- **A small, explicit tool surface** instead of a general shell. It's easier to reason about what the agent can do, and easier to sandbox.
+
+## Limitations
+
+- Python projects only, with `requirements*.txt` or a PEP 621 `pyproject.toml` (no Poetry or uv lockfiles yet).
+- One package per run.
+- The fix is only as good as your tests. If they don't cover what changed, patchpilot can't catch it, though the agent flags behaviour changes it notices under **Needs your attention**.
+- The sandbox needs network access to install packages, so code inside it can reach the internet.
+
+## Roadmap
+
+- [ ] Publish to PyPI (`pipx install patchpilot`)
+- [ ] GitHub Action: run weekly and open PRs automatically
+- [ ] Upgrade several packages in one run, ordered by risk
+- [ ] Turn off the sandbox's network access while tests run
+- [ ] uv and Poetry lockfile support
+
+## Development
+
+```bash
+git clone git@github.com:ilmeedesilva/patchpilot.git && cd patchpilot
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest          # Docker tests are skipped if Docker isn't running
+ruff check . && ruff format --check .
+```
+
+The test suite doesn't call the Anthropic API: the agent is replaced with a fake that makes known edits, and GitHub with a local bare repo plus a stand-in `gh`.
+
+## License
+
+[MIT](https://github.com/ilmeedesilva/patchpilot/blob/main/LICENSE)

patchpilot-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+patchpilot/__init__.py,sha256=UBmfZOHxiEFyeFNtKSjPAinbxPgDIzrwL61976nrzAM,103
+patchpilot/agent.py,sha256=LXESN7HH-R8R2FYI_roT268ln9YiSF07VOia54yDOnw,3374
+patchpilot/analyze.py,sha256=Asa30FY7g1lU3FJICbrmJHyhx4ZC_bk63QJaChvWKNc,1336
+patchpilot/cli.py,sha256=zVHOI3eXtJMks6CqjJYlPkQyoaffbwe1kQJYxpghqpw,5742
+patchpilot/github.py,sha256=jl-6PzEJOyBsAFptr4OA4xVhL12invTRx_b5r_Pcmhk,2992
+patchpilot/sandbox.py,sha256=_-i8WAwLbn7JR4LBhKRaKi4VTVlFH91f_L2BFVNf92I,4329
+patchpilot/tools.py,sha256=eSCXFe7nXgvopqQmlBuWRtf4eoIDUFzkwwRYSG6h7EU,11987
+patchpilot/upgrade.py,sha256=3CJJXGJxIFWXSVxzPhKp_zJujE681ztIs6qt5aNz_vw,11262
+patchpilot-0.1.0.dist-info/METADATA,sha256=lPF--XCDpT2hDigld0nt6t2dgbLd8Xi4FXPjxsQgSOQ,10709
+patchpilot-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+patchpilot-0.1.0.dist-info/entry_points.txt,sha256=E7vHakGW5WsfwwJOG4zOW730gZXQnm-GX2dDZwMz-Pg,51
+patchpilot-0.1.0.dist-info/licenses/LICENSE,sha256=pQ5TGEEuo0j5qmeDIbgM6_iu5qmD-gCwLJ6YKcOx_X4,1071
+patchpilot-0.1.0.dist-info/RECORD,,

patchpilot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

patchpilot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+patchpilot = patchpilot.cli:main

patchpilot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilmee De Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.