caudate-cli 0.1.0__py3-none-any.whl

execution/tools/agentic_tool.py

@@ -0,0 +1,297 @@
+"""Agentic — bridge to the Agentic marketplace (https://agentic.so).
+
+Lifts hosted LLM tools from the Agentic platform into Cognos's tool
+palette via plain HTTP — no Node.js bridge, no `@agentic/platform-tool-
+client` dependency, just the same wire protocol the TypeScript SDK
+uses underneath.
+
+Two endpoints (extracted from `@agentic/platform-tool-client/dist/`):
+  - GET  https://api.agentic.so/v1/projects/public/by-identifier
+    Returns the project + its `lastPublishedDeployment.tools` array
+    with name/description/inputSchema for each tool.
+  - POST https://gateway.agentic.so/<deploymentIdentifier>/<toolName>
+    Executes the tool. JSON body in, JSON out.
+
+Auth: optional `Authorization: Bearer <AGENTIC_API_KEY>` from env.
+
+Two Cognos tools ship from this module:
+  - `Agentic`        — execute a tool by (identifier, tool_name, args)
+  - `AgenticBrowse`  — list the tools published in a project
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from typing import Any
+
+import httpx
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+_API_BASE = os.environ.get("AGENTIC_API_BASE", "https://api.agentic.so")
+_GATEWAY_BASE = os.environ.get("AGENTIC_GATEWAY_BASE", "https://gateway.agentic.so")
+_DEFAULT_TIMEOUT_S = 30.0
+_DEPLOYMENT_CACHE_TTL_S = 600.0   # re-fetch deployment metadata every 10 min
+
+
+def _api_key() -> str | None:
+    return os.environ.get("AGENTIC_API_KEY") or None
+
+
+def _auth_headers() -> dict[str, str]:
+    key = _api_key()
+    return {"Authorization": f"Bearer {key}"} if key else {}
+
+
+# ---------------------------------------------------------------------
+# Cached deployment-metadata fetch.
+#
+# `AgenticTool` and `AgenticBrowseTool` share this cache so that two
+# back-to-back calls to e.g. '@agentic/search' don't both hit the
+# /v1/projects/public/by-identifier endpoint.
+# ---------------------------------------------------------------------
+
+_CACHE: dict[str, tuple[float, dict[str, Any]]] = {}
+
+
+async def _resolve_deployment(identifier: str) -> dict[str, Any]:
+    """Look up a project by identifier and return its latest deployment.
+
+    Returns the deployment dict, which has at minimum:
+        - identifier (string, used in the gateway URL)
+        - tools (list of {name, description, inputSchema, ...})
+    """
+    now = time.time()
+    cached = _CACHE.get(identifier)
+    if cached and (now - cached[0]) < _DEPLOYMENT_CACHE_TTL_S:
+        return cached[1]
+
+    url = f"{_API_BASE}/v1/projects/public/by-identifier"
+    params = {
+        "projectIdentifier": identifier,
+        "populate[]":        "lastPublishedDeployment",
+    }
+    async with httpx.AsyncClient(timeout=_DEFAULT_TIMEOUT_S) as client:
+        resp = await client.get(url, params=params, headers=_auth_headers())
+    if resp.status_code == 404:
+        raise ValueError(f"Agentic project not found: {identifier!r}")
+    resp.raise_for_status()
+    project = resp.json()
+    deployment = project.get("lastPublishedDeployment")
+    if not deployment:
+        raise ValueError(
+            f"Agentic project {identifier!r} has no published deployment"
+        )
+    _CACHE[identifier] = (now, deployment)
+    return deployment
+
+
+# ---------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------
+
+
+class AgenticTool(BaseTool):
+    name = "Agentic"
+    description = (
+        "[CURRENTLY DORMANT — agentic.so service is suspended] "
+        "Bridge to the Agentic marketplace. Pass `identifier` "
+        "('@agentic/search'), `tool_name`, and `args`. Calls go to "
+        "https://gateway.agentic.so but that endpoint returns "
+        "'Service Suspended' as of 2026-05-03. Will start working "
+        "again automatically if the service comes back, or set "
+        "AGENTIC_API_BASE/AGENTIC_GATEWAY_BASE env vars to a self-"
+        "hosted compatible gateway. Don't reach for this tool by "
+        "default — use OpenAPI for any REST API instead."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "identifier": {
+                    "type": "string",
+                    "description": "Agentic project identifier, e.g. '@agentic/search'.",
+                },
+                "tool_name": {
+                    "type": "string",
+                    "description": "Name of the specific tool within the project. Use AgenticBrowse to list tools first.",
+                },
+                "args": {
+                    "type": "object",
+                    "description": "Arguments to pass to the tool (JSON object).",
+                },
+                "timeout_s": {
+                    "type": "number",
+                    "description": "Override timeout in seconds (default 30).",
+                },
+            },
+            "required": ["identifier", "tool_name"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        identifier = (kwargs.get("identifier") or "").strip()
+        tool_name = (kwargs.get("tool_name") or "").strip()
+        args = kwargs.get("args") or {}
+        timeout = float(kwargs.get("timeout_s") or _DEFAULT_TIMEOUT_S)
+
+        if not identifier or not tool_name:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`identifier` and `tool_name` are both required",
+            )
+
+        # Resolve deployment + validate the tool exists locally before
+        # we send a request — cheaper to fail early than to get a 404
+        # from the gateway with an opaque message.
+        try:
+            deployment = await _resolve_deployment(identifier)
+        except (httpx.HTTPError, ValueError) as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"resolve failed: {e}",
+            )
+
+        tool_specs = deployment.get("tools") or []
+        names = [t.get("name") for t in tool_specs]
+        if tool_name not in names:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=(f"tool {tool_name!r} not in {identifier!r}; "
+                       f"available: {names}"),
+            )
+
+        deployment_id = (deployment.get("identifier")
+                         or deployment.get("deploymentIdentifier")
+                         or identifier)
+        url = f"{_GATEWAY_BASE}/{deployment_id}/{tool_name}"
+
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                resp = await client.post(
+                    url, json=args, headers=_auth_headers()
+                )
+        except httpx.TimeoutException:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"timed out after {timeout}s calling {tool_name}",
+            )
+        except httpx.RequestError as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"network error: {e}",
+            )
+
+        if resp.status_code >= 400:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=(f"{resp.status_code} from gateway: "
+                       f"{resp.text[:300]}"),
+            )
+
+        # Try to parse JSON, fall back to text
+        ctype = resp.headers.get("content-type", "")
+        if "json" in ctype:
+            try:
+                body = resp.json()
+                output = json.dumps(body, indent=2)
+            except Exception:
+                output = resp.text
+                body = None
+        else:
+            output = resp.text
+            body = None
+
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=output[:4000] + (
+                f"\n\n... ({len(output) - 4000} more chars truncated)"
+                if len(output) > 4000 else ""
+            ),
+            metadata={
+                "identifier":    identifier,
+                "tool_name":     tool_name,
+                "deployment_id": deployment_id,
+                "response":      body,
+            },
+        )
+
+
+class AgenticBrowseTool(BaseTool):
+    name = "AgenticBrowse"
+    description = (
+        "[CURRENTLY DORMANT — agentic.so suspended] List tools in an "
+        "Agentic project. Calls api.agentic.so/v1/projects/public; "
+        "currently returns 'Service Suspended'. Will start working "
+        "again if the service returns, or point AGENTIC_API_BASE at "
+        "a self-hosted gateway."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "identifier": {
+                    "type": "string",
+                    "description": "Agentic project identifier, e.g. '@agentic/search'.",
+                },
+            },
+            "required": ["identifier"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        identifier = (kwargs.get("identifier") or "").strip()
+        if not identifier:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`identifier` is required",
+            )
+
+        try:
+            deployment = await _resolve_deployment(identifier)
+        except (httpx.HTTPError, ValueError) as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"resolve failed: {e}",
+            )
+
+        tool_specs = deployment.get("tools") or []
+        if not tool_specs:
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=f"{identifier}: no tools published",
+                metadata={"identifier": identifier, "tools": []},
+            )
+
+        lines = [f"{identifier} — {len(tool_specs)} tool(s):"]
+        for t in tool_specs:
+            n = t.get("name") or "?"
+            desc = (t.get("description") or "").strip().splitlines()[0:1]
+            desc_line = desc[0] if desc else ""
+            lines.append(f"  - {n}: {desc_line[:160]}")
+            schema = t.get("inputSchema") or {}
+            props = (schema.get("properties") or {})
+            if props:
+                for pn, pdef in list(props.items())[:6]:
+                    ptype = pdef.get("type", "?")
+                    pdesc = (pdef.get("description") or "")[:80]
+                    lines.append(f"      {pn} ({ptype}): {pdesc}")
+
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={
+                "identifier":   identifier,
+                "tools":        tool_specs,
+                "deployment":   deployment.get("identifier"),
+            },
+        )

execution/tools/artifact_tool.py

@@ -0,0 +1,191 @@
+"""Artifact — create an interactive content pane (HTML / SVG / markdown / code).
+
+The LLM uses this when it wants to produce a substantive piece of
+content the user should view as a *thing* rather than as inline chat
+text. Examples: a small standalone web page, a flowchart SVG, a
+multi-paragraph design doc, a self-contained Python module.
+
+How it shows up in the UI:
+  - The tool saves content to FileStore with the right MIME type
+  - Returns a `markdown` field with a link the LLM pastes verbatim
+  - Open WebUI / chat UI renders the link inline:
+      * HTML / SVG / images  → opens in a new tab on click
+      * Markdown / text      → preview shown by the chat client
+      * Code                 → can be downloaded or viewed raw
+
+This is the substrate for "artifact panes." The full Anthropic-style
+side-pane experience requires UI work in the chat client; what we
+ship here is the server side: a clean, addressable URL per artifact
+and a generated markdown link the LLM can echo. The chat client
+decides how to render it.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+# Map artifact kind → file suffix (drives MIME via mimetypes.guess_type)
+_KIND_SUFFIX: dict[str, str] = {
+    "html":     ".html",
+    "svg":      ".svg",
+    "markdown": ".md",
+    "md":       ".md",
+    "json":     ".json",
+    "css":      ".css",
+    "js":       ".js",
+    "javascript": ".js",
+    "python":   ".py",
+    "py":       ".py",
+    "yaml":     ".yaml",
+    "yml":      ".yaml",
+    "xml":      ".xml",
+    "txt":      ".txt",
+    "text":     ".txt",
+}
+
+# Kinds the chat UI tends to render inline as a preview vs. open in
+# a new tab. Used to choose the right markdown shape: image-syntax
+# `![alt](url)` for inline-renderables, link-syntax `[alt](url)` for
+# new-tab-on-click ones.
+_INLINE_RENDER = frozenset({"svg"})
+
+
+def _public_base_url() -> str:
+    return os.environ.get("COGNOS_PUBLIC_URL", "http://127.0.0.1:8000").rstrip("/")
+
+
+class ArtifactTool(BaseTool):
+    mutates = True
+    name = "Artifact"
+    description = (
+        "Create a substantive piece of content the user should view "
+        "as an artifact (a standalone HTML page, SVG diagram, design "
+        "doc, code module, etc.) rather than as inline chat text. "
+        "Returns a `markdown` field — paste it VERBATIM into your "
+        "reply, the chat UI renders it as a link/preview. "
+        "Use this when:\n"
+        "  - The output is >30 lines AND meaningful as a unit\n"
+        "  - The user asks to see something visually (SVG, web page)\n"
+        "  - The output should be saveable / downloadable\n"
+        "Don't use it for short answers, short code snippets, or "
+        "chat-flow text — those go in your reply directly."
+    )
+
+    def __init__(self, file_store: Any | None = None):
+        self._file_store = file_store
+
+    def set_file_store(self, file_store: Any) -> None:
+        self._file_store = file_store
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "kind": {
+                    "type": "string",
+                    "enum": list(_KIND_SUFFIX.keys()),
+                    "description": "Content type — drives the MIME type and how the UI renders it.",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "The artifact body (HTML, SVG, markdown, code, etc.).",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "Short title used as the link label and stored filename.",
+                },
+            },
+            "required": ["kind", "content"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        kind = (kwargs.get("kind") or "").lower().strip()
+        content = kwargs.get("content") or ""
+        title = (kwargs.get("title") or "artifact").strip()
+
+        if kind not in _KIND_SUFFIX:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"unknown kind {kind!r}. supported: "
+                      f"{sorted(_KIND_SUFFIX.keys())}",
+            )
+        if not content.strip():
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="content is empty",
+            )
+        if self._file_store is None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="Artifact tool not wired to a FileStore",
+            )
+
+        suffix = _KIND_SUFFIX[kind]
+
+        # Write content to a tempfile with the right suffix, hand to
+        # FileStore (same pattern Draw uses).
+        try:
+            with tempfile.NamedTemporaryFile(
+                "w", suffix=suffix, delete=False
+            ) as tmp:
+                tmp.write(content)
+                tmp_path = tmp.name
+            # Friendly stored filename — title + suffix, sanitised
+            safe_title = "".join(
+                c if c.isalnum() or c in "-_." else "_" for c in title
+            )[:60] or "artifact"
+            stored_name = f"{safe_title}{suffix}"
+            record = self._file_store.upload(tmp_path, filename=stored_name)
+        except Exception as e:
+            logger.exception("Artifact tool failed")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"failed to store artifact: {e}",
+            )
+
+        # The /artifact/{id} route is the polished viewer (Phase 1 of
+        # COGNOS_UI_ROADMAP.md) — HTML preview / source toggle /
+        # download. Use it for the user-facing link. The raw-bytes
+        # /files/{id}/content URL stays available for inline-image
+        # rendering when the chat UI needs the binary directly.
+        viewer_url = f"{_public_base_url()}/artifact/{record.id}"
+        raw_url = f"{_public_base_url()}/files/{record.id}/content"
+        if kind in _INLINE_RENDER:
+            # Inline-renderables (SVG) use the raw URL so the image
+            # shows directly in chat. Add a viewer link below for
+            # source/download access.
+            markdown = f"![{title}]({raw_url})\n\n[📄 Open in viewer]({viewer_url})"
+        else:
+            markdown = f"[📄 {title}]({viewer_url})"
+        url = viewer_url   # what the metadata reports as the primary URL
+
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                f"Artifact created.\n"
+                f"  kind:     {kind}\n"
+                f"  filename: {record.filename}\n"
+                f"  size:     {record.size_bytes} bytes\n"
+                f"  url:      {url}\n\n"
+                f"Paste the markdown into your reply VERBATIM:\n"
+                f"  {markdown}"
+            ),
+            metadata={
+                "file_id": record.id,
+                "filename": record.filename,
+                "url": url,
+                "markdown": markdown,
+                "kind": kind,
+                "size_bytes": record.size_bytes,
+            },
+        )

