nanoPyCodeAgent 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

nanopycodeagent/agent.py

@@ -1,9 +1,9 @@
 """A minimal agent loop built on the Anthropic Python SDK.
 
 Run the program, type a message, and Agent replies. The full conversation is
-kept in memory so each turn has context. The model can call a single ``bash``
-tool to run shell commands; every command and its output are echoed to the
-terminal as they happen. Type ``/exit`` to quit.
+kept in memory so each turn has context. The model can call a ``read`` tool
+to view files and a ``bash`` tool to run shell commands; every call and its
+output are echoed to the terminal as they happen. Type ``/exit`` to quit.
 
 The loop handles only the happy path: anything unexpected — a network error,
 a Ctrl-C mid-turn — crashes the session, and restarting it is the recovery.
@@ -12,11 +12,13 @@ preserved at the ``hardened-agent-loop`` tag.
 """
 
 import os
+from importlib.metadata import PackageNotFoundError, version
 
 import anthropic
 from anthropic.types import MessageParam, ToolResultBlockParam, ToolUseBlock
 
 from .bash_tool import BASH_TOOL, run_bash
+from .read_tool import READ_TOOL, run_read
 from .settings import load_settings_env
 from .terminal import print_tool
 
@@ -26,16 +28,43 @@ DEFAULT_MODEL = "claude-sonnet-4-6"
 MAX_TOKENS = 8192
 SYSTEM_PROMPT = (
     "You are nanoPyCodeAgent, a concise and helpful coding assistant. "
-    "Use the bash tool to inspect files, run code, and complete tasks that "
-    "need real command output instead of guessing."
+    "Prefer the read tool for viewing files. Use the bash tool to run "
+    "commands, search with grep, and complete tasks that need real command "
+    "output instead of guessing."
 )
 
+# Every tool offered to the model on each request.
+TOOLS = [READ_TOOL, BASH_TOOL]
+
+
+def _package_version() -> str:
+    """Return the installed package version.
+
+    The version comes from the package metadata written at install time
+    (hatch-vcs derives it from the git tag). When the package is not
+    installed — e.g. the module is run straight from a source checkout —
+    there is no metadata to read, so fall back to a placeholder.
+    """
+    try:
+        return version("nanoPyCodeAgent")
+    except PackageNotFoundError:
+        return "unknown"
+
 
 def _run_one_tool(block: ToolUseBlock) -> ToolResultBlockParam:
-    """Execute one ``tool_use`` block, echoing the command and its output."""
-    command = block.input["command"]
-    print_tool(f"[bash]$ {command}")
-    output, is_error = run_bash(command)
+    """Execute one ``tool_use`` block, echoing the call and its output."""
+    if block.name == "read":
+        path = block.input["path"]
+        print_tool(f"[read] {path}")
+        output, is_error = run_read(
+            path,
+            offset=block.input.get("offset", 1),
+            limit=block.input.get("limit"),
+        )
+    else:  # bash — the only other tool offered
+        command = block.input["command"]
+        print_tool(f"[bash]$ {command}")
+        output, is_error = run_bash(command)
     print_tool(output)
     return {
         "type": "tool_result",
@@ -48,7 +77,7 @@ def _run_one_tool(block: ToolUseBlock) -> ToolResultBlockParam:
 def run() -> None:
     """Start the read → ask → answer loop until the user types ``/exit``.
 
-    A reply may include bash tool calls; they are executed and their results
+    A reply may include tool calls; they are executed and their results
     fed back to the model until it finishes the turn without tool use.
     """
     # Fill any unset ANTHROPIC_* keys from the config file (environment
@@ -67,7 +96,10 @@ def run() -> None:
         return
 
     model = os.environ.get("ANTHROPIC_MODEL", "").strip() or DEFAULT_MODEL
-    print(f"nanoPyCodeAgent — model {model} (set ANTHROPIC_MODEL to override).")
+    print(
+        f"nanoPyCodeAgent v{_package_version()} — model {model} "
+        "(set ANTHROPIC_MODEL to override)."
+    )
     print("Type a message to chat, or /exit to quit.")
 
     messages: list[MessageParam] = []
@@ -93,7 +125,7 @@ def run() -> None:
                 model=model,
                 max_tokens=MAX_TOKENS,
                 system=SYSTEM_PROMPT,
-                tools=[BASH_TOOL],
+                tools=TOOLS,
                 messages=messages,
             ) as stream:
                 for text in stream.text_stream:

nanopycodeagent/read_tool.py

