agent-cli 0.70.5__py3-none-any.whl

agent_cli/docs_gen.py

@@ -0,0 +1,417 @@
+"""Documentation generators for markdown-code-runner integration.
+
+This module provides functions to introspect Typer commands and generate
+Markdown documentation. Use with markdown-code-runner to auto-generate
+options tables in documentation.
+
+Example usage in Markdown files:
+    <!-- CODE:START -->
+    <!-- from agent_cli.docs_gen import all_options_for_docs -->
+    <!-- print(all_options_for_docs("transcribe")) -->
+    <!-- CODE:END -->
+    <!-- OUTPUT:START -->
+    ...auto-generated table...
+    <!-- OUTPUT:END -->
+"""
+
+from __future__ import annotations
+
+from typing import Any, get_origin
+
+import click
+from typer.main import get_command
+
+from agent_cli import opts
+from agent_cli.cli import app
+from agent_cli.install.extras import EXTRAS
+
+
+def _get_type_str(annotation: Any) -> str:
+    """Convert a type annotation to a readable string."""
+    if annotation is None:
+        return "str"
+
+    # Handle Optional types (Union[X, None])
+    origin = get_origin(annotation)
+    if origin is type(None):
+        return "None"
+
+    # Get the base type name
+    if hasattr(annotation, "__name__"):
+        return annotation.__name__.upper()
+    if hasattr(annotation, "__origin__"):
+        # Handle generic types like Optional[str]
+        args = getattr(annotation, "__args__", ())
+        non_none_args = [a for a in args if a is not type(None)]
+        if non_none_args:
+            return _get_type_str(non_none_args[0])
+    return str(annotation).replace("typing.", "").upper()
+
+
+def _format_default(default: Any) -> str:
+    """Format a default value for display."""
+    if default is None:
+        return "-"
+    if isinstance(default, bool):
+        return str(default).lower()
+    if isinstance(default, str) and default == "":
+        return '""'
+    return str(default)
+
+
+def _get_click_command(command_path: str) -> click.Command | None:
+    """Get a Click command from a path like 'transcribe' or 'memory.proxy'."""
+    parts = command_path.split(".")
+    click_app = get_command(app)
+
+    cmd: click.Command | click.Group = click_app
+    for part in parts:
+        if isinstance(cmd, click.Group):
+            cmd = cmd.commands.get(part)  # type: ignore[assignment]
+            if cmd is None:
+                return None
+        else:
+            return None
+    return cmd
+
+
+def _extract_options_from_click(cmd: click.Command) -> list[dict[str, Any]]:
+    """Extract options from a Click command."""
+    options = []
+    for param in cmd.params:
+        if isinstance(param, click.Option):
+            # Get the primary option name (longest one, usually --foo)
+            opt_names = [n for n in param.opts if n.startswith("--")]
+            if not opt_names:
+                opt_names = param.opts
+            primary_name = max(opt_names, key=len) if opt_names else param.name
+
+            # Handle boolean flags
+            if param.is_flag and param.secondary_opts:
+                # e.g., --llm/--no-llm
+                primary_name = f"{opt_names[0]}/{param.secondary_opts[0]}"
+
+            # Get panel from rich_help_panel or use default
+            panel = getattr(param, "rich_help_panel", None) or "Options"
+
+            options.append(
+                {
+                    "name": primary_name,
+                    "type": param.type.name.upper() if hasattr(param.type, "name") else "TEXT",
+                    "default": _format_default(param.default),
+                    "help": param.help or "",
+                    "panel": panel,
+                    "envvar": param.envvar[0] if param.envvar else None,
+                    "required": param.required,
+                    "is_flag": param.is_flag,
+                },
+            )
+    return options
+
+
+def _get_command_options(command_path: str) -> list[dict[str, Any]]:
+    """Extract all options from a Typer command."""
+    cmd = _get_click_command(command_path)
+    if cmd is None:
+        return []
+    return _extract_options_from_click(cmd)
+
+
+def _options_table(
+    command_path: str,
+    panel: str | None = None,
+    *,
+    include_type: bool = True,
+    include_default: bool = True,
+) -> str:
+    """Generate a Markdown table of options for a command."""
+    options = _get_command_options(command_path)
+    if panel:
+        options = [o for o in options if o["panel"] == panel]
+
+    if not options:
+        return f"*No options found for panel '{panel}'*" if panel else "*No options found*"
+
+    # Build header
+    header_parts = ["Option"]
+    if include_type:
+        header_parts.append("Type")
+    if include_default:
+        header_parts.append("Default")
+    header_parts.append("Description")
+
+    header = "| " + " | ".join(header_parts) + " |"
+    separator = "|" + "|".join("-" * (len(p) + 2) for p in header_parts) + "|"
+
+    lines = [header, separator]
+
+    for opt in options:
+        row_parts = [f"`{opt['name']}`"]
+        if include_type:
+            row_parts.append(opt["type"])
+        if include_default:
+            default = opt["default"]
+            row_parts.append(f"`{default}`" if default != "-" else "-")
+        row_parts.append(opt["help"])
+        lines.append("| " + " | ".join(row_parts) + " |")
+
+    return "\n".join(lines)
+
+
+def _options_by_panel(
+    command_path: str,
+    *,
+    include_type: bool = True,
+    include_default: bool = True,
+    heading_level: int = 3,
+) -> str:
+    """Generate options tables grouped by panel."""
+    options = _get_command_options(command_path)
+    if not options:
+        return "*No options found*"
+
+    # Get unique panels in order of first appearance
+    panels: list[str] = []
+    for opt in options:
+        if opt["panel"] not in panels:
+            panels.append(opt["panel"])
+
+    heading_prefix = "#" * heading_level
+    output = []
+
+    for panel in panels:
+        output.append(f"{heading_prefix} {panel}\n")
+        output.append(
+            _options_table(
+                command_path,
+                panel=panel,
+                include_type=include_type,
+                include_default=include_default,
+            ),
+        )
+        output.append("")  # Blank line between panels
+
+    return "\n".join(output)
+
+
+def _list_commands() -> list[str]:
+    """List all available commands including subcommands."""
+    click_app = get_command(app)
+    commands = []
+
+    def _walk(cmd: click.Command | click.Group, prefix: str = "") -> None:
+        if isinstance(cmd, click.Group):
+            for name, subcmd in cmd.commands.items():
+                path = f"{prefix}.{name}" if prefix else name
+                if isinstance(subcmd, click.Group):
+                    _walk(subcmd, path)
+                else:
+                    commands.append(path)
+        elif prefix:
+            commands.append(prefix)
+
+    _walk(click_app)
+    return sorted(commands)
+
+
+def env_vars_table() -> str:
+    """Generate a table of all environment variables.
+
+    Returns:
+        Markdown table of environment variables and descriptions
+
+    """
+    lines = [
+        "| Variable | Description |",
+        "|----------|-------------|",
+    ]
+
+    seen = set()
+    for name in dir(opts):
+        if name.startswith("_"):
+            continue
+        obj = getattr(opts, name)
+        if hasattr(obj, "envvar") and obj.envvar:
+            envvar = obj.envvar
+            if envvar not in seen:
+                seen.add(envvar)
+                help_text = getattr(obj, "help", "") or ""
+                lines.append(f"| `{envvar}` | {help_text} |")
+
+    return "\n".join(lines)
+
+
+def provider_matrix() -> str:
+    """Generate provider comparison matrix.
+
+    Returns:
+        Markdown table comparing local vs cloud providers
+
+    """
+    return """| Capability | Local (Default) | Cloud Options |
+|------------|-----------------|---------------|
+| **LLM** | Ollama (`ollama`) | OpenAI (`openai`), Gemini (`gemini`) |
+| **ASR** (Speech-to-Text) | Wyoming/Faster Whisper (`wyoming`) | OpenAI-compatible Whisper (`openai`), Gemini (`gemini`) |
+| **TTS** (Text-to-Speech) | Wyoming/Piper (`wyoming`), Kokoro (`kokoro`) | OpenAI-compatible TTS (`openai`) |
+| **Wake Word** | Wyoming/openWakeWord | - |"""
+
+
+def commands_table(
+    category: str | None = None,
+    link_prefix: str = "",
+) -> str:
+    """Generate a table of available commands.
+
+    Args:
+        category: Filter by category (voice, text, ai, install, config) or None for all
+        link_prefix: Prefix for links (e.g., "docs/commands/" for README.md)
+
+    Returns:
+        Markdown table of commands
+
+    """
+    # Define command metadata
+    command_info = {
+        "transcribe": ("Speech-to-text", "Record voice → text in clipboard", "voice"),
+        "transcribe-daemon": ("Continuous transcription", "Background VAD service", "voice"),
+        "speak": ("Text-to-speech", "Read text aloud", "voice"),
+        "voice-edit": ("Voice-powered editor", "Edit clipboard with voice", "voice"),
+        "assistant": ("Wake word assistant", "Hands-free voice interaction", "voice"),
+        "chat": ("Conversational AI", "Voice chat with tools", "voice"),
+        "autocorrect": ("Grammar & spelling", "Fix text from clipboard", "text"),
+        "rag-proxy": ("RAG server", "Chat with documents", "ai"),
+        "memory.proxy": ("Long-term memory", "Persistent conversation memory", "ai"),
+        "memory.add": ("Add memories", "Directly add facts to memory", "ai"),
+        "server": ("Transcription server", "HTTP API for transcription", "ai"),
+        "install-services": ("Install services", "Set up AI services", "install"),
+        "install-hotkeys": ("Install hotkeys", "Set up system hotkeys", "install"),
+        "start-services": ("Start services", "Launch all services", "install"),
+        "config": ("Configuration", "Manage config files", "config"),
+    }
+
+    if category:
+        commands = {k: v for k, v in command_info.items() if v[2] == category}
+    else:
+        commands = command_info
+
+    if not commands:
+        return "*No commands found*"
+
+    lines = [
+        "| Command | Purpose | Use Case |",
+        "|---------|---------|----------|",
+    ]
+
+    for cmd, (purpose, use_case, _) in commands.items():
+        # Convert command path to link
+        doc_path = cmd.replace(".", "/")
+        link = f"{link_prefix}{doc_path}.md"
+        lines.append(f"| [`{cmd}`]({link}) | {purpose} | {use_case} |")
+
+    return "\n".join(lines)
+
+
+def config_example(command_path: str | None = None) -> str:
+    """Generate example TOML configuration for a command.
+
+    Args:
+        command_path: Command path or None for defaults section
+
+    Returns:
+        TOML configuration snippet
+
+    """
+    if command_path is None:
+        # Generate defaults section
+        return """[defaults]
+# Provider defaults (can be overridden per command)
+# llm_provider = "ollama"
+# asr_provider = "wyoming"
+# tts_provider = "wyoming"
+
+# API keys (or use environment variables)
+# openai_api_key = "sk-..."
+# gemini_api_key = "..."
+
+# Audio devices
+# input_device_index = 1
+# output_device_index = 0"""
+
+    options = _get_command_options(command_path)
+    if not options:
+        return f"# No configurable options for {command_path}"
+
+    section = command_path.replace(".", "-")
+    lines = [f"[{section}]"]
+
+    for opt in options:
+        # Skip process management and meta options
+        if opt["panel"] in ("Process Management Options",):
+            continue
+
+        # Convert flag name to config key
+        key = opt["name"].lstrip("-").replace("-", "_").split("/")[0]
+        default = opt["default"]
+        help_text = opt["help"]
+
+        # Format the value appropriately
+        if default == "-":
+            value = '""' if opt["type"] == "TEXT" else "null"
+            lines.append(f"# {key} = {value}  # {help_text}")
+        elif opt["type"] == "TEXT":
+            lines.append(f'# {key} = "{default}"  # {help_text}')
+        elif opt["type"] in ("INTEGER", "FLOAT") or opt["is_flag"]:
+            lines.append(f"# {key} = {default}  # {help_text}")
+        else:
+            lines.append(f"# {key} = {default}  # {help_text}")
+
+    return "\n".join(lines)
+
+
+def all_options_for_docs(command_path: str) -> str:
+    """Generate complete options documentation for a command page.
+
+    This is the main function to use in docs/commands/*.md files.
+    It generates all options grouped by panel with proper formatting.
+
+    Args:
+        command_path: Command path like "transcribe" or "memory.proxy"
+
+    Returns:
+        Complete Markdown options section
+
+    """
+    return _options_by_panel(
+        command_path,
+        include_type=False,  # Types are often obvious and clutter the table
+        include_default=True,
+        heading_level=3,
+    )
+
+
+def extras_table() -> str:
+    """Generate a table of available extras for install-extras command."""
+    lines = [
+        "| Extra | Description |",
+        "|-------|-------------|",
+    ]
+    for name, description in EXTRAS.items():
+        lines.append(f"| `{name}` | {description} |")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    # Demo: print options for transcribe command
+    print("=== Available Commands ===")
+    for cmd in _list_commands():
+        print(f"  {cmd}")
+    print()
+
+    print("=== transcribe options by panel ===")
+    print(_options_by_panel("transcribe"))
+
+    print("\n=== Environment Variables ===")
+    print(env_vars_table())
+
+    print("\n=== Provider Matrix ===")
+    print(provider_matrix())

