caudate-cli 0.1.0__py3-none-any.whl

execution/tools/base.py

@@ -0,0 +1,81 @@
+"""Base tool interface — Claude SDK compatible tool protocol."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from core.schemas import ToolResult, ToolResultStatus
+
+
+class BaseTool(ABC):
+    """Abstract base class for all tools.
+
+    Tools define their interface via `input_schema` (JSON Schema),
+    matching the Claude SDK tool definition format.
+
+    Plan-mode contract: subclasses that perform any side-effect
+    (writing files, running shell commands, mutating external state)
+    set `mutates = True`. The executor refuses to run mutating tools
+    while plan mode is on. Read-only tools (Read, Grep, Glob,
+    SystemInfo, Calculator, etc.) leave `mutates = False`.
+    """
+
+    # Whether this tool produces side effects. Default False — every
+    # subclass that writes files / runs commands / sends network
+    # requests / changes durable state should override to True.
+    mutates: bool = False
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique tool name."""
+        ...
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Human-readable description of what the tool does."""
+        ...
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        """JSON Schema defining the tool's input parameters.
+
+        Override this in subclasses. Default returns empty object schema.
+        """
+        return {"type": "object", "properties": {}, "required": []}
+
+    @property
+    def parameters(self) -> dict[str, str]:
+        """Legacy parameter descriptions for LLM planning.
+
+        Auto-generated from input_schema for backward compatibility.
+        """
+        props = self.input_schema.get("properties", {})
+        return {k: v.get("description", "") for k, v in props.items()}
+
+    def to_tool_definition(self) -> dict[str, Any]:
+        """Return LiteLLM-compatible tool definition.
+
+        Format: {"type": "function", "function": {"name", "description", "parameters"}}
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.input_schema,
+            },
+        }
+
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        """Execute the tool with given arguments."""
+        ...
+
+    def _success(self, output: Any) -> ToolResult:
+        return ToolResult(tool_name=self.name, status=ToolResultStatus.SUCCESS, output=output)
+
+    def _error(self, error: str) -> ToolResult:
+        return ToolResult(tool_name=self.name, status=ToolResultStatus.ERROR, error=error)

execution/tools/calculator_tool.py

