agent-cli 0.70.5__py3-none-any.whl

agent_cli/rag/engine.py

@@ -0,0 +1,302 @@
+"""Core RAG Engine Logic (Functional)."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import AsyncGenerator  # noqa: TC003
+from pathlib import Path  # noqa: TC003
+from typing import TYPE_CHECKING, Any
+
+from fastapi.responses import StreamingResponse
+
+from agent_cli.core.sse import format_chunk, format_done
+from agent_cli.rag._prompt import RAG_PROMPT_NO_TOOLS, RAG_PROMPT_WITH_TOOLS
+from agent_cli.rag._retriever import search_context
+from agent_cli.rag._utils import load_document_text
+from agent_cli.rag.models import Message, RetrievalResult  # noqa: TC001
+
+if TYPE_CHECKING:
+    from chromadb import Collection
+    from pydantic_ai import Agent
+    from pydantic_ai.messages import ModelRequest, ModelResponse
+    from pydantic_ai.result import RunResult
+
+    from agent_cli.core.reranker import OnnxCrossEncoder
+    from agent_cli.rag.models import ChatRequest
+
+LOGGER = logging.getLogger(__name__)
+
+# Maximum context size in characters (~3000 tokens at 4 chars/token)
+_MAX_CONTEXT_CHARS = 12000
+
+
+def truncate_context(context: str, max_chars: int = _MAX_CONTEXT_CHARS) -> str:
+    """Truncate context to fit within token budget while keeping complete chunks.
+
+    Args:
+        context: Raw context string with chunks separated by "---".
+        max_chars: Maximum characters to keep (default ~3000 tokens).
+
+    Returns:
+        Truncated context with complete chunks only.
+
+    """
+    if len(context) <= max_chars:
+        return context
+
+    separator = "\n\n---\n\n"
+    chunks = context.split(separator)
+    result = []
+    total = 0
+
+    for chunk in chunks:
+        chunk_len = len(chunk) + len(separator)
+        if total + chunk_len > max_chars:
+            break
+        result.append(chunk)
+        total += chunk_len
+
+    return separator.join(result)
+
+
+def _is_path_safe(base: Path, requested: Path) -> bool:
+    """Check if requested path is safely within base directory."""
+    try:
+        requested.resolve().relative_to(base.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def _retrieve_context(
+    request: ChatRequest,
+    collection: Collection,
+    reranker_model: OnnxCrossEncoder,
+    default_top_k: int = 3,
+) -> RetrievalResult | None:
+    """Retrieve context for the request.
+
+    Returns:
+        The retrieval result, or None if no retrieval was performed.
+
+    """
+    # Get last user message
+    user_message = next(
+        (m.content for m in reversed(request.messages) if m.role == "user"),
+        None,
+    )
+
+    if not user_message:
+        return None
+
+    # Retrieve
+    top_k = request.rag_top_k if request.rag_top_k is not None else default_top_k
+    if top_k <= 0:
+        LOGGER.info("RAG retrieval disabled for this request (top_k=%s)", top_k)
+        return None
+
+    retrieval = search_context(collection, reranker_model, user_message, top_k=top_k)
+
+    if not retrieval.context:
+        LOGGER.info("ℹ️  No relevant context found for query: '%s'", user_message[:50])  # noqa: RUF001
+        return None
+
+    LOGGER.info(
+        "✅ Found %d relevant sources for query: '%s'",
+        len(retrieval.sources),
+        user_message[:50],
+    )
+    return retrieval
+
+
+def _convert_messages(
+    messages: list[Message],
+) -> tuple[list[ModelRequest | ModelResponse], str]:
+    """Convert OpenAI messages to Pydantic AI messages and extract user prompt."""
+    from pydantic_ai.messages import (  # noqa: PLC0415
+        ModelRequest,
+        ModelResponse,
+        SystemPromptPart,
+        TextPart,
+        UserPromptPart,
+    )
+
+    pyd_messages: list[ModelRequest | ModelResponse] = []
+
+    # Validation: Ensure there is at least one message
+    if not messages:
+        return [], ""
+
+    # Split history and last user prompt
+    history_msgs = messages[:-1]
+    last_msg = messages[-1]
+
+    for m in history_msgs:
+        if m.role == "system":
+            pyd_messages.append(ModelRequest(parts=[SystemPromptPart(content=m.content)]))
+        elif m.role == "user":
+            pyd_messages.append(ModelRequest(parts=[UserPromptPart(content=m.content)]))
+        elif m.role == "assistant":
+            pyd_messages.append(ModelResponse(parts=[TextPart(content=m.content)]))
+
+    return pyd_messages, last_msg.content
+
+
+def _extract_model_settings(request: ChatRequest) -> dict[str, Any]:
+    """Extract model settings from request."""
+    settings = {}
+    if request.temperature is not None:
+        settings["temperature"] = request.temperature
+    if request.max_tokens is not None:
+        settings["max_tokens"] = request.max_tokens
+    return settings
+
+
+def _build_openai_response(
+    result: RunResult,
+    model_name: str,
+    retrieval: RetrievalResult | None,
+) -> dict[str, Any]:
+    """Format the Pydantic AI result as an OpenAI-compatible dict."""
+    usage = result.usage()
+    response: dict[str, Any] = {
+        "id": f"chatcmpl-{result.run_id}",
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": model_name,
+        "choices": [
+            {
+                "index": 0,
+                "message": {"role": "assistant", "content": result.output},
+                "finish_reason": "stop",
+            },
+        ],
+    }
+
+    if usage:
+        response["usage"] = {
+            "prompt_tokens": usage.input_tokens or 0,
+            "completion_tokens": usage.output_tokens or 0,
+            "total_tokens": usage.total_tokens or 0,
+        }
+
+    if retrieval:
+        response["rag_sources"] = retrieval.sources
+
+    return response
+
+
+async def process_chat_request(
+    request: ChatRequest,
+    collection: Collection,
+    reranker_model: OnnxCrossEncoder,
+    openai_base_url: str,
+    docs_folder: Path,
+    default_top_k: int = 3,
+    api_key: str | None = None,
+    enable_rag_tools: bool = True,
+) -> Any:
+    """Process a chat request with RAG."""
+    # 1. Retrieve Context
+    retrieval = _retrieve_context(request, collection, reranker_model, default_top_k=default_top_k)
+
+    # 2. Define Tool
+    def read_full_document(file_path: str) -> str:
+        """Read the full content of a document by its path.
+
+        Use this tool when the context snippet is insufficient and you need
+        the complete document to answer the user's question accurately.
+        The file_path should match one of the [Source: ...] paths from the context.
+        """
+        try:
+            full_path = (docs_folder / file_path).resolve()
+            if not _is_path_safe(docs_folder, full_path):
+                return "Error: Access denied. Path is outside the document folder."
+            if not full_path.exists():
+                return f"Error: File not found: {file_path}"
+
+            text = load_document_text(full_path)
+            if text is None:
+                return "Error: Could not read file (unsupported format or encoding)."
+            return text
+        except Exception as e:
+            return f"Error reading file: {e}"
+
+    # 3. Define RAG System Prompt (additive - user's system prompt is preserved in history)
+    # Determine tool availability:
+    # - If CLI flag `enable_rag_tools` is False, tools are disabled globally.
+    # - If CLI flag is True, check request.rag_enable_tools (default True).
+    tools_allowed = enable_rag_tools and (request.rag_enable_tools is not False)
+
+    if retrieval and retrieval.context:
+        truncated = truncate_context(retrieval.context)
+        template = RAG_PROMPT_WITH_TOOLS if tools_allowed else RAG_PROMPT_NO_TOOLS
+        system_prompt = template.format(context=truncated)
+    else:
+        system_prompt = ""
+
+    # 4. Setup Agent
+    from pydantic_ai import Agent  # noqa: PLC0415
+    from pydantic_ai.models.openai import OpenAIModel  # noqa: PLC0415
+    from pydantic_ai.providers.openai import OpenAIProvider  # noqa: PLC0415
+
+    provider = OpenAIProvider(base_url=openai_base_url, api_key=api_key or "dummy")
+    model = OpenAIModel(model_name=request.model, provider=provider)
+
+    tools = [read_full_document] if tools_allowed else []
+    agent = Agent(model=model, tools=tools, system_prompt=system_prompt)
+
+    # 5. Prepare Message History & Prompt
+    history, user_prompt = _convert_messages(request.messages)
+
+    # 6. Model Settings
+    model_settings = _extract_model_settings(request)
+
+    # 7. Run Agent
+    if request.stream:
+        return StreamingResponse(
+            _stream_generator(
+                agent,
+                user_prompt,
+                history,
+                model_settings,
+                request.model,
+                retrieval,
+            ),
+            media_type="text/event-stream",
+        )
+
+    result = await agent.run(
+        user_prompt,
+        message_history=history,
+        model_settings=model_settings,
+    )
+
+    return _build_openai_response(result, request.model, retrieval)
+
+
+async def _stream_generator(
+    agent: Agent,
+    prompt: str,
+    history: list[ModelRequest | ModelResponse],
+    settings: dict[str, Any],
+    model_name: str,
+    retrieval: RetrievalResult | None,
+) -> AsyncGenerator[str, None]:
+    """Stream Pydantic AI result as OpenAI SSE."""
+    async with agent.run_stream(prompt, message_history=history, model_settings=settings) as result:
+        async for chunk in result.stream_text(delta=True):
+            yield format_chunk(result.run_id, model_name, content=chunk)
+
+        # Finish chunk with optional RAG sources
+        extra = None
+        if retrieval and retrieval.sources:
+            extra = {
+                "rag_sources": [
+                    {"source": s.source, "path": s.path, "chunk_id": s.chunk_id, "score": s.score}
+                    for s in retrieval.sources
+                ],
+            }
+        yield format_chunk(result.run_id, model_name, finish_reason="stop", extra=extra)
+        yield format_done()

agent_cli/rag/models.py

@@ -0,0 +1,55 @@
+"""RAG data models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Message(BaseModel):
+    """Chat message model."""
+
+    role: str
+    content: str
+
+
+class ChatRequest(BaseModel):
+    """Chat completion request model."""
+
+    model_config = ConfigDict(extra="allow")
+
+    model: str
+    messages: list[Message]
+    temperature: float | None = 0.7
+    max_tokens: int | None = 1000
+    stream: bool | None = False
+    rag_top_k: int | None = None
+    rag_enable_tools: bool | None = True
+
+
+class DocMetadata(BaseModel):
+    """Metadata for an indexed document chunk."""
+
+    source: str
+    file_path: str
+    file_type: str
+    chunk_id: int
+    total_chunks: int
+    indexed_at: str
+    file_hash: str
+    file_mtime: float
+
+
+class RagSource(BaseModel):
+    """Source information for RAG response."""
+
+    source: str
+    path: str
+    chunk_id: int
+    score: float
+
+
+class RetrievalResult(BaseModel):
+    """Result of a RAG retrieval operation."""
+
+    context: str
+    sources: list[RagSource]

