caudate-cli 0.1.0__py3-none-any.whl

execution/tools/datetime_tool.py

@@ -0,0 +1,215 @@
+"""DateTime — current time, parse, format, relative dates.
+
+LLMs always have a stale "today" because their training cut-off is
+in the past, and even if they hold a notion of "now" it drifts
+through a long conversation. This tool gives them an accurate
+single source of truth for time-related questions.
+
+Modes:
+  - now:     return the current datetime (UTC + local + ISO).
+  - parse:   parse a string into a datetime, return its components.
+  - format:  format a datetime string to a different layout.
+  - delta:   compute time elapsed between two datetimes, OR add/
+             subtract a duration from a base datetime.
+
+Pure stdlib. No timezone DB beyond what Python ships with.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+def _now_block() -> dict[str, str]:
+    now_utc = datetime.now(timezone.utc)
+    now_local = datetime.now().astimezone()
+    return {
+        "iso_utc":   now_utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "iso_local": now_local.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "weekday":   now_local.strftime("%A"),
+        "human":     now_local.strftime("%Y-%m-%d %H:%M:%S %Z"),
+    }
+
+
+def _parse_datetime(s: str) -> datetime:
+    """Best-effort datetime parse. Tries ISO 8601 first, then a few
+    common human formats."""
+    s = s.strip()
+    # ISO 8601 (most common LLM output)
+    try:
+        # Replace trailing Z with +00:00 for fromisoformat
+        return datetime.fromisoformat(s.replace("Z", "+00:00"))
+    except ValueError:
+        pass
+    # Common human formats
+    for fmt in (
+        "%Y-%m-%d %H:%M:%S",
+        "%Y-%m-%d %H:%M",
+        "%Y-%m-%d",
+        "%d/%m/%Y",
+        "%d-%m-%Y",
+        "%m/%d/%Y",
+        "%Y/%m/%d",
+        "%A, %d %B %Y %H:%M:%S",
+    ):
+        try:
+            return datetime.strptime(s, fmt)
+        except ValueError:
+            continue
+    raise ValueError(f"could not parse datetime: {s!r}")
+
+
+def _parse_duration(s: str) -> timedelta:
+    """Parse '3d', '24h', '90m', '60s', or signed combos like '-7d', '+30m'."""
+    s = s.strip().lower()
+    if not s:
+        raise ValueError("empty duration")
+    sign = 1
+    if s[0] in "+-":
+        sign = -1 if s[0] == "-" else 1
+        s = s[1:]
+    if s.endswith("d"):
+        return sign * timedelta(days=float(s[:-1]))
+    if s.endswith("h"):
+        return sign * timedelta(hours=float(s[:-1]))
+    if s.endswith("m"):
+        return sign * timedelta(minutes=float(s[:-1]))
+    if s.endswith("s"):
+        return sign * timedelta(seconds=float(s[:-1]))
+    if s.endswith("w"):
+        return sign * timedelta(weeks=float(s[:-1]))
+    raise ValueError(f"could not parse duration: {s!r}")
+
+
+class DateTimeTool(BaseTool):
+    name = "DateTime"
+    description = (
+        "Authoritative time tool. Use whenever the user asks 'what time "
+        "is it', 'what's today's date', 'how long ago was X', or "
+        "anything time-relative. Modes: 'now' (current time), 'parse' "
+        "(parse a string), 'format' (re-format a date), 'delta' "
+        "(compute elapsed time, or add/subtract duration). "
+        "Don't compute dates in your head — call this; you'll be wrong."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "mode": {
+                    "type": "string",
+                    "enum": ["now", "parse", "format", "delta"],
+                    "description": "What to do.",
+                },
+                "input": {
+                    "type": "string",
+                    "description": "For parse: the date string. For format: the date to re-format. For delta: the base datetime.",
+                },
+                "format": {
+                    "type": "string",
+                    "description": "strftime format for 'format' mode (e.g. '%Y-%m-%d').",
+                },
+                "duration": {
+                    "type": "string",
+                    "description": "For delta mode: a duration like '3d', '-24h', '+90m' to add to `input`.",
+                },
+                "until": {
+                    "type": "string",
+                    "description": "For delta mode: a second datetime to compute (until - input).",
+                },
+            },
+            "required": ["mode"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        mode = (kwargs.get("mode") or "").lower().strip()
+        try:
+            if mode == "now":
+                return ToolResult(
+                    tool_name=self.name, status="success",
+                    output="\n".join(f"{k}: {v}" for k, v in _now_block().items()),
+                    metadata=_now_block(),
+                )
+
+            if mode == "parse":
+                s = kwargs.get("input") or ""
+                dt = _parse_datetime(s)
+                meta = {
+                    "iso":       dt.isoformat(),
+                    "year":      dt.year, "month": dt.month, "day": dt.day,
+                    "hour":      dt.hour, "minute": dt.minute, "second": dt.second,
+                    "weekday":   dt.strftime("%A"),
+                    "tz":        str(dt.tzinfo) if dt.tzinfo else "naive",
+                }
+                return ToolResult(
+                    tool_name=self.name, status="success",
+                    output="\n".join(f"{k}: {v}" for k, v in meta.items()),
+                    metadata=meta,
+                )
+
+            if mode == "format":
+                s = kwargs.get("input") or ""
+                fmt = kwargs.get("format") or "%Y-%m-%d"
+                dt = _parse_datetime(s)
+                formatted = dt.strftime(fmt)
+                return ToolResult(
+                    tool_name=self.name, status="success",
+                    output=formatted,
+                    metadata={"formatted": formatted},
+                )
+
+            if mode == "delta":
+                base = _parse_datetime(kwargs.get("input") or "")
+                # Two sub-modes: until (compute elapsed) OR duration (add/subtract)
+                until = kwargs.get("until")
+                duration = kwargs.get("duration")
+                if until and duration:
+                    return ToolResult(
+                        tool_name=self.name, status="error",
+                        error="provide either 'until' or 'duration', not both",
+                    )
+                if until:
+                    other = _parse_datetime(until)
+                    delta = other - base
+                    return ToolResult(
+                        tool_name=self.name, status="success",
+                        output=f"{base.isoformat()} → {other.isoformat()}: "
+                               f"{delta.total_seconds():.0f}s "
+                               f"({delta.days}d {delta.seconds//3600}h)",
+                        metadata={
+                            "from": base.isoformat(),
+                            "to":   other.isoformat(),
+                            "seconds": delta.total_seconds(),
+                            "days":  delta.days,
+                        },
+                    )
+                if duration:
+                    delta = _parse_duration(duration)
+                    target = base + delta
+                    return ToolResult(
+                        tool_name=self.name, status="success",
+                        output=f"{base.isoformat()} {duration} → {target.isoformat()}",
+                        metadata={"result": target.isoformat()},
+                    )
+                return ToolResult(
+                    tool_name=self.name, status="error",
+                    error="delta mode needs either 'until' or 'duration'",
+                )
+
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"unknown mode {mode!r}; expected now/parse/format/delta",
+            )
+        except Exception as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"{type(e).__name__}: {e}",
+            )

execution/tools/describe_image_tool.py

@@ -0,0 +1,161 @@
+"""DescribeImage — caption / OCR / Q&A about a local image file.
+
+Uses the chat LLM (typically Haiku via system2) with a multimodal
+message — base64-encoded image + a text question. Both Haiku and Opus
+natively support image input via the OpenAI-compat content-blocks
+shape that LiteLLM forwards to Anthropic.
+
+Earlier versions tried to reach into Cognos's `InternVLVisionEncoder`
+for a `.chat()` method that doesn't exist (that encoder only produces
+4096-D embeddings, not natural-language output). This version uses
+the chat LLM the user already has configured — costs a small per-call
+quota burn but works against any multimodal provider.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import mimetypes
+import os
+from pathlib import Path
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+def _guess_mime(path: Path) -> str:
+    mime, _ = mimetypes.guess_type(str(path))
+    if mime and mime.startswith("image/"):
+        return mime
+    suffix = path.suffix.lower().lstrip(".")
+    return f"image/{suffix}" if suffix in ("png", "jpeg", "jpg", "webp", "gif") else "image/png"
+
+
+def _read_settings_model() -> str:
+    """Pick the LLM to ask. Prefer system2 (smarter, multimodal) so
+    the description quality is good. Fall back to system1 or a
+    sensible default."""
+    settings_path = Path.home() / ".cognos" / "settings.json"
+    try:
+        d = json.loads(settings_path.read_text())
+        return (d.get("system2")
+                or d.get("system1")
+                or "anthropic/claude-haiku-4-5")
+    except Exception:
+        return "anthropic/claude-haiku-4-5"
+
+
+class DescribeImageTool(BaseTool):
+    name = "DescribeImage"
+    description = (
+        "Describe / OCR / answer questions about a local image file. "
+        "Supports PNG, JPG, WEBP, GIF. Sends the image to the chat LLM "
+        "(Haiku / Opus / whichever multimodal provider is configured) "
+        "via a multimodal message. Use for screenshots, photos, "
+        "diagrams, OCR-style text extraction, or any 'what does this "
+        "image show?' question. Path must be a local file; use "
+        "WebFetch first if you need to pull a URL."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Path to a local image file (png/jpg/webp/gif/...).",
+                },
+                "prompt": {
+                    "type": "string",
+                    "description": "Optional question or framing (default: 'Describe this image in detail.')",
+                    "default": "Describe this image in detail.",
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Override the LLM model id. Default: settings.json system2.",
+                },
+            },
+            "required": ["path"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        path_str = (kwargs.get("path") or "").strip()
+        prompt = (kwargs.get("prompt") or "Describe this image in detail.").strip()
+        model = (kwargs.get("model") or "").strip() or _read_settings_model()
+
+        path = Path(path_str).expanduser().resolve()
+        if not path.exists() or not path.is_file():
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"image file not found: {path}",
+            )
+
+        # Bound the body — multimodal messages with > a few MB of base64
+        # are wasteful and may hit provider limits.
+        try:
+            raw = path.read_bytes()
+        except OSError as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"failed to read image: {e}",
+            )
+        if len(raw) > 8 * 1024 * 1024:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"image too large ({len(raw)/1024/1024:.1f}MB) "
+                      "— max 8MB; resize first",
+            )
+
+        mime = _guess_mime(path)
+        b64 = base64.b64encode(raw).decode("ascii")
+        data_url = f"data:{mime};base64,{b64}"
+
+        # Build multimodal message — OpenAI-compat content blocks shape
+        # that LiteLLM translates per provider (Anthropic uses its own
+        # `image` block; OpenAI uses `image_url`; the SDK handles both).
+        messages = [{
+            "role": "user",
+            "content": [
+                {"type": "text", "text": prompt},
+                {"type": "image_url", "image_url": {"url": data_url}},
+            ],
+        }]
+
+        try:
+            from llm.provider import LLMProvider
+            from core.anthropic_auth import subscription_auth_scope
+            llm = LLMProvider(model=model)
+            # Subscription-auth scope so anthropic/* models work without
+            # an API key (mirrors the chat path's behavior).
+            with subscription_auth_scope():
+                resp = await llm.chat(messages=messages, max_tokens=2048)
+        except Exception as e:
+            logger.exception("DescribeImage LLM call failed")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"LLM call failed: {e}",
+            )
+
+        description = (resp.content or "").strip()
+        if not description:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="LLM returned empty content",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=description,
+            metadata={
+                "path": str(path),
+                "mime": mime,
+                "size_bytes": len(raw),
+                "model": model,
+                "prompt": prompt,
+            },
+        )