execution/tools/ask_user_question_tool.py

@@ -0,0 +1,137 @@
+"""AskUserQuestion — structured disambiguation prompt for the user.
+
+The agent uses this when it needs the user to pick between several
+options before continuing. The tool returns a markdown-formatted
+prompt that the LLM is expected to echo verbatim as its turn-end
+response. The user's next chat reply provides the answer; there's
+no real "blocking wait" because Cognos is chat-driven, not REPL.
+
+Output shape (what the LLM sees back from the tool):
+  ## <question>
+
+  - **A.** <choice 1>
+  - **B.** <choice 2>
+  - **C.** <choice 3>
+
+  *Reply with the letter (or the choice text) to continue.*
+
+Why a dedicated tool instead of just typing the question?
+  1. Gives Caudate a clear "I am asking the user" signal in the
+     replay record so she can learn the disambiguation pattern.
+  2. Standardises the format so the WebUI could later detect the
+     marker and render real radio buttons.
+  3. Keeps the LLM honest: when there are concrete choices, present
+     them — don't ramble open-endedly.
+"""
+
+from __future__ import annotations
+
+import string
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+# Sentinel marker the WebUI / chat-front-end can detect to render a
+# nicer choice picker once that hook is added. Plain text below it
+# stays human-readable in any UI.
+_MARKER = "<!-- cognos:ask_user_question -->"
+
+
+class AskUserQuestionTool(BaseTool):
+    name = "AskUserQuestion"
+    description = (
+        "Ask the user a multiple-choice question to disambiguate "
+        "before proceeding. Provide a clear `question` and 2-6 "
+        "`choices`. The tool returns a markdown prompt the LLM "
+        "should surface verbatim as its turn-end response; the "
+        "user's next reply (a letter A/B/C... or the choice text) "
+        "is the answer. Use this whenever the work depends on a "
+        "decision the user can make in one tap — file path, "
+        "destination, model variant, scope, etc. Don't use it for "
+        "open-ended questions; just ask those directly."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "question": {
+                    "type": "string",
+                    "description": "The question to ask the user. One sentence ideally.",
+                },
+                "choices": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "minItems": 2,
+                    "maxItems": 6,
+                    "description": (
+                        "Between 2 and 6 distinct options. Each is a "
+                        "single phrase or short sentence."
+                    ),
+                },
+                "context": {
+                    "type": "string",
+                    "description": (
+                        "Optional one-line context shown above the "
+                        "question (e.g. why you're asking)."
+                    ),
+                },
+            },
+            "required": ["question", "choices"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        question = (kwargs.get("question") or "").strip()
+        choices = kwargs.get("choices") or []
+        context = (kwargs.get("context") or "").strip()
+
+        if not question:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`question` is required",
+            )
+        if not isinstance(choices, list) or len(choices) < 2:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="provide at least 2 choices",
+            )
+        if len(choices) > 6:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="too many choices (max 6)",
+            )
+
+        clean_choices = [str(c).strip() for c in choices if str(c).strip()]
+        if len(clean_choices) < 2:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="need at least 2 non-empty choices",
+            )
+
+        letters = string.ascii_uppercase[: len(clean_choices)]
+        lines: list[str] = [_MARKER, ""]
+        if context:
+            lines.append(f"_{context}_")
+            lines.append("")
+        lines.append(f"## {question}")
+        lines.append("")
+        for letter, choice in zip(letters, clean_choices):
+            lines.append(f"- **{letter}.** {choice}")
+        lines.append("")
+        lines.append(
+            "*Reply with the letter (or the choice text) to continue.*"
+        )
+
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={
+                "question": question,
+                "choices": clean_choices,
+                "letters": list(letters),
+                "context": context,
+            },
+        )