ferrum-cli 0.1.0__py3-none-any.whl

ferrum/__init__.py

@@ -0,0 +1,6 @@
+"""Ferrum — a coding harness for low-level and systems programming.
+
+Understand -> Change -> Build -> Verify.
+"""
+
+__version__ = "0.1.0"

ferrum/agent.py

@@ -0,0 +1,387 @@
+"""The agent loop: the model reads (and, in fix mode, patches) until done."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, ClassVar
+
+from ferrum.config import Config
+from ferrum.context import ProjectContext
+from ferrum.model import (
+    MALFORMED_JSON,
+    ModelProvider,
+    ModelResponse,
+    extract_tool_calls,
+)
+from ferrum.patch import Patch, format_unified_diff
+from ferrum.safety import PathEscapeError, is_denied, safe_join
+from ferrum.tools import Tool, ToolError, ToolRegistry, ToolResult, _require_string
+from ferrum.verifier import Verifier, VerifyOutcome
+
+log = logging.getLogger(__name__)
+
+# Inside the package, so wheel installs ship the real prompt too.
+PROMPT_PATH = Path(__file__).resolve().parent / "prompts" / "system.md"
+FALLBACK_SYSTEM = (
+    "You are Ferrum, a coding harness for systems programming. "
+    "Inspect before you modify, cite file:line evidence, make the smallest "
+    "change, and never claim a fix is verified unless a build or test "
+    "actually passed."
+)
+
+READ_ONLY_NOTE = (
+    "Read-only mode: investigate thoroughly before answering. A directory "
+    "listing alone is not an answer — read the relevant source files and "
+    "search for the relevant names; several tool calls are expected. You "
+    "cannot modify files, so do not call apply_patch."
+)
+
+FIX_NOTE = (
+    "Fix mode: inspect thoroughly before patching — read the file you are "
+    "about to change and its callers; several tool calls are expected. "
+    "Call apply_patch only with text you have read in this session."
+)
+
+DRY_RUN_NOTE = (
+    "Dry run: apply_patch will display your proposed diff, but the harness "
+    "will not modify files, ask for confirmation, or run verification. "
+    "Propose the one correct patch and then summarize it for the user."
+)
+
+NUDGE = (
+    "You have not called any tools yet. Investigate first: call list_files, "
+    "read_file or search_code and base your answer on what you read."
+)
+
+READ_NUDGE = (
+    "A directory listing alone does not answer the question. Use read_file "
+    "on the most relevant source file (and search_code for names) before "
+    "you answer."
+)
+
+MAX_NUDGES = 2
+READ_TOOLS = ("read_file", "search_code", "apply_patch")
+
+PROGRESS = {
+    "list_files": "inspecting the project",
+    "read_file": "reading",
+    "search_code": "searching",
+    "apply_patch": "proposing a patch to",
+}
+
+
+@dataclass
+class AgentResult:
+    text: str
+    turns: int
+    capped: bool = False
+    patched: bool = False
+    verified: bool | None = None
+    verify_report: str | None = None
+
+
+class ApplyPatch(Tool):
+    name = "apply_patch"
+    description = (
+        "Replace exact text in a project file after showing the diff and "
+        "asking the user. The old text must match the file verbatim and "
+        "uniquely. After a successful patch the project is built and "
+        "tested; the verification output comes back in the result."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "File path relative to the project root.",
+            },
+            "old": {
+                "type": "string",
+                "description": "Exact text currently in the file.",
+            },
+            "new": {
+                "type": "string",
+                "description": "Replacement text.",
+            },
+            "description": {
+                "type": "string",
+                "description": "One line: why this change fixes the problem.",
+            },
+        },
+        "required": ["path", "old", "new"],
+    }
+
+    def __init__(
+        self,
+        root: Path,
+        confirm: Callable[[str], bool],
+        ui: Callable[[str], None] = print,
+        verifier: Verifier | None = None,
+        dry_run: bool = False,
+    ) -> None:
+        self.root = Path(root)
+        self.confirm = confirm
+        self.ui = ui
+        self.verifier = verifier
+        self.dry_run = dry_run
+        self.applied = False
+        self.outcome: VerifyOutcome | None = None
+
+    def execute(self, arguments: Mapping[str, Any]) -> ToolResult:
+        rel = _require_string(arguments, "path")
+        old = _require_string(arguments, "old")
+        new = arguments.get("new")
+        if not isinstance(new, str):
+            raise ToolError("new is required and must be a string")
+        description = arguments.get("description") or ""
+        if not isinstance(description, str):
+            description = str(description)
+
+        if is_denied(PurePosixPath(rel.replace("\\", "/"))):
+            raise ToolError(f"refused: {rel} is excluded (secret, binary, or ignored)")
+        try:
+            target = safe_join(self.root, rel)
+        except PathEscapeError as exc:
+            raise ToolError(str(exc)) from exc
+        if target.is_dir():
+            raise ToolError(f"is a directory: {rel}")
+        if not target.exists():
+            raise ToolError(f"file not found: {rel} (read it first)")
+
+        try:
+            data = target.read_bytes()
+        except OSError as exc:
+            raise ToolError(f"cannot read {rel}: {exc}") from exc
+        if b"\x00" in data[:8192]:
+            raise ToolError(f"refused: {rel} looks like a binary file")
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ToolError(f"not valid UTF-8 text: {rel}") from exc
+
+        crlf = "\r\n" in text
+        current = text.replace("\r\n", "\n").replace("\r", "\n")
+        patch = Patch(rel=rel, old=old, new=new, description=description)
+        try:
+            updated = patch.apply(current)
+        except Exception as exc:
+            raise ToolError(f"Patch rejected: {exc}. Re-read the file and retry.") from exc
+
+        self.ui(format_unified_diff(current, updated, rel))
+        if self.dry_run:
+            return ToolResult.success(
+                f"Dry run: the patch was NOT applied to {rel}"
+                " — the file on disk is unchanged and no verification ran. "
+                "Summarize this proposed change for the user and stop."
+            )
+        if not self.confirm("Apply patch? [y/N] "):
+            return ToolResult.failure(
+                "The user declined this patch. Do not apply it. "
+                "Ask what they would prefer or stop."
+            )
+
+        out = updated.replace("\n", "\r\n") if crlf else updated
+        try:
+            target.write_bytes(out.encode("utf-8"))
+        except OSError as exc:
+            raise ToolError(f"cannot write {rel}: {exc}") from exc
+        self.applied = True
+
+        report = f"Patch applied to {rel}."
+        if description:
+            report += f" ({description})"
+        if self.verifier is not None:
+            self.outcome = self.verifier.verify()
+            report += "\n\n--- verification ---\n" + self.outcome.report()
+        else:
+            report += "\n(verification unavailable)"
+        return ToolResult.success(report)
+
+
+class Agent:
+    def __init__(
+        self,
+        config: Config,
+        provider: ModelProvider,
+        registry: ToolRegistry,
+        printer: Callable[[str], None] | None = None,
+        verifier: Verifier | None = None,
+    ) -> None:
+        self.config = config
+        self.provider = provider
+        self.registry = registry
+        self.printer = printer
+        self.verifier = verifier
+        self.apply_tool: ApplyPatch | None = None
+
+    @staticmethod
+    def system_prompt() -> str:
+        try:
+            return PROMPT_PATH.read_text(encoding="utf-8")
+        except OSError:
+            return FALLBACK_SYSTEM
+
+    def run(
+        self,
+        task: str,
+        context: ProjectContext,
+        *,
+        edit: bool = False,
+        confirm: Callable[[str], bool] | None = None,
+        dry_run: bool = False,
+    ) -> AgentResult:
+        if edit and "apply_patch" not in self.registry:
+            if confirm is None:
+                raise ValueError("edit mode requires a confirm callback")
+            self.apply_tool = ApplyPatch(
+                context.root,
+                confirm,
+                ui=self.printer or print,
+                verifier=self.verifier,
+                dry_run=dry_run,
+            )
+            self.registry.register(self.apply_tool)
+
+        user = task
+        user += "\n\n" + (FIX_NOTE if edit else READ_ONLY_NOTE)
+        if dry_run:
+            user += "\n\n" + DRY_RUN_NOTE
+        user += "\n\nProject:\n" + context.summary()
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": self.system_prompt()},
+            {"role": "user", "content": user},
+        ]
+
+        turns = 0
+        nudges = 0
+        used_tools = False
+        used_read = False
+        read_nudges = 0
+        for turn in range(1, self.config.max_iterations + 1):
+            turns = turn
+            response = self.provider.complete(messages, self.registry.schemas())
+            calls = _merge_tool_calls(
+                response.tool_calls, extract_tool_calls(response.content)
+            )
+            if calls:
+                response = ModelResponse(response.content, calls)
+            if not response.tool_calls:
+                if not used_tools and nudges < MAX_NUDGES:
+                    # Small models love answering from memory; force one look.
+                    nudges += 1
+                    messages.append(_assistant_message(response))
+                    messages.append({"role": "user", "content": NUDGE})
+                    continue
+                if (
+                    used_tools
+                    and not used_read
+                    and read_nudges < MAX_NUDGES
+                ):
+                    # Listing is not reading; push for the actual source.
+                    read_nudges += 1
+                    messages.append(_assistant_message(response))
+                    messages.append({"role": "user", "content": READ_NUDGE})
+                    continue
+                return self._finish(response.content, turns, capped=False, edit=edit)
+            messages.append(_assistant_message(response))
+            used_tools = True
+            for call in response.tool_calls:
+                if call.name in READ_TOOLS:
+                    used_read = True
+                self._progress(call)
+                result = self._execute(call)
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": call.id,
+                        "content": result.to_model_message(),
+                    }
+                )
+        return self._finish(
+            f"Stopped after {self.config.max_iterations} iterations "
+            "without a final answer.",
+            turns,
+            capped=True,
+            edit=edit,
+        )
+
+    def _execute(self, call) -> ToolResult:
+        if MALFORMED_JSON in call.arguments:
+            raw = str(call.arguments[MALFORMED_JSON])[:500]
+            return ToolResult.failure(
+                f"invalid JSON arguments for {call.name!r}: {raw!r}. "
+                "Send only the argument values as a JSON object "
+                '(e.g. {"path": "main.c"}); escape newlines as \\n.'
+            )
+        if not call.name:
+            return ToolResult.failure("tool call had no name")
+        return self.registry.execute(call.name, call.arguments)
+
+    def _progress(self, call) -> None:
+        if self.printer is None:
+            return
+        label = PROGRESS.get(call.name)
+        if label is None:
+            self.printer(f"Ferrum > {call.name}...")
+            return
+        if call.name in ("read_file", "apply_patch"):
+            detail = f" {call.arguments.get('path', '')}"
+        elif call.name == "search_code":
+            detail = f" {call.arguments.get('pattern', '')!r}"
+        else:
+            detail = ""
+        self.printer(f"Ferrum > {label}{detail}...")
+
+    def _finish(self, text: str, turns: int, *, capped: bool, edit: bool) -> AgentResult:
+        if not text:
+            text = "The model returned no answer."
+        patched = bool(self.apply_tool and self.apply_tool.applied)
+        verified: bool | None = None
+        report: str | None = None
+        if patched and self.apply_tool and self.apply_tool.outcome:
+            verified = self.apply_tool.outcome.verified
+            report = self.apply_tool.outcome.report()
+        return AgentResult(
+            text=text,
+            turns=turns,
+            capped=capped,
+            patched=patched,
+            verified=verified,
+            verify_report=report,
+        )
+
+
+def _merge_tool_calls(native: list, extracted: list) -> list:
+    """Native calls first, then JSON-from-text calls that are not duplicates."""
+    seen = {(c.name, json.dumps(c.arguments, sort_keys=True)) for c in native}
+    merged = list(native)
+    for call in extracted:
+        key = (call.name, json.dumps(call.arguments, sort_keys=True))
+        if key not in seen:
+            seen.add(key)
+            merged.append(call)
+    return merged
+
+
+def _assistant_message(response: ModelResponse) -> dict[str, Any]:
+    message: dict[str, Any] = {
+        "role": "assistant",
+        "content": response.content or "",
+    }
+    if response.tool_calls:
+        message["tool_calls"] = [
+            {
+                "id": call.id,
+                "type": "function",
+                "function": {
+                    "name": call.name,
+                    "arguments": json.dumps(call.arguments),
+                },
+            }
+            for call in response.tool_calls
+        ]
+    return message