eljay-ai 1.1.0

package/agent/gitaware.py

@@ -0,0 +1,126 @@
+"""Read-only Git awareness.
+
+The agent may INSPECT the repository (branch, changed files) but never commits,
+pushes, resets, or cleans. Only read-only git subcommands are invoked here.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from .workspace import Workspace
+
+# Only these read-only subcommands are ever run from this module.
+_ALLOWED = ("status", "branch", "rev-parse", "log", "diff", "remote")
+
+
+def is_git_repo(ws: Workspace) -> bool:
+    return (ws.root / ".git").exists()
+
+
+def _git(ws: Workspace, args: list[str], timeout: int = 20):
+    if args and args[0] not in _ALLOWED:
+        return None, f"refused: '{args[0]}' is not a read-only git subcommand"
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            cwd=str(ws.root),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return None, str(exc)
+    return proc, None
+
+
+def branch(ws: Workspace) -> str:
+    if not is_git_repo(ws):
+        return ""
+    proc, err = _git(ws, ["rev-parse", "--abbrev-ref", "HEAD"])
+    if err or proc is None or proc.returncode != 0:
+        return ""
+    return proc.stdout.strip()
+
+
+def status(ws: Workspace) -> str:
+    """Return a readable git status, or a clear message if not a repo."""
+    if not is_git_repo(ws):
+        return "This folder is not a git repository."
+    proc, err = _git(ws, ["status", "--short", "--branch"])
+    if err:
+        return f"ERROR: could not run git: {err}"
+    if proc is None:
+        return "ERROR: could not run git."
+    if proc.returncode != 0:
+        detail = (proc.stderr or "").strip()
+        return f"ERROR: git status failed: {detail}"
+
+    output = proc.stdout.strip()
+    if not output:
+        return "Working tree is clean."
+
+    lines = output.splitlines()
+    changed = [line for line in lines if not line.startswith("##")]
+    header = lines[0] if lines and lines[0].startswith("##") else ""
+    parts = [f"Git status ({header[3:].strip() if header else 'unknown branch'}):"]
+    if changed:
+        parts.append(f"Changed files ({len(changed)}):")
+        parts.extend(f"  {line}" for line in changed)
+    else:
+        parts.append("No changed files.")
+    return "\n".join(parts)
+
+
+def git_log(ws: Workspace, n: int = 10) -> str:
+    """Show the last *n* git log entries (read-only)."""
+    if not is_git_repo(ws):
+        return "This folder is not a git repository."
+    proc, err = _git(ws, ["log", f"-{n}", "--oneline", "--decorate"])
+    if err:
+        return f"ERROR: could not run git: {err}"
+    if proc is None or proc.returncode != 0:
+        detail = (proc.stderr if proc else "") or ""
+        return f"ERROR: git log failed: {detail}"
+    output = proc.stdout.strip()
+    if not output:
+        return "No commits yet."
+    lines = [f"Recent commits (last {n}):"]
+    lines.extend(f"  {line}" for line in output.splitlines())
+    return "\n".join(lines)
+
+
+def git_diff(ws: Workspace, target: str = "", n: int = 3) -> str:
+    """Show uncommitted changes or a diff of *target* (read-only)."""
+    if not is_git_repo(ws):
+        return "This folder is not a git repository."
+    args = ["diff", "--stat"]
+    if target:
+        args = ["diff", f"-{n}", target]
+    proc, err = _git(ws, args)
+    if err:
+        return f"ERROR: could not run git: {err}"
+    if proc is None or proc.returncode != 0:
+        detail = (proc.stderr if proc else "") or ""
+        return f"ERROR: git diff failed: {detail}"
+    output = proc.stdout.strip()
+    if not output:
+        return "No changes to show (working tree clean or no diff for that target)."
+    lines = [f"Git diff ({' '.join(args[1:]) or 'uncommitted'}):"]
+    lines.extend(f"  {line}" for line in output.splitlines())
+    return "\n".join(lines)
+
+
+def changed_files(ws: Workspace) -> list[str]:
+    if not is_git_repo(ws):
+        return []
+    proc, err = _git(ws, ["status", "--porcelain"])
+    if err or proc is None or proc.returncode != 0:
+        return []
+    files = []
+    for line in proc.stdout.splitlines():
+        if len(line) > 3:
+            files.append(line[3:].strip())
+    return files

package/agent/hardware.py

@@ -0,0 +1,331 @@
+"""Hardware detection for ElJay AI.
+
+Detects practical hardware constraints that determine whether local AI
+tasks (especially image/video generation) are feasible. Uses stdlib and
+platform commands only — no third-party packages.
+
+Reports **total** VRAM *and* **currently available (free)** VRAM separately,
+so the caller can make hardware-aware decisions:
+
+High-end GPU  → large models
+Mid-range GPU → medium / quantized models
+~4 GB VRAM    → small / quantized models or CPU offloading
+Low VRAM      → CPU / system RAM where practical
+No GPU        → CPU-only mode
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class HardwareInfo:
+    """Structured hardware profile relevant to local AI."""
+
+    os: str = ""
+    os_version: str = ""
+    arch: str = ""
+    cpu_brand: str = ""
+    cpu_cores: int = 0
+    ram_gb: float = 0.0
+    disk_free_gb: float = 0.0
+    gpu: str = "none"
+    # Total VRAM and currently-available (free) VRAM, both in GB.
+    vram_total_gb: float = 0.0
+    vram_available_gb: float = 0.0
+    # Derived readiness flags
+    can_code: bool = False        # text generation (CPU-capable)
+    can_research: bool = False    # web search (network-capable)
+    can_image: bool = False       # local image generation
+    can_video: bool = False       # local video generation (needs VRAM)
+    notes: list[str] = field(default_factory=list)
+
+    # Convenience aliases for backward compatibility.
+    @property
+    def vram_gb(self) -> float:
+        """Alias for total VRAM (kept for simpler banners)."""
+        return self.vram_total_gb
+
+    @property
+    def available_vram_gb(self) -> float:
+        """Currently free VRAM in GB."""
+        return self.vram_available_gb
+
+    def recommended_image_mode(self) -> str:
+        """Return a human-readable recommendation for image generation."""
+        vram = self.vram_available_gb
+        if vram >= 8.0:
+            return "GPU large-model (full precision)"
+        if vram >= 4.0:
+            return "GPU medium/quantized model"
+        if self.gpu != "none" and self.ram_gb >= 16.0:
+            return "CPU offload with RAM"
+        if self.cpu_cores >= 6 and self.ram_gb >= 12.0:
+            return "CPU model (slow)"
+        return "No local option — use a free external provider"
+
+    def recommended_video_mode(self) -> str:
+        """Return a recommendation for video generation."""
+        vram = self.vram_available_gb
+        if vram >= 8.0:
+            return "GPU local video (e.g. Wan-2.1 / AnimateDiff)"
+        if vram >= 6.0:
+            return "GPU local video (limited resolution)"
+        if vram > 0.0:
+            return "GPU VRAM insufficient for local video"
+        return "No GPU — use a free external provider or CPU (slow)"
+
+
+def _detect_os() -> tuple[str, str]:
+    return platform.system(), platform.release()
+
+
+def _detect_cpu() -> tuple[str, int]:
+    brand = "unknown"
+    cores = os.cpu_count() or 1
+
+    if platform.system() == "Windows":
+        try:
+            out = subprocess.check_output(
+                "wmic cpu get name", shell=True, timeout=5,
+                stderr=subprocess.DEVNULL,
+            ).decode("utf-8", errors="replace").strip()
+            lines = [l.strip() for l in out.splitlines() if l.strip()]
+            if len(lines) > 1:
+                brand = lines[1]
+        except Exception:
+            pass
+    else:
+        if os.path.exists("/proc/cpuinfo"):
+            try:
+                with open("/proc/cpuinfo") as f:
+                    for line in f:
+                        if line.startswith("model name"):
+                            brand = line.split(":", 1)[1].strip()
+                            break
+            except Exception:
+                pass
+
+    return brand, cores
+
+
+def _detect_ram() -> float:
+    """Return total system RAM in GB."""
+    if platform.system() == "Windows":
+        try:
+            out = subprocess.check_output(
+                "wmic computersystem get TotalPhysicalMemory",
+                shell=True, timeout=5, stderr=subprocess.DEVNULL,
+            ).decode("utf-8", errors="replace").strip()
+            lines = [l.strip() for l in out.splitlines() if l.strip()]
+            if len(lines) > 1:
+                return round(int(lines[1]) / (1024 ** 3), 1)
+        except Exception:
+            pass
+    else:
+        try:
+            with open("/proc/meminfo") as f:
+                for line in f:
+                    if line.startswith("MemTotal:"):
+                        kb = int(line.split()[1])
+                        return round(kb / (1024 * 1024), 1)
+        except Exception:
+            pass
+    return 0.0
+
+
+def _detect_disk() -> float:
+    """Return free disk space in GB at the project root."""
+    try:
+        st = os.statvfs(".") if platform.system() != "Windows" else None
+    except Exception:
+        st = None
+
+    if st:
+        return round(st.f_bavail * st.f_frsize / (1024 ** 3), 1)
+
+    if platform.system() == "Windows":
+        try:
+            out = subprocess.check_output(
+                "dir", shell=True, timeout=5, stderr=subprocess.DEVNULL,
+            ).decode("utf-8", errors="replace")
+            for line in out.splitlines():
+                if "bytes free" in line.lower():
+                    parts = line.split()
+                    for p in parts:
+                        p = p.replace(",", "")
+                        if p.isdigit():
+                            return round(int(p) / (1024 ** 3), 1)
+        except Exception:
+            pass
+    return 0.0
+
+
+def _detect_gpu() -> tuple[str, float, float]:
+    """Return (gpu_name, total_vram_gb, available_vram_gb).
+
+    Uses nvidia-smi which reports both total and free VRAM.
+    Returns ("none", 0.0, 0.0) if no GPU is found.
+    """
+    # Try NVIDIA first (most common for AI).
+    if shutil.which("nvidia-smi"):
+        try:
+            out = subprocess.check_output(
+                ["nvidia-smi",
+                 "--query-gpu=name,memory.total,memory.free",
+                 "--format=csv,noheader"],
+                timeout=5, stderr=subprocess.DEVNULL,
+            ).decode("utf-8", errors="replace").strip()
+            if out:
+                parts = out.split(",")
+                name = parts[0].strip()
+                total_mb = int(parts[1].strip()) if len(parts) > 1 else 0
+                free_mb = int(parts[2].strip()) if len(parts) > 2 else 0
+                return name, round(total_mb / 1024, 1), round(free_mb / 1024, 1)
+        except Exception:
+            pass
+
+    # Try dxdiag (Windows, captures Intel/AMD too) — total only, no free.
+    if platform.system() == "Windows" and shutil.which("dxdiag"):
+        try:
+            out = subprocess.check_output(
+                "dxdiag /t /d 2>nul & type dxdiag.txt",
+                shell=True, timeout=10, stderr=subprocess.DEVNULL,
+            ).decode("utf-8", errors="replace").strip()
+            for line in out.splitlines():
+                if "chip type" in line.lower() or "card name" in line.lower():
+                    name = line.split(":", 1)[1].strip()
+                    if name and name != "n/a":
+                        return name, 0.0, 0.0
+        except Exception:
+            pass
+
+    return "none", 0.0, 0.0
+
+
+def detect_hardware() -> HardwareInfo:
+    """Probe the system and return a HardwareInfo profile."""
+    info = HardwareInfo()
+
+    info.os, info.os_version = _detect_os()
+    info.arch = platform.machine()
+    info.cpu_brand, info.cpu_cores = _detect_cpu()
+    info.ram_gb = _detect_ram()
+    info.disk_free_gb = _detect_disk()
+    info.gpu, info.vram_total_gb, info.vram_available_gb = _detect_gpu()
+
+    # --- Derive capability flags ----------------------------------------
+
+    # Text generation / coding: any modern CPU can run small models via Ollama.
+    info.can_code = info.cpu_cores >= 2 and info.ram_gb >= 4.0
+
+    # Web research: network-dependent; assume available, user can override.
+    info.can_research = True
+
+    # Image generation: need either enough available VRAM or enough RAM/CPU.
+    vram = info.vram_available_gb
+    if vram >= 4.0:
+        info.can_image = True
+    elif vram >= 2.0:
+        info.can_image = True  # small models may fit
+    elif info.cpu_cores >= 6 and info.ram_gb >= 12.0:
+        info.can_image = True  # CPU offloading possible (slow)
+    elif info.ram_gb >= 16.0:
+        info.can_image = True  # CPU model (very slow)
+
+    # Video generation: requires >= 6 GB VRAM for practical local generation.
+    if vram >= 6.0:
+        info.can_video = True
+
+    # Collect human-readable notes about limitations.
+    if not info.can_image:
+        if info.gpu == "none":
+            info.notes.append(
+                "No GPU detected. Image generation is CPU-only (very slow) "
+                "or requires an external/free provider."
+            )
+        else:
+            info.notes.append(
+                f"GPU has {info.vram_available_gb:.1f} GB available VRAM "
+                f"(total: {info.vram_total_gb:.1f} GB). Local image "
+                "generation requires >= 2 GB free VRAM or a CPU with >= 12 GB RAM."
+            )
+
+    if not info.can_video:
+        if info.gpu == "none":
+            info.notes.append(
+                "No GPU detected. Video generation requires >= 6 GB VRAM. "
+                "Use a free external provider or expect CPU-only (impractical)."
+            )
+        elif info.vram_available_gb < 6.0:
+            info.notes.append(
+                f"GPU available VRAM ({info.vram_available_gb:.1f} GB) is below "
+                "the 6 GB threshold for local video generation."
+            )
+
+    return info
+
+
+def hardware_summary() -> str:
+    """Return a short human-readable hardware summary."""
+    info = detect_hardware()
+    parts = [
+        f"OS: {info.os} {info.os_version} ({info.arch})",
+        f"CPU: {info.cpu_brand or 'unknown'} ({info.cpu_cores} cores)",
+        f"RAM: {info.ram_gb:.1f} GB",
+        f"Disk free: {info.disk_free_gb:.1f} GB",
+        f"GPU: {info.gpu}",
+    ]
+    if info.vram_total_gb > 0:
+        parts.append(
+            f"VRAM: {info.vram_total_gb:.1f} GB total, "
+            f"{info.vram_available_gb:.1f} GB available"
+        )
+    return "\n".join(parts)
+
+
+def summarize_hardware(hw: HardwareInfo) -> str:
+    """Return a compact hardware summary string for a given HardwareInfo."""
+    if hw.gpu != "none" and hw.vram_total_gb > 0:
+        gpu_str = (
+            f"GPU: {hw.gpu} "
+            f"(total {hw.vram_total_gb:.1f} GB, "
+            f"available {hw.vram_available_gb:.1f} GB)"
+        )
+    elif hw.gpu != "none":
+        gpu_str = f"GPU: {hw.gpu} (VRAM: unknown)"
+    else:
+        gpu_str = "GPU: none"
+
+    caps = []
+    if hw.can_code:
+        caps.append("code")
+    if hw.can_image:
+        caps.append("image")
+    if hw.can_video:
+        caps.append("video")
+    cap_str = "capable: " + ", ".join(caps) if caps else "no local AI acceleration"
+    return f"{gpu_str}; {cap_str}"
+
+
+if __name__ == "__main__":
+    print(hardware_summary())
+    print()
+    info = detect_hardware()
+    print("Capabilities:")
+    print(f"  Code/reasoning : {'yes' if info.can_code else 'no'}")
+    print(f"  Web research   : {'yes' if info.can_research else 'no'}")
+    print(f"  Image generation: {'yes' if info.can_image else 'no'}")
+    print(f"  Video generation: {'yes' if info.can_video else 'no'}")
+    if info.can_image:
+        print(f"  Image mode: {info.recommended_image_mode()}")
+    if info.can_video:
+        print(f"  Video mode: {info.recommended_video_mode()}")
+    for n in info.notes:
+        print(f"  note: {n}")

