caudate-cli 0.1.0__py3-none-any.whl

core/file_refs.py

@@ -0,0 +1,119 @@
+"""@file references — inline or attach files mentioned in user prompts.
+
+Two modes, picked per call site:
+
+  1. **Inline** (default for short prompts) — the file is read and pasted
+     into the message inside a fenced code block. Preserves the user's
+     literal text but expands the @path token to file contents.
+
+  2. **Attach** (when `file_store` is provided) — the file is uploaded
+     to the FileStore and the @path token is replaced with a small
+     `[file:<id>]` marker. The returned attachment list goes through
+     the same multimodal path as `chat(attachments=...)` so PDFs and
+     images work end-to-end.
+
+Tokens follow this grammar:
+  - `@path/to/file.py`              — relative or absolute, no spaces
+  - `@"path with spaces.txt"`        — quoted form for paths with spaces
+  - `@./local.md`, `@~/home.md`      — both supported
+
+Globs (`@src/**/*.py`) are NOT auto-expanded — too easy to flood the
+context window. The user can use the Glob tool if they need that.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# Match either `@"quoted path"` or `@unquoted_path`. The unquoted form
+# stops at whitespace; we strip a trailing punctuation char (.,;:!?) so
+# `@README.md.` resolves to README.md without the trailing period.
+_REF_RE = re.compile(
+    r'@(?:"([^"]+)"|([^\s"]+))'
+)
+_TRAILING_PUNCT = ".,;:!?)]}"
+
+
+def find_refs(text: str) -> list[str]:
+    """Return all @-referenced paths in `text`, preserving order, deduped."""
+    seen: dict[str, None] = {}
+    for match in _REF_RE.finditer(text):
+        raw = match.group(1) or match.group(2) or ""
+        if not match.group(1):
+            while raw and raw[-1] in _TRAILING_PUNCT:
+                raw = raw[:-1]
+        if raw:
+            seen.setdefault(raw, None)
+    return list(seen.keys())
+
+
+def _resolve(path_str: str) -> Path | None:
+    p = Path(path_str).expanduser()
+    if not p.is_absolute():
+        p = Path.cwd() / p
+    return p if p.exists() and p.is_file() else None
+
+
+def expand_inline(text: str, max_chars_per_file: int = 8000) -> str:
+    """Replace each @path with the file's contents in a fenced block."""
+    def _sub(match: re.Match) -> str:
+        raw = match.group(1) or match.group(2) or ""
+        trailing = ""
+        if not match.group(1):
+            while raw and raw[-1] in _TRAILING_PUNCT:
+                trailing = raw[-1] + trailing
+                raw = raw[:-1]
+        path = _resolve(raw)
+        if path is None:
+            return match.group(0)  # leave the original token in place
+        try:
+            content = path.read_text(errors="ignore")
+        except Exception as e:
+            logger.debug(f"@file read failed for {path}: {e}")
+            return match.group(0)
+        truncated = content[:max_chars_per_file]
+        suffix = ""
+        if len(content) > max_chars_per_file:
+            suffix = f"\n... (truncated at {max_chars_per_file} chars)"
+        lang = path.suffix.lstrip(".") or ""
+        return f"\n\n```{lang} {raw}\n{truncated}{suffix}\n```\n" + trailing
+    return _REF_RE.sub(_sub, text)
+
+
+def expand_with_attachments(
+    text: str,
+    file_store: Any,
+) -> tuple[str, list[str]]:
+    """Upload each @path to `file_store` and replace with [file:<id>] markers.
+
+    Returns (rewritten_text, [file_id, ...]). The returned list is
+    intended to be passed straight to `agent.chat(..., attachments=...)`.
+    """
+    attachments: list[str] = []
+
+    def _sub(match: re.Match) -> str:
+        raw = match.group(1) or match.group(2) or ""
+        trailing = ""
+        if not match.group(1):
+            while raw and raw[-1] in _TRAILING_PUNCT:
+                trailing = raw[-1] + trailing
+                raw = raw[:-1]
+        path = _resolve(raw)
+        if path is None:
+            return match.group(0)
+        try:
+            record = file_store.upload(path, filename=path.name)
+        except Exception as e:
+            logger.debug(f"@file upload failed for {path}: {e}")
+            return match.group(0)
+        attachments.append(record.id)
+        return f"[file:{record.id} {path.name}]" + trailing
+
+    rewritten = _REF_RE.sub(_sub, text)
+    return rewritten, attachments

