llmcode-cli 1.0.0__py3-none-any.whl

llm_code/tools/notebook_edit.py

@@ -0,0 +1,107 @@
+"""NotebookEditTool — replace, insert, or delete cells in a Jupyter notebook."""
+from __future__ import annotations
+
+import json
+import pathlib
+
+from pydantic import BaseModel
+
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+from llm_code.utils.notebook import edit_notebook, validate_notebook
+
+
+class NotebookEditInput(BaseModel):
+    path: str
+    command: str
+    cell_index: int
+    source: str | None = None
+    cell_type: str | None = None
+
+
+class NotebookEditTool(Tool):
+    @property
+    def name(self) -> str:
+        return "notebook_edit"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Edit a Jupyter notebook (.ipynb) file by replacing, inserting, or deleting a cell. "
+            "Use 'replace' to change a cell's source, 'insert' to add a new cell before a given index, "
+            "or 'delete' to remove a cell."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Absolute path to the .ipynb file"},
+                "command": {
+                    "type": "string",
+                    "enum": ["replace", "insert", "delete"],
+                    "description": "Edit command: replace, insert, or delete",
+                },
+                "cell_index": {
+                    "type": "integer",
+                    "description": "0-based cell index to operate on",
+                },
+                "source": {
+                    "type": "string",
+                    "description": "New cell source (required for replace and insert)",
+                },
+                "cell_type": {
+                    "type": "string",
+                    "enum": ["code", "markdown", "raw"],
+                    "description": "Cell type for insert or replace (default: code)",
+                },
+            },
+            "required": ["path", "command", "cell_index"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.WORKSPACE_WRITE
+
+    @property
+    def input_model(self) -> type[NotebookEditInput]:
+        return NotebookEditInput
+
+    def execute(self, args: dict) -> ToolResult:
+        path = pathlib.Path(args["path"])
+        command: str = args["command"]
+        cell_index: int = int(args["cell_index"])
+        source: str | None = args.get("source")
+        cell_type: str | None = args.get("cell_type")
+
+        if command not in ("replace", "insert", "delete"):
+            return ToolResult(
+                output=f"Invalid command {command!r}. Use replace, insert, or delete.",
+                is_error=True,
+            )
+
+        if not path.exists():
+            return ToolResult(output=f"Notebook not found: {path}", is_error=True)
+
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            return ToolResult(output=f"Failed to parse notebook JSON: {exc}", is_error=True)
+
+        if not validate_notebook(data):
+            return ToolResult(
+                output="Invalid notebook: requires nbformat >= 4 and a cells list.",
+                is_error=True,
+            )
+
+        try:
+            updated = edit_notebook(data, command, cell_index, source=source, cell_type=cell_type)
+        except (IndexError, ValueError) as exc:
+            return ToolResult(output=str(exc), is_error=True)
+
+        path.write_text(json.dumps(updated, indent=1, ensure_ascii=False), encoding="utf-8")
+
+        n_cells = len(updated.get("cells", []))
+        return ToolResult(
+            output=f"Notebook updated: {command} at cell {cell_index}. Notebook now has {n_cells} cell(s)."
+        )

llm_code/tools/notebook_read.py

@@ -0,0 +1,81 @@
+"""NotebookReadTool — reads Jupyter notebook cells with outputs."""
+from __future__ import annotations
+
+import json
+import pathlib
+
+from pydantic import BaseModel
+
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+from llm_code.utils.notebook import format_cells, parse_notebook, validate_notebook
+
+
+class NotebookReadInput(BaseModel):
+    path: str
+
+
+class NotebookReadTool(Tool):
+    @property
+    def name(self) -> str:
+        return "notebook_read"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Read a Jupyter notebook (.ipynb) file. "
+            "Returns all cells with their source code, outputs, and execution counts. "
+            "Images from outputs are returned as base64 in metadata."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Absolute path to the .ipynb file"},
+            },
+            "required": ["path"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.READ_ONLY
+
+    @property
+    def input_model(self) -> type[NotebookReadInput]:
+        return NotebookReadInput
+
+    def is_read_only(self, args: dict) -> bool:
+        return True
+
+    def is_concurrency_safe(self, args: dict) -> bool:
+        return True
+
+    def execute(self, args: dict) -> ToolResult:
+        path = pathlib.Path(args["path"])
+
+        if not path.exists():
+            return ToolResult(output=f"Notebook not found: {path}", is_error=True)
+
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            return ToolResult(output=f"Failed to parse notebook JSON: {exc}", is_error=True)
+
+        if not validate_notebook(data):
+            return ToolResult(
+                output="Invalid notebook: requires nbformat >= 4 and a cells list.",
+                is_error=True,
+            )
+
+        cells = parse_notebook(data)
+        output_text = format_cells(cells)
+
+        # Collect all images from all cells
+        all_images: list[dict] = []
+        for cell in cells:
+            all_images.extend(cell.images)
+
+        metadata: dict | None = {"images": all_images} if all_images else None
+
+        return ToolResult(output=output_text, metadata=metadata)

llm_code/tools/parsing.py

@@ -0,0 +1,63 @@
+"""Dual-track tool call parsing: native API format and XML tag format."""
+from __future__ import annotations
+
+import dataclasses
+import json
+import re
+import uuid
+
+_XML_TOOL_CALL_RE = re.compile(
+    r"<tool_call>(.*?)</tool_call>",
+    re.DOTALL,
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class ParsedToolCall:
+    id: str
+    name: str
+    args: dict
+    source: str  # "native" | "xml_tag"
+
+
+def parse_tool_calls(
+    response_text: str,
+    native_tool_calls: list[dict] | None,
+) -> list[ParsedToolCall]:
+    """Parse tool calls from either native API format or XML tags in text.
+
+    If native_tool_calls is a non-empty list, parse those (native track).
+    Otherwise, fall back to scanning response_text for <tool_call>...</tool_call> tags.
+    """
+    if native_tool_calls:
+        return _parse_native(native_tool_calls)
+    return _parse_xml(response_text)
+
+
+def _parse_native(native: list[dict]) -> list[ParsedToolCall]:
+    result: list[ParsedToolCall] = []
+    for call in native:
+        call_id = call.get("id", str(uuid.uuid4()))
+        name = call.get("name", "")
+        args = call.get("input", {})
+        if not name:
+            continue
+        result.append(ParsedToolCall(id=call_id, name=name, args=args, source="native"))
+    return result
+
+
+def _parse_xml(text: str) -> list[ParsedToolCall]:
+    result: list[ParsedToolCall] = []
+    for match in _XML_TOOL_CALL_RE.finditer(text):
+        raw = match.group(1).strip()
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        name = data.get("tool")
+        if not name:
+            continue
+        args = data.get("args", {})
+        call_id = str(uuid.uuid4())
+        result.append(ParsedToolCall(id=call_id, name=name, args=args, source="xml_tag"))
+    return result

llm_code/tools/read_file.py

@@ -0,0 +1,154 @@
+"""ReadFileTool — reads text files with line numbers, or images as base64."""
+from __future__ import annotations
+
+import base64
+import json
+import pathlib
+
+from pydantic import BaseModel
+
+from llm_code.runtime.file_protection import check_read
+from llm_code.tools.base import PermissionLevel, Tool, ToolResult
+from llm_code.utils.errors import friendly_error
+
+
+class ReadFileInput(BaseModel):
+    path: str
+    offset: int = 1
+    limit: int = 2000
+
+_NOTEBOOK_EXTENSION = ".ipynb"
+
+_IMAGE_EXTENSIONS = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".svg": "image/svg+xml",
+}
+
+
+class ReadFileTool(Tool):
+    @property
+    def name(self) -> str:
+        return "read_file"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Read a file from the filesystem. "
+            "Text files are returned with line numbers. "
+            "Images are returned as base64 in metadata."
+        )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Absolute path to the file"},
+                "offset": {
+                    "type": "integer",
+                    "description": "1-based line number to start reading from (default 1)",
+                    "default": 1,
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum number of lines to read (default 2000)",
+                    "default": 2000,
+                },
+            },
+            "required": ["path"],
+        }
+
+    @property
+    def required_permission(self) -> PermissionLevel:
+        return PermissionLevel.READ_ONLY
+
+    @property
+    def input_model(self) -> type[ReadFileInput]:
+        return ReadFileInput
+
+    def is_read_only(self, args: dict) -> bool:
+        return True
+
+    def is_concurrency_safe(self, args: dict) -> bool:
+        return True
+
+    def execute(self, args: dict) -> ToolResult:
+        path = pathlib.Path(args["path"])
+        offset: int = int(args.get("offset", 1))
+        limit: int = int(args.get("limit", 2000))
+
+        if not path.exists():
+            return ToolResult(output=f"File not found: {path}", is_error=True)
+
+        if path.is_dir():
+            return ToolResult(
+                output=f"Path is a directory, not a file: {path}\nUse glob_search or bash 'ls' to list directory contents.",
+                is_error=True,
+            )
+
+        read_check = check_read(str(path))
+        read_warning = read_check.reason if read_check.severity == "warn" else ""
+
+        suffix = path.suffix.lower()
+
+        if suffix == _NOTEBOOK_EXTENSION:
+            result = self._read_notebook(path)
+        elif suffix in _IMAGE_EXTENSIONS:
+            result = self._read_image(path, _IMAGE_EXTENSIONS[suffix])
+        else:
+            result = self._read_text(path, offset, limit)
+
+        if read_warning and not result.is_error:
+            result = ToolResult(
+                output=f"[WARNING] {read_warning}\n{result.output}",
+                metadata=result.metadata,
+                is_error=result.is_error,
+            )
+        return result
+
+    def _read_notebook(self, path: pathlib.Path) -> ToolResult:
+        from llm_code.utils.notebook import format_cells, parse_notebook, validate_notebook
+
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            return ToolResult(output=f"Failed to parse notebook JSON: {exc}", is_error=True)
+
+        if not validate_notebook(data):
+            return ToolResult(
+                output="Invalid notebook: requires nbformat >= 4 and a cells list.",
+                is_error=True,
+            )
+
+        cells = parse_notebook(data)
+        output_text = format_cells(cells)
+
+        all_images: list[dict] = []
+        for cell in cells:
+            all_images.extend(cell.images)
+
+        metadata: dict | None = {"images": all_images} if all_images else None
+        return ToolResult(output=output_text, metadata=metadata)
+
+    def _read_image(self, path: pathlib.Path, media_type: str) -> ToolResult:
+        data = base64.b64encode(path.read_bytes()).decode()
+        return ToolResult(
+            output=f"[image: {path.name}]",
+            metadata={"type": "image", "media_type": media_type, "data": data},
+        )
+
+    def _read_text(self, path: pathlib.Path, offset: int, limit: int) -> ToolResult:
+        try:
+            lines = path.read_text(errors="replace").splitlines()
+        except (PermissionError, OSError) as exc:
+            return ToolResult(output=friendly_error(exc, str(path)), is_error=True)
+        # offset is 1-based
+        start = max(offset - 1, 0)
+        selected = lines[start : start + limit]
+        numbered = "\n".join(f"{start + i + 1}\t{line}" for i, line in enumerate(selected))
+        return ToolResult(output=numbered)

