caudate-cli 0.1.0__py3-none-any.whl

execution/tools/system_info_tool.py

@@ -0,0 +1,212 @@
+"""SystemInfo — one-call summary of host hardware + software state.
+
+Saves the LLM from chaining Bash calls (`uname`, `nvidia-smi`, `df`,
+`free`, …) just to answer "what hardware do you have?". Intentionally
+read-only; everything is via well-known commands.
+
+The output is a structured text block that's easy for the LLM to
+quote back to the user verbatim or summarise. Sections that are
+unavailable (e.g. no NVIDIA GPU) are simply omitted.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+import shutil
+import subprocess
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+_SECTION_TIMEOUT_S = 5   # per subprocess; SystemInfo isn't worth blocking on
+
+
+def _run(cmd: list[str]) -> str:
+    """Run a command and return stdout (or empty on failure)."""
+    try:
+        out = subprocess.run(
+            cmd, capture_output=True, text=True,
+            timeout=_SECTION_TIMEOUT_S,
+        )
+        return (out.stdout or out.stderr or "").strip()
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return ""
+
+
+def _section_kernel() -> str:
+    bits = []
+    bits.append(f"OS:           {platform.system()} {platform.release()}")
+    if platform.system() == "Linux":
+        # Distro name from /etc/os-release
+        os_release = ""
+        try:
+            with open("/etc/os-release") as f:
+                kv = dict(
+                    line.strip().split("=", 1)
+                    for line in f if "=" in line
+                )
+            os_release = kv.get("PRETTY_NAME", "").strip('"')
+        except OSError:
+            pass
+        if os_release:
+            bits.append(f"Distribution: {os_release}")
+    bits.append(f"Architecture: {platform.machine()}")
+    bits.append(f"Hostname:     {platform.node()}")
+    return "\n".join(bits)
+
+
+def _section_cpu_ram() -> str:
+    bits = []
+    cpu_count = os.cpu_count() or 0
+    bits.append(f"CPUs:         {cpu_count} logical")
+    # CPU model from /proc/cpuinfo on Linux
+    try:
+        with open("/proc/cpuinfo") as f:
+            for line in f:
+                if line.startswith("model name"):
+                    bits.append(f"CPU model:    {line.split(':',1)[1].strip()}")
+                    break
+    except OSError:
+        pass
+    # Memory from /proc/meminfo
+    try:
+        mem = {}
+        with open("/proc/meminfo") as f:
+            for line in f:
+                k, _, v = line.partition(":")
+                mem[k.strip()] = v.strip()
+        total_kb = int(mem.get("MemTotal", "0 kB").split()[0] or "0")
+        avail_kb = int(mem.get("MemAvailable", "0 kB").split()[0] or "0")
+        gb = lambda x: x / 1024 / 1024
+        bits.append(
+            f"Memory:       {gb(total_kb):.1f} GB total, "
+            f"{gb(avail_kb):.1f} GB available"
+        )
+    except (OSError, ValueError):
+        pass
+    return "\n".join(bits)
+
+
+def _section_gpu() -> str:
+    if not shutil.which("nvidia-smi"):
+        return "GPU:          (no nvidia-smi found)"
+    raw = _run([
+        "nvidia-smi",
+        "--query-gpu=name,memory.total,memory.used,utilization.gpu,driver_version",
+        "--format=csv,noheader,nounits",
+    ])
+    if not raw:
+        return "GPU:          nvidia-smi present but no GPU info"
+    lines = ["GPUs:"]
+    for entry in raw.splitlines():
+        parts = [p.strip() for p in entry.split(",")]
+        if len(parts) < 5:
+            continue
+        name, mem_total, mem_used, util, driver = parts
+        lines.append(
+            f"  - {name}  ({mem_used}/{mem_total} MB used, "
+            f"{util}% util, driver {driver})"
+        )
+    return "\n".join(lines)
+
+
+def _section_disk() -> str:
+    raw = _run(["df", "-h", "--output=source,size,used,avail,pcent,target"])
+    if not raw:
+        return ""
+    lines = raw.splitlines()
+    # Filter to interesting mounts: skip squashfs, snap, tmpfs, etc.
+    keep = []
+    header = lines[0] if lines else ""
+    keep.append(header)
+    for ln in lines[1:]:
+        if any(k in ln for k in ("/snap/", "tmpfs", "udev", "squashfs", "overlay")):
+            continue
+        keep.append(ln)
+    return "Disks:\n" + "\n".join(f"  {l}" for l in keep[:12])
+
+
+def _section_python_cuda() -> str:
+    bits = [f"Python:       {platform.python_version()}"]
+    # PyTorch + CUDA detection — best-effort, doesn't fail if torch missing
+    try:
+        import torch
+        bits.append(f"PyTorch:      {torch.__version__}")
+        if torch.cuda.is_available():
+            bits.append(
+                f"CUDA:         {torch.version.cuda} "
+                f"({torch.cuda.device_count()} device(s) visible to torch)"
+            )
+        else:
+            bits.append("CUDA:         not available to torch")
+    except Exception as e:
+        bits.append(f"PyTorch:      not importable ({e!s:.60})")
+    return "\n".join(bits)
+
+
+def _section_uptime_load() -> str:
+    bits = []
+    try:
+        with open("/proc/uptime") as f:
+            up = float(f.read().split()[0])
+        days, rem = divmod(up, 86400)
+        hours, rem = divmod(rem, 3600)
+        mins = rem // 60
+        bits.append(
+            f"Uptime:       {int(days)}d {int(hours)}h {int(mins)}m"
+        )
+    except OSError:
+        pass
+    try:
+        with open("/proc/loadavg") as f:
+            la = f.read().strip().split()[:3]
+        bits.append(f"Load avg:     {' / '.join(la)} (1/5/15 min)")
+    except OSError:
+        pass
+    return "\n".join(bits)
+
+
+class SystemInfoTool(BaseTool):
+    name = "SystemInfo"
+    description = (
+        "Read-only one-call summary of the host machine: OS, CPU, RAM, "
+        "GPU (incl. NVIDIA), disk usage, Python/PyTorch/CUDA versions, "
+        "uptime. Use this when the user asks about the hardware/software "
+        "Cognos is running on, instead of chaining several Bash calls."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {"type": "object", "properties": {}, "required": []}
+
+    async def execute(self, **_: Any) -> ToolResult:
+        # Run sections in a thread so we don't block the event loop on
+        # subprocesses (nvidia-smi can take a second or two).
+        loop = asyncio.get_event_loop()
+        sections = await loop.run_in_executor(None, self._collect_all)
+        return ToolResult(
+            tool_name=self.name, status="success", output=sections
+        )
+
+    @staticmethod
+    def _collect_all() -> str:
+        parts: list[str] = []
+        for fn in (
+            _section_kernel,
+            _section_cpu_ram,
+            _section_gpu,
+            _section_disk,
+            _section_python_cuda,
+            _section_uptime_load,
+        ):
+            try:
+                out = fn()
+                if out:
+                    parts.append(out)
+            except Exception as e:
+                parts.append(f"({fn.__name__} failed: {e!s:.80})")
+        return "\n\n".join(parts)

execution/tools/task_tool.py

@@ -0,0 +1,323 @@
+"""Task tools — durable tracking for long-running async work.
+
+Wraps `core/background.py::BackgroundTaskPool` so the LLM can spawn
+fire-and-forget agent turns and check on them later. Useful when the
+user asks for something that takes minutes (e.g. "generate a 12-panel
+storyboard, I'll come back later") — the agent kicks off the work,
+hands back a task id, and the next chat turn can `TaskGet` to surface
+the result.
+
+Five tools:
+
+  - **`TaskCreate`** — spawn a sub-prompt as a background task. The
+    agent runs the prompt in the same process; the user's chat turn
+    returns immediately with the task id.
+  - **`TaskList`**   — show all tasks in the pool with status.
+  - **`TaskGet`**    — fetch a single task by id (status, duration, result).
+  - **`TaskOutput`** — same as TaskGet but returns just the result text.
+  - **`TaskStop`**   — cancel a running task by id.
+
+Persistence: in-process only. When the Cognos server restarts, all
+running tasks are lost (per the upstream BackgroundTaskPool design).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from core.background import BackgroundTask, get_global_pool
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+def _format_task(t: BackgroundTask, *, brief: bool = False) -> str:
+    head = (
+        f"  {t.id}  [{t.status:>9}]  duration={t.duration:6.1f}s\n"
+        f"    label: {t.label[:80]}"
+    )
+    if brief:
+        return head
+    extra = []
+    if t.error:
+        extra.append(f"    error: {t.error[:200]}")
+    if t.result:
+        extra.append(f"    result (head): {t.result[:160]}")
+    return head + ("\n" + "\n".join(extra) if extra else "")
+
+
+class TaskCreateTool(BaseTool):
+    mutates = True
+    name = "TaskCreate"
+    description = (
+        "Spawn a sub-prompt as a background task. The agent runs the "
+        "given `prompt` in the same Cognos process but doesn't block "
+        "the current chat turn — you get a task id back immediately. "
+        "Use this when the work will take longer than ~30 seconds and "
+        "the user doesn't want to wait. Use `TaskGet` / `TaskOutput` "
+        "later to fetch the result. Limitation: tasks run in-process, "
+        "so they die if the Cognos server restarts."
+    )
+
+    def __init__(self, agent: Any | None = None):
+        self._agent = agent
+
+    def set_agent(self, agent: Any) -> None:
+        self._agent = agent
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "prompt": {
+                    "type": "string",
+                    "description": "What the background agent turn should do.",
+                },
+                "label": {
+                    "type": "string",
+                    "description": "Short human-readable label shown in TaskList.",
+                },
+            },
+            "required": ["prompt"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        prompt = (kwargs.get("prompt") or "").strip()
+        label = (kwargs.get("label") or prompt[:60]).strip()
+        if not prompt:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`prompt` is required",
+            )
+        if self._agent is None or not hasattr(self._agent, "chat"):
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=(
+                    "TaskCreate is not wired to a CognosAgent. The "
+                    "agent must call set_agent() at startup."
+                ),
+            )
+
+        pool = get_global_pool()
+        agent = self._agent
+
+        async def _run() -> str:
+            return await agent.chat(prompt)
+
+        bg = pool.submit(_run, label=label)
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                f"Background task started.\n"
+                f"  task_id:  {bg.id}\n"
+                f"  label:    {bg.label}\n"
+                f"Use TaskGet({bg.id!r}) or TaskOutput({bg.id!r}) to "
+                f"check on it. Use TaskStop({bg.id!r}) to cancel."
+            ),
+            metadata={"task_id": bg.id, "label": bg.label, "status": bg.status},
+        )
+
+
+class TaskListTool(BaseTool):
+    name = "TaskList"
+    description = (
+        "List all background tasks in this process with their status, "
+        "duration, label, and (for finished ones) the result-head or "
+        "error. No arguments. Tasks are sorted newest-first."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {"type": "object", "properties": {}}
+
+    async def execute(self, **_: Any) -> ToolResult:
+        tasks = get_global_pool().list()
+        if not tasks:
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output="No background tasks.",
+                metadata={"tasks": []},
+            )
+        lines = [f"{len(tasks)} background task(s):", ""]
+        lines.extend(_format_task(t) for t in tasks)
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={
+                "tasks": [
+                    {
+                        "id":          t.id,
+                        "status":      t.status,
+                        "label":       t.label,
+                        "duration_s":  t.duration,
+                        "started_at":  t.started_at,
+                        "finished_at": t.finished_at or None,
+                        "error":       t.error,
+                    }
+                    for t in tasks
+                ],
+            },
+        )
+
+
+class TaskGetTool(BaseTool):
+    name = "TaskGet"
+    description = (
+        "Fetch one background task by id. Returns its status, duration, "
+        "label, error (if any), and the full result text (if done). Use "
+        "this to check on work spawned via TaskCreate."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "Task id from TaskCreate / TaskList.",
+                },
+            },
+            "required": ["task_id"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        task_id = (kwargs.get("task_id") or "").strip()
+        if not task_id:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`task_id` is required",
+            )
+        bg = get_global_pool().get(task_id)
+        if bg is None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"no task with id {task_id!r}",
+            )
+        lines = [
+            f"task {bg.id}",
+            f"  status:    {bg.status}",
+            f"  label:     {bg.label}",
+            f"  duration:  {bg.duration:.1f}s",
+        ]
+        if bg.error:
+            lines.append(f"  error:     {bg.error[:400]}")
+        if bg.result:
+            lines.append(f"  result:")
+            lines.append(bg.result)
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={
+                "id":         bg.id,
+                "status":     bg.status,
+                "label":      bg.label,
+                "duration_s": bg.duration,
+                "error":      bg.error,
+                "result":     bg.result,
+            },
+        )
+
+
+class TaskOutputTool(BaseTool):
+    name = "TaskOutput"
+    description = (
+        "Return only the final output (result text) of a finished "
+        "background task. Errors if the task is still running, has "
+        "no output yet, or doesn't exist. Use this when you just "
+        "want the answer and don't care about metadata."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "Task id from TaskCreate / TaskList.",
+                },
+            },
+            "required": ["task_id"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        task_id = (kwargs.get("task_id") or "").strip()
+        if not task_id:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`task_id` is required",
+            )
+        bg = get_global_pool().get(task_id)
+        if bg is None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"no task with id {task_id!r}",
+            )
+        if bg.status in ("pending", "running"):
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"task {task_id} is still {bg.status} ({bg.duration:.1f}s elapsed)",
+            )
+        if bg.status == "failed":
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"task {task_id} failed: {bg.error}",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=bg.result or "(empty)",
+            metadata={"id": bg.id, "status": bg.status},
+        )
+
+
+class TaskStopTool(BaseTool):
+    mutates = True
+    name = "TaskStop"
+    description = (
+        "Cancel a running background task by id. No-op if the task is "
+        "already finished or doesn't exist. Returns success or 'not "
+        "cancellable'."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "Task id from TaskList.",
+                },
+            },
+            "required": ["task_id"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        task_id = (kwargs.get("task_id") or "").strip()
+        if not task_id:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`task_id` is required",
+            )
+        ok = get_global_pool().cancel(task_id)
+        if not ok:
+            bg = get_global_pool().get(task_id)
+            if bg is None:
+                return ToolResult(
+                    tool_name=self.name, status="error",
+                    error=f"no task with id {task_id!r}",
+                )
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"task {task_id} is {bg.status} — not cancellable",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=f"Cancellation requested for task {task_id}.",
+            metadata={"task_id": task_id},
+        )

