caudate-cli 0.1.0__py3-none-any.whl

execution/tools/semantic_search_tool.py

@@ -0,0 +1,106 @@
+"""SemanticSearch — vector-similarity recall over the SemanticMemory store.
+
+Cognos's `memory/semantic.py` keeps a chromadb collection of durable
+facts/concepts the agent has learned. Stuff goes in via `.store()`
+calls (currently from a few places in the agent loop); this tool is
+the read side, exposed to the LLM so it can ask "have I seen this
+topic before?" without the user having to type the answer.
+
+Complements `UpdateMemory` (which writes a flat markdown file): this
+one handles the *vector-indexed* knowledge — semantic similarity
+beats string match for paraphrased recall.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class SemanticSearchTool(BaseTool):
+    name = "SemanticSearch"
+    description = (
+        "Vector-similarity search over Cognos's long-term semantic "
+        "memory (durable facts the agent has learned). Use this when "
+        "the user asks 'do you remember anything about X?', when "
+        "you'd benefit from prior context on a topic, or when "
+        "answering a question that might have been answered before. "
+        "Complements UpdateMemory (which is for the flat markdown "
+        "memory file): use this for fuzzy/semantic recall, "
+        "UpdateMemory for explicit append/replace."
+    )
+
+    def __init__(self):
+        # Lazy-initialise the store so cold-start of the executor
+        # doesn't pay the chromadb load cost. First call materialises.
+        self._store: Any | None = None
+
+    def _get_store(self):
+        if self._store is None:
+            from memory.semantic import SemanticMemory
+            self._store = SemanticMemory()
+        return self._store
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Natural-language query — paraphrasing is fine, the search uses semantic similarity.",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Max results to return. Default 5.",
+                    "default": 5,
+                },
+                "category": {
+                    "type": "string",
+                    "description": "Optional category filter (e.g. 'preferences', 'project').",
+                },
+            },
+            "required": ["query"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        query = (kwargs.get("query") or "").strip()
+        if not query:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="empty query",
+            )
+        limit = max(1, int(kwargs.get("limit") or 5))
+        category = kwargs.get("category") or None
+
+        try:
+            store = self._get_store()
+            hits = store.recall(query=query, limit=limit, category=category)
+        except Exception as e:
+            logger.exception("SemanticSearch failed")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"{type(e).__name__}: {e}",
+            )
+
+        if not hits:
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=f"No semantic matches for: {query!r}",
+                metadata={"query": query, "hits": []},
+            )
+        lines = [f"Found {len(hits)} semantic match(es) for: {query!r}"]
+        for i, h in enumerate(hits, 1):
+            cat = h.get("category", "general")
+            content = h.get("content", "")[:300]
+            lines.append(f"  {i}. [{cat}] {content}")
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={"query": query, "hits": hits},
+        )

execution/tools/shell_tool.py

@@ -0,0 +1,283 @@
+"""Shell tools — synchronous + background execution.
+
+Two tools live here:
+
+  - **`Bash`** runs a command via `/bin/sh -c` (or `bash -c`). When
+    `run_in_background: true` the process is detached, its output is
+    redirected to a temp log file, and the tool returns the PID + log
+    path immediately so the LLM can keep going while the job runs.
+  - **`PowerShell`** invokes PowerShell Core (`pwsh`) with the same
+    `run_in_background` semantics. Useful for cross-platform scripts
+    that target Windows / .NET-flavoured tooling.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import shlex
+import tempfile
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+# Where background-job logs live. Tucked under tempdir so they're
+# auto-cleaned by OS housekeeping; the path is returned to the caller
+# so they can `Read` it any time before then.
+_BG_LOG_DIR = Path(tempfile.gettempdir()) / "cognos-bg-jobs"
+_BG_LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+# Patterns we never run, regardless of mode.
+_BLOCKED = ("rm -rf /", "mkfs", "dd if=", ":(){", "fork bomb")
+
+
+def _is_blocked(cmd: str) -> bool:
+    low = cmd.lower()
+    return any(b in low for b in _BLOCKED)
+
+
+async def _run_foreground(
+    argv: list[str] | str, *, shell: bool, timeout: int,
+    env: dict[str, str] | None = None,
+) -> tuple[int, str, str, bool]:
+    """Run a command foreground; returns (returncode, stdout, stderr, timed_out)."""
+    if shell:
+        proc = await asyncio.create_subprocess_shell(
+            argv if isinstance(argv, str) else " ".join(argv),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+    else:
+        proc = await asyncio.create_subprocess_exec(
+            *(argv if isinstance(argv, list) else shlex.split(argv)),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+    try:
+        stdout, stderr = await asyncio.wait_for(
+            proc.communicate(), timeout=timeout,
+        )
+        return (
+            proc.returncode or 0,
+            stdout.decode("utf-8", errors="replace").strip(),
+            stderr.decode("utf-8", errors="replace").strip(),
+            False,
+        )
+    except asyncio.TimeoutError:
+        try:
+            proc.kill()
+        except Exception:
+            pass
+        return (-1, "", f"command timed out after {timeout}s", True)
+
+
+def _spawn_background(
+    argv: list[str] | str, *, shell: bool,
+    label: str, env: dict[str, str] | None = None,
+) -> tuple[int, Path]:
+    """Detach a long-running process; returns (pid, log_path).
+
+    Stdout + stderr are merged into a single log file under
+    `_BG_LOG_DIR` so the caller can read it incrementally with `Read`
+    or `Grep` and decide when to consider the job done.
+    """
+    job_id = f"{int(time.time())}-{uuid.uuid4().hex[:6]}-{label}"
+    log_path = _BG_LOG_DIR / f"{job_id}.log"
+    log_fh = open(log_path, "wb", buffering=0)
+
+    # `setsid` so the child gets its own session and outlives us if we
+    # exit. `start_new_session=True` is the Python equivalent.
+    if shell:
+        cmd_str = argv if isinstance(argv, str) else " ".join(argv)
+        proc = asyncio.subprocess.subprocess.Popen(  # type: ignore[attr-defined]
+            cmd_str, shell=True,
+            stdout=log_fh, stderr=log_fh,
+            stdin=asyncio.subprocess.subprocess.DEVNULL,  # type: ignore[attr-defined]
+            start_new_session=True,
+            env=env,
+        )
+    else:
+        proc = asyncio.subprocess.subprocess.Popen(  # type: ignore[attr-defined]
+            argv if isinstance(argv, list) else shlex.split(argv),
+            stdout=log_fh, stderr=log_fh,
+            stdin=asyncio.subprocess.subprocess.DEVNULL,  # type: ignore[attr-defined]
+            start_new_session=True,
+            env=env,
+        )
+    log_fh.close()  # the subprocess holds the fd; we don't need ours
+    return proc.pid, log_path
+
+
+class ShellTool(BaseTool):
+    mutates = True
+    name = "Bash"
+    description = (
+        "Execute a shell command and return its output. Use for system "
+        "commands, file operations, git, and any CLI tool. Set "
+        "`run_in_background: true` for long-running commands — Cognos "
+        "spawns the process detached, returns the PID + log path "
+        "immediately, and you can `Read` the log file to track "
+        "progress without blocking the conversation."
+    )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The shell command to execute (passed to sh -c).",
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Timeout in seconds (default 30, foreground only).",
+                    "default": 30,
+                },
+                "run_in_background": {
+                    "type": "boolean",
+                    "description": (
+                        "If true, the command is spawned detached. "
+                        "Returns the PID + path to a log file capturing "
+                        "stdout+stderr; the tool returns immediately "
+                        "without waiting for the process to finish."
+                    ),
+                    "default": False,
+                },
+            },
+            "required": ["command"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        command = kwargs.get("command", "")
+        if not command:
+            return self._error("No command provided")
+        if _is_blocked(command):
+            return self._error(f"Blocked dangerous command: {command}")
+
+        if kwargs.get("run_in_background"):
+            try:
+                pid, log_path = _spawn_background(
+                    command, shell=True, label="bash",
+                )
+            except Exception as e:
+                return self._error(f"failed to spawn background job: {e}")
+            return self._success(
+                f"Background job started.\n"
+                f"  pid:       {pid}\n"
+                f"  log file:  {log_path}\n"
+                f"Use `Read` on the log path to inspect output. The "
+                f"process continues to run after this turn finishes."
+            )
+
+        timeout = int(kwargs.get("timeout", 30))
+        try:
+            rc, stdout, stderr, timed_out = await _run_foreground(
+                command, shell=True, timeout=timeout,
+            )
+        except Exception as e:
+            return self._error(str(e))
+
+        if timed_out:
+            return self._error(f"Command timed out after {timeout}s")
+        if rc == 0:
+            return self._success(stdout or "(no output)")
+        return self._error(f"Exit code {rc}: {stderr or stdout}")
+
+
+class PowerShellTool(BaseTool):
+    mutates = True
+    name = "PowerShell"
+    description = (
+        "Execute a PowerShell Core (`pwsh`) command. Same semantics as "
+        "Bash but runs in a PowerShell session — useful for "
+        "cross-platform scripts targeting Windows tooling, .NET "
+        "objects, or PowerShell modules. Set `run_in_background: true` "
+        "for long-running commands."
+    )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": (
+                        "PowerShell command or script. Equivalent to "
+                        "running `pwsh -NoProfile -Command \"<command>\"`."
+                    ),
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Timeout in seconds (default 30, foreground only).",
+                    "default": 30,
+                },
+                "run_in_background": {
+                    "type": "boolean",
+                    "description": (
+                        "If true, spawn detached and return the PID + "
+                        "log path immediately. See Bash for details."
+                    ),
+                    "default": False,
+                },
+            },
+            "required": ["command"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        command = kwargs.get("command", "")
+        if not command:
+            return self._error("No command provided")
+
+        pwsh_path = shutil.which("pwsh") or shutil.which("powershell")
+        if not pwsh_path:
+            return self._error(
+                "PowerShell Core (`pwsh`) is not installed. Install it "
+                "via `snap install powershell --classic` (Linux) or "
+                "from https://github.com/PowerShell/PowerShell."
+            )
+
+        # Refuse the blocked set on the underlying string too — easy to
+        # try `Invoke-Expression "rm -rf /"` from PowerShell.
+        if _is_blocked(command):
+            return self._error(f"Blocked dangerous command: {command}")
+
+        argv = [pwsh_path, "-NoProfile", "-NonInteractive",
+                "-Command", command]
+
+        if kwargs.get("run_in_background"):
+            try:
+                pid, log_path = _spawn_background(
+                    argv, shell=False, label="pwsh",
+                )
+            except Exception as e:
+                return self._error(f"failed to spawn background pwsh job: {e}")
+            return self._success(
+                f"Background PowerShell job started.\n"
+                f"  pid:       {pid}\n"
+                f"  log file:  {log_path}\n"
+                f"Use `Read` on the log path to inspect output."
+            )
+
+        timeout = int(kwargs.get("timeout", 30))
+        try:
+            rc, stdout, stderr, timed_out = await _run_foreground(
+                argv, shell=False, timeout=timeout,
+            )
+        except Exception as e:
+            return self._error(str(e))
+
+        if timed_out:
+            return self._error(f"Command timed out after {timeout}s")
+        if rc == 0:
+            return self._success(stdout or "(no output)")
+        return self._error(f"Exit code {rc}: {stderr or stdout}")

execution/tools/speak_tool.py

@@ -0,0 +1,134 @@
+"""Speak — text-to-speech, returns a markdown audio link.
+
+Uses Cognos's existing Kokoro TTS backend (`voice/tts.py`). The
+synthesized audio is saved to FileStore so the chat UI can play it
+back via the `/files/{id}/content` endpoint, just like images.
+
+Returns a `markdown` field with `[🔊 alt](url)` that the LLM should
+echo verbatim in its reply — Open WebUI renders the link as a
+playable audio control.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+import wave
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+def _public_base_url() -> str:
+    return os.environ.get("COGNOS_PUBLIC_URL", "http://127.0.0.1:8000").rstrip("/")
+
+
+class SpeakTool(BaseTool):
+    mutates = True
+    name = "Speak"
+    description = (
+        "Synthesize text into speech via Kokoro TTS, save the audio "
+        "to FileStore, and return a markdown audio link the chat UI "
+        "can play. Use when the user asks you to read something aloud, "
+        "produce a voice clip, or generate a TTS preview. Returns a "
+        "`markdown` field — paste it VERBATIM into your reply."
+    )
+
+    def __init__(self, file_store: Any | None = None):
+        self._file_store = file_store
+        self._tts: Any | None = None
+
+    def set_file_store(self, file_store: Any) -> None:
+        self._file_store = file_store
+
+    def _get_tts(self):
+        if self._tts is None:
+            from voice.tts import make_tts
+            self._tts = make_tts(name="kokoro")
+        return self._tts
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "text": {
+                    "type": "string",
+                    "description": "What to speak. Keep under ~500 chars for fast synthesis.",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "Optional short label (used as audio link text).",
+                },
+            },
+            "required": ["text"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        text = (kwargs.get("text") or "").strip()
+        title = (kwargs.get("title") or "Audio clip").strip()
+        if not text:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="empty text",
+            )
+        if self._file_store is None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="Speak tool not wired to a FileStore",
+            )
+
+        try:
+            tts = self._get_tts()
+            audio, sr = tts.synthesize(text)
+        except Exception as e:
+            logger.exception("Speak: synthesis failed")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"synthesis failed: {e}",
+            )
+
+        # Persist as 16-bit PCM WAV
+        try:
+            with tempfile.NamedTemporaryFile(
+                "wb", suffix=".wav", delete=False
+            ) as tmp:
+                tmp_path = tmp.name
+            with wave.open(tmp_path, "wb") as wav:
+                wav.setnchannels(1)
+                wav.setsampwidth(2)
+                wav.setframerate(int(sr))
+                wav.writeframes(audio.tobytes())
+            safe_title = "".join(
+                c if c.isalnum() or c in "-_" else "_" for c in title
+            )[:40] or "speech"
+            stored_name = f"{safe_title}.wav"
+            record = self._file_store.upload(tmp_path, filename=stored_name)
+        except Exception as e:
+            logger.exception("Speak: persist failed")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"persist failed: {e}",
+            )
+
+        url = f"{_public_base_url()}/files/{record.id}/content"
+        markdown = f"[🔊 {title}]({url})"
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                f"Speech synthesized.\n"
+                f"  text:     {text[:80]}{'...' if len(text) > 80 else ''}\n"
+                f"  duration: ~{len(audio) / int(sr):.1f}s\n"
+                f"  url:      {url}\n\n"
+                f"Paste in your reply VERBATIM:\n"
+                f"  {markdown}"
+            ),
+            metadata={
+                "file_id": record.id, "url": url, "markdown": markdown,
+                "duration_s": len(audio) / int(sr),
+            },
+        )