agent-cli 0.70.5__py3-none-any.whl

agent_cli/install/extras.py

@@ -0,0 +1,174 @@
+"""Install optional extras at runtime with pinned versions."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import tomllib
+from importlib.metadata import version as get_version
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agent_cli.cli import app
+from agent_cli.core.deps import EXTRAS as _EXTRAS_META
+from agent_cli.core.utils import console, print_error_message
+
+# Extract descriptions from the centralized EXTRAS metadata
+EXTRAS: dict[str, str] = {name: desc for name, (desc, _) in _EXTRAS_META.items()}
+
+
+def _requirements_dir() -> Path:
+    return Path(__file__).parent.parent / "_requirements"
+
+
+def _available_extras() -> list[str]:
+    """List available extras based on requirements files."""
+    req_dir = _requirements_dir()
+    if not req_dir.exists():
+        return []
+    return sorted(p.stem for p in req_dir.glob("*.txt"))
+
+
+def _requirements_path(extra: str) -> Path:
+    return _requirements_dir() / f"{extra}.txt"
+
+
+def _in_virtualenv() -> bool:
+    """Check if running inside a virtual environment."""
+    return sys.prefix != sys.base_prefix
+
+
+def _is_uv_tool_install() -> bool:
+    """Check if running from a uv tool environment."""
+    receipt = Path(sys.prefix) / "uv-receipt.toml"
+    return receipt.exists()
+
+
+def _get_current_uv_tool_extras() -> list[str]:
+    """Get extras currently configured in uv-receipt.toml."""
+    receipt = Path(sys.prefix) / "uv-receipt.toml"
+    if not receipt.exists():
+        return []
+    data = tomllib.loads(receipt.read_text())
+    requirements = data.get("tool", {}).get("requirements", [])
+    for req in requirements:
+        if req.get("name") == "agent-cli":
+            return req.get("extras", [])
+    return []
+
+
+def _install_via_uv_tool(extras: list[str], *, quiet: bool = False) -> bool:
+    """Reinstall agent-cli via uv tool with the specified extras."""
+    current_version = get_version("agent-cli").split("+")[0]  # Strip local version
+    extras_str = ",".join(extras)
+    package_spec = f"agent-cli[{extras_str}]=={current_version}"
+    python_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    cmd = ["uv", "tool", "install", package_spec, "--force", "--python", python_version]
+    if quiet:
+        cmd.append("-q")
+    console.print(f"Running: [cyan]{' '.join(cmd)}[/]")
+    result = subprocess.run(cmd, check=False)
+    return result.returncode == 0
+
+
+def _install_cmd() -> list[str]:
+    """Build the install command with appropriate flags."""
+    in_venv = _in_virtualenv()
+    if shutil.which("uv"):
+        cmd = ["uv", "pip", "install", "--python", sys.executable]
+        if not in_venv:
+            # Allow installing to system Python when not in a venv
+            cmd.append("--system")
+        return cmd
+    cmd = [sys.executable, "-m", "pip", "install"]
+    if not in_venv:
+        # Install to user site-packages when not in a venv
+        cmd.append("--user")
+    return cmd
+
+
+def _install_extras_impl(extras: list[str], *, quiet: bool = False) -> bool:
+    """Install extras. Returns True on success, False on failure."""
+    if _is_uv_tool_install():
+        current_extras = _get_current_uv_tool_extras()
+        new_extras = sorted(set(current_extras) | set(extras))
+        return _install_via_uv_tool(new_extras, quiet=quiet)
+
+    cmd = _install_cmd()
+    for extra in extras:
+        req_file = _requirements_path(extra)
+        if not quiet:
+            console.print(f"Installing [cyan]{extra}[/]...")
+        result = subprocess.run(
+            [*cmd, "-r", str(req_file)],
+            check=False,
+            capture_output=quiet,
+        )
+        if result.returncode != 0:
+            return False
+    return True
+
+
+def install_extras_programmatic(extras: list[str], *, quiet: bool = False) -> bool:
+    """Install extras programmatically (for auto-install feature)."""
+    available = _available_extras()
+    valid = [e for e in extras if e in available]
+    invalid = [e for e in extras if e not in available]
+    if invalid:
+        console.print(f"[yellow]Unknown extras (skipped): {', '.join(invalid)}[/]")
+    return bool(valid) and _install_extras_impl(valid, quiet=quiet)
+
+
+@app.command("install-extras", rich_help_panel="Installation", no_args_is_help=True)
+def install_extras(
+    extras: Annotated[list[str] | None, typer.Argument(help="Extras to install")] = None,
+    list_extras: Annotated[
+        bool,
+        typer.Option("--list", "-l", help="List available extras"),
+    ] = False,
+    all_extras: Annotated[
+        bool,
+        typer.Option("--all", "-a", help="Install all available extras"),
+    ] = False,
+) -> None:
+    """Install optional extras (rag, memory, vad, etc.) with pinned versions.
+
+    Examples:
+        - `agent-cli install-extras rag`           # Install RAG dependencies
+        - `agent-cli install-extras memory vad`    # Install multiple extras
+        - `agent-cli install-extras --list`        # Show available extras
+        - `agent-cli install-extras --all`         # Install all extras
+
+    """
+    available = _available_extras()
+
+    if list_extras:
+        console.print("[bold]Available extras:[/]")
+        for name in available:
+            desc = EXTRAS.get(name, "")
+            console.print(f"  [cyan]{name}[/]: {desc}")
+        return
+
+    if all_extras:
+        extras = available
+
+    if not extras:
+        print_error_message("No extras specified. Use --list to see available, or --all.")
+        raise typer.Exit(1)
+
+    invalid = [e for e in extras if e not in available]
+    if invalid:
+        print_error_message(f"Unknown extras: {invalid}. Use --list to see available.")
+        raise typer.Exit(1)
+
+    if not _install_extras_impl(extras):
+        print_error_message("Failed to install extras")
+        raise typer.Exit(1)
+
+    if _is_uv_tool_install():
+        console.print("[green]Done! Extras will persist across uv tool upgrade.[/]")
+    else:
+        console.print("[green]Done![/]")

agent_cli/install/hotkeys.py

@@ -0,0 +1,48 @@
+"""Hotkey installation commands."""
+
+from __future__ import annotations
+
+import platform
+
+from agent_cli.cli import app
+from agent_cli.core.utils import print_with_style
+from agent_cli.install.common import execute_installation_script, get_platform_script
+
+
+@app.command("install-hotkeys", rich_help_panel="Installation")
+def install_hotkeys() -> None:
+    """Install system-wide hotkeys for agent-cli commands.
+
+    Sets up the following hotkeys:
+
+    macOS:
+    - Cmd+Shift+R: Toggle voice transcription
+    - Cmd+Shift+A: Autocorrect clipboard text
+    - Cmd+Shift+V: Voice edit clipboard text
+
+    Linux:
+    - Super+Shift+R: Toggle voice transcription
+    - Super+Shift+A: Autocorrect clipboard text
+    - Super+Shift+V: Voice edit clipboard text
+
+    Note: On macOS, you may need to grant Accessibility permissions to skhd
+    in System Settings → Privacy & Security → Accessibility.
+    """
+    script_name = get_platform_script("setup-macos-hotkeys.sh", "setup-linux-hotkeys.sh")
+    system = platform.system().lower()
+
+    execute_installation_script(
+        script_name=script_name,
+        operation_name="Set up hotkeys",
+        success_message="Hotkeys installed successfully!",
+    )
+
+    # Post-installation steps for macOS
+    if system == "darwin":
+        print_with_style("\n⚠️  Important:", "yellow")
+        print_with_style("If hotkeys don't work, grant Accessibility permissions:", "yellow")
+        print_with_style(
+            "  1. Open System Settings → Privacy & Security → Accessibility",
+            "cyan",
+        )
+        print_with_style("  2. Add and enable 'skhd'", "cyan")

agent_cli/install/services.py

@@ -0,0 +1,87 @@
+"""Service installation and management commands."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+import typer
+
+from agent_cli.cli import app
+from agent_cli.core.utils import console, print_error_message, print_with_style
+from agent_cli.install.common import (
+    execute_installation_script,
+    get_platform_script,
+    get_script_path,
+)
+
+
+@app.command("install-services", rich_help_panel="Installation")
+def install_services() -> None:
+    """Install all required services (Ollama, Whisper, Piper, OpenWakeWord).
+
+    This command installs:
+    - Ollama (local LLM server)
+    - Wyoming Faster Whisper (speech-to-text)
+    - Wyoming Piper (text-to-speech)
+    - Wyoming OpenWakeWord (wake word detection)
+
+    The appropriate installation method is used based on your operating system.
+    """
+    script_name = get_platform_script("setup-macos.sh", "setup-linux.sh")
+
+    execute_installation_script(
+        script_name=script_name,
+        operation_name="Install services",
+        success_message="Services installed successfully!",
+        next_steps=[
+            "Start services: agent-cli start-services",
+            "Set up hotkeys: agent-cli install-hotkeys",
+        ],
+    )
+
+
+@app.command("start-services", rich_help_panel="Service Management")
+def start_services(
+    attach: bool = typer.Option(
+        True,  # noqa: FBT003
+        "--attach/--no-attach",
+        help="Attach to Zellij session after starting",
+    ),
+) -> None:
+    """Start all agent-cli services in a Zellij session.
+
+    This starts:
+    - Ollama (LLM server)
+    - Wyoming Faster Whisper (speech-to-text)
+    - Wyoming Piper (text-to-speech)
+    - Wyoming OpenWakeWord (wake word detection)
+
+    Services run in a Zellij terminal multiplexer session named 'agent-cli'.
+    Use Ctrl-Q to quit or Ctrl-O d to detach from the session.
+    """
+    try:
+        script_path = get_script_path("start-all-services.sh")
+    except FileNotFoundError as e:
+        print_error_message("Service scripts not found")
+        console.print(str(e))
+        raise typer.Exit(1) from None
+
+    env = os.environ.copy()
+    if not attach:
+        env["AGENT_CLI_NO_ATTACH"] = "true"
+
+    try:
+        subprocess.run([str(script_path)], check=True, env=env)
+        if not attach:
+            print_with_style("✅ Services started in background.", "green")
+            print_with_style("Run 'zellij attach agent-cli' to view the session.", "yellow")
+        else:
+            # If we get here with attach=True, user likely detached
+            print_with_style("\n👋 Detached from Zellij session.")
+            print_with_style(
+                "Services are still running. Use 'zellij attach agent-cli' to reattach.",
+            )
+    except subprocess.CalledProcessError as e:
+        print_error_message(f"Failed to start services. Exit code: {e.returncode}")
+        raise typer.Exit(e.returncode) from None