agent_cli/scripts/__init__.py

@@ -0,0 +1 @@
+"""Scripts package containing installation and service management scripts."""

agent_cli/scripts/check_plugin_skill_sync.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Check that plugin skill files are in sync with source files."""
+
+import sys
+from pathlib import Path
+
+SYNC_PAIRS = [
+    # Plugin marketplace distribution
+    ("agent_cli/dev/skill/SKILL.md", ".claude-plugin/skills/agent-cli-dev/SKILL.md"),
+    ("agent_cli/dev/skill/examples.md", ".claude-plugin/skills/agent-cli-dev/examples.md"),
+    # Project-local skill (for Claude Code working on this repo)
+    ("agent_cli/dev/skill/SKILL.md", ".claude/skills/agent-cli-dev/SKILL.md"),
+    ("agent_cli/dev/skill/examples.md", ".claude/skills/agent-cli-dev/examples.md"),
+]
+
+
+def main() -> int:
+    """Check that plugin skill files match source files."""
+    root = Path(__file__).parent.parent
+    out_of_sync = []
+
+    for source, target in SYNC_PAIRS:
+        source_path = root / source
+        target_path = root / target
+
+        if not source_path.exists():
+            print(f"Source not found: {source}")
+            continue
+
+        if not target_path.exists():
+            out_of_sync.append((source, target, "target missing"))
+            continue
+
+        if source_path.read_text() != target_path.read_text():
+            out_of_sync.append((source, target, "content differs"))
+
+    if out_of_sync:
+        print("Plugin skill files are out of sync:")
+        for source, target, reason in out_of_sync:
+            print(f"  {source} -> {target} ({reason})")
+        print("\nRun:")
+        print("  cp agent_cli/dev/skill/*.md .claude-plugin/skills/agent-cli-dev/")
+        print("  cp agent_cli/dev/skill/*.md .claude/skills/agent-cli-dev/")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_cli/scripts/linux-hotkeys/README.md

@@ -0,0 +1,63 @@
+# Linux Hotkeys
+
+System-wide hotkeys for agent-cli voice AI features on Linux.
+
+## Setup
+
+```bash
+./setup-linux-hotkeys.sh
+```
+
+The setup script will:
+1. Install notification support if missing
+2. Show you the exact hotkey bindings to add to your desktop environment
+3. Provide copy-paste ready configuration for popular desktop environments
+
+## Usage
+
+- **`Super+Shift+R`** → Toggle voice transcription (start/stop with result)
+- **`Super+Shift+A`** → Autocorrect clipboard text
+- **`Super+Shift+V`** → Toggle voice edit mode for clipboard
+
+Results appear in notifications and clipboard.
+
+## Desktop Environment Support
+
+The setup script provides copy-paste ready instructions for:
+
+- **Hyprland**: Add bindings to `~/.config/hypr/hyprland.conf`
+- **Sway**: Add bindings to `~/.config/sway/config`
+- **i3**: Add bindings to `~/.config/i3/config`
+- **GNOME**: Use Settings → Keyboard → Custom Shortcuts
+- **KDE**: Use System Settings → Shortcuts → Custom Shortcuts
+- **XFCE**: Use Settings Manager → Keyboard → Application Shortcuts
+- **Other**: Manual hotkey configuration in your desktop environment
+
+## Features
+
+- **Manual configuration**: Simple setup with clear instructions for each desktop environment
+- **Wayland support**: Includes clipboard syncing for Wayland compositors
+- **Fallback notifications**: Uses `notify-send`, `dunstify`, or console output
+- **Error handling**: Shows notifications for both success and failure cases
+- **PATH handling**: Scripts automatically find agent-cli installation
+
+## Troubleshooting
+
+**Hotkeys not working?**
+- Check your desktop's keyboard shortcut settings for conflicts
+- Make sure you added the bindings to your desktop environment's config
+- Verify the script paths are correct
+
+**No notifications?**
+```bash
+sudo apt install libnotify-bin  # Ubuntu/Debian
+sudo dnf install libnotify      # Fedora/RHEL
+sudo pacman -S libnotify        # Arch
+```
+
+**Services not running?**
+```bash
+./start-all-services.sh
+```
+
+That's it! System-wide hotkeys for agent-cli on Linux.

agent_cli/scripts/linux-hotkeys/toggle-autocorrect.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+# Toggle script for agent-cli autocorrect on Linux
+#
+# This script corrects text from clipboard using AI:
+# - Reads text from clipboard
+# - Processes it with LLM for grammar/spelling corrections
+# - Displays the corrected result
+#
+# Works across different Linux desktop environments
+
+# Function to send notification
+notify() {
+    local title="$1"
+    local message="$2"
+    local timeout="${3:-3000}"
+
+    if command -v notify-send &> /dev/null; then
+        notify-send -t "$timeout" "$title" "$message"
+    elif command -v dunstify &> /dev/null; then
+        dunstify -t "$timeout" "$title" "$message"
+    else
+        echo "$title: $message"
+    fi
+}
+
+# Function to sync clipboard (Wayland)
+sync_clipboard() {
+    if command -v wl-paste &> /dev/null && command -v wl-copy &> /dev/null; then
+        wl-paste | wl-copy -p 2>/dev/null || true
+    fi
+}
+
+# Ensure agent-cli is in PATH
+export PATH="$PATH:$HOME/.local/bin"
+
+notify "📝 Autocorrect" "Processing clipboard text..."
+
+OUTPUT=$(agent-cli autocorrect --quiet 2>/dev/null) && {
+    # Sync clipboard to primary selection (Wayland)
+    sync_clipboard
+    notify "✅ Corrected" "$OUTPUT" 5000
+} || {
+    notify "❌ Error" "No text to correct or processing failed" 3000
+}

agent_cli/scripts/linux-hotkeys/toggle-transcription.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# Toggle script for agent-cli transcription on Linux
+#
+# This script provides a simple toggle mechanism for voice transcription:
+# - First invocation: Starts transcription in the background
+# - Second invocation: Stops transcription and displays the result
+#
+# Works across different Linux desktop environments
+
+# Function to send notification
+notify() {
+    local title="$1"
+    local message="$2"
+    local timeout="${3:-3000}"
+
+    if command -v notify-send &> /dev/null; then
+        notify-send -t "$timeout" "$title" "$message"
+    elif command -v dunstify &> /dev/null; then
+        dunstify -t "$timeout" "$title" "$message"
+    else
+        echo "$title: $message"
+    fi
+}
+
+# Function to sync clipboard (Wayland)
+sync_clipboard() {
+    if command -v wl-paste &> /dev/null && command -v wl-copy &> /dev/null; then
+        wl-paste | wl-copy -p 2>/dev/null || true
+    fi
+}
+
+# Check if agent-cli transcribe is already running
+if pgrep -f "agent-cli transcribe" > /dev/null; then
+    # Transcription is running - stop it
+    pkill -INT -f "agent-cli transcribe"
+    notify "🛑 Transcription Stopped" "Processing results..."
+else
+    # Transcription is not running - start it
+
+    # Ensure agent-cli is in PATH
+    export PATH="$PATH:$HOME/.local/bin"
+
+    # Notify user that recording has started
+    notify "🎙️ Transcription Started" "Listening in background..."
+
+    # Start transcription in background
+    (
+        OUTPUT=$(agent-cli transcribe --llm --quiet 2>/dev/null)
+        if [ -n "$OUTPUT" ]; then
+            # Sync clipboard to primary selection (Wayland)
+            sync_clipboard
+            notify "📄 Transcription Result" "$OUTPUT" 5000
+        else
+            notify "❌ Error" "No output" 3000
+        fi
+    ) &
+fi

agent_cli/scripts/linux-hotkeys/toggle-voice-edit.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# Toggle script for agent-cli voice-edit on Linux
+#
+# This script provides voice editing for clipboard text:
+# - First invocation: Starts voice editing in the background
+# - Second invocation: Stops voice editing and displays the result
+#
+# Works across different Linux desktop environments
+
+# Function to send notification
+notify() {
+    local title="$1"
+    local message="$2"
+    local timeout="${3:-3000}"
+
+    if command -v notify-send &> /dev/null; then
+        notify-send -t "$timeout" "$title" "$message"
+    elif command -v dunstify &> /dev/null; then
+        dunstify -t "$timeout" "$title" "$message"
+    else
+        echo "$title: $message"
+    fi
+}
+
+# Function to sync clipboard (Wayland)
+sync_clipboard() {
+    if command -v wl-paste &> /dev/null && command -v wl-copy &> /dev/null; then
+        wl-paste | wl-copy -p 2>/dev/null || true
+    fi
+}
+
+# Check if agent-cli voice-edit is already running
+if pgrep -f "agent-cli voice-edit" > /dev/null; then
+    # Voice edit is running - stop it
+    pkill -INT -f "agent-cli voice-edit"
+    notify "🛑 Voice Edit Stopped" "Processing voice command..."
+else
+    # Voice edit is not running - start it
+
+    # Ensure agent-cli is in PATH
+    export PATH="$PATH:$HOME/.local/bin"
+
+    # Notify user that recording has started
+    notify "🎙️ Voice Edit Started" "Listening for voice command..."
+
+    # Start voice edit in background
+    (
+        OUTPUT=$(agent-cli voice-edit --quiet 2>/dev/null)
+        if [ -n "$OUTPUT" ]; then
+            # Sync clipboard to primary selection (Wayland)
+            sync_clipboard
+            notify "✨ Voice Edit Result" "$OUTPUT" 5000
+        else
+            notify "❌ Error" "No output" 3000
+        fi
+    ) &
+fi

agent_cli/scripts/macos-hotkeys/README.md

@@ -0,0 +1,45 @@
+# macOS Hotkeys
+
+System-wide hotkeys for agent-cli voice AI features on macOS.
+
+## Setup
+
+```bash
+./setup-macos-hotkeys.sh
+```
+
+## Usage
+
+- **`Cmd+Shift+R`** → Toggle voice transcription (start/stop with result)
+- **`Cmd+Shift+A`** → Autocorrect clipboard text
+- **`Cmd+Shift+V`** → Toggle voice edit mode for clipboard
+
+Results appear in notifications and clipboard.
+
+> [!TIP]
+> For a persistent "Listening…" indicator, open System Settings → Notifications → *terminal-notifier* and set the Alert style to **Persistent** (or choose **Alerts** on older macOS versions).
+> Also enable "Allow notification when mirroring or sharing the display".
+> The scripts keep that alert pinned while dismissing status/result notifications automatically.
+
+## What it installs
+
+- **skhd**: Hotkey manager
+- **terminal-notifier**: Notifications
+- **Configuration**: Automatic setup
+
+## Troubleshooting
+
+**Hotkey not working?**
+- Grant accessibility permissions in System Settings
+
+**No notifications?**
+```bash
+terminal-notifier -title "Test" -message "Hello"
+```
+
+**Services not running?**
+```bash
+./start-all-services.sh
+```
+
+That's it! System-wide hotkeys for agent-cli on macOS.

agent_cli/scripts/macos-hotkeys/skhd-config-example

@@ -0,0 +1,5 @@
+# Simple skhd configuration for transcription toggle
+# Save to ~/.config/skhd/skhdrc
+
+# Press Cmd+Shift+R to toggle transcription
+cmd + shift - r : /path/to/toggle-transcription.sh