package/agent/knowledge.py

@@ -0,0 +1,133 @@
+"""Knowledge base for ElJay AI.
+
+Supports two levels:
+
+* **Global knowledge** — ``knowledge/`` in the ElJay installation directory.
+  Reusable across all projects.
+* **Project knowledge** — ``.agent/knowledge/`` in the project workspace.
+  Project-specific facts the agent should remember.
+
+Each entry is a ``.md`` file whose first line is a description. Knowledge
+entries are *not* treated as guaranteed truth — they are user-provided
+context that should be verified where possible.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class KnowledgeEntry:
+    """One knowledge file."""
+
+    name: str
+    category: str
+    source: str
+    description: str
+    content: str
+
+
+class KnowledgeBase:
+    """Read/search knowledge from global and project-local directories."""
+
+    def __init__(self, project_root: str | os.PathLike, global_root: Optional[str | os.PathLike] = None):
+        self.project_root = str(project_root)
+        self.global_root = str(global_root) if global_root else None
+
+    def _scan_dir(self, directory: str) -> list[KnowledgeEntry]:
+        if not os.path.isdir(directory):
+            return []
+        found: list[KnowledgeEntry] = []
+        for category in sorted(os.listdir(directory)):
+            cat_dir = os.path.join(directory, 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()
+                desc = lines[0].lstrip("# ").strip() if lines else ""
+                found.append(
+                    KnowledgeEntry(
+                        name=fname.rsplit(".", 1)[0],
+                        category=category,
+                        source=fpath,
+                        description=desc,
+                        content=content,
+                    )
+                )
+        return found
+
+    @property
+    def project_dir(self) -> str:
+        return os.path.join(self.project_root, ".agent", "knowledge")
+
+    @property
+    def global_dir(self) -> Optional[str]:
+        if self.global_root:
+            return os.path.join(self.global_root, "knowledge")
+        return None
+
+    def entries(self) -> list[KnowledgeEntry]:
+        """All entries (global + project), project takes precedence."""
+        result = []
+        seen = set()
+        if self.global_dir:
+            for e in self._scan_dir(self.global_dir):
+                result.append(e)
+                seen.add(e.name)
+        for e in self._scan_dir(self.project_dir):
+            result.append(e)
+        return result
+
+    def search(self, query: str) -> list[KnowledgeEntry]:
+        """Search all knowledge entries for *query*."""
+        q = query.lower()
+        q_words = set(w.strip() for w in q.split())
+        results: list[tuple[KnowledgeEntry, int]] = []
+        for entry in self.entries():
+            score = 0
+            for word in q_words:
+                if word in entry.name.lower():
+                    score += 3
+                if word in entry.category.lower():
+                    score += 2
+                if word in entry.description.lower():
+                    score += 1
+                if word in entry.content.lower():
+                    score += 1
+            if score > 0:
+                results.append((entry, score))
+        results.sort(key=lambda x: -x[1])
+        return [e for e, _ in results]
+
+    def add_entry(self, category: str, name: str, description: str, content: str,
+                  project_local: bool = True) -> str:
+        """Add a new knowledge entry. Returns the file path written."""
+        if project_local:
+            target_dir = os.path.join(self.project_dir, category)
+        elif self.global_dir:
+            target_dir = os.path.join(self.global_dir, category)
+        else:
+            raise ValueError("No global knowledge directory configured.")
+        os.makedirs(target_dir, exist_ok=True)
+        fpath = os.path.join(target_dir, f"{name}.md")
+        header = f"# {description}\n\n{content}"
+        import datetime
+        header = f"# {description}\n\n<!-- {datetime.date.today().isoformat()} -->\n\n{content}"
+        with open(fpath, "w", encoding="utf-8") as f:
+            f.write(header)
+        return fpath
+
+    def summary(self) -> str:
+        entries = self.entries()
+        cats = set(e.category for e in entries)
+        return f"{len(entries)} entr(ies) in {len(cats)} categor(ies)" if entries else "empty"

package/agent/memory.py

@@ -0,0 +1,98 @@
+"""Lightweight local memory, stored under the project's `.agent/` folder.
+
+Layout (gitignored — never part of the user's source):
+    .agent/config.json    small agent settings
+    .agent/history.json   the most recent conversation turns
+    .agent/context.json   notes worth remembering between sessions
+
+The user can inspect or clear all of it (`/memory`, `/memory clear`).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .workspace import Workspace
+
+HISTORY_LIMIT = 100
+
+
+class Memory:
+    def __init__(self, ws: Workspace) -> None:
+        self.dir = ws.root / ".agent"
+        self.config_path = self.dir / "config.json"
+        self.history_path = self.dir / "history.json"
+        self.context_path = self.dir / "context.json"
+
+    # -- helpers -----------------------------------------------------------
+
+    def _ensure_dir(self) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def _read(self, path: Path, default: Any) -> Any:
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, ValueError):
+            return default
+
+    # -- history -----------------------------------------------------------
+
+    def save_history(self, messages: list[dict[str, Any]]) -> None:
+        try:
+            self._ensure_dir()
+            trimmed = messages[-HISTORY_LIMIT:]
+            self.history_path.write_text(
+                json.dumps(trimmed, ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+        except OSError:
+            pass  # memory is best-effort; never break the session over it
+
+    def load_history(self) -> list[dict[str, Any]]:
+        data = self._read(self.history_path, [])
+        return data if isinstance(data, list) else []
+
+    # -- notes -------------------------------------------------------------
+
+    def load_notes(self) -> list[str]:
+        data = self._read(self.context_path, {})
+        notes = data.get("notes", []) if isinstance(data, dict) else []
+        return [str(n) for n in notes] if isinstance(notes, list) else []
+
+    def add_note(self, text: str) -> None:
+        text = (text or "").strip()
+        if not text:
+            return
+        notes = self.load_notes()
+        notes.append(text)
+        try:
+            self._ensure_dir()
+            self.context_path.write_text(
+                json.dumps({"notes": notes}, ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+        except OSError:
+            pass
+
+    def clear(self) -> None:
+        for path in (self.history_path, self.context_path):
+            try:
+                path.unlink()
+            except OSError:
+                pass
+
+    # -- reporting ---------------------------------------------------------
+
+    def summary(self) -> str:
+        history = self.load_history()
+        notes = self.load_notes()
+        lines = [f"Memory folder: {self.dir}"]
+        lines.append(f"  history: {len(history)} message(s)  ->  {self.history_path.name}")
+        lines.append(f"  notes:   {len(notes)}  ->  {self.context_path.name}")
+        if notes:
+            lines.append("  remembered notes:")
+            for note in notes[-10:]:
+                lines.append(f"    - {note}")
+        lines.append("Use /memory clear to erase all local memory.")
+        return "\n".join(lines)