core/files.py

@@ -0,0 +1,199 @@
+"""Files API — store, reference, and extract content from uploaded files.
+
+Local equivalent of Anthropic's Files API. A file is registered in the
+FileStore (copied to `data/files/`), gets a stable `file_id`, and can be
+referenced in subsequent `chat()` calls. At LLM call time, the attachment
+is materialized:
+
+  - PDFs  → text extraction via pypdf, prepended as a block
+  - Text  → read as UTF-8, prepended as a block
+  - Images → base64-encoded into a multimodal content block (the model must
+             be vision-capable, else the image is represented as a path ref)
+
+The store is intentionally simple — flat directory, JSON manifest. No
+multi-tenancy, no TTL, no cleanup job. Delete the file to remove it.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import mimetypes
+import shutil
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+# Kinds the store recognizes. Anything else is "binary" and rendered as a
+# file-path reference (agents can still `Read` or run tools against it).
+KIND_TEXT = "text"
+KIND_PDF = "pdf"
+KIND_IMAGE = "image"
+KIND_AUDIO = "audio"
+KIND_BINARY = "binary"
+
+
+IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"}
+TEXT_EXTS = {".txt", ".md", ".py", ".js", ".ts", ".json", ".yaml", ".yml",
+             ".toml", ".csv", ".html", ".xml", ".rst", ".log"}
+AUDIO_EXTS = {".wav", ".mp3", ".ogg", ".flac", ".m4a"}
+
+
+def _classify(path: Path) -> str:
+    ext = path.suffix.lower()
+    if ext == ".pdf":
+        return KIND_PDF
+    if ext in IMAGE_EXTS:
+        return KIND_IMAGE
+    if ext in AUDIO_EXTS:
+        return KIND_AUDIO
+    if ext in TEXT_EXTS:
+        return KIND_TEXT
+    return KIND_BINARY
+
+
+class FileRecord(BaseModel):
+    id: str
+    filename: str
+    path: str  # absolute path under FILES_DIR
+    kind: str
+    mime_type: str = ""
+    size_bytes: int = 0
+    sha256: str = ""
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class FileStore:
+    """Local file store with stable IDs and a manifest."""
+
+    def __init__(self, root: Path):
+        self.root = root
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._manifest_path = self.root / "manifest.json"
+        self._records: dict[str, FileRecord] = {}
+        self._load()
+
+    # ------------------------------------------------------------------
+    # CRUD
+    # ------------------------------------------------------------------
+
+    def upload(self, source_path: Path, filename: str | None = None) -> FileRecord:
+        """Copy a file into the store, return its FileRecord."""
+        src = Path(source_path).expanduser().resolve()
+        if not src.exists() or not src.is_file():
+            raise FileNotFoundError(f"Not a file: {src}")
+
+        name = filename or src.name
+        file_id = str(uuid.uuid4())
+        dest = self.root / f"{file_id}{src.suffix}"
+        shutil.copy2(src, dest)
+
+        data = dest.read_bytes()
+        record = FileRecord(
+            id=file_id,
+            filename=name,
+            path=str(dest),
+            kind=_classify(dest),
+            mime_type=mimetypes.guess_type(src.name)[0] or "application/octet-stream",
+            size_bytes=len(data),
+            sha256=hashlib.sha256(data).hexdigest(),
+        )
+        self._records[file_id] = record
+        self._save()
+        logger.info(f"FileStore upload: {name} ({record.kind}, {record.size_bytes}B) → {file_id}")
+        return record
+
+    def get(self, file_id: str) -> FileRecord | None:
+        return self._records.get(file_id)
+
+    def delete(self, file_id: str) -> bool:
+        rec = self._records.pop(file_id, None)
+        if rec is None:
+            return False
+        Path(rec.path).unlink(missing_ok=True)
+        self._save()
+        return True
+
+    def list(self) -> list[FileRecord]:
+        return sorted(self._records.values(), key=lambda r: r.created_at, reverse=True)
+
+    # ------------------------------------------------------------------
+    # Content extraction
+    # ------------------------------------------------------------------
+
+    def extract_text(self, file_id: str, max_chars: int = 100_000) -> str:
+        """Return the textual content of a file (empty string for images etc.)."""
+        rec = self.get(file_id)
+        if rec is None:
+            return ""
+        path = Path(rec.path)
+
+        if rec.kind == KIND_TEXT:
+            return path.read_text(errors="ignore")[:max_chars]
+
+        if rec.kind == KIND_PDF:
+            try:
+                import pypdf
+            except ImportError:
+                logger.warning("pypdf not installed — PDF extraction unavailable")
+                return f"[PDF file at {path} — install pypdf to extract text]"
+            try:
+                reader = pypdf.PdfReader(str(path))
+                pages = [p.extract_text() or "" for p in reader.pages]
+                text = "\n\n".join(pages)
+                return text[:max_chars]
+            except Exception as e:
+                logger.warning(f"PDF extraction failed for {path}: {e}")
+                return f"[PDF extraction failed: {e}]"
+
+        return ""  # images/audio/binary handled separately
+
+    def to_image_content(self, file_id: str) -> dict[str, Any] | None:
+        """Return a multimodal image content block ready for a chat message.
+
+        Shape matches OpenAI/LiteLLM multimodal format; Anthropic receives
+        equivalent via LiteLLM translation.
+        """
+        rec = self.get(file_id)
+        if rec is None or rec.kind != KIND_IMAGE:
+            return None
+        data = Path(rec.path).read_bytes()
+        b64 = base64.b64encode(data).decode("ascii")
+        return {
+            "type": "image_url",
+            "image_url": {
+                "url": f"data:{rec.mime_type};base64,{b64}",
+            },
+        }
+
+    # ------------------------------------------------------------------
+    # Manifest persistence
+    # ------------------------------------------------------------------
+
+    def _load(self) -> None:
+        if not self._manifest_path.exists():
+            return
+        try:
+            raw = json.loads(self._manifest_path.read_text())
+        except Exception as e:
+            logger.warning(f"Failed to load file manifest: {e}")
+            return
+        for entry in raw.get("files", []):
+            try:
+                rec = FileRecord.model_validate(entry)
+                self._records[rec.id] = rec
+            except Exception as e:
+                logger.debug(f"Skipping bad manifest entry {entry}: {e}")
+
+    def _save(self) -> None:
+        payload = {"files": [r.model_dump(mode="json") for r in self._records.values()]}
+        self._manifest_path.write_text(json.dumps(payload, indent=2, default=str))

core/hooks.py

@@ -0,0 +1,209 @@
+"""Hooks system — event-driven extensibility for the agentic loop.
+
+Events are fired at key points in the loop (see HookEvent). Each event can
+have zero or more handlers. Handlers are either Python callables or shell
+commands loaded from a JSON config file.
+
+Handler signature: async def handler(event: str, payload: dict) -> dict | None
+  - Return a dict with "block": True to short-circuit (e.g. PRE_TOOL_USE)
+  - Return a dict with "modified_args": {...} to mutate tool args (PRE_TOOL_USE)
+  - Return None for pure side-effect handlers (logging, audit, etc.)
+
+Shell-command handlers receive the payload via stdin as JSON and may emit
+the same response dict as JSON on stdout.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from enum import Enum
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class HookEvent(str, Enum):
+    PRE_TOOL_USE = "pre_tool_use"
+    POST_TOOL_USE = "post_tool_use"
+    POST_TOOL_USE_FAILURE = "post_tool_use_failure"
+    USER_PROMPT_SUBMIT = "user_prompt_submit"
+    STOP = "stop"
+    SUBAGENT_START = "subagent_start"
+    SUBAGENT_STOP = "subagent_stop"
+    PRE_COMPACT = "pre_compact"
+    NOTIFICATION = "notification"
+
+
+HookHandler = Callable[[str, dict[str, Any]], Awaitable[dict[str, Any] | None] | dict[str, Any] | None]
+
+
+class HookMatcher:
+    """A matcher selects which tool/payloads a handler fires on."""
+
+    def __init__(
+        self,
+        tool: str | None = None,
+        pattern: str | None = None,
+    ):
+        self.tool = tool
+        self.pattern = re.compile(pattern) if pattern else None
+
+    def matches(self, payload: dict[str, Any]) -> bool:
+        if self.tool:
+            tool = payload.get("tool") or payload.get("tool_name")
+            if tool != self.tool and self.tool != "*":
+                return False
+        if self.pattern:
+            try:
+                serialized = json.dumps(payload, ensure_ascii=False, default=str)
+            except Exception:
+                serialized = str(payload)
+            return bool(self.pattern.search(serialized))
+        return True
+
+
+class HookManager:
+    """Registers and dispatches hook handlers."""
+
+    def __init__(self):
+        self._handlers: dict[HookEvent, list[tuple[HookMatcher, HookHandler]]] = {
+            e: [] for e in HookEvent
+        }
+
+    def register(
+        self,
+        event: HookEvent,
+        handler: HookHandler,
+        matcher: HookMatcher | None = None,
+    ) -> None:
+        """Register a handler for an event."""
+        self._handlers[event].append((matcher or HookMatcher(), handler))
+
+    def register_shell(
+        self,
+        event: HookEvent,
+        command: str,
+        matcher: HookMatcher | None = None,
+    ) -> None:
+        """Register a shell command as a hook handler."""
+        async def _shell_handler(evt: str, payload: dict[str, Any]):
+            return await _run_shell_hook(command, evt, payload)
+
+        self.register(event, _shell_handler, matcher)
+
+    async def emit(self, event: HookEvent, payload: dict[str, Any]) -> dict[str, Any]:
+        """Fire all handlers for an event. Returns the aggregated response dict.
+
+        If any handler returns {"block": True}, subsequent handlers still run
+        (for audit), but the combined response will preserve block=True.
+        If any handler returns {"modified_args": ...}, the latest such value
+        wins (later handlers override earlier ones).
+        """
+        combined: dict[str, Any] = {}
+        for matcher, handler in self._handlers.get(event, []):
+            if not matcher.matches(payload):
+                continue
+            try:
+                result = handler(event.value, payload)
+                if asyncio.iscoroutine(result):
+                    result = await result
+            except Exception as e:
+                logger.warning(f"Hook {event.value} handler failed: {e}")
+                continue
+            if isinstance(result, dict):
+                if result.get("block"):
+                    combined["block"] = True
+                    if "reason" in result:
+                        combined["reason"] = result["reason"]
+                if "modified_args" in result:
+                    combined["modified_args"] = result["modified_args"]
+        return combined
+
+    # ------------------------------------------------------------------
+    # Config loading
+    # ------------------------------------------------------------------
+
+    def load_from_file(self, path: Path) -> int:
+        """Load hook definitions from a JSON config file. Returns count loaded.
+
+        Format:
+        {
+          "hooks": [
+            {
+              "event": "pre_tool_use",
+              "command": "/path/to/script.sh",
+              "matcher": {"tool": "Bash", "pattern": "rm "}
+            }
+          ]
+        }
+        """
+        if not path.exists():
+            return 0
+        try:
+            data = json.loads(path.read_text())
+        except Exception as e:
+            logger.warning(f"Failed to load hooks from {path}: {e}")
+            return 0
+
+        count = 0
+        for h in data.get("hooks", []):
+            try:
+                event = HookEvent(h["event"])
+            except (KeyError, ValueError):
+                logger.warning(f"Invalid hook event: {h.get('event')}")
+                continue
+            matcher_cfg = h.get("matcher") or {}
+            matcher = HookMatcher(
+                tool=matcher_cfg.get("tool"),
+                pattern=matcher_cfg.get("pattern"),
+            )
+            if "command" in h:
+                self.register_shell(event, h["command"], matcher)
+                count += 1
+            # Python-callable hooks can't be declared in JSON; would require
+            # an import path. For now, only shell hooks are supported via file.
+        return count
+
+
+async def _run_shell_hook(
+    command: str,
+    event: str,
+    payload: dict[str, Any],
+) -> dict[str, Any] | None:
+    """Run a shell hook, piping the payload as JSON on stdin."""
+    try:
+        payload_json = json.dumps({"event": event, **payload}, default=str)
+    except Exception:
+        payload_json = json.dumps({"event": event})
+
+    try:
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await asyncio.wait_for(
+            proc.communicate(payload_json.encode()),
+            timeout=30,
+        )
+    except Exception as e:
+        logger.warning(f"Shell hook {command!r} failed: {e}")
+        return None
+
+    if proc.returncode != 0:
+        logger.debug(f"Shell hook {command!r} exit={proc.returncode}: {stderr.decode(errors='ignore')[:200]}")
+        return None
+
+    out = stdout.decode(errors="ignore").strip()
+    if not out:
+        return None
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError:
+        logger.debug(f"Shell hook {command!r} returned non-JSON output")
+        return None