eljay-ai 1.1.0

package/agent/builtin_tools.py

@@ -0,0 +1,591 @@
+"""Built-in tools for ElJay AI.
+
+This module registers every tool the agent can use. Tools are classified by
+risk tier:
+
+* ``RISK_SAFE``  — read-only, never prompts.
+* ``RISK_ASK``   — needs user confirmation (file writes, commands).
+* ``RISK_HIGH``  — dangerous (reserved for future delete/git-push).
+
+Phases 4-6 added read-only project inspection. Phase 7 added safe file
+editing. Phase 9 adds terminal execution, web research, git history, and
+detection-only image/video generation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .edits import (
+    create_file as _create_file,
+    edit_file as _edit_file,
+    preview_create,
+    preview_edit,
+)
+from .gitaware import (
+    changed_files,
+    git_diff as _git_diff,
+    git_log as _git_log,
+    status as _git_status,
+)
+from .memory import Memory
+from .providers import (
+    PROVIDERS,
+    ImageProvider,
+    OllamaProvider,
+    VideoProvider,
+    WebSearchProvider,
+    detect_ollama,
+)
+from .providers.web import fetch_web_page as _fetch_web_page
+from .providers.web import search_ddg as _search_ddg
+from .runner import classify_command
+from .runner import run_command as _run_command
+from .tools import RISK_ASK, RISK_HIGH, RISK_SAFE, Tool, ToolRegistry
+from .verification import format_checks
+from .workspace import Workspace
+
+try:
+    from .agents import list_agents as _list_agent_defs
+    _has_agents = True
+except Exception:
+    _has_agents = False
+    _list_agent_defs = None
+
+
+def _as_int(value: Any, default: int, minimum: int, maximum: int | None = None) -> int:
+    try:
+        result = int(value)
+    except (TypeError, ValueError):
+        return default
+    if result < minimum:
+        result = minimum
+    if maximum is not None and result > maximum:
+        result = maximum
+    return result
+
+
+def _as_bool(value: Any, default: bool = False) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, str):
+        return value.strip().lower() in ("1", "true", "yes", "y", "on")
+    return bool(value)
+
+
+def _get_current_time() -> str:
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def register_builtin_tools(
+    registry: ToolRegistry,
+    workspace: Workspace,
+    memory: Memory | None = None,
+) -> None:
+    # --- safe read-only tools ------------------------------------------
+
+    def project_info() -> str:
+        return workspace.summary()
+
+    def detect_checks() -> str:
+        return format_checks(workspace)
+
+    def git_status() -> str:
+        return _git_status(workspace)
+
+    def git_log(n: Any = 10) -> str:
+        return _git_log(workspace, _as_int(n, 10, 1, 50))
+
+    def git_diff(target: str = "", n: Any = 3) -> str:
+        return _git_diff(workspace, str(target), _as_int(n, 3, 1, 20))
+
+    def remember(text: str) -> str:
+        if memory is None:
+            return "ERROR: memory is not available"
+        memory.add_note(str(text))
+        return f"Remembered: {text}"
+
+    def list_files(path: str = ".", depth: int = 2, max_entries: int = 200) -> str:
+        return workspace.list_tree(
+            rel=str(path) if path is not None else ".",
+            depth=_as_int(depth, 2, 0, 12),
+            max_entries=_as_int(max_entries, 200, 1, 2000),
+        )
+
+    def read_file(path: str, start_line: Any = None, end_line: Any = None) -> str:
+        start = _as_int(start_line, 0, 0, 10 ** 9) or None
+        end = _as_int(end_line, 0, 0, 10 ** 9) or None
+        return workspace.read_file(str(path), start, end)
+
+    def search_code(
+        query: str,
+        path: str = ".",
+        regex: Any = False,
+        case_sensitive: Any = False,
+        max_results: Any = 50,
+    ) -> str:
+        return workspace.search(
+            query=str(query),
+            rel=str(path) if path is not None else ".",
+            regex=_as_bool(regex),
+            case_sensitive=_as_bool(case_sensitive),
+            max_results=_as_int(max_results, 50, 1, 500),
+        )
+
+    # --- write tools (risk: ask) --------------------------------------
+
+    def create_file(path: str, content: str) -> str:
+        return _create_file(workspace, str(path), content)
+
+    def edit_file(
+        path: str, old_text: str, new_text: str, replace_all: Any = False
+    ) -> str:
+        return _edit_file(
+            workspace, str(path), old_text, new_text, _as_bool(replace_all)
+        )
+
+    # --- command execution (risk: per-call) --------------------------
+
+    def run_command(command: str, cwd: str = ".", timeout: Any = 120) -> str:
+        return _run_command(
+            workspace,
+            str(command),
+            cwd=str(cwd) if cwd not in (None, "") else ".",
+            timeout=_as_int(timeout, 120, 1, 600),
+        )
+
+    def preview_run(command: str = "", cwd: str = ".", **_: Any) -> str:
+        risk = classify_command(str(command))
+        where = str(cwd) if cwd not in (None, "") else "."
+        return f"RUN (risk: {risk}) in {where}:\n    $ {command}"
+
+    def risk_run(command: str = "", **_: Any) -> str:
+        return classify_command(str(command))
+
+    # --- web research tools (safe) ------------------------------------
+
+    def web_search(query: str, max_results: Any = 10) -> str:
+        results = _search_ddg(query=str(query), max_results=_as_int(max_results, 10, 1, 50))
+        if not results:
+            return "No search results returned."
+        lines = ["Search results for: " + str(query)]
+        for i, r in enumerate(results, 1):
+            if "error" in r:
+                lines.append(f"  [{i}] (error) {r['error']}")
+                continue
+            url = r.get("url", "")
+            snippet = r.get("snippet", "(no snippet)")
+            lines.append(
+                f"  [{i}] {r.get('title', '?')}\n"
+                f"      URL: {url}\n"
+                f"      {snippet[:200]}"
+            )
+        return "\n".join(lines)
+
+    def fetch_web_page(url: str, max_chars: Any = 8000) -> str:
+        text = _fetch_web_page(str(url), _as_int(max_chars, 8000, 100, 50000))
+        return text
+
+    # --- git history tools (safe) -------------------------------------
+
+    def get_git_log(n: Any = 10) -> str:
+        return _git_log(workspace, _as_int(n, 10, 1, 50))
+
+    def get_git_diff(target: str = "", n: Any = 3) -> str:
+        return _git_diff(workspace, str(target), _as_int(n, 3, 1, 20))
+
+    # --- provider / agent info (safe) ---------------------------------
+
+    def list_providers() -> str:
+        if not __import__("os").environ.get("AGENT_NO_PROVIDER_CHECK"):
+            for p in PROVIDERS:
+                p.is_available()
+        lines = ["Available providers:"]
+        for p in PROVIDERS:
+            lines.append(f"  {p.status_string()}")
+        if not any(p.is_available() for p in PROVIDERS):
+            lines.append("  (none available)")
+        return "\n".join(lines)
+
+    def list_agents_func() -> str:
+        if not _has_agents or _list_agent_defs is None:
+            return "Agent registry not available."
+        lines = ["Specialized agents:"]
+        for agent in sorted(_list_agent_defs(), key=lambda a: (-a.priority, a.name)):
+            tools_list = ", ".join(agent.tools[:8])
+            if len(agent.tools) > 8:
+                tools_list += f" (+{len(agent.tools) - 8} more)"
+            lines.append(f"  {agent.name:12s} — {agent.purpose}")
+            lines.append(f"               tools: {tools_list}")
+            lines.append(f"               providers: {', '.join(agent.providers) or 'none'}")
+        return "\n".join(lines)
+
+    # --- image / video generation (detection only) --------------------
+
+    def _check_image_provider() -> tuple[ImageProvider, bool, str]:
+        provider = ImageProvider()
+        ok = provider.is_available()
+        return provider, ok, provider.error or ""
+
+    def generate_image(prompt: str, style: str = "", steps: Any = 20) -> str:
+        provider, ok, err = _check_image_provider()
+        if not ok:
+            return (
+                f"[unavailable] No local image-generation backend found.\n{err}\n"
+                "Install one of: ComfyUI, or `pip install diffusers[torch]`."
+            )
+        result = provider.execute("image-generation", prompt=prompt, style=style, steps=steps)
+        # If the provider returned a placeholder, surface it honestly.
+        if result.startswith("[ComfyUI]") or result.startswith("[diffusers]"):
+            return result
+        return f"[{provider.model}] {result}"
+
+    def _check_video_provider() -> tuple[VideoProvider, bool, str]:
+        provider = VideoProvider()
+        ok = provider.is_available()
+        return provider, ok, provider.error or ""
+
+    def generate_video(prompt: str, duration: Any = 4) -> str:
+        provider, ok, err = _check_video_provider()
+        if not ok:
+            return (
+                f"[unavailable] Video generation is not available on this system.\n{err}\n"
+                "Local video generation requires a GPU with >= 6 GB VRAM and a backend "
+                "like ComfyUI + AnimateDiff or diffusers + animatediff. "
+                "Cloud services are an alternative for this task."
+            )
+        return provider.execute("video-generation", prompt=prompt, duration=duration)
+
+    # -- previews for confirmation ---------------------------------------
+
+    def preview_create_callable(path: str = "", content: str = "", **_: Any) -> str:
+        return preview_create(str(path), content)
+
+    def preview_edit_callable(
+        path: str = "",
+        old_text: str = "",
+        new_text: str = "",
+        replace_all: Any = False,
+        **_: Any,
+    ) -> str:
+        return preview_edit(str(path), old_text, new_text, _as_bool(replace_all))
+
+    # -- registration ----------------------------------------------------
+
+    _register_get_current_time(registry)
+    _register_project_info(registry, project_info)
+    _register_detect_checks(registry, detect_checks)
+    _register_git_status(registry, git_status)
+    _register_git_log(registry, get_git_log)
+    _register_git_diff(registry, get_git_diff)
+    _register_remember(registry, remember)
+    _register_list_files(registry, list_files)
+    _register_read_file(registry, read_file)
+    _register_search_code(registry, search_code)
+    _register_create_file(registry, create_file, preview_create_callable)
+    _register_edit_file(registry, edit_file, preview_edit_callable)
+    _register_run_command(registry, run_command, preview_run, risk_run)
+    _register_web_search(registry, web_search)
+    _register_fetch_web_page(registry, fetch_web_page)
+    _register_list_providers(registry, list_providers)
+    _register_list_agents(registry, list_agents_func)
+    _register_generate_image(registry, generate_image)
+    _register_generate_video(registry, generate_video)
+
+
+# ---------------------------------------------------------------------------
+# Individual registration helpers (keeps the function above clean and makes
+# it easy to see each tool's schema + risk at a glance).
+# ---------------------------------------------------------------------------
+
+def _register_get_current_time(registry: ToolRegistry) -> None:
+    registry.register(Tool(
+        name="get_current_time",
+        description="Return the current local date and time on the user's machine.",
+        parameters={"type": "object", "properties": {}, "required": []},
+        func=_get_current_time,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_project_info(registry, func):
+    registry.register(Tool(
+        name="project_info",
+        description="Describe the current project: name, root folder, detected technologies.",
+        parameters={"type": "object", "properties": {}, "required": []},
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_detect_checks(registry, func):
+    registry.register(Tool(
+        name="detect_checks",
+        description="List the project's verification commands (lint, test, build), smallest first.",
+        parameters={"type": "object", "properties": {}, "required": []},
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_git_status(registry, func):
+    registry.register(Tool(
+        name="git_status",
+        description="Show the git branch and changed files (read-only). Never commits or pushes.",
+        parameters={"type": "object", "properties": {}, "required": []},
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_git_log(registry, func):
+    registry.register(Tool(
+        name="git_log",
+        description="Show recent git commit history (read-only, up to 50 entries).",
+        parameters={
+            "type": "object",
+            "properties": {"n": {"type": "integer", "description": "Number of commits to show (1-50). Default 10."}},
+            "required": [],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_git_diff(registry, func):
+    registry.register(Tool(
+        name="git_diff",
+        description="Show uncommitted changes or diff for a target (read-only).",
+        parameters={
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "File or branch to diff against. Default: uncommitted changes."},
+                "n": {"type": "integer", "description": "Max number of lines. Default 3."},
+            },
+            "required": [],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_remember(registry, func):
+    registry.register(Tool(
+        name="remember",
+        description="Save a fact to local memory (.agent/) for future recall.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "text": {"type": "string", "description": "The fact to remember, one short sentence."}
+            },
+            "required": ["text"],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_list_files(registry, func):
+    registry.register(Tool(
+        name="list_files",
+        description="List files and folders in the project (read-only). Skips build/cache folders.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Folder to list, relative to root. Defaults to root."},
+                "depth": {"type": "integer", "description": "Folder levels to show (0-12). Default 2."},
+                "max_entries": {"type": "integer", "description": "Max entries (1-2000). Default 200."},
+            },
+            "required": [],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_read_file(registry, func):
+    registry.register(Tool(
+        name="read_file",
+        description="Read a text file (read-only) with line numbers. Binary files refused.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "File to read, relative to project root."},
+                "start_line": {"type": "integer", "description": "First line (1-based). Optional."},
+                "end_line": {"type": "integer", "description": "Last line (inclusive). Optional."},
+            },
+            "required": ["path"],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_search_code(registry, func):
+    registry.register(Tool(
+        name="search_code",
+        description="Search project files for text/regex. Returns path:line: snippet.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Text to find (or regex if regex=true)."},
+                "path": {"type": "string", "description": "Folder/file to search. Defaults to whole project."},
+                "regex": {"type": "boolean", "description": "Treat query as regex. Default false."},
+                "case_sensitive": {"type": "boolean", "description": "Exact case. Default false."},
+                "max_results": {"type": "integer", "description": "Max matches (1-500). Default 50."},
+            },
+            "required": ["query"],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_create_file(registry, func, preview):
+    registry.register(Tool(
+        name="create_file",
+        description="Create a NEW file. Cannot overwrite existing files. Requires approval.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "New file path, relative to project root."},
+                "content": {"type": "string", "description": "Full content of the new file."},
+            },
+            "required": ["path", "content"],
+        },
+        func=func,
+        risk=RISK_ASK,
+        preview=preview,
+    ))
+
+
+def _register_edit_file(registry, func, preview):
+    registry.register(Tool(
+        name="edit_file",
+        description="Replace exact text in an existing file. Requires approval.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "File to edit."},
+                "old_text": {"type": "string", "description": "Exact text to replace."},
+                "new_text": {"type": "string", "description": "Replacement text."},
+                "replace_all": {"type": "boolean", "description": "Replace all occurrences. Default false."},
+            },
+            "required": ["path", "old_text", "new_text"],
+        },
+        func=func,
+        risk=RISK_ASK,
+        preview=preview,
+    ))
+
+
+def _register_run_command(registry, func, preview, risk_func):
+    registry.register(Tool(
+        name="run_command",
+        description="Run ONE terminal command in the project. No pipes/redirects. Shown for approval first.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "command": {"type": "string", "description": "The single command to run."},
+                "cwd": {"type": "string", "description": "Working dir relative to root. Defaults to root."},
+                "timeout": {"type": "integer", "description": "Seconds (1-600). Default 120."},
+            },
+            "required": ["command"],
+        },
+        func=func,
+        risk=RISK_ASK,
+        preview=preview,
+        risk_func=risk_func,
+    ))
+
+
+def _register_web_search(registry, func):
+    registry.register(Tool(
+        name="web_search",
+        description="Search the web via DuckDuckGo Lite (free, no API key). Returns titles, URLs, snippets.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query."},
+                "max_results": {"type": "integer", "description": "Max results (1-50). Default 10."},
+            },
+            "required": ["query"],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_fetch_web_page(registry, func):
+    registry.register(Tool(
+        name="fetch_web_page",
+        description="Fetch a URL and return readable text. Respects rate limits; no paywall bypass.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "url": {"type": "string", "description": "Full http:// or https:// URL."},
+                "max_chars": {"type": "integer", "description": "Max characters to return. Default 8000."},
+            },
+            "required": ["url"],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_list_providers(registry, func):
+    registry.register(Tool(
+        name="list_providers",
+        description="List all AI providers and their availability status.",
+        parameters={"type": "object", "properties": {}, "required": []},
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_list_agents(registry, func):
+    registry.register(Tool(
+        name="list_agents",
+        description="List all specialized agents (Coding, Research, Image, Video, Knowledge) and their capabilities.",
+        parameters={"type": "object", "properties": {}, "required": []},
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_generate_image(registry, func):
+    registry.register(Tool(
+        name="generate_image",
+        description="Generate an image from a text prompt using local providers. Reports availability honestly.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "prompt": {"type": "string", "description": "Detailed image description."},
+                "style": {"type": "string", "description": "Optional style modifier. Default empty."},
+                "steps": {"type": "integer", "description": "Generation steps. Default 20."},
+            },
+            "required": ["prompt"],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))
+
+
+def _register_generate_video(registry, func):
+    registry.register(Tool(
+        name="generate_video",
+        description="Generate video from a text prompt. Reports hardware requirements honestly.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "prompt": {"type": "string", "description": "Detailed video description."},
+                "duration": {"type": "integer", "description": "Duration in seconds. Default 4."},
+            },
+            "required": ["prompt"],
+        },
+        func=func,
+        risk=RISK_SAFE,
+    ))