eljay-ai 1.1.0

package/agent/skills.py

@@ -0,0 +1,161 @@
+"""Skills system for ElJay AI.
+
+A *skill* is a reusable bundle of instructions/knowledge for a domain
+(e.g. "Laravel authentication", "React debugging", "security review").
+Skills live in the ``skills/`` directory, organized by category:
+
+    skills/
+    ├── coding/
+    ├── debugging/
+    ├── testing/
+    ├── react/
+    ├── laravel/
+    ├── php/
+    ├── mysql/
+    ├── security/
+    ├── research/
+    ├── image-generation/
+    ├── video-generation/
+    └── general/
+
+Each skill is a single ``.md`` or ``.txt`` file whose first line is a
+one-sentence description. The system loads only relevant skills per request,
+keeping context lean.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Skill:
+    """Metadata + content for one skill."""
+
+    name: str
+    category: str
+    source: str  # file path
+    description: str
+    content: str  # full instructions
+
+
+# Category ordering for /skills display.
+DEFAULT_CATEGORIES = [
+    "coding", "debugging", "testing", "react", "laravel", "php", "mysql",
+    "security", "research", "image-generation", "video-generation", "general",
+]
+
+
+class Skills:
+    """Load and query skills from the project's ``skills/`` directory."""
+
+    def __init__(self, root: str | os.PathLike):
+        self.root = str(root)
+        self.skills_dir = os.path.join(self.root, "skills")
+        self._cache: list[Skill] | None = None
+
+    def _scan(self) -> list[Skill]:
+        if not os.path.isdir(self.skills_dir):
+            return []
+        found: list[Skill] = []
+        for category in sorted(os.listdir(self.skills_dir)):
+            cat_dir = os.path.join(self.skills_dir, category)
+            if not os.path.isdir(cat_dir):
+                continue
+            for fname in sorted(os.listdir(cat_dir)):
+                if not fname.endswith((".md", ".txt")):
+                    continue
+                fpath = os.path.join(cat_dir, fname)
+                try:
+                    content = open(fpath, encoding="utf-8").read()
+                except OSError:
+                    continue
+                lines = content.splitlines()
+                description = lines[0].lstrip("# ").strip() if lines else ""
+                found.append(
+                    Skill(
+                        name=fname.rsplit(".", 1)[0],
+                        category=category,
+                        source=fpath,
+                        description=description,
+                        content=content,
+                    )
+                )
+        return found
+
+    def all_skills(self) -> list[Skill]:
+        if self._cache is None:
+            self._cache = self._scan()
+        return self._cache
+
+    def by_category(self) -> dict[str, list[Skill]]:
+        """Group skills by category (excluding empty categories)."""
+        result: dict[str, list[Skill]] = {}
+        for skill in self.all_skills():
+            result.setdefault(skill.category, []).append(skill)
+        return result
+
+    def search(self, query: str) -> list[Skill]:
+        """Return skills whose name/category/description mentions *query*."""
+        q = query.lower()
+        return [
+            s for s in self.all_skills()
+            if q in s.name.lower()
+            or q in s.category.lower()
+            or q in s.description.lower()
+        ]
+
+    def relevant_to(self, query: str) -> list[Skill]:
+        """Return skills relevant to a user query (keyword overlap)."""
+        q_lower = query.lower()
+        q_words = set(w.strip(".,!?") for w in q_lower.split())
+        results: list[tuple[Skill, int]] = []
+        for skill in self.all_skills():
+            score = 0
+            for word in q_words:
+                if word in skill.name.lower():
+                    score += 3
+                if word in skill.category.lower():
+                    score += 2
+                if word in skill.description.lower():
+                    score += 1
+            if score > 0:
+                results.append((skill, score))
+        results.sort(key=lambda x: -x[1])
+        return [s for s, _ in results]
+
+    def summary(self) -> str:
+        """One-line summary for the banner."""
+        n = len(self.all_skills())
+        return f"{n} skill(s) in {len(self.by_category())} categor(ies)" if n else "no skills"
+
+
+def ensure_default_skills(root) -> None:
+    """Create the default skills/ directory with a few starter skills.
+
+    This is called by the CLI on first run. It only writes if the directory
+    doesn't already exist.
+    """
+    skills_dir = os.path.join(str(root), "skills")
+    if os.path.isdir(skills_dir):
+        return
+    os.makedirs(os.path.join(skills_dir, "general"), exist_ok=True)
+    starter = [
+        ("coding", "code-review.md",
+         "# Code Review\n\nCheck for: correctness, edge cases, security issues, "
+         "readability, and adherence to existing project conventions."),
+        ("general", "communication.md",
+         "# Communication\n\nBe concise, accurate, and helpful. Never fabricate "
+         "facts. If unsure, say so and suggest how to find out."),
+        ("research", "source-tracking.md",
+         "# Source Tracking\n\nAlways cite sources. Distinguish between direct "
+         "quotes, paraphrased information, and your own reasoning."),
+    ]
+    for category, fname, content in starter:
+        cat_dir = os.path.join(skills_dir, category)
+        os.makedirs(cat_dir, exist_ok=True)
+        fpath = os.path.join(cat_dir, fname)
+        if not os.path.exists(fpath):
+            with open(fpath, "w", encoding="utf-8") as f:
+                f.write(content)

