agent-cli 0.70.5__py3-none-any.whl

agent_cli/core/audio_format.py

@@ -0,0 +1,299 @@
+"""Audio format conversion utilities using FFmpeg."""
+
+from __future__ import annotations
+
+import io
+import logging
+import shutil
+import subprocess
+import tempfile
+import wave
+from pathlib import Path
+from typing import NamedTuple
+
+from agent_cli import constants
+
+logger = logging.getLogger(__name__)
+
+VALID_EXTENSIONS = (".wav", ".mp3", ".m4a", ".flac", ".ogg", ".aac", ".webm")
+
+
+class WavPcmData(NamedTuple):
+    """PCM data and parameters extracted from a WAV file."""
+
+    pcm_data: bytes
+    sample_rate: int
+    num_channels: int
+    sample_width: int
+
+
+def extract_pcm_from_wav(wav_bytes: bytes) -> WavPcmData:
+    """Extract raw PCM data and WAV parameters from WAV bytes.
+
+    Args:
+        wav_bytes: WAV file data as bytes.
+
+    Returns:
+        WavPcmData with pcm_data, sample_rate, num_channels, sample_width.
+
+    Raises:
+        wave.Error: If the data is not a valid WAV file.
+
+    """
+    with io.BytesIO(wav_bytes) as buf, wave.open(buf, "rb") as wav_file:
+        return WavPcmData(
+            pcm_data=wav_file.readframes(wav_file.getnframes()),
+            sample_rate=wav_file.getframerate(),
+            num_channels=wav_file.getnchannels(),
+            sample_width=wav_file.getsampwidth(),
+        )
+
+
+def is_valid_audio_file(value: object) -> bool:
+    """Check if the provided value is a valid audio file.
+
+    Works with FastAPI UploadFile or any object with filename and content_type attributes.
+
+    Args:
+        value: Object to check (typically an UploadFile).
+
+    Returns:
+        True if the object appears to be a valid audio file.
+
+    """
+    filename = getattr(value, "filename", None)
+    content_type = getattr(value, "content_type", None)
+
+    if not filename and not content_type:
+        return False
+
+    if content_type and content_type.startswith("audio/"):
+        return True
+    return bool(filename and str(filename).lower().endswith(VALID_EXTENSIONS))
+
+
+def convert_audio_to_wyoming_format(
+    audio_data: bytes,
+    source_filename: str,
+) -> bytes:
+    """Convert audio data to Wyoming-compatible format using FFmpeg.
+
+    Args:
+        audio_data: Raw audio data
+        source_filename: Source filename to help FFmpeg detect format
+
+    Returns:
+        Converted audio data as raw PCM bytes (16kHz, 16-bit, mono)
+
+    Raises:
+        RuntimeError: If FFmpeg is not available or conversion fails
+
+    """
+    # Check if FFmpeg is available
+    if not shutil.which("ffmpeg"):
+        msg = "FFmpeg not found in PATH. Please install FFmpeg to convert audio formats."
+        raise RuntimeError(msg)
+
+    # Create temporary files for input and output
+    suffix = _get_file_extension(source_filename)
+    with (
+        tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as input_file,
+        tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as output_file,
+    ):
+        input_path = Path(input_file.name)
+        output_path = Path(output_file.name)
+
+        try:
+            # Write input audio data
+            input_file.write(audio_data)
+            input_file.flush()
+
+            # Build FFmpeg command to convert to Wyoming format
+            # -f s16le: 16-bit signed little-endian PCM
+            # -ar 16000: 16kHz sample rate
+            # -ac 1: mono (1 channel)
+            cmd = [
+                "ffmpeg",
+                "-y",
+                "-i",
+                str(input_path),
+                "-f",
+                "s16le",
+                "-ar",
+                str(constants.AUDIO_RATE),
+                "-ac",
+                str(constants.AUDIO_CHANNELS),
+                str(output_path),
+            ]
+
+            logger.debug("Running FFmpeg command: %s", " ".join(cmd))
+
+            # Run FFmpeg
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=False,
+                check=False,
+            )
+
+            if result.returncode != 0:
+                stderr_text = result.stderr.decode("utf-8", errors="replace")
+                logger.error("FFmpeg failed with return code %d", result.returncode)
+                logger.error("FFmpeg stderr: %s", stderr_text)
+                msg = f"FFmpeg conversion failed: {stderr_text}"
+                raise RuntimeError(msg)
+
+            # Read converted audio data
+            return output_path.read_bytes()
+
+        finally:
+            # Clean up temporary files
+            input_path.unlink(missing_ok=True)
+            output_path.unlink(missing_ok=True)
+
+
+def _get_file_extension(filename: str) -> str:
+    """Get file extension from filename, defaulting to .tmp.
+
+    Args:
+        filename: Source filename
+
+    Returns:
+        File extension including the dot
+
+    """
+    filename = str(filename).lower()
+
+    for ext in VALID_EXTENSIONS:
+        if filename.endswith(ext):
+            return ext
+
+    return ".tmp"
+
+
+def check_ffmpeg_available() -> bool:
+    """Check if FFmpeg is available in the system PATH.
+
+    Returns:
+        True if FFmpeg is available, False otherwise
+
+    """
+    return shutil.which("ffmpeg") is not None
+
+
+def _run_ffmpeg(
+    cmd: list[str],
+    timeout: int | None,
+) -> None:
+    """Run ffmpeg command with error handling."""
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            check=False,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as e:
+        msg = f"FFmpeg conversion timed out after {timeout} seconds"
+        raise RuntimeError(msg) from e
+
+    if result.returncode != 0:
+        stderr_text = result.stderr.decode("utf-8", errors="replace")
+        logger.error("FFmpeg MP3 conversion failed: %s", stderr_text)
+        msg = f"FFmpeg MP3 conversion failed: {stderr_text}"
+        raise RuntimeError(msg)
+
+
+def convert_to_mp3(
+    audio_data: bytes,
+    *,
+    input_format: str = "wav",
+    sample_rate: int | None = None,
+    channels: int | None = None,
+    bitrate: str = "128k",
+    timeout: int | None = 60,
+) -> bytes:
+    """Convert audio data to MP3 format using FFmpeg.
+
+    Args:
+        audio_data: Audio data as bytes.
+        input_format: Input format - "wav" (auto-detected) or "pcm" (raw s16le).
+        sample_rate: Sample rate in Hz (required if input_format is "pcm").
+        channels: Number of channels (required if input_format is "pcm").
+        bitrate: MP3 bitrate (e.g., "128k", "192k").
+        timeout: Timeout in seconds for FFmpeg, or None for no timeout.
+
+    Returns:
+        MP3 audio data as bytes.
+
+    Raises:
+        RuntimeError: If FFmpeg is not available or conversion fails.
+        ValueError: If input_format is "pcm" but sample_rate or channels not provided.
+
+    """
+    if input_format == "pcm" and (sample_rate is None or channels is None):
+        msg = "sample_rate and channels are required when input_format is 'pcm'"
+        raise ValueError(msg)
+
+    if not shutil.which("ffmpeg"):
+        msg = "FFmpeg not found in PATH. Please install FFmpeg for MP3 conversion."
+        raise RuntimeError(msg)
+
+    input_suffix = ".wav" if input_format == "wav" else ".raw"
+    tmp_dir = Path(tempfile.mkdtemp())
+    input_path = tmp_dir / f"input{input_suffix}"
+    output_path = tmp_dir / "output.mp3"
+
+    try:
+        input_path.write_bytes(audio_data)
+
+        cmd = ["ffmpeg", "-y"]
+        if input_format == "pcm":
+            cmd.extend(["-f", "s16le", "-ar", str(sample_rate), "-ac", str(channels)])
+        cmd.extend(["-i", str(input_path), "-b:a", bitrate, "-q:a", "2", str(output_path)])
+
+        logger.debug("Running FFmpeg MP3 conversion: %s", " ".join(cmd))
+        _run_ffmpeg(cmd, timeout)
+
+        return output_path.read_bytes()
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+def save_audio_as_mp3(
+    audio_data: bytes,
+    output_path: Path,
+    sample_rate: int = constants.AUDIO_RATE,
+    channels: int = constants.AUDIO_CHANNELS,
+    bitrate: str = "64k",
+) -> Path:
+    """Convert raw PCM audio data to MP3 format and save to file.
+
+    Args:
+        audio_data: Raw PCM audio data (16-bit signed little-endian).
+        output_path: Path where the MP3 file will be saved.
+        sample_rate: Audio sample rate in Hz.
+        channels: Number of audio channels.
+        bitrate: MP3 bitrate (e.g., "128k", "192k", "256k").
+
+    Returns:
+        Path to the saved MP3 file.
+
+    Raises:
+        RuntimeError: If FFmpeg is not available or conversion fails.
+
+    """
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    mp3_data = convert_to_mp3(
+        audio_data,
+        input_format="pcm",
+        sample_rate=sample_rate,
+        channels=channels,
+        bitrate=bitrate,
+        timeout=None,
+    )
+
+    output_path.write_bytes(mp3_data)
+    logger.debug("Saved MP3 to %s", output_path)
+    return output_path

