agent-cli 0.66.2__py3-none-any.whl → 0.67.1__py3-none-any.whl

agent_cli/core/deps.py

@@ -2,22 +2,138 @@
 
 from __future__ import annotations
 
+import functools
+import json
 from importlib.util import find_spec
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeVar
 
+import typer
 
-def ensure_optional_dependencies(
-    required: dict[str, str],
-    *,
-    extra_name: str,
-    install_hint: str | None = None,
-) -> None:
-    """Ensure optional dependencies are present, otherwise raise ImportError."""
-    missing = [
-        pkg_name for module_name, pkg_name in required.items() if find_spec(module_name) is None
+from agent_cli.core.utils import print_error_message
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+F = TypeVar("F", bound="Callable[..., object]")
+
+# Load extras from JSON file
+_EXTRAS_FILE = Path(__file__).parent.parent / "_extras.json"
+EXTRAS: dict[str, tuple[str, list[str]]] = {
+    k: (v[0], v[1]) for k, v in json.loads(_EXTRAS_FILE.read_text()).items()
+}
+
+
+def _check_package_installed(pkg: str) -> bool:
+    """Check if a single package is installed."""
+    top_module = pkg.split(".")[0]
+    try:
+        return find_spec(top_module) is not None
+    except (ValueError, ModuleNotFoundError):
+        return False
+
+
+def check_extra_installed(extra: str) -> bool:
+    """Check if packages for an extra are installed using find_spec (no actual import).
+
+    Supports `|` syntax for alternatives: "piper|kokoro" means ANY of these extras.
+    For regular extras, ALL packages must be installed.
+    """
+    # Handle "extra1|extra2" syntax - any of these extras is sufficient
+    if "|" in extra:
+        return any(check_extra_installed(e) for e in extra.split("|"))
+
+    if extra not in EXTRAS:
+        return True  # Unknown extra, assume OK
+    _, packages = EXTRAS[extra]
+
+    # All packages must be installed
+    return all(_check_package_installed(pkg) for pkg in packages)
+
+
+def get_install_hint(extra: str) -> str:
+    """Get install command hint for an extra.
+
+    Supports `|` syntax for alternatives: "piper|kokoro" shows both options.
+    """
+    # Handle "extra1|extra2" syntax - show all options
+    if "|" in extra:
+        alternatives = extra.split("|")
+        options = []
+        for alt in alternatives:
+            desc, _ = EXTRAS.get(alt, ("", []))
+            options.append((alt, desc))
+
+        lines = ["This command requires one of:"]
+        for alt, desc in options:
+            if desc:
+                lines.append(f"  - '{alt}' ({desc})")
+            else:
+                lines.append(f"  - '{alt}'")
+        lines.append("")
+        lines.append("Install one with:")
+        for alt, _ in options:
+            lines.append(f'  uv tool install "agent-cli[{alt}]" -p 3.13')
+        lines.append("  # or")
+        for alt, _ in options:
+            lines.append(f"  agent-cli install-extras {alt}")
+        return "\n".join(lines)
+
+    desc, _ = EXTRAS.get(extra, ("", []))
+    lines = [
+        f"This command requires the '{extra}' extra",
     ]
-    if not missing:
-        return
+    if desc:
+        lines[0] += f" ({desc})"
+    lines[0] += "."
+    lines.append("")
+    lines.append("Install with:")
+    lines.append(f'  uv tool install "agent-cli[{extra}]" -p 3.13')
+    lines.append("  # or")
+    lines.append(f"  agent-cli install-extras {extra}")
+    return "\n".join(lines)
+
+
+def requires_extras(*extras: str) -> Callable[[F], F]:
+    """Decorator to declare required extras for a command.
+
+    When a required extra is missing, the decorator prints a helpful error
+    message and exits with code 1.
+
+    The decorator stores the required extras on the function for test validation.
+
+    Process management flags (--stop, --status, --toggle) skip the dependency
+    check since they just manage running processes without using the actual
+    dependencies.
+
+    Example:
+        @app.command("rag-proxy")
+        @requires_extras("rag")
+        def rag_proxy(...):
+            ...
+
+    """
+
+    def decorator(func: F) -> F:
+        # Store extras on function for test introspection
+        func._required_extras = extras  # type: ignore[attr-defined]
+
+        @functools.wraps(func)
+        def wrapper(*args: object, **kwargs: object) -> object:
+            # Skip dependency check for process management and info operations
+            # These don't need the actual dependencies, just manage processes or list info
+            if any(kwargs.get(flag) for flag in ("stop", "status", "toggle", "list_devices")):
+                return func(*args, **kwargs)
+
+            missing = [e for e in extras if not check_extra_installed(e)]
+            if missing:
+                for extra in missing:
+                    print_error_message(get_install_hint(extra))
+                raise typer.Exit(1)
+            return func(*args, **kwargs)
+
+        # Preserve the extras on wrapper too
+        wrapper._required_extras = extras  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
 
-    hint = install_hint or f"`pip install agent-cli[{extra_name}]`"
-    msg = f"Missing required dependencies for {extra_name}: {', '.join(missing)}. Please install with {hint}."
-    raise ImportError(msg)
+    return decorator

agent_cli/dev/skill/SKILL.md

@@ -13,10 +13,10 @@ If `agent-cli` is not available, install it first:
 
 ```bash
 # Install globally
-uv tool install agent-cli
+uv tool install agent-cli -p 3.13
 
 # Or run directly without installing
-uvx agent-cli dev new <branch-name> --agent --prompt "..."
+uvx --python 3.13 agent-cli dev new <branch-name> --agent --prompt "..."
 ```
 
 ## When to spawn parallel agents

agent_cli/docs_gen.py

@@ -16,7 +16,6 @@ Example usage in Markdown files:
 
 from __future__ import annotations
 
-from pathlib import Path
 from typing import Any, get_origin
 
 import click
@@ -369,47 +368,6 @@ def config_example(command_path: str | None = None) -> str:
     return "\n".join(lines)
 
 
-def readme_section(section_name: str) -> str:
-    """Extract a section from README.md for reuse in other docs.
-
-    Sections are marked with HTML comments like:
-        <!-- SECTION:section_name:START -->
-        Content here...
-        <!-- SECTION:section_name:END -->
-
-    Args:
-        section_name: The name of the section to extract (e.g., "why-i-built-this")
-
-    Returns:
-        The content between the section markers (without the markers themselves)
-
-    """
-    # Find the README.md relative to this module
-    readme_path = Path(__file__).parent.parent / "README.md"
-    if not readme_path.exists():
-        return f"*Could not find README.md at {readme_path}*"
-
-    content = readme_path.read_text()
-
-    # Look for section markers
-    start_marker = f"<!-- SECTION:{section_name}:START -->"
-    end_marker = f"<!-- SECTION:{section_name}:END -->"
-
-    start_idx = content.find(start_marker)
-    if start_idx == -1:
-        return f"*Section '{section_name}' not found in README.md*"
-
-    end_idx = content.find(end_marker, start_idx)
-    if end_idx == -1:
-        return f"*End marker for section '{section_name}' not found in README.md*"
-
-    # Extract content between markers (excluding the markers themselves)
-    section_content = content[start_idx + len(start_marker) : end_idx]
-
-    # Strip leading/trailing whitespace but preserve internal formatting
-    return section_content.strip()
-
-
 def all_options_for_docs(command_path: str) -> str:
     """Generate complete options documentation for a command page.
 

agent_cli/install/extras.py

@@ -12,20 +12,11 @@ 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
 
-# Extra name -> description mapping (used for docs generation)
-EXTRAS: dict[str, str] = {
-    "rag": "RAG proxy (ChromaDB, embeddings)",
-    "memory": "Long-term memory proxy",
-    "vad": "Voice Activity Detection (silero-vad)",
-    "whisper": "Local Whisper ASR (faster-whisper)",
-    "whisper-mlx": "MLX Whisper for Apple Silicon",
-    "tts": "Local Piper TTS",
-    "tts-kokoro": "Kokoro neural TTS",
-    "server": "FastAPI server components",
-    "speed": "Audio speed adjustment (audiostretchy)",
-}
+# Extract descriptions from the centralized EXTRAS metadata
+EXTRAS: dict[str, str] = {name: desc for name, (desc, _) in _EXTRAS_META.items()}
 
 
 def _requirements_dir() -> Path:
@@ -72,8 +63,9 @@ def _install_via_uv_tool(extras: list[str]) -> bool:
     """Reinstall agent-cli via uv tool with the specified extras."""
     extras_str = ",".join(extras)
     package_spec = f"agent-cli[{extras_str}]"
-    console.print(f"Reinstalling via uv tool: [cyan]{package_spec}[/]")
-    cmd = ["uv", "tool", "install", package_spec, "--force"]
+    python_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    console.print(f"Reinstalling via uv tool: [cyan]{package_spec}[/] (Python {python_version})")
+    cmd = ["uv", "tool", "install", package_spec, "--force", "--python", python_version]
     result = subprocess.run(cmd, check=False)
     return result.returncode == 0
 

agent_cli/memory/__init__.py

@@ -2,23 +2,6 @@
 
 from __future__ import annotations
 
-from agent_cli.core.deps import ensure_optional_dependencies
-
-_REQUIRED_DEPS = {
-    "chromadb": "chromadb",
-    "fastapi": "fastapi",
-    "uvicorn": "uvicorn",
-    "onnxruntime": "onnxruntime",
-    "huggingface_hub": "huggingface-hub",
-    "transformers": "transformers",
-}
-
-ensure_optional_dependencies(
-    _REQUIRED_DEPS,
-    extra_name="memory",
-    install_hint="`pip install agent-cli[memory]` or `uv sync --extra memory`",
-)
-
-from agent_cli.memory.client import MemoryClient  # noqa: E402
+from agent_cli.memory.client import MemoryClient
 
 __all__ = ["MemoryClient"]

agent_cli/rag/__init__.py

@@ -1,22 +1,3 @@
 """RAG module."""
 
 from __future__ import annotations
-
-from agent_cli.core.deps import ensure_optional_dependencies
-
-_REQUIRED_DEPS = {
-    "chromadb": "chromadb",
-    "watchfiles": "watchfiles",
-    "markitdown": "markitdown",
-    "fastapi": "fastapi",
-    "uvicorn": "uvicorn",
-    "onnxruntime": "onnxruntime",
-    "huggingface_hub": "huggingface-hub",
-    "transformers": "transformers",
-}
-
-ensure_optional_dependencies(
-    _REQUIRED_DEPS,
-    extra_name="rag",
-    install_hint="`pip install agent-cli[rag]` or `uv sync --extra rag`",
-)

agent_cli/scripts/sync_extras.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Generate _extras.json from pyproject.toml.
+
+This script parses the optional-dependencies in pyproject.toml and generates
+the agent_cli/_extras.json file with package-to-import mappings.
+
+Usage:
+    python scripts/sync_extras.py
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).parent.parent
+PYPROJECT = REPO_ROOT / "pyproject.toml"
+EXTRAS_FILE = REPO_ROOT / "agent_cli" / "_extras.json"
+
+# Extras to skip (dev/test dependencies, not runtime installable)
+SKIP_EXTRAS = {"dev", "test"}
+
+# Manual mapping of extra name -> (description, list of import names)
+# Import names should be the Python module name (how you import it)
+# Bundle extras (voice, cloud, full) have empty import lists since they just install other extras
+EXTRA_METADATA: dict[str, tuple[str, list[str]]] = {
+    # Provider extras (base dependencies now optional)
+    "audio": ("Audio recording/playback", ["sounddevice"]),
+    "wyoming": ("Wyoming protocol support", ["wyoming"]),
+    "openai": ("OpenAI API provider", ["openai"]),
+    "gemini": ("Google Gemini provider", ["google.genai"]),
+    "llm": ("LLM framework (pydantic-ai)", ["pydantic_ai"]),
+    # Feature extras
+    "rag": ("RAG proxy (ChromaDB, embeddings)", ["chromadb"]),
+    "memory": ("Long-term memory proxy", ["chromadb", "yaml"]),
+    "vad": ("Voice Activity Detection (silero-vad)", ["silero_vad"]),
+    "whisper": ("Local Whisper ASR (faster-whisper)", ["faster_whisper"]),
+    "whisper-mlx": ("MLX Whisper for Apple Silicon", ["mlx_whisper"]),
+    "tts": ("Local Piper TTS", ["piper"]),
+    "tts-kokoro": ("Kokoro neural TTS", ["kokoro"]),
+    "server": ("FastAPI server components", ["fastapi"]),
+    "speed": ("Audio speed adjustment (audiostretchy)", ["audiostretchy"]),
+}
+
+
+def get_extras_from_pyproject() -> set[str]:
+    """Parse optional-dependencies from pyproject.toml."""
+    with PYPROJECT.open("rb") as f:
+        data = tomllib.load(f)
+    all_extras = set(data.get("project", {}).get("optional-dependencies", {}).keys())
+    return all_extras - SKIP_EXTRAS
+
+
+def extract_package_name(dep: str) -> str:
+    """Extract the package name from a dependency specification.
+
+    Examples:
+        "chromadb>=0.4.22" -> "chromadb"
+        "pydantic-ai-slim[openai,duckduckgo]" -> "pydantic-ai-slim"
+        'mlx-whisper>=0.4.0; sys_platform == "darwin"' -> "mlx-whisper"
+
+    """
+    # Remove markers (;...) and extras ([...])
+    dep = re.split(r"[;\[]", dep)[0]
+    # Remove version specifiers
+    dep = re.split(r"[<>=!~]", dep)[0]
+    return dep.strip()
+
+
+def package_to_import_name(package: str) -> str:
+    """Convert a package name to its Python import name.
+
+    Examples:
+        "google-genai" -> "google.genai"
+        "pydantic-ai-slim" -> "pydantic_ai"
+        "silero-vad" -> "silero_vad"
+        "faster-whisper" -> "faster_whisper"
+
+    """
+    # Special cases where the import name differs significantly
+    special_cases = {
+        "google-genai": "google.genai",
+        "pydantic-ai-slim": "pydantic_ai",
+        "silero-vad": "silero_vad",
+        "faster-whisper": "faster_whisper",
+        "mlx-whisper": "mlx_whisper",
+        "piper-tts": "piper",
+        "huggingface-hub": "huggingface_hub",
+        "fastapi": "fastapi",
+        "audiostretchy": "audiostretchy",
+    }
+    if package in special_cases:
+        return special_cases[package]
+    # Default: replace hyphens with underscores
+    return package.replace("-", "_")
+
+
+def generate_extras_json(extras: set[str]) -> dict[str, list]:
+    """Generate the content for _extras.json."""
+    result = {}
+    for extra in sorted(extras):
+        if extra in EXTRA_METADATA:
+            desc, imports = EXTRA_METADATA[extra]
+            result[extra] = [desc, imports]
+        else:
+            # Unknown extra - add a placeholder
+            result[extra] = ["TODO: add description", []]
+    return result
+
+
+def check_missing_metadata(extras: set[str]) -> list[str]:
+    """Check for extras that don't have metadata defined."""
+    return [e for e in extras if e not in EXTRA_METADATA]
+
+
+def main() -> int:
+    """Generate _extras.json from pyproject.toml."""
+    extras = get_extras_from_pyproject()
+
+    # Check for missing metadata
+    missing = check_missing_metadata(extras)
+    if missing:
+        print(f"Warning: The following extras need metadata in EXTRA_METADATA: {missing}")
+        print("Please update EXTRA_METADATA in scripts/sync_extras.py")
+
+    # Generate the file
+    content = generate_extras_json(extras)
+    EXTRAS_FILE.write_text(json.dumps(content, indent=2) + "\n")
+    print(f"Generated {EXTRAS_FILE}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_cli/server/cli.py

@@ -12,6 +12,7 @@ import typer
 from rich.console import Console
 
 from agent_cli.cli import app as main_app
+from agent_cli.core.deps import requires_extras
 from agent_cli.core.process import set_process_title
 from agent_cli.server.common import setup_rich_logging
 
@@ -163,6 +164,7 @@ def _check_whisper_deps(backend: str, *, download_only: bool = False) -> None:
 
 
 @app.command("whisper")
+@requires_extras("server", "faster-whisper|mlx-whisper")
 def whisper_cmd(  # noqa: PLR0912, PLR0915
     model: Annotated[
         list[str] | None,
@@ -422,6 +424,7 @@ def whisper_cmd(  # noqa: PLR0912, PLR0915
 
 
 @app.command("transcription-proxy")
+@requires_extras("server")
 def transcription_proxy_cmd(
     host: Annotated[
         str,
@@ -475,6 +478,7 @@ def transcription_proxy_cmd(
 
 
 @app.command("tts")
+@requires_extras("server", "piper|kokoro")
 def tts_cmd(  # noqa: PLR0915
     model: Annotated[
         list[str] | None,

agent_cli/services/_wyoming_utils.py

@@ -5,14 +5,14 @@ from __future__ import annotations
 from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING
 
-from wyoming.client import AsyncClient
-
 from agent_cli.core.utils import print_error_message
 
 if TYPE_CHECKING:
     import logging
     from collections.abc import AsyncGenerator
 
+    from wyoming.client import AsyncClient
+
 
 @asynccontextmanager
 async def wyoming_client_context(
@@ -40,6 +40,8 @@ async def wyoming_client_context(
         Exception: For other connection errors
 
     """
+    from wyoming.client import AsyncClient  # noqa: PLC0415
+
     uri = f"tcp://{server_ip}:{server_port}"
     logger.info("Connecting to Wyoming %s server at %s", server_type, uri)
 

agent_cli/services/asr.py

@@ -10,9 +10,6 @@ from functools import partial
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from wyoming.asr import Transcribe, Transcript, TranscriptChunk, TranscriptStart, TranscriptStop
-from wyoming.audio import AudioChunk, AudioStart, AudioStop
-
 from agent_cli import constants
 from agent_cli.core.audio import (
     open_audio_stream,
@@ -225,6 +222,9 @@ async def _send_audio(
     initial_prompt: str | None = None,
 ) -> None:
     """Read from mic and send to Wyoming server."""
+    from wyoming.asr import Transcribe  # noqa: PLC0415
+    from wyoming.audio import AudioChunk, AudioStart, AudioStop  # noqa: PLC0415
+
     # Build context with initial_prompt if provided
     context = {"initial_prompt": initial_prompt} if initial_prompt else None
     await client.write_event(Transcribe(context=context).event())
@@ -282,6 +282,13 @@ async def _receive_transcript(
     final_callback: Callable[[str], None] | None = None,
 ) -> str:
     """Receive transcription events and return the final transcript."""
+    from wyoming.asr import (  # noqa: PLC0415
+        Transcript,
+        TranscriptChunk,
+        TranscriptStart,
+        TranscriptStop,
+    )
+
     transcript_text = ""
     while True:
         event = await client.read_event()
@@ -370,6 +377,9 @@ async def _transcribe_recorded_audio_wyoming(
     **_kwargs: object,
 ) -> str:
     """Process pre-recorded audio data with Wyoming ASR server."""
+    from wyoming.asr import Transcribe  # noqa: PLC0415
+    from wyoming.audio import AudioChunk, AudioStart, AudioStop  # noqa: PLC0415
+
     try:
         async with wyoming_client_context(
             wyoming_asr_cfg.asr_wyoming_ip,

agent_cli/services/tts.py

@@ -10,8 +10,6 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from rich.live import Live
-from wyoming.audio import AudioChunk, AudioStart, AudioStop
-from wyoming.tts import Synthesize, SynthesizeVoice
 
 from agent_cli import config, constants
 from agent_cli.core.audio import open_audio_stream, setup_output_stream
@@ -32,6 +30,7 @@ if TYPE_CHECKING:
 
     from rich.live import Live
     from wyoming.client import AsyncClient
+    from wyoming.tts import Synthesize
 
 
 has_audiostretchy = importlib.util.find_spec("audiostretchy") is not None
@@ -134,6 +133,8 @@ def _create_synthesis_request(
     speaker: str | None = None,
 ) -> Synthesize:
     """Create a synthesis request with optional voice parameters."""
+    from wyoming.tts import Synthesize, SynthesizeVoice  # noqa: PLC0415
+
     synthesize_event = Synthesize(text=text)
 
     # Add voice parameters if specified
@@ -152,6 +153,8 @@ async def _process_audio_events(
     logger: logging.Logger,
 ) -> tuple[bytes, int | None, int | None, int | None]:
     """Process audio events from TTS server and return audio data with metadata."""
+    from wyoming.audio import AudioChunk, AudioStart, AudioStop  # noqa: PLC0415
+
     audio_data = io.BytesIO()
     sample_rate = None
     sample_width = None

agent_cli/services/wake_word.py

@@ -6,9 +6,6 @@ import asyncio
 from functools import partial
 from typing import TYPE_CHECKING
 
-from wyoming.audio import AudioChunk, AudioStart, AudioStop
-from wyoming.wake import Detect, Detection, NotDetected
-
 from agent_cli import config, constants
 from agent_cli.core.audio import read_from_queue
 from agent_cli.core.utils import manage_send_receive_tasks
@@ -38,6 +35,8 @@ async def _send_audio_from_queue_for_wake_detection(
     progress_message: str,
 ) -> None:
     """Read from a queue and send to Wyoming wake word server."""
+    from wyoming.audio import AudioChunk, AudioStart, AudioStop  # noqa: PLC0415
+
     await client.write_event(AudioStart(**constants.WYOMING_AUDIO_CONFIG).event())
     seconds_streamed = 0.0
 
@@ -76,6 +75,8 @@ async def _receive_wake_detection(
         Name of detected wake word or None if no detection
 
     """
+    from wyoming.wake import Detection, NotDetected  # noqa: PLC0415
+
     while True:
         event = await client.read_event()
         if event is None:
@@ -108,6 +109,8 @@ async def _detect_wake_word_from_queue(
     progress_message: str = "Listening for wake word",
 ) -> str | None:
     """Detect wake word from an audio queue."""
+    from wyoming.wake import Detect  # noqa: PLC0415
+
     try:
         async with wyoming_client_context(
             wake_word_cfg.wake_server_ip,