eljay-ai 1.1.0

package/agent/agent.py

@@ -0,0 +1,269 @@
+"""Agent core: the reason -> act -> observe loop with tool calling.
+
+The model is asked to reply either with a normal answer, or with a JSON object
+`{"name": "<tool>", "arguments": {...}}` when it needs a tool. We support two
+mechanisms so the agent works across models:
+
+1. Native tool calls (`message.tool_calls`) — used by larger/capable models.
+2. Text fallback — small models like qwen2.5-coder:3b emit the call as plain
+   JSON text in `message.content`. We parse that.
+
+Phase 1/3 testing on this machine showed qwen2.5-coder:3b uses mechanism (2),
+so the fallback is not optional — it is the primary path here.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from typing import Any
+
+from .context import trim_messages
+from .ollama_client import OllamaClient
+from .permissions import PermissionPolicy
+from .tools import ToolRegistry
+
+# Matches fenced code blocks (```json ... ``` or ``` ... ```).
+_FENCE_RE = re.compile(r"```(?:json)?\s*(.*?)```", re.DOTALL)
+
+# Keys models use to carry tool arguments.
+_ARG_KEYS = ("arguments", "parameters", "args")
+
+
+def _first_balanced_object(text: str) -> str | None:
+    """Return the first balanced {...} substring, ignoring braces in strings."""
+    start = text.find("{")
+    if start == -1:
+        return None
+    depth = 0
+    in_string = False
+    escaped = False
+    for i in range(start, len(text)):
+        ch = text[i]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start : i + 1]
+    return None
+
+
+def _json_object(text: str) -> dict[str, Any] | None:
+    try:
+        obj = json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    return obj if isinstance(obj, dict) else None
+
+
+class AgentCore:
+    def __init__(
+        self,
+        client: OllamaClient,
+        model: str,
+        registry: ToolRegistry,
+        system_prompt: str,
+        max_steps: int = 6,
+        on_event: Callable[[str], None] | None = None,
+        policy: PermissionPolicy | None = None,
+        max_context_chars: int = 0,
+    ) -> None:
+        self.client = client
+        self.model = model
+        self.registry = registry
+        self.system_prompt = system_prompt
+        self.max_steps = max_steps
+        self.on_event = on_event or (lambda _msg: None)
+        # Fail closed by default: a non-safe tool with no way to confirm is denied.
+        self.policy = policy or PermissionPolicy(on_event=self.on_event)
+        # 0 means "no trimming".
+        self.max_context_chars = max_context_chars
+
+    # -- tool call detection ----------------------------------------------
+
+    def _native_calls(self, message: dict[str, Any]) -> list[tuple[str, dict[str, Any]]]:
+        calls: list[tuple[str, dict[str, Any]]] = []
+        for raw in message.get("tool_calls") or []:
+            fn = raw.get("function") or {}
+            name = fn.get("name")
+            if not isinstance(name, str) or name not in self.registry:
+                continue
+            args = fn.get("arguments")
+            if isinstance(args, str):
+                args = _json_object(args) or {}
+            if not isinstance(args, dict):
+                args = {}
+            calls.append((name, args))
+        return calls
+
+    def _text_call(self, content: str) -> list[tuple[str, dict[str, Any]]]:
+        candidates: list[str] = [content.strip()]
+        candidates += [b.strip() for b in _FENCE_RE.findall(content)]
+        balanced = _first_balanced_object(content)
+        if balanced:
+            candidates.append(balanced)
+
+        for cand in candidates:
+            if not cand:
+                continue
+            obj = _json_object(cand)
+            if not obj:
+                continue
+            name = obj.get("name")
+            if not isinstance(name, str) or name not in self.registry:
+                continue
+            args: Any = {}
+            for key in _ARG_KEYS:
+                if key in obj:
+                    args = obj[key]
+                    break
+            if isinstance(args, str):
+                args = _json_object(args) or {}
+            if not isinstance(args, dict):
+                args = {}
+            return [(name, args)]
+        return []
+
+    def _detect_calls(
+        self, message: dict[str, Any], content: str
+    ) -> list[tuple[str, dict[str, Any]]]:
+        return self._native_calls(message) or self._text_call(content)
+
+    def _looks_like_bad_tool_call(self, content: str) -> bool:
+        """True if the model emitted tool-call-shaped JSON naming no real tool.
+
+        Small models sometimes emit `{"name": "None"}` or `{"name": "await"}`
+        for ordinary questions. We must not show that raw JSON to the user.
+        """
+        if not content.strip():
+            return False
+        candidates = [content.strip()]
+        candidates += [b.strip() for b in _FENCE_RE.findall(content)]
+        balanced = _first_balanced_object(content)
+        if balanced:
+            candidates.append(balanced)
+        for cand in candidates:
+            obj = _json_object(cand)
+            if not obj:
+                continue
+            if not any(k in obj for k in ("name",) + _ARG_KEYS):
+                continue
+            name = obj.get("name")
+            if not (isinstance(name, str) and name in self.registry):
+                return True
+        return False
+
+    def _nudge_message(self) -> str:
+        names = ", ".join(self.registry.names()) or "(none)"
+        return (
+            f"That JSON was not a valid tool call. Available tools: {names}. "
+            "Answer the user's request directly in plain language, or call one of "
+            'the available tools using {"name": "<tool_name>", "arguments": {...}}.'
+        )
+
+    # -- execution ---------------------------------------------------------
+
+    def _handle_call(self, name: str, args: dict[str, Any]) -> str:
+        """Run a tool, but only after it passes the permission gate."""
+        tool = self.registry.get(name)
+        if tool is None:
+            return f"ERROR: unknown tool '{name}'"
+        preview = tool.make_preview(args)
+        risk = tool.risk_for(args)
+        if not self.policy.request(tool, preview, risk):
+            return (
+                "PERMISSION DENIED: the user did not approve this operation. "
+                "Do not retry it. Explain what you intended to do, or ask the user."
+            )
+        return self._execute(name, args)
+
+    def _execute(self, name: str, args: dict[str, Any]) -> str:
+        self.on_event(f"[tool] {name}({json.dumps(args, ensure_ascii=False)})")
+        tool = self.registry.get(name)
+        if tool is None:  # defensive; _detect_calls already checked
+            return f"ERROR: unknown tool '{name}'"
+        try:
+            output = tool.run(args)
+        except TypeError as exc:
+            return f"ERROR: bad arguments for '{name}': {exc}"
+        except Exception as exc:  # noqa: BLE001 - surface any tool failure to the model
+            return f"ERROR: {type(exc).__name__}: {exc}"
+        if isinstance(output, str):
+            return output
+        return json.dumps(output, ensure_ascii=False, indent=2, default=str)
+
+    @staticmethod
+    def _result_message(name: str, output: str) -> str:
+        # Feeding results back as a *user* turn (not the `tool` role) was verified
+        # to be reliable with qwen2.5-coder:3b on this machine.
+        if output.lstrip().startswith("ERROR"):
+            return (
+                f"TOOL RESULT ({name}):\n{output}\n\n"
+                "That call failed. Do not repeat the same call with the same "
+                "arguments. Try a different tool or different arguments "
+                "(for example use list_files or search_code to find the right "
+                "path), or explain the problem to the user."
+            )
+        return (
+            f"TOOL RESULT ({name}):\n{output}\n\n"
+            "Using this result, answer the user's question directly. "
+            "Do not call the same tool again unless it returned an error."
+        )
+
+    # -- main loop ---------------------------------------------------------
+
+    def run(self, messages: list[dict[str, Any]]) -> str:
+        """Run one user turn to completion, mutating `messages` in place."""
+        nudged = False
+        for _step in range(1, self.max_steps + 1):
+            # Never send the whole conversation unbounded: trim to the budget.
+            payload = trim_messages(messages, self.max_context_chars)
+            response = self.client.chat_full(
+                self.model, payload, tools=self.registry.schemas() or None
+            )
+            message = response.get("message", {}) or {}
+            content = message.get("content") or ""
+            calls = self._detect_calls(message, content)
+
+            if calls:
+                # Record the model's tool request, then each result.
+                messages.append({"role": "assistant", "content": content})
+                for name, args in calls:
+                    output = self._handle_call(name, args)
+                    messages.append(
+                        {"role": "user", "content": self._result_message(name, output)}
+                    )
+                continue
+
+            if self._looks_like_bad_tool_call(content):
+                if nudged:
+                    self.on_event("[warn] model kept requesting an unknown tool")
+                    return (
+                        "I couldn't complete that request: the model kept trying to "
+                        "call an unavailable tool. Try rephrasing, or check /tools."
+                    )
+                nudged = True
+                self.on_event("[warn] unknown tool call; asking model to answer directly")
+                messages.append({"role": "assistant", "content": content})
+                messages.append({"role": "user", "content": self._nudge_message()})
+                continue
+
+            return content.strip()
+
+        self.on_event("[warn] reached the maximum number of tool steps")
+        return (
+            "I stopped after reaching the maximum number of tool steps without "
+            "a final answer. Try rewording the request."
+        )

package/agent/agents/__init__.py

@@ -0,0 +1,34 @@
+"""Agent registry for ElJay AI.
+
+Each agent is a specialized persona with its own system prompt, tool subset,
+and provider capabilities. The Main Agent acts as a coordinator that routes
+user requests to the appropriate specialized agent.
+"""
+
+from .registry import (
+    AgentDefinition,
+    AGENTS,
+    MAIN,
+    CODING,
+    RESEARCH,
+    IMAGE,
+    VIDEO,
+    KNOWLEDGE,
+    get_agent,
+    list_agents,
+    route_request,
+)
+
+__all__ = [
+    "AgentDefinition",
+    "AGENTS",
+    "MAIN",
+    "CODING",
+    "RESEARCH",
+    "IMAGE",
+    "VIDEO",
+    "KNOWLEDGE",
+    "get_agent",
+    "list_agents",
+    "route_request",
+]

package/agent/agents/registry.py

@@ -0,0 +1,212 @@
+"""Agent definitions and request routing for ElJay AI.
+
+An ``AgentDefinition`` captures everything needed to run a specialized agent:
+its name/purpose, the tool names it can use, the providers it depends on,
+the system-prompt additions, and a routing keyword list.
+
+The ``route_request`` function does keyword + context-based dispatch. It is
+deliberately simple (no LLM call) so routing is fast and deterministic.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class AgentDefinition:
+    """Static definition of a specialized agent."""
+
+    name: str
+    purpose: str
+    tools: list[str] = field(default_factory=list)
+    providers: list[str] = field(default_factory=list)
+    system_additions: str = ""
+    keywords: list[str] = field(default_factory=list)
+    priority: int = 0  # higher = more specific, wins ties
+
+
+# ---------------------------------------------------------------------------
+# Tool name constants — each agent gets the tools it needs.
+# Coding: list_files, read_file, search_code, write_file, edit_file,
+#          run_command, git_status, git_diff, git_log, run_test,
+#          run_lint, run_build, project_info, detect_checks
+# Research: web_search, fetch_web_page
+# Image: generate_image
+# Video: generate_video
+# Knowledge: read_file, search_code, list_files, search_knowledge, remember
+# Main: all (coordination)
+# ---------------------------------------------------------------------------
+
+CODING_TOOLS = [
+    "list_files", "read_file", "search_code", "edit_file", "create_file",
+    "run_command", "git_status", "git_log", "git_diff",
+    "run_test", "run_lint", "run_build",
+    "project_info", "detect_checks",
+]
+RESEARCH_TOOLS = ["web_search", "fetch_web_page"]
+IMAGE_TOOLS = ["generate_image"]
+VIDEO_TOOLS = ["generate_video"]
+GENERAL_TOOLS = [
+    "list_files", "read_file", "search_code", "search_knowledge", "remember",
+    "project_info",
+]
+MAIN_TOOLS = sorted(set(
+    CODING_TOOLS + RESEARCH_TOOLS + IMAGE_TOOLS + VIDEO_TOOLS + GENERAL_TOOLS
+))
+
+
+MAIN = AgentDefinition(
+    name="main",
+    purpose="Coordinator — routes requests to the right specialist agent.",
+    tools=["list_agents"],
+    system_additions=(
+        "You are ElJay AI, the main coordinator. You route user requests to "
+        "specialized sub-agents when beneficial, but you can also handle "
+        "general conversation directly."
+    ),
+    priority=0,
+)
+
+CODING = AgentDefinition(
+    name="coding",
+    purpose="Coding — inspect, read, modify, test, and verify project code.",
+    tools=CODING_TOOLS,
+    providers=["ollama"],
+    system_additions=(
+        "You are the Coding Agent. Follow this workflow:\n"
+        "1. Inspect the project structure\n"
+        "2. Understand the codebase\n"
+        "3. Explain the problem\n"
+        "4. Propose a fix\n"
+        "5. Ask for permission before risky changes\n"
+        "6. Modify files\n"
+        "7. Verify the actual tool result\n"
+        "Never claim a change worked without verifying."
+    ),
+    keywords=["fix", "bug", "error", "code", "function", "method", "refactor",
+              "file", "test", "build", "lint", "compile", "php", "laravel",
+              "react", "vue", "python", "api", "endpoint"],
+    priority=3,
+)
+
+RESEARCH = AgentDefinition(
+    name="research",
+    purpose="Web research — search, collect, compare, and summarize sources.",
+    tools=RESEARCH_TOOLS,
+    providers=["duckduckgo"],
+    system_additions=(
+        "You are the Research Agent. For each question:\n"
+        "1. Search for relevant sources\n"
+        "2. Fetch and extract key information\n"
+        "3. Compare sources\n"
+        "4. Summarize with clear source attribution\n"
+        "Distinguish: direct quotes, model reasoning, and uncertainty.\n"
+        "Never fabricate citations or pretend a source was consulted."
+    ),
+    keywords=["research", "latest", "current", "upcoming", "recent", "update",
+              "new in", "documentation", "docs", "best practice", "comparison"],
+    priority=2,
+)
+
+IMAGE = AgentDefinition(
+    name="image",
+    purpose="Image generation via local / free back-ends.",
+    tools=IMAGE_TOOLS,
+    providers=["image-local"],
+    system_additions=(
+        "You are the Image Agent. You generate images from text prompts using "
+        "local providers. Report which provider/model was used. If no provider "
+        "is available, give the user the exact setup steps."
+    ),
+    keywords=["image", "picture", "photo", "graphic", "draw", "create an image",
+              "generate an image", "render", "illustration", "art"],
+    priority=2,
+)
+
+VIDEO = AgentDefinition(
+    name="video",
+    purpose="Video generation — concept and render via local back-ends.",
+    tools=VIDEO_TOOLS,
+    providers=["video-local"],
+    system_additions=(
+        "You are the Video Agent. You create video concepts and, where a local "
+        "GPU back-end exists, generate video. Report hardware requirements "
+        "honestly. If generation is unavailable, describe the concept and the "
+        "setup needed."
+    ),
+    keywords=["video", "clip", "animation", "motion", "cinematic", "music video",
+              "animate"],
+    priority=2,
+)
+
+KNOWLEDGE = AgentDefinition(
+    name="knowledge",
+    purpose="General knowledge — answers, explanations, creative writing.",
+    tools=GENERAL_TOOLS,
+    providers=["ollama"],
+    system_additions=(
+        "You are the General Knowledge Agent. Answer questions, explain "
+        "concepts, help with writing, and provide ideas. Use web research "
+        "only when the user asks for current information."
+    ),
+    keywords=["what is", "explain", "how to", "why", "describe", "what are",
+              "definition", "meaning", "help me write", "email", "birthday"],
+    priority=1,
+)
+
+
+AGENTS = [MAIN, CODING, RESEARCH, IMAGE, VIDEO, KNOWLEDGE]
+
+
+def get_agent(name: str) -> Optional[AgentDefinition]:
+    """Look up an agent by name."""
+    for agent in AGENTS:
+        if agent.name == name:
+            return agent
+    return None
+
+
+def list_agents() -> list[AgentDefinition]:
+    """Return all agents sorted by priority (most specific first)."""
+    return sorted(AGENTS, key=lambda a: -a.priority)
+
+
+def _keyword_match(keyword: str, query: str) -> bool:
+    """Return True if *keyword* appears as a whole-word phrase in *query*.
+
+    Uses regex word boundaries so 'test' does not match inside 'latest'.
+    """
+    pattern = r"\b" + re.escape(keyword) + r"\b"
+    return re.search(pattern, query) is not None
+
+
+def route_request(query: str, providers_available: dict[str, bool] | None = None) -> AgentDefinition:
+    """Route *query* to the best agent via keyword matching.
+
+    Falls back to the Main coordinator when no specific agent matches, or
+    when a required provider is unavailable (the agent would just error).
+    """
+    query_lower = query.lower()
+
+    # Collect candidate agents that have a keyword present in the query.
+    candidates = []
+    for agent in AGENTS:
+        if agent.name == "main":
+            continue
+        score = sum(1 for kw in agent.keywords if _keyword_match(kw, query_lower))
+        if score > 0:
+            # Note: we do NOT skip agents when their provider is unavailable.
+            # The agent itself reports unavailability and gives setup steps.
+            # This lets the user ask about image/video generation even when
+            # no local provider is configured.
+            candidates.append((agent, score))
+
+    if candidates:
+        # Highest score wins; highest priority breaks ties.
+        candidates.sort(key=lambda c: (c[1], c[0].priority), reverse=True)
+        return candidates[0][0]
+
+    return MAIN