execution/tools/draw_tool.py

@@ -0,0 +1,164 @@
+"""Draw tool — generate an image from a text prompt.
+
+The agent calls `Draw(prompt=..., size=...)`, the tool runs the
+configured image-gen backend, persists the result via FileStore, and
+returns a markdown image link the agent can paste directly into the
+chat reply so the user's UI (Open WebUI / Claude Code) renders the
+image inline.
+
+Backends:
+  - "diffusers" (default, local)
+  - "comfyui" (HTTP proxy)
+  - "litellm" (cloud)
+
+Backend choice + model id come from settings (`image.backend`,
+`image.model`) so a project can override the default without touching
+code. Backend instances are cached per-tool so the diffusers pipeline
+loads once and stays in VRAM.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from core.image import ImageGen, generate_to_file_store, make_image_gen
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+def _public_base_url() -> str:
+    """Where files served at /files/{id}/content are reachable from.
+
+    Defaults to http://127.0.0.1:8000 (same-host browser). Override via
+    COGNOS_PUBLIC_URL when Cognos is being accessed remotely (mobile,
+    LAN), so generated images render in the remote browser too.
+    """
+    return os.environ.get("COGNOS_PUBLIC_URL", "http://127.0.0.1:8000").rstrip("/")
+
+
+class DrawTool(BaseTool):
+    mutates = True
+    name = "Draw"
+    description = (
+        "Generate an image from a text description. Use when the user "
+        "asks for a drawing, illustration, diagram, picture, or visual "
+        "concept. The tool returns a `markdown` field — copy that "
+        "string VERBATIM into your reply (looks like "
+        "`![alt](http://.../files/<id>/content)`) so the user's chat "
+        "UI renders the image inline. Be specific in the prompt: "
+        "subject, composition, style (e.g. 'watercolor', 'pixel art', "
+        "'photorealistic'), lighting, mood. Don't include text-in-"
+        "image instructions; image models render text poorly."
+    )
+
+    def __init__(
+        self,
+        file_store: Any | None = None,
+        backend: str = "diffusers",
+        backend_kwargs: dict | None = None,
+    ):
+        self._file_store = file_store
+        self._backend_name = backend
+        self._backend_kwargs = backend_kwargs or {}
+        self._backend: ImageGen | None = None
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "prompt": {
+                    "type": "string",
+                    "description": "Text description of the image to generate.",
+                },
+                "size": {
+                    "type": "string",
+                    "description": "Pixel dimensions. Common: 1024x1024 (square), 1024x768 (4:3), 768x1024 (3:4), 1280x720 (16:9). Default 1024x1024.",
+                    "default": "1024x1024",
+                },
+                "negative_prompt": {
+                    "type": "string",
+                    "description": "Things to avoid (e.g. 'blurry, deformed, text'). Optional.",
+                },
+                "seed": {
+                    "type": "integer",
+                    "description": "Random seed for reproducibility. Omit for random.",
+                },
+                "steps": {
+                    "type": "integer",
+                    "description": "Inference steps. Defaults vary by model; only set if you know the model.",
+                },
+                "style": {
+                    "type": "string",
+                    "description": "Optional style hint, prepended to the prompt (e.g. 'watercolor', 'photorealistic', 'oil painting').",
+                },
+            },
+            "required": ["prompt"],
+        }
+
+    def set_file_store(self, file_store: Any) -> None:
+        self._file_store = file_store
+
+    def _get_backend(self) -> ImageGen:
+        if self._backend is None:
+            self._backend = make_image_gen(self._backend_name, **self._backend_kwargs)
+        return self._backend
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        prompt = (kwargs.get("prompt") or "").strip()
+        if not prompt:
+            return self._error("No prompt provided")
+        if self._file_store is None:
+            return self._error("Draw is not wired to a FileStore. Configure one on the tool.")
+
+        size = kwargs.get("size") or "1024x1024"
+        style = (kwargs.get("style") or "").strip()
+        if style:
+            prompt = f"{style}, {prompt}"
+
+        gen_kwargs: dict[str, Any] = {}
+        if "negative_prompt" in kwargs and kwargs["negative_prompt"]:
+            gen_kwargs["negative_prompt"] = kwargs["negative_prompt"]
+        if kwargs.get("seed") is not None:
+            gen_kwargs["seed"] = int(kwargs["seed"])
+        if kwargs.get("steps") is not None:
+            gen_kwargs["steps"] = int(kwargs["steps"])
+
+        try:
+            backend = self._get_backend()
+            record = await generate_to_file_store(
+                backend, self._file_store, prompt, size=size, **gen_kwargs,
+            )
+        except Exception as e:
+            logger.exception("Draw failed")
+            return self._error(f"Image generation failed: {e}")
+
+        # Build URLs:
+        #  - raw bytes URL drives the inline `![alt](url)` markdown so
+        #    chat UIs render the image directly in the conversation
+        #  - viewer URL (Phase 1 of COGNOS_UI_ROADMAP.md) gives a
+        #    polished standalone page with download + larger view
+        url = f"{_public_base_url()}/files/{record.id}/content"
+        viewer_url = f"{_public_base_url()}/artifact/{record.id}"
+        alt = (prompt or record.filename)[:120].replace("]", "")
+        # Inline image first (so it shows in chat), then a small
+        # "open in viewer" link for download / full-size.
+        markdown = f"![{alt}]({url})\n\n[📄 Open in viewer]({viewer_url})"
+
+        return self._success({
+            "file_id": record.id,
+            "filename": record.filename,
+            "path": record.path,
+            "url": url,
+            "markdown": markdown,
+            "size_bytes": record.size_bytes,
+            "kind": record.kind,
+            "note": (
+                "Image generated. Paste the `markdown` field above into "
+                "your reply VERBATIM — the chat UI will render it inline."
+            ),
+        })