llm_code/tools/registry.py

@@ -0,0 +1,58 @@
+"""Tool registry for managing and dispatching tools."""
+from __future__ import annotations
+
+from llm_code.api.types import ToolDefinition
+from llm_code.tools.base import Tool, ToolResult
+
+
+class ToolRegistry:
+    """Central registry for tools with lookup and execution."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        """Register a tool; raises ValueError if name already registered."""
+        if tool.name in self._tools:
+            raise ValueError(f"Tool '{tool.name}' is already registered")
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool | None:
+        """Return the tool with the given name, or None if not found."""
+        return self._tools.get(name)
+
+    def all_tools(self) -> tuple[Tool, ...]:
+        """Return all registered tools as a tuple."""
+        return tuple(self._tools.values())
+
+    def definitions(self, allowed: set[str] | None = None) -> tuple[ToolDefinition, ...]:
+        """Return ToolDefinitions, optionally filtered to allowed names."""
+        tools = self._tools.values()
+        if allowed is not None:
+            tools = (t for t in tools if t.name in allowed)  # type: ignore[assignment]
+        return tuple(t.to_definition() for t in tools)
+
+    def definitions_with_deferred(
+        self,
+        allowed: set[str] | None = None,
+        max_visible: int = 20,
+    ) -> tuple[tuple[ToolDefinition, ...], int]:
+        """Return (visible_definitions, deferred_count) using DeferredToolManager.
+
+        Core tools are always visible; remaining tools fill slots up to
+        max_visible; the rest are deferred.  Returns the visible definitions
+        as a tuple and the count of deferred tools as an integer.
+        """
+        from llm_code.tools.deferred import DeferredToolManager
+
+        all_defs = list(self.definitions(allowed=allowed))
+        manager = DeferredToolManager()
+        visible, deferred = manager.select_tools(all_defs, max_visible=max_visible)
+        return tuple(visible), len(deferred)
+
+    def execute(self, name: str, args: dict) -> ToolResult:
+        """Execute a tool by name; returns is_error=True if tool not found."""
+        tool = self._tools.get(name)
+        if tool is None:
+            return ToolResult(output=f"Tool '{name}' not found", is_error=True)
+        return tool.execute(args)

llm_code/tools/search_backends/__init__.py

@@ -0,0 +1,56 @@
+"""Search backend protocol and factory."""
+from __future__ import annotations
+
+import dataclasses
+from typing import Protocol, runtime_checkable
+
+
+@dataclasses.dataclass(frozen=True)
+class SearchResult:
+    """A single search result."""
+
+    title: str
+    url: str
+    snippet: str
+
+
+@runtime_checkable
+class SearchBackend(Protocol):
+    """Protocol for search backends."""
+
+    @property
+    def name(self) -> str:
+        """Backend identifier."""
+        ...
+
+    def search(self, query: str, *, max_results: int = 10) -> tuple[SearchResult, ...]:
+        """Execute search and return results.
+
+        Returns empty tuple on error.
+        """
+        ...
+
+
+def create_backend(backend_name: str, **kwargs: object) -> SearchBackend:
+    """Factory function to create a search backend by name.
+
+    Args:
+        backend_name: One of "duckduckgo", "brave", "tavily", "searxng".
+        **kwargs: Backend-specific keyword arguments (e.g. api_key, base_url).
+
+    Raises:
+        ValueError: If backend_name is not recognized.
+    """
+    if backend_name == "duckduckgo":
+        from llm_code.tools.search_backends.duckduckgo import DuckDuckGoBackend
+        return DuckDuckGoBackend(**kwargs)
+    if backend_name == "brave":
+        from llm_code.tools.search_backends.brave import BraveBackend
+        return BraveBackend(**kwargs)
+    if backend_name == "tavily":
+        from llm_code.tools.search_backends.tavily import TavilyBackend
+        return TavilyBackend(**kwargs)
+    if backend_name == "searxng":
+        from llm_code.tools.search_backends.searxng import SearXNGBackend
+        return SearXNGBackend(**kwargs)
+    raise ValueError(f"Unknown search backend: {backend_name!r}")

llm_code/tools/search_backends/brave.py

@@ -0,0 +1,56 @@
+"""Brave Search backend."""
+from __future__ import annotations
+
+import httpx
+
+from llm_code.tools.search_backends import SearchResult
+
+_BRAVE_SEARCH_URL = "https://api.search.brave.com/res/v1/web/search"
+
+
+class BraveBackend:
+    """Search backend using Brave Search API (free tier: 2000 queries/month)."""
+
+    def __init__(self, api_key: str) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key must not be empty")
+        self._api_key = api_key
+
+    @property
+    def name(self) -> str:
+        return "brave"
+
+    def search(self, query: str, *, max_results: int = 10) -> tuple[SearchResult, ...]:
+        try:
+            response = httpx.get(
+                _BRAVE_SEARCH_URL,
+                params={"q": query, "count": max_results},
+                headers={
+                    "Accept": "application/json",
+                    "Accept-Encoding": "gzip",
+                    "X-Subscription-Token": self._api_key,
+                },
+                timeout=15.0,
+            )
+        except httpx.RequestError:
+            return ()
+
+        if response.status_code != 200:
+            return ()
+
+        try:
+            data = response.json()
+        except Exception:
+            return ()
+
+        web_results = data.get("web", {}).get("results", [])
+        results = tuple(
+            SearchResult(
+                title=r.get("title", ""),
+                url=r.get("url", ""),
+                snippet=r.get("description", ""),
+            )
+            for r in web_results[:max_results]
+            if r.get("url")
+        )
+        return results