opencommand 0.1.0__py3-none-any.whl

opencommand/modules/system/platform.py

@@ -0,0 +1,197 @@
+"""Platform / host autodetection for OpenCommand setup and per-host config.
+
+On first run (or `opencommand setup`) this probes the host and derives a
+recommended configuration: shell, Python build (free-threaded vs GIL), CPU
+topology (core count -> worker pool size), instruction-set support (AVX2 /
+AVX-512 -> llama.cpp build flags), GPU backend (CUDA / ROCm / Metal / Vulkan /
+none -> n_gpu_layers), available system tools (git, yara, ffmpeg, playwright
+browsers), and total RAM. The result feeds `recommend_config()` which returns an
+`OpenCommandConfig` plus engine hints, so the swarm is tuned per machine without
+hand-editing anything.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import sys
+
+
+def detect() -> dict:
+    """Return a full host descriptor dict (everything OpenCommand cares about)."""
+    return {
+        "system": platform.system(),
+        "release": platform.release(),
+        "machine": platform.machine(),
+        "python": sys.version.split()[0],
+        "free_threaded": _free_threaded(),
+        "shell": shell_kind(),
+        "cores": os.cpu_count() or 1,
+        "isa": _isa(),
+        "gpu": _gpu(),
+        "ram_gb": _ram_gb(),
+        "tools": _tools(),
+    }
+
+
+def shell_kind() -> str:
+    return "cmd" if sys.platform.startswith("win") else "sh"
+
+
+def _free_threaded() -> bool:
+    fn = getattr(sys, "_is_gil_enabled", None)
+    if fn is None:
+        return False
+    try:
+        return not fn()
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _isa() -> dict:
+    """Detect CPU instruction-set extensions (drives llama.cpp build flags)."""
+    caps: set[str] = set()
+    try:
+        import cpuid  # type: ignore
+    except Exception:
+        cpuid = None
+    if cpuid is not None and hasattr(cpuid, "get_extended_feature_bits"):
+        bits = cpuid.get_extended_feature_bits(0)
+        if bits & (1 << 28):
+            caps.add("avx")
+        if bits & (1 << 5):
+            caps.add("avx2")
+        if bits & (1 << 16):
+            caps.add("avx512f")
+    else:
+        if sys.platform.startswith("linux"):
+            try:
+                from pathlib import Path
+                info = Path("/proc/cpuinfo").read_text(encoding="utf-8", errors="ignore")
+                for line in info.splitlines():
+                    if line.lower().startswith("flags"):
+                        for f in line.split()[2:]:
+                            if f in ("avx", "avx2", "avx512f"):
+                                caps.add(f)
+                        break
+            except Exception:  # noqa: BLE001
+                pass
+        if not caps:
+            mach = platform.machine().lower()
+            if mach in ("x86_64", "amd64"):
+                caps.add("avx2")  # assume baseline AVX2 on modern x86_64
+            elif mach in ("arm64", "aarch64"):
+                caps.add("neon")
+    return {"extensions": sorted(caps), "avx2": "avx2" in caps, "avx512": "avx512f" in caps}
+
+
+def _gpu() -> dict:
+    """Detect the best available GPU backend for llama.cpp offload."""
+    backend = "none"
+    detail = ""
+    if shutil.which("nvidia-smi"):
+        try:
+            out = subprocess.run(["nvidia-smi", "--query-gpu=name,memory.total",
+                                  "--format=csv,noheader"], capture_output=True,
+                                  text=True, timeout=10).stdout.strip()
+            backend, detail = "cuda", out.replace("\n", " | ")
+        except Exception:  # noqa: BLE001
+            backend = "cuda"
+    elif shutil.which("rocm-smi") or os.path.exists("/opt/rocm"):
+        backend = "rocm"
+    elif platform.system() == "Darwin" and platform.machine() == "arm64":
+        backend, detail = "metal", "Apple Silicon"
+    elif shutil.which("vulkaninfo") or os.environ.get("VK_ICD_FILENAMES"):
+        backend = "vulkan"
+    return {"backend": backend, "detail": detail}
+
+
+def _ram_gb() -> float:
+    """Total system RAM in GB. Uses ctypes (no extra deps); Linux falls back to /proc."""
+    if sys.platform.startswith("win"):
+        try:
+            import ctypes
+
+            class _MEMORYSTATUSEX(ctypes.Structure):
+                _fields_ = [
+                    ("dwLength", ctypes.c_ulong),
+                    ("dwMemoryLoad", ctypes.c_ulong),
+                    ("ullTotalPhys", ctypes.c_ulonglong),
+                    ("ullAvailPhys", ctypes.c_ulonglong),
+                    ("ullTotalPageFile", ctypes.c_ulonglong),
+                    ("ullAvailPageFile", ctypes.c_ulonglong),
+                    ("ullTotalVirtual", ctypes.c_ulonglong),
+                    ("ullAvailVirtual", ctypes.c_ulonglong),
+                    ("ullAvailExtendedVirtual", ctypes.c_ulonglong),
+                ]
+
+            stat = _MEMORYSTATUSEX()
+            stat.dwLength = ctypes.sizeof(stat)
+            if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(stat)):
+                return round(stat.ullTotalPhys / (1024 ** 3), 1)
+        except Exception:  # noqa: BLE001
+            pass
+    try:
+        if sys.platform.startswith("linux"):
+            from pathlib import Path
+            for line in Path("/proc/meminfo").read_text(encoding="utf-8",
+                                                        errors="ignore").splitlines():
+                if line.startswith("MemTotal:"):
+                    return round(int(line.split()[1]) / 1024 / 1024, 1)
+    except Exception:  # noqa: BLE001
+        pass
+    return 0.0
+
+
+def _tools() -> dict:
+    """Detect optional external tools the swarm can use."""
+    found: dict[str, bool] = {}
+    for name in ("git", "yara", "ffmpeg", "cmake", "cl", "gcc", "cc"):
+        found[name] = shutil.which(name) is not None
+    pw = False
+    try:
+        from playwright.sync_api import sync_playwright
+        with sync_playwright() as p:
+            pw = p.chromium.executable_path is not None
+    except Exception:  # noqa: BLE001
+        pw = False
+    found["playwright_chromium"] = pw
+    return found
+
+
+def describe() -> str:
+    d = detect()
+    ft = "free-threaded" if d["free_threaded"] else "GIL"
+    gpu = d["gpu"]["backend"]
+    isa = ",".join(d["isa"]["extensions"]) or "base"
+    return (f"{d['system']} {d['release']} ({d['machine']}), Python {d['python']} "
+            f"[{ft}], {d['cores']} cores, ISA={isa}, GPU={gpu}")
+
+
+def recommend_config(d: dict | None = None) -> dict:
+    """Map a host descriptor to OpenCommand + engine configuration hints.
+
+    Returns a dict with `config` (kwargs for OpenCommandConfig) and `engine`
+    (kwargs for Engine), ready to apply on setup.
+    """
+    d = d or detect()
+    cores = max(1, d["cores"])
+    pool = max(1, min(cores - 1, 8))  # leave cores for OS; cap to avoid RAM blowup
+    n_gpu_layers = -1 if d["gpu"]["backend"] != "none" else 0
+    build_flags = []
+    if d["isa"]["avx512"]:
+        build_flags.append("-DGGML_AVX512=ON")
+    elif d["isa"]["avx2"]:
+        build_flags.append("-DGGML_AVX2=ON")
+    return {
+        "config": {
+            "max_workers": pool,
+            "vision": d["gpu"]["backend"] != "none" or cores >= 4,
+        },
+        "engine": {"pool_size": pool},
+        "runner": {"n_gpu_layers": n_gpu_layers},
+        "build": {"cmake_args": " ".join(build_flags) if build_flags else ""},
+    }
+

opencommand/modules/templates.py

@@ -0,0 +1,227 @@
+"""Required markdown templates for every artifact OpenCommand can create.
+
+Each template declares the mandatory front-matter / header fields and the body
+sections an artifact must contain. The instructions tool and commander use these
+to ensure every skill, task, doc, memory, scaffold, research, plan, and report
+note is complete and consistent, so the knowledge base and memory store stay
+structured and machine-readable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Template:
+    """A required-shape template for one markdown artifact type."""
+
+    kind: str
+    title: str
+    # YAML-ish front-matter keys that MUST be present (value may be filled later).
+    required_fields: list[str] = field(default_factory=list)
+    # Markdown section headings (## ...) that MUST appear in the body.
+    required_sections: list[str] = field(default_factory=list)
+    # A concrete skeleton the writer fills in.
+    skeleton: str = ""
+
+    def render(self, **values: str) -> str:
+        """Render the skeleton, substituting {field} placeholders from ``values``."""
+        try:
+            return self.skeleton.format(**values)
+        except (KeyError, IndexError):
+            return self.skeleton
+
+
+TEMPLATES: dict[str, Template] = {
+    "skill": Template(
+        kind="skill",
+        title="Skill",
+        required_fields=["name", "category", "updated", "tags"],
+        required_sections=["Summary", "Conventions", "When to use", "Examples", "Gotchas"],
+        skeleton=(
+            "---\n"
+            "name: {name}\n"
+            "category: {category}\n"
+            "updated: {updated}\n"
+            "tags: [{tags}]\n"
+            "---\n\n"
+            "# {name}\n\n"
+            "## Summary\n{description}\n\n"
+            "## Conventions\n- \n\n"
+            "## When to use\n- \n\n"
+            "## Examples\n```\n\n```\n\n"
+            "## Gotchas\n- \n"
+        ),
+    ),
+    "task": Template(
+        kind="task",
+        title="Task Playbook",
+        required_fields=["name", "goal", "updated", "tags"],
+        required_sections=["Objective", "Preconditions", "Steps", "Verification", "Rollback"],
+        skeleton=(
+            "---\n"
+            "name: {name}\n"
+            "goal: {goal}\n"
+            "updated: {updated}\n"
+            "tags: [{tags}]\n"
+            "---\n\n"
+            "# {name}\n\n"
+            "## Objective\n\n"
+            "## Preconditions\n- \n\n"
+            "## Steps\n1. \n\n"
+            "## Verification\n- \n\n"
+            "## Rollback\n- \n"
+        ),
+    ),
+    "doc": Template(
+        kind="doc",
+        title="Reference Doc",
+        required_fields=["name", "topic", "updated", "tags"],
+        required_sections=["Overview", "Details", "References"],
+        skeleton=(
+            "---\n"
+            "name: {name}\n"
+            "topic: {topic}\n"
+            "updated: {updated}\n"
+            "tags: [{tags}]\n"
+            "---\n\n"
+            "# {name}\n\n"
+            "## Overview\n\n"
+            "## Details\n\n"
+            "## References\n- \n"
+        ),
+    ),
+    "memory": Template(
+        kind="memory",
+        title="Memory Note",
+        required_fields=["topic", "tags", "created"],
+        required_sections=["Body"],
+        skeleton=(
+            "---\n"
+            "topic: {topic}\n"
+            "tags: [{tags}]\n"
+            "created: {created}\n"
+            "---\n\n"
+            "# {topic}\n\n"
+            "## Body\n\n"
+        ),
+    ),
+    "scaffold": Template(
+        kind="scaffold",
+        title="Scaffold Manifest",
+        required_fields=["phase", "index", "created"],
+        required_sections=["Purpose", "Layout", "Conventions"],
+        skeleton=(
+            "---\n"
+            "phase: {phase}\n"
+            "index: {index}\n"
+            "created: {created}\n"
+            "---\n\n"
+            "# Scaffold: {phase}\n\n"
+            "## Purpose\n\n"
+            "## Layout\n- \n\n"
+            "## Conventions\n- Write implementation under this directory.\n"
+            "- Do not modify files outside this phase's scope.\n"
+        ),
+    ),
+    "research": Template(
+        kind="research",
+        title="Research Findings",
+        required_fields=["phase", "iteration", "created"],
+        required_sections=["Question", "Findings", "Sources", "Confidence", "Gaps"],
+        skeleton=(
+            "---\n"
+            "phase: {phase}\n"
+            "iteration: {iteration}\n"
+            "created: {created}\n"
+            "---\n\n"
+            "# Research: {phase} (iter {iteration})\n\n"
+            "## Question\n\n"
+            "## Findings\n- \n\n"
+            "## Sources\n- \n\n"
+            "## Confidence\n- high | medium | low\n\n"
+            "## Gaps\n- \n"
+        ),
+    ),
+    "plan": Template(
+        kind="plan",
+        title="Goal Plan",
+        required_fields=["goal", "created", "phases"],
+        required_sections=["Goal", "Phases", "Assumptions"],
+        skeleton=(
+            "---\n"
+            "goal: {goal}\n"
+            "created: {created}\n"
+            "phases: {phases}\n"
+            "---\n\n"
+            "# Plan\n\n"
+            "## Goal\n{goal}\n\n"
+            "## Phases\n\n"
+            "## Assumptions\n- \n"
+        ),
+    ),
+    "report": Template(
+        kind="report",
+        title="Goal Report",
+        required_fields=["goal", "created", "status"],
+        required_sections=["Summary", "Phases", "Review", "Self-Improvement"],
+        skeleton=(
+            "---\n"
+            "goal: {goal}\n"
+            "created: {created}\n"
+            "status: {status}\n"
+            "---\n\n"
+            "# Report\n\n"
+            "## Summary\n\n"
+            "## Phases\n\n"
+            "## Review\n\n"
+            "## Self-Improvement\n\n"
+        ),
+    ),
+}
+
+
+def get_template(kind: str) -> Template | None:
+    return TEMPLATES.get(kind)
+
+
+def template_for(kind: str) -> Template:
+    """Return the template for ``kind`` or raise ``KeyError``."""
+    t = TEMPLATES.get(kind)
+    if t is None:
+        raise KeyError(f"no template for kind {kind!r}")
+    return t
+
+
+def validate_markdown(kind: str, text: str) -> list[str]:
+    """Return a list of missing required front-matter fields/sections for ``kind``."""
+    t = TEMPLATES.get(kind)
+    if t is None:
+        return [f"unknown kind: {kind}"]
+    missing: list[str] = []
+    fm = _parse_front_matter(text)
+    for field_name in t.required_fields:
+        if field_name not in fm:
+            missing.append(f"field:{field_name}")
+    for section in t.required_sections:
+        if f"## {section}" not in text:
+            missing.append(f"section:{section}")
+    return missing
+
+
+def _parse_front_matter(text: str) -> dict[str, str]:
+    """Extract a simple YAML front-matter block (key: value) into a dict."""
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    block = text[3:end]
+    fm: dict[str, str] = {}
+    for line in block.splitlines():
+        if ":" not in line:
+            continue
+        key, _, val = line.partition(":")
+        fm[key.strip()] = val.strip()
+    return fm