agent_cli/core/chroma.py

@@ -0,0 +1,88 @@
+"""Shared ChromaDB helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from agent_cli.constants import DEFAULT_OPENAI_EMBEDDING_MODEL
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+    from chromadb import Collection
+    from pydantic import BaseModel
+
+
+def init_collection(
+    persistence_path: Path,
+    *,
+    name: str,
+    embedding_model: str = DEFAULT_OPENAI_EMBEDDING_MODEL,
+    openai_base_url: str | None = None,
+    openai_api_key: str | None = None,
+    subdir: str | None = None,
+) -> Collection:
+    """Initialize a Chroma collection with OpenAI-compatible embeddings."""
+    import chromadb  # noqa: PLC0415
+    from chromadb.config import Settings  # noqa: PLC0415
+    from chromadb.utils import embedding_functions  # noqa: PLC0415
+
+    target_path = persistence_path / subdir if subdir else persistence_path
+    target_path.mkdir(parents=True, exist_ok=True)
+    client = chromadb.PersistentClient(
+        path=str(target_path),
+        settings=Settings(anonymized_telemetry=False),
+    )
+    embed_fn = embedding_functions.OpenAIEmbeddingFunction(
+        api_base=openai_base_url,
+        api_key=openai_api_key or "dummy",
+        model_name=embedding_model,
+    )
+    return client.get_or_create_collection(name=name, embedding_function=embed_fn)
+
+
+def flatten_metadatas(metadatas: Sequence[BaseModel]) -> list[dict[str, Any]]:
+    """Serialize metadata models to JSON-safe dicts while preserving lists."""
+    return [meta.model_dump(mode="json", exclude_none=True) for meta in metadatas]
+
+
+def upsert(
+    collection: Collection,
+    *,
+    ids: list[str],
+    documents: list[str],
+    metadatas: Sequence[BaseModel],
+    batch_size: int = 10,
+) -> None:
+    """Upsert documents with JSON-serialized metadata.
+
+    Args:
+        collection: ChromaDB collection.
+        ids: Document IDs.
+        documents: Document contents.
+        metadatas: Pydantic metadata models.
+        batch_size: Max documents per embedding API call (default: 10).
+
+    """
+    if not ids:
+        return
+    serialized = flatten_metadatas(metadatas)
+
+    # Process in batches to avoid overwhelming the embedding service
+    for i in range(0, len(ids), batch_size):
+        batch_ids = ids[i : i + batch_size]
+        batch_docs = documents[i : i + batch_size]
+        batch_metas = serialized[i : i + batch_size]
+        collection.upsert(ids=batch_ids, documents=batch_docs, metadatas=batch_metas)
+
+
+def delete(collection: Collection, ids: list[str]) -> None:
+    """Delete documents by ID."""
+    if ids:
+        collection.delete(ids=ids)
+
+
+def delete_where(collection: Collection, where: Mapping[str, Any]) -> None:
+    """Delete documents by a filter."""
+    collection.delete(where=where)

agent_cli/core/deps.py

@@ -0,0 +1,191 @@
+"""Helpers for optional dependency checks."""
+
+from __future__ import annotations
+
+import functools
+import json
+import os
+from importlib.util import find_spec
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeVar
+
+import typer
+
+from agent_cli.config import load_config
+from agent_cli.core.utils import console, print_error_message
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+F = TypeVar("F", bound="Callable[..., object]")
+
+
+def _get_auto_install_setting() -> bool:
+    """Check if auto-install is enabled (default: True)."""
+    if os.environ.get("AGENT_CLI_NO_AUTO_INSTALL", "").lower() in ("1", "true", "yes"):
+        return False
+    return load_config().get("settings", {}).get("auto_install_extras", True)
+
+
+# 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 False  # Unknown extra, trigger install attempt to surface error
+    _, packages = EXTRAS[extra]
+
+    # All packages must be installed
+    return all(_check_package_installed(pkg) for pkg in packages)
+
+
+def _format_extra_item(extra: str) -> str:
+    """Format a single extra as a list item with description."""
+    desc, _ = EXTRAS.get(extra, ("", []))
+    if desc:
+        return f"  - '{extra}' ({desc})"
+    return f"  - '{extra}'"
+
+
+def _format_install_commands(extras: list[str]) -> list[str]:
+    """Format install commands for one or more extras."""
+    combined = ",".join(extras)
+    extras_args = " ".join(extras)
+    return [
+        "Install with:",
+        f'  [bold cyan]uv tool install -p 3.13 "agent-cli\\[{combined}]"[/bold cyan]',
+        "  # or",
+        f"  [bold cyan]agent-cli install-extras {extras_args}[/bold cyan]",
+    ]
+
+
+def get_install_hint(extra: str) -> str:
+    """Get install command hint for a single extra.
+
+    Supports `|` syntax for alternatives: "piper|kokoro" shows both options.
+    """
+    # Handle "extra1|extra2" syntax - show all options
+    if "|" in extra:
+        alternatives = extra.split("|")
+        lines = ["This command requires one of:"]
+        lines.extend(_format_extra_item(alt) for alt in alternatives)
+        lines.append("")
+        lines.append("Install one with:")
+        lines.extend(
+            f'  [bold cyan]uv tool install -p 3.13 "agent-cli\\[{alt}]"[/bold cyan]'
+            for alt in alternatives
+        )
+        lines.append("  # or")
+        lines.extend(
+            f"  [bold cyan]agent-cli install-extras {alt}[/bold cyan]" for alt in alternatives
+        )
+        return "\n".join(lines)
+
+    desc, _ = EXTRAS.get(extra, ("", []))
+    header = f"This command requires the '{extra}' extra"
+    if desc:
+        header += f" ({desc})"
+    header += "."
+
+    lines = [header, ""]
+    lines.extend(_format_install_commands([extra]))
+    return "\n".join(lines)
+
+
+def get_combined_install_hint(extras: list[str]) -> str:
+    """Get a combined install hint for multiple missing extras."""
+    if len(extras) == 1:
+        return get_install_hint(extras[0])
+
+    lines = ["This command requires the following extras:"]
+    lines.extend(_format_extra_item(extra) for extra in extras)
+    lines.append("")
+    lines.extend(_format_install_commands(extras))
+    return "\n".join(lines)
+
+
+def _try_auto_install(missing: list[str]) -> bool:
+    """Attempt to auto-install missing extras. Returns True if successful."""
+    from agent_cli.install.extras import install_extras_programmatic  # noqa: PLC0415
+
+    # Flatten alternatives (e.g., "piper|kokoro" -> just pick the first one)
+    extras_to_install = []
+    for extra in missing:
+        if "|" in extra:
+            # For alternatives, install the first option
+            extras_to_install.append(extra.split("|")[0])
+        else:
+            extras_to_install.append(extra)
+
+    console.print(
+        f"[yellow]Auto-installing missing extras: {', '.join(extras_to_install)}[/]",
+    )
+    return install_extras_programmatic(extras_to_install, quiet=True)
+
+
+def _check_and_install_extras(extras: tuple[str, ...]) -> list[str]:
+    """Check for missing extras and attempt auto-install. Returns list of still-missing."""
+    missing = [e for e in extras if not check_extra_installed(e)]
+    if not missing:
+        return []
+
+    if not _get_auto_install_setting():
+        print_error_message(get_combined_install_hint(missing))
+        return missing
+
+    if not _try_auto_install(missing):
+        print_error_message("Auto-install failed.\n" + get_combined_install_hint(missing))
+        return missing
+
+    console.print("[green]Installation complete![/]")
+    still_missing = [e for e in extras if not check_extra_installed(e)]
+    if still_missing:
+        print_error_message(
+            "Auto-install completed but some dependencies are still missing.\n"
+            + get_combined_install_hint(still_missing),
+        )
+    return still_missing
+
+
+def requires_extras(*extras: str) -> Callable[[F], F]:
+    """Decorator to declare required extras for a command.
+
+    Auto-installs missing extras by default. Disable via AGENT_CLI_NO_AUTO_INSTALL=1
+    or config [settings] auto_install_extras = false.
+    """
+
+    def decorator(func: F) -> F:
+        func._required_extras = extras  # type: ignore[attr-defined]
+
+        @functools.wraps(func)
+        def wrapper(*args: object, **kwargs: object) -> object:
+            if _check_and_install_extras(extras):
+                raise typer.Exit(1)
+            return func(*args, **kwargs)
+
+        wrapper._required_extras = extras  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
+
+    return decorator