agent_cli/memory/__init__.py

@@ -0,0 +1,7 @@
+"""Memory module for long-term chat history."""
+
+from __future__ import annotations
+
+from agent_cli.memory.client import MemoryClient
+
+__all__ = ["MemoryClient"]

agent_cli/memory/_files.py

@@ -0,0 +1,250 @@
+"""File-backed memory helpers."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from pydantic import ValidationError
+
+from agent_cli.core.utils import atomic_write_text
+from agent_cli.memory.models import MemoryMetadata
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+LOGGER = logging.getLogger(__name__)
+
+_ENTRIES_DIRNAME = "entries"
+_SNAPSHOT_FILENAME = "memory_index.json"
+_DELETED_DIRNAME = "deleted"
+
+
+@dataclass
+class MemoryFileRecord:
+    """Materialized memory file on disk."""
+
+    id: str
+    path: Path
+    metadata: MemoryMetadata
+    content: str
+
+
+def ensure_store_dirs(root: Path) -> tuple[Path, Path]:
+    """Ensure base folders exist and return (entries_dir, snapshot_path)."""
+    entries_dir = root / _ENTRIES_DIRNAME
+    entries_dir.mkdir(parents=True, exist_ok=True)
+    snapshot_path = root / _SNAPSHOT_FILENAME
+    return entries_dir, snapshot_path
+
+
+def _safe_timestamp(value: str) -> str:
+    """Return a filesystem-safe timestamp-ish token."""
+    return "".join(ch if ch.isalnum() or ch in "-._" else "-" for ch in value) or "ts"
+
+
+def soft_delete_memory_file(
+    path: Path,
+    entries_dir: Path,
+    replaced_by: str | None = None,
+) -> None:
+    """Move a memory file to the deleted directory, updating metadata if replaced."""
+    try:
+        rel_path = path.relative_to(entries_dir)
+    except ValueError:
+        # Not in entries_dir? Just unlink.
+        path.unlink(missing_ok=True)
+        return
+
+    # Prepare destination
+    dest_path = entries_dir / _DELETED_DIRNAME / rel_path
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # If we need to update metadata, read-modify-write
+    if replaced_by:
+        record = read_memory_file(path)
+        if record:
+            record.metadata.replaced_by = replaced_by
+            front_matter = _render_front_matter(record.id, record.metadata)
+            body = front_matter + "\n" + record.content + "\n"
+            atomic_write_text(dest_path, body)
+            path.unlink(missing_ok=True)
+            return
+
+    # Simple move if no metadata change
+    path.rename(dest_path)
+
+
+def write_memory_file(
+    root: Path,
+    *,
+    conversation_id: str,
+    role: str,
+    created_at: str,
+    content: str,
+    summary_kind: str | None = None,
+    doc_id: str | None = None,
+    source_id: str | None = None,
+) -> MemoryFileRecord:
+    """Render and persist a memory document to disk."""
+    entries_dir, _ = ensure_store_dirs(root)
+    safe_conversation = _slugify(conversation_id)
+    doc_id = doc_id or str(uuid4())
+    safe_ts = _safe_timestamp(created_at)
+
+    # Route by role/category for readability
+    if summary_kind:
+        subdir = Path("summaries")
+        filename = "summary.md"
+    elif role == "user":
+        subdir = Path("turns") / "user"
+        filename = f"{safe_ts}__{doc_id}.md"
+    elif role == "assistant":
+        subdir = Path("turns") / "assistant"
+        filename = f"{safe_ts}__{doc_id}.md"
+    elif role == "memory":
+        subdir = Path("facts")
+        filename = f"{safe_ts}__{doc_id}.md"
+    else:
+        subdir = Path()
+        filename = f"{doc_id}.md"
+
+    metadata = MemoryMetadata(
+        conversation_id=conversation_id,
+        role=role,
+        created_at=created_at,
+        summary_kind=summary_kind,
+        source_id=source_id,
+    )
+
+    front_matter = _render_front_matter(doc_id, metadata)
+    body = front_matter + "\n" + content.strip() + "\n"
+
+    file_path = entries_dir / safe_conversation / subdir / filename
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    atomic_write_text(file_path, body)
+
+    return MemoryFileRecord(id=doc_id, path=file_path, metadata=metadata, content=content)
+
+
+def load_memory_files(root: Path) -> list[MemoryFileRecord]:
+    """Load all memory files from disk."""
+    entries_dir, _ = ensure_store_dirs(root)
+    records: list[MemoryFileRecord] = []
+    for path in entries_dir.rglob("*.md"):
+        # Skip anything under a deleted tombstone folder.
+        if _DELETED_DIRNAME in path.parts:
+            continue
+        rec = read_memory_file(path)
+        if rec:
+            records.append(rec)
+    return records
+
+
+def read_memory_file(path: Path) -> MemoryFileRecord | None:
+    """Parse a single memory file; return None if invalid."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception:
+        LOGGER.warning("Failed to read memory file %s", path, exc_info=True)
+        return None
+
+    fm, body = _split_front_matter(text)
+    if fm is None:
+        LOGGER.warning("Memory file %s missing front matter; skipping", path)
+        return None
+
+    doc_id = fm.pop("id", None)
+    if not doc_id:
+        LOGGER.warning("Memory file %s missing id; skipping", path)
+        return None
+
+    try:
+        metadata = MemoryMetadata(**fm)
+    except ValidationError:
+        LOGGER.warning("Memory file %s has invalid metadata; skipping", path, exc_info=True)
+        return None
+
+    return MemoryFileRecord(id=str(doc_id), path=path, metadata=metadata, content=body.strip())
+
+
+def write_snapshot(snapshot_path: Path, records: Iterable[MemoryFileRecord]) -> None:
+    """Write a JSON snapshot of current memories for easy inspection."""
+    payload = [
+        {
+            "id": rec.id,
+            "path": str(rec.path),
+            "metadata": rec.metadata.model_dump(exclude_none=True),
+            "content": rec.content,
+        }
+        for rec in records
+    ]
+
+    atomic_write_text(snapshot_path, json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def load_snapshot(snapshot_path: Path) -> dict[str, MemoryFileRecord]:
+    """Load snapshot into a mapping from id to record (if the snapshot exists)."""
+    if not snapshot_path.exists():
+        return {}
+    try:
+        data = json.loads(snapshot_path.read_text(encoding="utf-8"))
+    except Exception:
+        LOGGER.warning("Failed to read memory snapshot %s", snapshot_path, exc_info=True)
+        return {}
+
+    records: dict[str, MemoryFileRecord] = {}
+    for item in data:
+        try:
+            metadata = MemoryMetadata(**item["metadata"])
+            record = MemoryFileRecord(
+                id=str(item["id"]),
+                path=Path(item["path"]),
+                metadata=metadata,
+                content=str(item.get("content") or ""),
+            )
+            records[record.id] = record
+        except Exception:
+            LOGGER.warning("Invalid snapshot entry; skipping", exc_info=True)
+            continue
+    return records
+
+
+def _render_front_matter(doc_id: str, metadata: MemoryMetadata) -> str:
+    """Return YAML front matter string."""
+    import yaml  # noqa: PLC0415
+
+    meta_dict = metadata.model_dump(exclude_none=True)
+    meta_dict = {"id": doc_id, **meta_dict}
+    yaml_block = yaml.safe_dump(meta_dict, sort_keys=False)
+    return f"---\n{yaml_block}---"
+
+
+def _split_front_matter(text: str) -> tuple[dict | None, str]:
+    """Split YAML front matter from body."""
+    if not text.startswith("---"):
+        return None, text
+    end = text.find("\n---", 3)
+    if end == -1:
+        return None, text
+    yaml_part = text[3:end]
+    try:
+        import yaml  # noqa: PLC0415
+
+        meta = yaml.safe_load(yaml_part) or {}
+    except Exception:
+        return None, text
+    body_start = end + len("\n---")
+    body = text[body_start:].lstrip("\n")
+    return meta, body
+
+
+def _slugify(value: str) -> str:
+    """Filesystem-safe slug for folder names."""
+    safe = "".join(ch if ch.isalnum() or ch in "-._" else "_" for ch in value)
+    return safe or "default"

agent_cli/memory/_filters.py

@@ -0,0 +1,63 @@
+"""Filter conversion utilities for ChromaDB."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _convert_condition(key: str, value: Any) -> dict[str, Any] | None:
+    """Convert a single filter condition to ChromaDB format."""
+    if isinstance(value, dict):
+        # Operator dict: {"gte": 10} → {"$gte": 10}
+        for op, val in value.items():
+            chroma_op = f"${op}" if not op.startswith("$") else op
+            return {key: {chroma_op: val}}
+        return None
+    # Simple equality
+    return {key: {"$eq": value}}
+
+
+def _process_or(conditions: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """Process $or conditions."""
+    or_conditions = []
+    for cond in conditions:
+        for sub_key, sub_val in cond.items():
+            converted = _convert_condition(sub_key, sub_val)
+            if converted:
+                or_conditions.append(converted)
+    if len(or_conditions) > 1:
+        return {"$or": or_conditions}
+    if or_conditions:
+        return or_conditions[0]
+    return None
+
+
+def to_chroma_where(filters: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Convert universal filter format to ChromaDB WHERE clause.
+
+    Supports:
+    - Simple equality: {"role": "user"} → {"role": {"$eq": "user"}}
+    - Operators: {"created_at": {"gte": "2024-01-01"}} → {"created_at": {"$gte": "2024-01-01"}}
+    - Logical OR: {"$or": [{"role": "user"}, {"role": "assistant"}]}
+
+    Operators: eq, ne, gt, gte, lt, lte, in, nin
+    """
+    if not filters:
+        return None
+
+    processed: list[dict[str, Any]] = []
+    for key, value in filters.items():
+        if key == "$or":
+            or_result = _process_or(value)
+            if or_result:
+                processed.append(or_result)
+        elif not key.startswith("$"):
+            converted = _convert_condition(key, value)
+            if converted:
+                processed.append(converted)
+
+    if not processed:
+        return None
+    if len(processed) == 1:
+        return processed[0]
+    return {"$and": processed}