@@ -0,0 +1,176 @@
+"""The ``read`` tool: its definition and its execution.
+
+Each call reads a window of a UTF-8 text file and returns it with 1-based
+line numbers, ``cat -n`` style, plus a continuation hint whenever the
+window stops short of the end of the file.
+"""
+
+import shlex
+from pathlib import Path
+
+from anthropic.types import ToolParam
+
+# Guardrails for the read tool: one call returns at most this many lines and
+# this many characters, whichever is hit first, so a single file cannot flood
+# the context. Truncation happens at line boundaries, never mid-line.
+MAX_READ_LINES = 2_000
+MAX_READ_CHARS = 50_000
+
+# The output caps above only bound what reaches the context; the file itself
+# is read whole, so a byte cap is what bounds memory. It is generous next to
+# the output caps because a small window may sit deep inside a large source
+# file — it only has to keep a multi-gigabyte log from being loaded at all.
+MAX_READ_BYTES = 10_000_000
+
+READ_TOOL: ToolParam = {
+    "name": "read",
+    "description": (
+        "Read a UTF-8 text file and return its content with 1-based line "
+        "numbers, `cat -n` style. Use `offset` (first line to read) and "
+        "`limit` (number of lines) to read a window of a large file. Output "
+        "is capped by line count and character count; a truncated result "
+        "names the range returned, the file's total line count, and the "
+        "offset to continue from. Binary files are rejected. Prefer this "
+        "over `cat`/`sed` in bash for viewing files; use bash for searching "
+        "(grep) and for slicing single lines too long to return."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": (
+                    "Path to the file, absolute or relative to the agent's "
+                    "working directory. A leading ~ is expanded."
+                ),
+            },
+            "offset": {
+                "type": "integer",
+                "description": "1-based line number to start from (default 1).",
+            },
+            "limit": {
+                "type": "integer",
+                "description": (
+                    f"Maximum number of lines to return. Omit to read up to "
+                    f"the {MAX_READ_LINES}-line cap; larger values are "
+                    f"clamped to it."
+                ),
+            },
+        },
+        "required": ["path"],
+    },
+}
+
+
+def run_read(
+    path_str: str, offset: int = 1, limit: int | None = None
+) -> tuple[str, bool]:
+    """Read a window of the file and return ``(output, is_error)``.
+
+    ``is_error`` is true when the tool could not produce a reading: a bad
+    argument, a missing file, a directory or any other non-regular file, a
+    file over the byte cap, a binary file, or a single line over the
+    character cap. Only regular files are opened — a FIFO or a device file
+    would block or never end, and there is no timeout here to escape that.
+    Every error message states what to do next — the file's total line
+    count, a bash command to slice an over-long line — rather than just
+    what failed.
+
+    Content is decoded as UTF-8 with invalid bytes replaced, matching the
+    bash tool's tolerance. The whole file is read into memory: fine for
+    source and config files, and the output caps bound what reaches the
+    context either way. Files over the byte cap are turned away before the
+    read, since the output caps would otherwise apply only after the whole
+    file had already been loaded.
+    """
+    if offset < 1:
+        return f"[invalid offset {offset}: line numbers start at 1]", True
+    if limit is not None and limit < 1:
+        return f"[invalid limit {limit}: must be at least 1]", True
+
+    path = Path(path_str).expanduser()
+    if not path.exists():
+        return f"[file not found: {path_str}]", True
+    if path.is_dir():
+        return f"[{path_str} is a directory, not a file]", True
+    if not path.is_file():
+        # A FIFO blocks until something writes to it and a device file like
+        # /dev/zero never ends. Reading either would hang the session, and
+        # unlike the bash tool there is no timeout to escape it.
+        return f"[{path_str} is not a regular file; read is text-only]", True
+    try:
+        size = path.stat().st_size
+        if size > MAX_READ_BYTES:
+            return (
+                f"[{path_str} is {size} bytes, over the "
+                f"{MAX_READ_BYTES}-byte cap; read loads the whole file into "
+                f"memory, so slice it with bash instead, e.g. with "
+                f"sed -n '1,200p']",
+                True,
+            )
+        data = path.read_bytes()
+    except FileNotFoundError:  # the file went away after the check above
+        return f"[file not found: {path_str}]", True
+    except OSError as exc:
+        return f"[cannot read {path_str}: {exc}]", True
+
+    # Null bytes near the start mark a binary file; a text reading of it
+    # would only waste context.
+    if b"\x00" in data[:8192]:
+        return f"[{path_str} looks like a binary file; read is text-only]", True
+
+    # Split on \n alone, not with splitlines(): that also breaks on \x0c,
+    # \x0b, \x85 and U+2028, which would number the lines differently from
+    # sed, grep -n and the user's editor. A trailing \r is dropped so CRLF
+    # files read like LF ones.
+    lines = [
+        line.removesuffix("\r")
+        for line in data.decode("utf-8", errors="replace").split("\n")
+    ]
+    if lines and lines[-1] == "":
+        lines.pop()  # the newline ending the last line starts no new one
+    total = len(lines)
+    if total == 0:
+        return "(empty file)", False
+    if offset > total:
+        return (
+            f"[offset {offset} is past the end of {path_str} ({total} lines)]",
+            True,
+        )
+
+    max_lines = MAX_READ_LINES if limit is None else min(limit, MAX_READ_LINES)
+    window = lines[offset - 1 : offset - 1 + max_lines]
+
+    # A single line over the character cap cannot be returned whole, and
+    # returning a bare fragment would hide where it came from — point at
+    # bash instead. The path goes into a command the model may run, so it
+    # is the expanded one (quoting would stop the shell from expanding ~),
+    # quoted so spaces and $(...) in a filename cannot reshape the command,
+    # and behind -- so a leading dash cannot read as an option.
+    if len(window[0]) > MAX_READ_CHARS:
+        return (
+            f"[line {offset} is {len(window[0])} characters long, over the "
+            f"{MAX_READ_CHARS}-character cap; slice it with bash instead, "
+            f"e.g. sed -n '{offset}p' -- {shlex.quote(str(path))} "
+            f"| cut -c 1-2000]",
+            True,
+        )
+
+    selected: list[str] = []
+    chars = 0
+    for number, line in enumerate(window, start=offset):
+        rendered = f"{number:6}\t{line}"
+        added = len(rendered) + (1 if selected else 0)  # + the joining newline
+        if selected and chars + added > MAX_READ_CHARS:
+            break
+        selected.append(rendered)
+        chars += added
+
+    last = offset + len(selected) - 1
+    body = "\n".join(selected)
+    if last < total:
+        body += (
+            f"\n[showing lines {offset}-{last} of {total}; "
+            f"continue with offset={last + 1}]"
+        )
+    return body, False