@@ -0,0 +1,137 @@
+"""Calculator — exact arithmetic and symbolic math.
+
+LLMs hallucinate digits past ~10-digit precision and get basic
+multi-step arithmetic wrong surprisingly often. This tool does the
+computation deterministically using Python's expression evaluator,
+then optionally falls through to `sympy` for symbolic ops if the
+expression contains symbolic markers.
+
+Safety: uses a strict allowlist of names + AST validation. No
+imports, no attribute access, no comprehensions, no function calls
+except a curated math whitelist. Untrusted expressions can't escape
+the sandbox.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+import math
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+# Allowed top-level names — math constants and a curated set of
+# functions. Anything not in this dict raises NameError.
+_ALLOWED_NAMES: dict[str, Any] = {
+    # constants
+    "pi": math.pi, "e": math.e, "tau": math.tau, "inf": math.inf,
+    # safe scalar functions
+    "abs": abs, "round": round, "min": min, "max": max,
+    "sum": sum, "pow": pow,
+    # math module
+    "sqrt": math.sqrt, "log": math.log, "log2": math.log2,
+    "log10": math.log10, "exp": math.exp,
+    "sin": math.sin, "cos": math.cos, "tan": math.tan,
+    "asin": math.asin, "acos": math.acos, "atan": math.atan, "atan2": math.atan2,
+    "sinh": math.sinh, "cosh": math.cosh, "tanh": math.tanh,
+    "ceil": math.ceil, "floor": math.floor, "trunc": math.trunc,
+    "factorial": math.factorial, "gcd": math.gcd, "lcm": math.lcm,
+    "degrees": math.degrees, "radians": math.radians,
+    "hypot": math.hypot, "fabs": math.fabs,
+    "fmod": math.fmod, "modf": math.modf,
+    "isclose": math.isclose, "isfinite": math.isfinite, "isnan": math.isnan,
+}
+
+
+# AST node types that are NOT allowed in the expression. We allow
+# arithmetic, comparisons, conditionals, name lookups (gated by the
+# allowlist above), and function calls (also gated).
+_FORBIDDEN_NODES = (
+    ast.Import, ast.ImportFrom,
+    ast.Lambda, ast.FunctionDef, ast.ClassDef,
+    ast.Attribute,                    # no x.y access — blocks os.system etc
+    ast.Subscript,                    # no list/dict subscripting
+    ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp,
+    ast.Yield, ast.YieldFrom,
+    ast.Await,
+    ast.Assign, ast.AugAssign, ast.AnnAssign,
+    ast.Delete,
+    ast.Global, ast.Nonlocal,
+    ast.Try,
+    ast.With, ast.AsyncWith, ast.AsyncFor, ast.AsyncFunctionDef,
+)
+
+
+def _validate_ast(tree: ast.AST) -> None:
+    """Raise ValueError if tree contains forbidden nodes."""
+    for node in ast.walk(tree):
+        if isinstance(node, _FORBIDDEN_NODES):
+            raise ValueError(
+                f"forbidden expression element: {type(node).__name__}"
+            )
+        # Function calls must use names from the allowlist
+        if isinstance(node, ast.Call):
+            func = node.func
+            if not isinstance(func, ast.Name):
+                raise ValueError("function calls must be on bare names")
+            if func.id not in _ALLOWED_NAMES:
+                raise ValueError(f"function not allowed: {func.id}")
+
+
+def _eval_safe(expr: str) -> Any:
+    """Parse + validate + eval an arithmetic expression."""
+    tree = ast.parse(expr, mode="eval")
+    _validate_ast(tree)
+    return eval(compile(tree, "<calculator>", "eval"),
+                {"__builtins__": {}}, _ALLOWED_NAMES)
+
+
+class CalculatorTool(BaseTool):
+    name = "Calculator"
+    description = (
+        "Evaluate an arithmetic or scalar-math expression exactly. "
+        "Use this whenever the user asks for arithmetic, percentages, "
+        "unit conversions, or anything where digits past ~10 places "
+        "matter. Supports +, -, *, /, **, math constants (pi, e), and "
+        "common math functions (sqrt, log, sin, cos, factorial, etc.). "
+        "No variables, no imports — pure expressions."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "expression": {
+                    "type": "string",
+                    "description": "Expression to evaluate, e.g. "
+                                   "'2 ** 32 - 1' or 'sqrt(2) * 5'.",
+                },
+            },
+            "required": ["expression"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        expr = (kwargs.get("expression") or "").strip()
+        if not expr:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="empty expression",
+            )
+        try:
+            result = _eval_safe(expr)
+        except Exception as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"{type(e).__name__}: {e}",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=f"{expr} = {result}",
+            metadata={"expression": expr, "result": result},
+        )

execution/tools/cognos_card_tool.py

@@ -0,0 +1,124 @@
+"""CognosCard — read the Cognos self-spec card.
+
+Mirrors the structure of the Anthropic Opus self-card the user
+showed: confirmable facts / architecture / training / capabilities /
+**what we can't honestly tell you**. The card lives at
+`data/COGNOS_CARD.md` and is human-edited (not auto-generated).
+
+The LLM can call this tool to:
+  - Answer "what is Cognos?" / "what can you do?" honestly
+  - Self-introspect before claiming a capability ("can I do X?")
+  - Anchor on the explicit boundaries section before responding
+"""
+
+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__)
+
+
+_CARD_PATH = Path("/home/raveuk/cognos/data/COGNOS_CARD.md")
+
+
+def render_cognos_card_short() -> str:
+    """One-paragraph reference to the card, suitable for system-prompt
+    injection. Tells the LLM the card exists + how to read it; doesn't
+    bloat the prompt with the full card body.
+    """
+    return (
+        "## About Cognos\n\n"
+        "You are running inside **Cognos** — a local-first cognitive "
+        "agent on the user's own machine. The full structured "
+        "self-spec lives at `data/COGNOS_CARD.md` and is also "
+        "available via the `CognosCard` tool: confirmable facts, "
+        "architecture, capabilities, and an explicit list of what "
+        "Cognos cannot honestly tell you. **Call CognosCard before "
+        "claiming a capability you're unsure about** — the card is "
+        "the source of truth, not your model's training defaults."
+    )
+
+
+class CognosCardTool(BaseTool):
+    name = "CognosCard"
+    description = (
+        "Read the Cognos self-spec card — verifiable facts about the "
+        "agent you're running inside, its architecture, what it can "
+        "do, and (importantly) what it CANNOT honestly tell you. "
+        "Call this whenever the user asks 'what are you', 'what can "
+        "you do', or whenever you'd otherwise speculate about Cognos "
+        "internals. Returns the full markdown card."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "section": {
+                    "type": "string",
+                    "enum": [
+                        "all",
+                        "confirm",
+                        "architecture",
+                        "training",
+                        "capabilities",
+                        "boundaries",
+                    ],
+                    "description": "Which section to return. 'all' returns the full card; the others return only that section.",
+                },
+            },
+            "required": [],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        if not _CARD_PATH.exists():
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"card not found at {_CARD_PATH}",
+            )
+        text = _CARD_PATH.read_text()
+        section = (kwargs.get("section") or "all").lower().strip()
+        if section == "all":
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=text,
+                metadata={"path": str(_CARD_PATH), "section": "all"},
+            )
+
+        # Section extraction — find the relevant H2 heading and return
+        # everything until the next H2.
+        section_headings = {
+            "confirm":      "## What I can publicly confirm",
+            "architecture": "## Architecture (publicly known shape)",
+            "training":     "## Caudate training pipeline (general shape)",
+            "capabilities": "## Capabilities at inference",
+            "boundaries":   "## What I cannot honestly tell you",
+        }
+        marker = section_headings.get(section)
+        if not marker:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"unknown section {section!r}",
+            )
+        idx = text.find(marker)
+        if idx < 0:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"section heading not found: {marker!r}",
+            )
+        # Slice from the heading to the next H2 (or end of file)
+        end = text.find("\n## ", idx + len(marker))
+        if end < 0:
+            end = len(text)
+        body = text[idx:end].rstrip()
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=body,
+            metadata={"path": str(_CARD_PATH), "section": section},
+        )

execution/tools/cron_tool.py

@@ -0,0 +1,215 @@
+"""Cron tools — schedule, list, and delete recurring agent prompts.
+
+Three thin wrappers on top of `core/scheduler.py::CronStore`:
+
+  - **`CronCreate`** — register a new recurring prompt.
+  - **`CronList`**   — show all registered jobs (with status).
+  - **`CronDelete`** — remove a job by id.
+
+Schedule syntax (matching `core/scheduler.py::_parse_schedule`):
+
+  - `every 30s` / `every 5m` / `every 2h` / `every 1d`
+  - `daily HH:MM`                  (e.g. `daily 09:30`)
+  - `weekly mon HH:MM`             (mon|tue|wed|thu|fri|sat|sun)
+  - `at YYYY-MM-DD HH:MM`          (one-shot)
+
+Persistence: jobs live in `data/cron.json`. The runtime fires them
+when `cognos cron run` is active (a separate daemon process). These
+tools just manage the registry — they don't fire anything immediately.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+def _store():
+    """Lazy-init the CronStore against the configured data dir."""
+    from pathlib import Path
+    from config import DATA_DIR
+    from core.scheduler import CronStore
+    return CronStore(Path(DATA_DIR) / "cron.json")
+
+
+def _format_job(job) -> str:
+    status = "enabled " if job.enabled else "disabled"
+    nxt = job.next_run or "—"
+    last = job.last_run or "never"
+    return (
+        f"  {job.id}  [{status}]  schedule={job.schedule!r}\n"
+        f"    next:   {nxt}\n"
+        f"    last:   {last}\n"
+        f"    prompt: {job.prompt[:80]}{'…' if len(job.prompt) > 80 else ''}"
+    )
+
+
+class CronCreateTool(BaseTool):
+    mutates = True
+    name = "CronCreate"
+    description = (
+        "Schedule a recurring prompt that Cognos will run automatically "
+        "when the cron daemon is active. Pass a `prompt` (what the agent "
+        "should do each fire) and a `schedule` string. Schedule syntax: "
+        "`every 30s|5m|2h|1d`, `daily HH:MM`, `weekly mon HH:MM`, or "
+        "`at YYYY-MM-DD HH:MM` for one-shot. Returns the new job id. "
+        "Note: the daemon runs separately via `cognos cron run`; this "
+        "tool only registers the job."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "prompt": {
+                    "type": "string",
+                    "description": "What the agent should do each fire (e.g. 'Summarize today's storyboard runs').",
+                },
+                "schedule": {
+                    "type": "string",
+                    "description": (
+                        "When to fire. Examples: 'every 5m', 'daily "
+                        "09:30', 'weekly mon 09:00', 'at 2026-12-25 08:00'."
+                    ),
+                },
+            },
+            "required": ["prompt", "schedule"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        prompt = (kwargs.get("prompt") or "").strip()
+        schedule = (kwargs.get("schedule") or "").strip()
+        if not prompt or not schedule:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`prompt` and `schedule` are both required",
+            )
+        try:
+            store = _store()
+            job = store.add(prompt, schedule)
+        except ValueError as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=(
+                    f"{e}. Valid schedules: 'every 5m', 'daily 09:30', "
+                    "'weekly mon 09:00', 'at YYYY-MM-DD HH:MM'."
+                ),
+            )
+        except Exception as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"failed to create cron job: {e}",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                f"Cron job created.\n"
+                f"  id:        {job.id}\n"
+                f"  schedule:  {job.schedule}\n"
+                f"  next run:  {job.next_run}\n"
+                f"  prompt:    {job.prompt[:100]}"
+            ),
+            metadata={
+                "job_id": job.id,
+                "schedule": job.schedule,
+                "next_run": job.next_run,
+            },
+        )
+
+
+class CronListTool(BaseTool):
+    name = "CronList"
+    description = (
+        "List all registered cron jobs with their schedule, next run "
+        "time, last run time, and the prompt. No arguments. Returns a "
+        "human-readable list; the metadata field has the structured "
+        "version."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {"type": "object", "properties": {}}
+
+    async def execute(self, **_: Any) -> ToolResult:
+        try:
+            jobs = _store().list()
+        except Exception as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"failed to read cron store: {e}",
+            )
+        if not jobs:
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output="No cron jobs registered.",
+                metadata={"jobs": []},
+            )
+        lines = [f"{len(jobs)} cron job(s):", ""]
+        lines.extend(_format_job(j) for j in jobs)
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={
+                "jobs": [
+                    {
+                        "id":       j.id,
+                        "schedule": j.schedule,
+                        "enabled":  j.enabled,
+                        "next_run": j.next_run,
+                        "last_run": j.last_run,
+                        "prompt":   j.prompt,
+                    }
+                    for j in jobs
+                ],
+            },
+        )
+
+
+class CronDeleteTool(BaseTool):
+    mutates = True
+    name = "CronDelete"
+    description = (
+        "Delete a cron job by its id. Use `CronList` first to find the "
+        "id. Returns success or 'not found'."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "job_id": {
+                    "type": "string",
+                    "description": "Cron job id from CronList.",
+                },
+            },
+            "required": ["job_id"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        job_id = (kwargs.get("job_id") or "").strip()
+        if not job_id:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`job_id` is required",
+            )
+        try:
+            ok = _store().remove(job_id)
+        except Exception as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"failed to delete cron job: {e}",
+            )
+        if not ok:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"no cron job with id {job_id!r}",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=f"Deleted cron job {job_id}.",
+            metadata={"job_id": job_id},
+        )