opencommand/modules/tools/desktop.py

@@ -0,0 +1,127 @@
+"""Desktop control tool: realtime vision + mouse/keyboard action loop.
+
+Captures the screen, asks a small embedded vision-language model what is
+happening and what to do next, then executes the chosen action via
+pyautogui/pynput. Used for fully interactive testing (e.g. clicking UI,
+verifying behavior). The vision model is the built-in Qwen3-VL (or MiniCPM-V)
+the Engine (no external server).
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+from dataclasses import dataclass
+
+from ...core.tools import BaseTool
+from ...engine.runner import LocalRunner
+
+try:
+    import pyautogui
+    import mss
+    _HAVE_DESKTOP = True
+except Exception:  # pragma: no cover
+    _HAVE_DESKTOP = False
+
+
+@dataclass
+class DesktopStep:
+    observation: str
+    action: str
+    ok: bool
+
+
+def capture_screen() -> bytes:
+    """Return a PNG screenshot of the primary monitor as bytes."""
+    if not _HAVE_DESKTOP:
+        raise RuntimeError("pyautogui/mss not available")
+    with mss.mss() as sct:
+        img = sct.grab(sct.monitors[1])
+        import PIL.Image
+        buf = io.BytesIO()
+        PIL.Image.frombytes("RGB", img.size, img.rgb).save(buf, format="PNG")
+        return buf.getvalue()
+
+
+def act(action: str) -> None:
+    """Execute a high-level action string: click(x,y), type(text), key(name), wait."""
+    if not _HAVE_DESKTOP:
+        raise RuntimeError("pyautogui not available")
+    action = action.strip()
+    if action.startswith("click("):
+        import re
+        m = re.match(r"click\((\d+),\s*(\d+)\)", action)
+        if m:
+            pyautogui.click(int(m.group(1)), int(m.group(2)))
+    elif action.startswith("type("):
+        pyautogui.write(action[len("type("):-1], interval=0.02)
+    elif action.startswith("key("):
+        pyautogui.press(action[len("key("):-1])
+    elif action.startswith("wait("):
+        import time
+        time.sleep(float(action[len("wait("):-1]))
+    else:
+        raise ValueError(f"unknown action: {action}")
+
+
+class DesktopTool(BaseTool):
+    name = "desktop"
+    description = (
+        "Realtime computer control: capture screen, ask a small vision model what "
+        "to do, and execute mouse/keyboard actions. For interactive testing."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "goal": {"type": "string", "description": "What to accomplish on screen."},
+            "steps": {"type": "integer", "description": "Max interaction steps (default 10)."},
+        },
+        "required": ["goal"],
+    }
+
+    def __init__(self, vision_runner: LocalRunner | None = None) -> None:
+        self.vision = vision_runner
+
+    def run(self, goal: str, steps: int = 10) -> str:
+        if not _HAVE_DESKTOP:
+            return "ERROR: desktop control libs (pyautogui/mss) not installed"
+        if self.vision is None:
+            return "ERROR: no vision model configured for desktop tool"
+        history: list[DesktopStep] = []
+        for i in range(steps):
+            b64 = base64.b64encode(capture_screen()).decode()
+            content = [
+                {"type": "text", "text": (
+                    f"Goal: {goal}\nStep {i+1}. Describe the screen and decide the "
+                    "next single action as: click(x,y) | type(text) | key(name) | "
+                    "wait(secs) | done. Reply with ACTION: <action> and a short WHY.")},
+                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
+            ]
+            resp = self.vision.chat([{"role": "user", "content": content}],
+                                    temperature=0.1, max_tokens=256)
+            text = resp["choices"][0]["message"].get("content") or ""
+            action = self._extract_action(text)
+            if action == "done" or action == "":
+                history.append(DesktopStep(text, "done", True))
+                break
+            try:
+                act(action)
+                history.append(DesktopStep(text, action, True))
+            except Exception as e:  # noqa: BLE001
+                history.append(DesktopStep(text, action, False))
+                return f"ERROR on step {i+1}: {e}\n{self._summarize(history)}"
+        return self._summarize(history)
+
+    @staticmethod
+    def _extract_action(text: str) -> str:
+        for line in text.splitlines():
+            if line.strip().upper().startswith("ACTION:"):
+                return line.split(":", 1)[1].strip()
+        return ""
+
+    @staticmethod
+    def _summarize(history: list[DesktopStep]) -> str:
+        lines = [f"desktop loop: {len(history)} steps"]
+        for i, s in enumerate(history, 1):
+            lines.append(f"  {i}. {s.action} -> {'ok' if s.ok else 'FAIL'}")
+        return "\n".join(lines)

opencommand/modules/tools/files.py

@@ -0,0 +1,82 @@
+"""Filesystem tool: deterministic file authoring for agents (write/read/edit/list).
+
+On Windows the shell tool cannot reliably emit multi-line files (no heredoc /
+cat >), so agents need a real file API to write full codebases. All paths are
+resolved under the workspace root; traversal outside it is rejected.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ...core.tools import BaseTool
+
+
+class FilesTool(BaseTool):
+    name = "files"
+    description = (
+        "Author and inspect files in the workspace: write/create, read, edit "
+        "(old->new string replace), list a directory, and mkdir. Paths are "
+        "relative to or inside the workspace root; traversal outside is rejected."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["write", "read", "edit", "list", "mkdir"],
+                "description": "Which filesystem operation to perform.",
+            },
+            "path": {"type": "string", "description": "Target path (relative to workspace)."},
+            "content": {"type": "string", "description": "File content for write."},
+            "old": {"type": "string", "description": "Substring to replace for edit."},
+            "new": {"type": "string", "description": "Replacement substring for edit."},
+        },
+        "required": ["action", "path"],
+    }
+
+    def __init__(self, workspace: Path) -> None:
+        self.root = Path(workspace).resolve()
+
+    def _resolve(self, path: str) -> Path:
+        p = (self.root / path).resolve()
+        if self.root not in p.parents and p != self.root:
+            raise ValueError(f"path escapes workspace: {path}")
+        return p
+
+    def run(self, action: str, path: str, content: str | None = None,
+            old: str | None = None, new: str | None = None) -> str:
+        try:
+            p = self._resolve(path)
+        except ValueError as e:
+            return f"ERROR: {e}"
+        if action == "write":
+            if content is None:
+                return "ERROR: write requires 'content'"
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text(content, encoding="utf-8")
+            return f"Wrote {p} ({len(content)} bytes)"
+        if action == "read":
+            if not p.is_file():
+                return f"ERROR: not a file: {path}"
+            return p.read_text(encoding="utf-8")
+        if action == "edit":
+            if old is None or new is None:
+                return "ERROR: edit requires 'old' and 'new'"
+            if not p.is_file():
+                return f"ERROR: not a file: {path}"
+            text = p.read_text(encoding="utf-8")
+            if old not in text:
+                return "ERROR: 'old' substring not found"
+            p.write_text(text.replace(old, new, 1), encoding="utf-8")
+            return f"Edited {p}"
+        if action == "list":
+            if not p.is_dir():
+                return f"ERROR: not a directory: {path}"
+            items = sorted(
+                (f"{'d' if c.is_dir() else 'f'} {c.name}" for c in p.iterdir()))
+            return "\n".join(items) if items else "(empty)"
+        if action == "mkdir":
+            p.mkdir(parents=True, exist_ok=True)
+            return f"Mkdir {p}"
+        return f"ERROR: unknown action '{action}'"