{nanopycodeagent-0.4.0.dist-info → nanopycodeagent-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nanoPyCodeAgent
-Version: 0.4.0
+Version: 0.5.0
 Summary: A nano code agent built from scratch in pure Python.
 Project-URL: Homepage, https://github.com/minixalpha/nanoPyCodeAgent
 Project-URL: Repository, https://github.com/minixalpha/nanoPyCodeAgent

nanopycodeagent-0.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+nanopycodeagent/__init__.py,sha256=pYFCw7WNkZsGXbqNLkXituX4iBy86RJ4LKKAr78XwM8,70
+nanopycodeagent/agent.py,sha256=AAOnt1q-6FQgcAOODxHv2iM0UwlbqSnPD8kmtPGPo68,5452
+nanopycodeagent/bash_tool.py,sha256=fTaGz4gfFpBykBaw4jyYeKgibOKrIfJMKqBYoBEE4og,2958
+nanopycodeagent/read_tool.py,sha256=4AddoZ8uHGzPNKMFagrskjmOWv5nhpk3oJbG8eBBgcM,7374
+nanopycodeagent/settings.py,sha256=Tn9si3uRTt2IioP4GTYJGuCYVBCyTTJErq9FmuTs0pw,1296
+nanopycodeagent/terminal.py,sha256=ZkRvKbGQGiu7SI8Pe40THVYR1-4CMBEMVEgAH8h8Ytw,995
+nanopycodeagent-0.5.0.dist-info/METADATA,sha256=Bep9XESPN7PJ34J9zPvh4YtXdfQ1h2Yeh1Ht5uZdG9E,3028
+nanopycodeagent-0.5.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+nanopycodeagent-0.5.0.dist-info/entry_points.txt,sha256=4gU7YNzQaf2RKlOdfebOWYNYIUk2LDoyhu3G4Vgole8,57
+nanopycodeagent-0.5.0.dist-info/licenses/LICENSE,sha256=g24TppoiLdeF_1_-Y7H2H_eOavKseWA5utuK83Vq1sA,1067
+nanopycodeagent-0.5.0.dist-info/RECORD,,

nanopycodeagent-0.4.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-nanopycodeagent/__init__.py,sha256=pYFCw7WNkZsGXbqNLkXituX4iBy86RJ4LKKAr78XwM8,70
-nanopycodeagent/agent.py,sha256=AvfiDvaPVycbA3H_jJhD8DA_gELbcPOxrZWrZfa2hek,4354
-nanopycodeagent/bash_tool.py,sha256=fTaGz4gfFpBykBaw4jyYeKgibOKrIfJMKqBYoBEE4og,2958
-nanopycodeagent/settings.py,sha256=Tn9si3uRTt2IioP4GTYJGuCYVBCyTTJErq9FmuTs0pw,1296
-nanopycodeagent/terminal.py,sha256=ZkRvKbGQGiu7SI8Pe40THVYR1-4CMBEMVEgAH8h8Ytw,995
-nanopycodeagent-0.4.0.dist-info/METADATA,sha256=a0FBbVdPfx9K8zYiGA6fMZh2ZqC6tvFUm2OZTymLeUs,3028
-nanopycodeagent-0.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-nanopycodeagent-0.4.0.dist-info/entry_points.txt,sha256=4gU7YNzQaf2RKlOdfebOWYNYIUk2LDoyhu3G4Vgole8,57
-nanopycodeagent-0.4.0.dist-info/licenses/LICENSE,sha256=g24TppoiLdeF_1_-Y7H2H_eOavKseWA5utuK83Vq1sA,1067
-nanopycodeagent-0.4.0.dist-info/RECORD,,