agent_cli/example-config.toml

@@ -0,0 +1,185 @@
+# Example configuration for agent-cli
+# Copy this file to ~/.config/agent-cli/config.toml or ./agent-cli-config.toml and edit
+#
+# This file demonstrates how to configure all available options.
+# Keys use dashes to match the command-line arguments.
+# Any option here can be overridden by a command-line argument.
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# --- Default Settings ---
+# These settings apply to all commands unless overridden in a command-specific
+# section below.
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[defaults]
+
+# --- Provider Selection ---
+# Select the default provider for each service ("ollama"/"openai"/"gemini" for LLM, "wyoming"/"openai" for ASR).
+llm-provider = "ollama"  # "local" still works as a deprecated alias
+tts-provider = "wyoming"
+
+# --- API Keys ---
+# Your OpenAI API key. Can also be set via the OPENAI_API_KEY environment variable.
+openai-api-key = "sk-..."
+
+# --- Audio Device Settings ---
+# You can specify partial names for devices, and the first match will be used.
+# Use `agent-cli speak --list-devices` to see available devices.
+# input-device-name = "logitech,airpods,macbook"
+# output-device-name = "airpods,macbook"
+# You can also specify device by index, though name is more stable.
+# input-device-index = 1
+# output-device-index = 1
+
+# --- LLM Settings ---
+# Ollama (local)
+llm-ollama-model = "gemma3:4b"
+llm-ollama-host = "http://localhost:11434"
+# OpenAI
+llm-openai-model = "gpt-5-mini"
+# For llama-server (llama-cpp) or other OpenAI-compatible APIs:
+# openai-base-url = "http://localhost:8080/v1"
+
+# --- ASR (Speech-to-Text) Settings ---
+# Wyoming (local)
+asr-wyoming-ip = "localhost"
+asr-wyoming-port = 10300
+# OpenAI
+asr-openai-model = "whisper-1"
+# Custom ASR endpoint (e.g., NVIDIA Canary, local Whisper server)
+# Uncomment and configure to use a custom OpenAI-compatible Whisper API:
+# asr-provider = "openai"
+# asr-openai-base-url = "http://localhost:9898"
+# asr-openai-model = "nvidia/canary-qwen-2.5b"  # Optional: override model
+# asr-openai-prompt = "Transcribe the following:"  # Optional: add prompt
+
+# --- TTS (Text-to-Speech) Settings ---
+# Wyoming (local)
+tts-wyoming-ip = "localhost"
+tts-wyoming-port = 10200
+tts-wyoming-voice = "en_US-lessac-medium"
+# tts-wyoming-language = "en_US"  # Optional: specify language for the voice
+# tts-wyoming-speaker = "speaker_name" # Optional: specify speaker for the voice
+# OpenAI
+tts-openai-model = "tts-1"
+tts-openai-voice = "alloy"
+# Custom OpenAI-compatible TTS endpoint (e.g., your own proxy)
+# tts-openai-base-url = "http://localhost:8000/v1"
+# Kokoro (high-quality local TTS)
+# tts-kokoro-model = "kokoro"
+# tts-kokoro-voice = "af_sky"
+# tts-kokoro-host = "http://localhost:8880/v1"
+# Gemini TTS
+# tts-gemini-model = "gemini-2.5-flash-preview-tts"
+# tts-gemini-voice = "Kore"
+
+# --- Embedding Model (for RAG and Memory) ---
+# Used by rag-proxy and memory-proxy for vectorization.
+# embedding-model = "text-embedding-3-small"  # OpenAI default
+# embedding-model = "embeddinggemma:300m"  # Ollama local model
+
+# --- General Behavior ---
+log-level = "WARNING"  # Logging level (e.g., DEBUG, INFO, WARNING, ERROR)
+# log-file = "/path/to/agent-cli.log" # Path to a file to write logs to
+quiet = false # Suppress most console output
+clipboard = true # Copy results to clipboard by default
+# save-file = "/path/to/output.wav" # Save TTS audio to a file instead of playing
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# --- Command-Specific Overrides ---
+# Settings in these sections will override the [defaults] for that specific
+# command.
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[assistant]
+# Wake-word specific settings
+wake-server-ip = "localhost"
+wake-server-port = 10400
+wake-word = "ok_nabu" # e.g., "ok_nabu", "hey_jarvis"
+# The assistant agent also uses ASR, LLM, and TTS settings from [defaults]
+enable_tts = true
+
+[autocorrect]
+# Use a more powerful model specifically for the autocorrect command.
+llm-provider = "ollama"
+llm-ollama-model = "devstral:24b"
+
+[chat]
+# By default, chat uses local providers.
+# For better tool use, you might want to switch to OpenAI:
+# llm-provider = "openai"
+# tts-provider = "openai"
+# llm-openai-model = "gpt-4-turbo"
+enable_tts = true
+tts-speed = 1.2
+# Conversation history settings
+history-dir = "~/.config/agent-cli/history"
+last-n-messages = 50 # Number of messages to load from history
+
+[speak]
+# Use a specific voice for the speak command.
+tts-provider = "wyoming"
+tts-wyoming-voice = "en_US-ryan-high"
+tts-speed = 1.0
+
+[transcribe]
+# By default, transcription uses local providers.
+# For higher accuracy, you can switch to OpenAI:
+# asr-provider = "openai"
+# llm-provider = "openai"
+# Enable LLM cleanup for the transcript.
+llm = true
+# Allow the user to provide additional instructions for the LLM.
+# Use this to improve transcription accuracy for domain-specific terms.
+extra-instructions = """
+Assume the user is often discussing Python programming.
+Use backticks for variable names, function names, and other code elements.
+Follow PEP8: use `snake_case` for variables, functions, and package names; `CamelCase` for classes.
+"""
+# Log all transcriptions with timestamps for later reference.
+# transcription-log = "~/.config/agent-cli/transcription.log"
+
+[voice-edit]
+# Use a powerful local model for the voice assistant.
+llm-provider = "ollama"
+llm-ollama-model = "llama3"
+enable_tts = true
+
+[rag-proxy]
+# RAG (Retrieval-Augmented Generation) proxy server settings.
+# docs-folder = "./rag_docs"  # Folder to watch for documents
+# chroma-path = "./rag_db"  # Path to ChromaDB persistence directory
+# limit = 3  # Number of document chunks to retrieve per query
+# rag-tools = true  # Allow agent to fetch full documents when snippets are insufficient
+# host = "0.0.0.0"
+# port = 8000
+
+[memory.proxy]
+# Long-term memory proxy server settings.
+# memory-path = "./memory_db"  # Path to the memory store
+# default-top-k = 5  # Number of memory entries to retrieve per query
+# max-entries = 500  # Maximum stored memory entries per conversation
+# mmr-lambda = 0.7  # MMR lambda (0-1): higher favors relevance, lower favors diversity
+# recency-weight = 0.2  # Recency score weight (0.0-1.0)
+# score-threshold = 0.35  # Minimum semantic relevance threshold
+# summarization = true  # Enable automatic fact extraction and summaries
+# git-versioning = true  # Enable automatic git commit of memory changes
+# host = "0.0.0.0"
+# port = 8100
+
+[transcribe-daemon]
+# Continuous transcription settings
+# role = "user"
+# silence-threshold = 1.0
+# min-segment = 0.25
+# vad-threshold = 0.3
+# save-audio = true
+# audio-dir = "~/.config/agent-cli/audio"
+# transcription-log = "~/.config/agent-cli/transcriptions.jsonl"
+# clipboard = false
+
+[server]
+# Transcription server settings
+# host = "0.0.0.0"
+# port = 61337
+# reload = false