execution/tools/think_tool.py

@@ -0,0 +1,49 @@
+"""Think tool — use the LLM to reason, generate knowledge, or synthesize information."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+class ThinkTool(BaseTool):
+    name = "Think"
+    description = "Use the LLM to reason about a topic, answer a question, or synthesize information. Use this for knowledge questions, analysis, explanations, and any task that requires thinking rather than external tools."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "question": {
+                    "type": "string",
+                    "description": "The question or topic to think about",
+                },
+            },
+            "required": ["question"],
+        }
+
+    def __init__(self, llm=None):
+        self._llm = llm
+
+    def set_llm(self, llm) -> None:
+        self._llm = llm
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        question = kwargs.get("question", "")
+        if not question:
+            return self._error("No question provided")
+
+        if not self._llm:
+            return self._error("LLM not configured for think tool")
+
+        try:
+            response = await self._llm.complete(
+                prompt=question,
+                system="You are a knowledgeable assistant. Provide clear, accurate, and helpful responses. Be thorough but concise.",
+            )
+            return self._success(response.content)
+        except Exception as e:
+            return self._error(f"Thinking failed: {e}")

execution/tools/transcribe_audio_tool.py

@@ -0,0 +1,86 @@
+"""TranscribeAudio — speech-to-text for a local audio file.
+
+Uses Cognos's existing Whisper STT backend from `voice/stt.py`.
+Loaded lazily on first call.
+
+Accepts wav/mp3/flac/ogg/m4a — anything Whisper can read. Returns
+the transcript as a single text block.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class TranscribeAudioTool(BaseTool):
+    name = "TranscribeAudio"
+    description = (
+        "Convert a local audio file to text via Whisper. Use for "
+        "voice notes, meeting recordings, podcasts, voicemails, or "
+        "any 'what does this audio say?' request. Path must be a "
+        "local file (wav/mp3/flac/ogg/m4a/etc.). Returns the full "
+        "transcript."
+    )
+
+    def __init__(self):
+        self._stt: Any | None = None
+
+    def _get_stt(self):
+        if self._stt is None:
+            from voice.stt import make_stt
+            self._stt = make_stt(name="whisper")
+        return self._stt
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Path to a local audio file.",
+                },
+            },
+            "required": ["path"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        path = (kwargs.get("path") or "").strip()
+        p = Path(path).expanduser().resolve()
+        if not p.exists() or not p.is_file():
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"audio file not found: {p}",
+            )
+
+        try:
+            audio_bytes = p.read_bytes()
+            stt = self._get_stt()
+            transcript = stt.transcribe(audio_bytes)
+        except Exception as e:
+            logger.exception("TranscribeAudio failed")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"{type(e).__name__}: {e}",
+            )
+
+        if not transcript or not transcript.strip():
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output="(empty transcript — no speech detected)",
+                metadata={"path": str(p), "transcript": ""},
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=transcript,
+            metadata={"path": str(p),
+                      "transcript": transcript,
+                      "char_count": len(transcript)},
+        )