package/agent/tools.py

@@ -0,0 +1,102 @@
+"""Tool abstraction and registry.
+
+A tool is a named function the model may ask the agent to run. Each tool
+carries a JSON-schema description (so models that support native tool calling
+can use it) and a `risk` level that the permission system will enforce from
+Phase 8 onward. In Phase 3 the risk level is metadata only — nothing is gated
+yet, because only safe tools exist so far.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+# Risk levels: "safe" (auto-run), "ask" (needs confirmation), "high" (explicit).
+RISK_SAFE = "safe"
+RISK_ASK = "ask"
+RISK_HIGH = "high"
+
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    func: Callable[..., Any]
+    risk: str = RISK_SAFE
+    # Optional: builds a human-readable preview of a call, shown before asking
+    # permission (e.g. a diff of the change). Receives the call's arguments.
+    preview: Callable[..., str] | None = None
+    # Optional: computes the risk for a SPECIFIC call from its arguments. Used by
+    # tools whose danger depends on the arguments (e.g. run_command).
+    risk_func: Callable[..., str] | None = None
+
+    def schema(self) -> dict[str, Any]:
+        """Return the OpenAI/Ollama-style function schema for this tool."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def run(self, arguments: dict[str, Any]) -> Any:
+        """Execute the tool. Raises on failure; the caller handles errors."""
+        return self.func(**arguments)
+
+    def risk_for(self, arguments: dict[str, Any]) -> str:
+        """Risk level for this specific call (falls back to the static risk)."""
+        if self.risk_func is not None:
+            try:
+                return self.risk_func(**arguments)
+            except (TypeError, ValueError):
+                return self.risk
+        return self.risk
+
+    def make_preview(self, arguments: dict[str, Any]) -> str:
+        """Return a human-readable preview of what this call would do."""
+        if self.preview is not None:
+            try:
+                return self.preview(**arguments)
+            except (TypeError, ValueError):
+                pass
+        try:
+            rendered = json.dumps(arguments, ensure_ascii=False)
+        except (TypeError, ValueError):
+            rendered = str(arguments)
+        return f"{self.name}({rendered})"
+
+
+class ToolRegistry:
+    """Holds the tools available to the agent."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        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 self._tools.get(name)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._tools
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def tools(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    def names(self) -> list[str]:
+        return list(self._tools)
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return [t.schema() for t in self._tools.values()]

package/agent/verification.py

@@ -0,0 +1,80 @@
+"""Detect the smallest useful verification commands for a project.
+
+Serves the rule "use the smallest useful verification first": we look at the
+project's own files and suggest lint / typecheck / test / build commands, ordered
+smallest-and-cheapest first. We never run anything here — that goes through
+run_command and the permission gate.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .workspace import Workspace
+
+
+@dataclass
+class Check:
+    command: str
+    purpose: str
+    weight: int  # lower = smaller / faster
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return {}
+
+
+def detect_checks(ws: Workspace) -> list[Check]:
+    root = ws.root
+    checks: list[Check] = []
+
+    package_json = root / "package.json"
+    if package_json.exists():
+        scripts = _read_json(package_json).get("scripts", {}) or {}
+        wanted = (
+            ("lint", "Lint the frontend", 1),
+            ("typecheck", "Type-check the frontend", 2),
+            ("type-check", "Type-check the frontend", 2),
+            ("test", "Run frontend tests", 3),
+            ("build", "Build the frontend", 4),
+        )
+        for name, purpose, weight in wanted:
+            if name in scripts:
+                checks.append(Check(f"npm run {name}", purpose, weight))
+
+    if (root / "composer.json").exists():
+        checks.append(Check("composer validate --no-check-publish", "Validate composer.json", 1))
+        if (root / "artisan").exists():
+            checks.append(Check("php artisan test", "Run Laravel tests", 3))
+
+    if (root / "pyproject.toml").exists() or (root / "requirements.txt").exists() or (root / "setup.py").exists() or (root / "tests").is_dir():
+        checks.append(Check("python -m pytest -q", "Run Python tests", 3))
+
+    if (root / "go.mod").exists():
+        checks.append(Check("go build ./...", "Compile Go packages", 3))
+    if (root / "Cargo.toml").exists():
+        checks.append(Check("cargo check", "Compile the Rust project", 3))
+
+    deduped: list[Check] = []
+    seen: set[str] = set()
+    for check in sorted(checks, key=lambda c: (c.weight, c.command)):
+        if check.command not in seen:
+            seen.add(check.command)
+            deduped.append(check)
+    return deduped
+
+
+def format_checks(ws: Workspace) -> str:
+    checks = detect_checks(ws)
+    if not checks:
+        return "No standard test/build commands were detected for this project."
+    lines = ["Suggested verification (smallest first):"]
+    for check in checks:
+        lines.append(f"  ({check.weight}) {check.command}  -- {check.purpose}")
+    lines.append("Prefer the smallest check that covers your change.")
+    return "\n".join(lines)