agent_cli/install/__init__.py

@@ -0,0 +1,5 @@
+"""Installation commands for agent-cli."""
+
+from __future__ import annotations
+
+__all__ = ["extras", "hotkeys", "services"]

agent_cli/install/common.py

@@ -0,0 +1,89 @@
+"""Common utilities for installation commands."""
+
+from __future__ import annotations
+
+import platform
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+from agent_cli.core.utils import print_error_message, print_with_style
+
+if TYPE_CHECKING:
+    from subprocess import CompletedProcess
+
+
+def _script_directory() -> Path:
+    """Get the directory containing all scripts."""
+    # First check if we're running from source (development)
+    source_scripts = Path(__file__).parent.parent.parent / "scripts"
+    if source_scripts.exists():
+        return source_scripts
+    # Check for scripts bundled with the package
+    package_scripts = Path(__file__).parent.parent / "scripts"
+    if package_scripts.exists():
+        return package_scripts
+    msg = "Should never happen: no scripts directory found, please report an issue."
+    raise RuntimeError(msg)
+
+
+def get_script_path(script_name: str) -> Path:
+    """Get the path to a script in the scripts directory."""
+    script_dir = _script_directory()
+    return script_dir / script_name
+
+
+def _run_script(script_path: Path) -> CompletedProcess[bytes]:
+    """Run a shell script, streaming its output directly to the terminal."""
+    if not script_path.exists():
+        msg = f"Script not found: {script_path}"
+        raise FileNotFoundError(msg)
+
+    # Run the script through the shell, which handles execution permissions
+    # This avoids modifying file permissions in the package directory
+    return subprocess.run(
+        ["bash", str(script_path)],  # noqa: S607
+        check=True,
+        cwd=script_path.parent,
+    )
+
+
+def get_platform_script(macos_script: str, linux_script: str) -> str:
+    """Get the appropriate script name based on the platform."""
+    system = platform.system().lower()
+
+    if system == "darwin":
+        return macos_script
+    if system == "linux":
+        return linux_script
+    print_error_message(f"Unsupported operating system: {system}")
+    raise typer.Exit(1) from None
+
+
+def execute_installation_script(
+    script_name: str,
+    operation_name: str,
+    success_message: str,
+    next_steps: list[str] | None = None,
+) -> None:
+    """Execute an installation script with standard error handling."""
+    script_path = get_script_path(script_name)
+    print_with_style(f"🚀 Running {script_name} to {operation_name.lower()}...", "green")
+
+    try:
+        _run_script(script_path)
+        print_with_style(f"✅ {success_message}", "green")
+        if next_steps:
+            print_with_style("\nNext steps:", "yellow")
+            for i, step in enumerate(next_steps, 1):
+                print_with_style(f"  {i}. {step}", "cyan")
+    except FileNotFoundError as e:
+        # This case is for when the script file itself is not found
+        print_error_message(f"{operation_name} failed: {e}")
+        raise typer.Exit(1) from None
+    except subprocess.CalledProcessError as e:
+        # This case handles non-zero exit codes from the script
+        print_error_message(f"{operation_name} failed with exit code {e.returncode}")
+        raise typer.Exit(e.returncode) from None