agent-cli 0.70.2__py3-none-any.whl → 0.72.1__py3-none-any.whl

agent_cli/server/cli.py

@@ -10,6 +10,7 @@ from typing import Annotated
 
 import typer
 
+from agent_cli import opts
 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
@@ -28,7 +29,30 @@ def _has(package: str) -> bool:
 
 app = typer.Typer(
     name="server",
-    help="Run ASR/TTS servers (Whisper, TTS, or proxy mode).",
+    help="""Run local ASR/TTS servers with OpenAI-compatible APIs.
+
+**Available servers:**
+
+- `whisper` - Local speech-to-text using Whisper models (faster-whisper or MLX)
+- `tts` - Local text-to-speech using Piper (CPU) or Kokoro (GPU)
+- `transcribe-proxy` - Proxy to external ASR providers (OpenAI, Gemini, Wyoming)
+
+**Common workflows:**
+
+```bash
+# Run local Whisper server (lazy loads large-v3 by default)
+agent-cli server whisper
+
+# Run local TTS with Kokoro backend (GPU-accelerated)
+agent-cli server tts --backend kokoro
+
+# Run transcription proxy using your configured ASR provider
+agent-cli server transcribe-proxy
+```
+
+All servers support Home Assistant via Wyoming protocol and can be used as
+drop-in replacements for OpenAI's audio APIs.
+""",
     add_completion=True,
     rich_markup_mode="markdown",
     no_args_is_help=True,
@@ -169,14 +193,18 @@ def whisper_cmd(  # noqa: PLR0912, PLR0915
         typer.Option(
             "--model",
             "-m",
-            help="Model name(s) to load (can specify multiple)",
+            help=(
+                "Whisper model(s) to load. Common models: `tiny`, `base`, `small`, "
+                "`medium`, `large-v3`, `distil-large-v3`. Can specify multiple for "
+                "different accuracy/speed tradeoffs. Default: `large-v3`"
+            ),
         ),
     ] = None,
     default_model: Annotated[
         str | None,
         typer.Option(
             "--default-model",
-            help="Default model when not specified in request",
+            help=("Model to use when client doesn't specify one. Must be in the `--model` list"),
         ),
     ] = None,
     device: Annotated[
@@ -184,42 +212,54 @@ def whisper_cmd(  # noqa: PLR0912, PLR0915
         typer.Option(
             "--device",
             "-d",
-            help="Device: auto, cuda, cuda:0, cpu",
+            help=(
+                "Compute device: `auto` (detect GPU), `cuda`, `cuda:0`, `cpu`. "
+                "MLX backend always uses Apple Silicon"
+            ),
         ),
     ] = "auto",
     compute_type: Annotated[
         str,
         typer.Option(
             "--compute-type",
-            help="Compute type: auto, float16, int8, int8_float16",
+            help=(
+                "Precision for faster-whisper: `auto`, `float16`, `int8`, `int8_float16`. "
+                "Lower precision = faster + less VRAM"
+            ),
         ),
     ] = "auto",
     cache_dir: Annotated[
         Path | None,
         typer.Option(
             "--cache-dir",
-            help="Model cache directory",
+            help="Custom directory for downloaded models (default: HuggingFace cache)",
         ),
     ] = None,
     ttl: Annotated[
         int,
         typer.Option(
             "--ttl",
-            help="Seconds before unloading idle model",
+            help=(
+                "Seconds of inactivity before unloading model from memory. "
+                "Set to 0 to keep loaded indefinitely"
+            ),
         ),
     ] = 300,
     preload: Annotated[
         bool,
         typer.Option(
             "--preload",
-            help="Load model(s) at startup and wait for completion",
+            help=(
+                "Load model(s) immediately at startup instead of on first request. "
+                "Useful for reducing first-request latency"
+            ),
         ),
     ] = False,
     host: Annotated[
         str,
         typer.Option(
             "--host",
-            help="Host to bind the server to",
+            help="Network interface to bind. Use `0.0.0.0` for all interfaces",
         ),
     ] = "0.0.0.0",  # noqa: S104
     port: Annotated[
@@ -227,44 +267,40 @@ def whisper_cmd(  # noqa: PLR0912, PLR0915
         typer.Option(
             "--port",
             "-p",
-            help="HTTP API port",
+            help="Port for OpenAI-compatible HTTP API (`/v1/audio/transcriptions`)",
         ),
     ] = 10301,
     wyoming_port: Annotated[
         int,
         typer.Option(
             "--wyoming-port",
-            help="Wyoming protocol port",
+            help="Port for Wyoming protocol (Home Assistant integration)",
         ),
     ] = 10300,
     no_wyoming: Annotated[
         bool,
         typer.Option(
             "--no-wyoming",
-            help="Disable Wyoming server",
+            help="Disable Wyoming protocol server (only run HTTP API)",
         ),
     ] = False,
     download_only: Annotated[
         bool,
         typer.Option(
             "--download-only",
-            help="Download model(s) and exit without starting server",
+            help="Download model(s) to cache and exit. Useful for Docker builds",
         ),
     ] = False,
-    log_level: Annotated[
-        str,
-        typer.Option(
-            "--log-level",
-            "-l",
-            help="Logging level: debug, info, warning, error",
-        ),
-    ] = "info",
+    log_level: opts.LogLevel = opts.SERVER_LOG_LEVEL,
     backend: Annotated[
         str,
         typer.Option(
             "--backend",
             "-b",
-            help="Backend: auto (platform detection), faster-whisper, mlx",
+            help=(
+                "Inference backend: `auto` (faster-whisper on CUDA/CPU, MLX on Apple Silicon), "
+                "`faster-whisper`, `mlx`"
+            ),
         ),
     ] = "auto",
 ) -> None:
@@ -278,7 +314,8 @@ def whisper_cmd(  # noqa: PLR0912, PLR0915
     Models are loaded lazily on first request and unloaded after being
     idle for the TTL duration, freeing VRAM for other applications.
 
-    Examples:
+    **Examples:**
+
         # Run with default large-v3 model
         agent-cli server whisper
 
@@ -290,7 +327,6 @@ def whisper_cmd(  # noqa: PLR0912, PLR0915
 
         # Download model without starting server
         agent-cli server whisper --model large-v3 --download-only
-
     """
     # Setup Rich logging for consistent output
     setup_rich_logging(log_level)
@@ -378,6 +414,7 @@ def whisper_cmd(  # noqa: PLR0912, PLR0915
     console.print()
     console.print("[dim]Configuration:[/dim]")
     console.print(f"  Backend: [cyan]{actual_backend}[/cyan]")
+    console.print(f"  Log level: [cyan]{log_level}[/cyan]")
     console.print()
     console.print("[dim]Endpoints:[/dim]")
     console.print(f"  HTTP API: [cyan]http://{host}:{port}[/cyan]")
@@ -422,45 +459,64 @@ def whisper_cmd(  # noqa: PLR0912, PLR0915
 
 
 @app.command("transcribe-proxy")
-@requires_extras("server", "audio", "llm")
+@requires_extras("server", "wyoming", "llm")
 def transcribe_proxy_cmd(
     host: Annotated[
         str,
-        typer.Option("--host", help="Host to bind the server to"),
+        typer.Option("--host", help="Network interface to bind. Use `0.0.0.0` for all interfaces"),
     ] = "0.0.0.0",  # noqa: S104
     port: Annotated[
         int,
-        typer.Option("--port", "-p", help="Port to bind the server to"),
+        typer.Option("--port", "-p", help="Port for the HTTP API"),
     ] = 61337,
     reload: Annotated[
         bool,
-        typer.Option("--reload", help="Enable auto-reload for development"),
+        typer.Option("--reload", help="Auto-reload on code changes (development only)"),
     ] = False,
+    log_level: opts.LogLevel = opts.SERVER_LOG_LEVEL,
 ) -> None:
-    """Run transcription proxy server.
+    r"""Run transcription proxy that forwards to your configured ASR provider.
 
-    This server proxies transcription requests to configured ASR providers
-    (Wyoming, OpenAI, or Gemini) based on your agent-cli configuration.
+    Unlike `server whisper` which runs a local Whisper model, this proxy
+    forwards audio to external ASR providers configured in your agent-cli
+    config file or environment variables.
 
-    It exposes:
-    - /transcribe endpoint for audio transcription
-    - /health endpoint for health checks
+    **Supported ASR providers:** `wyoming`, `openai`, `gemini`
+    **Supported LLM providers for cleanup:** `ollama`, `openai`, `gemini`
 
-    This is the original server command functionality.
+    The server exposes:
 
-    Examples:
-        # Run on default port
+    - `POST /transcribe` - Accepts audio files, returns `{raw_transcript, cleaned_transcript}`
+    - `GET /health` - Health check endpoint
+
+    **When to use this vs `server whisper`:**
+
+    - Use `transcribe-proxy` when you want to use cloud ASR (OpenAI/Gemini)
+      or connect to a remote Wyoming server
+    - Use `server whisper` when you want to run a local Whisper model
+
+    Configuration is read from `~/.config/agent-cli/config.yaml` or env vars
+    like `ASR_PROVIDER`, `LLM_PROVIDER`, `OPENAI_API_KEY`, etc.
+
+    **Examples:**
+
+        # Run with providers from config file
         agent-cli server transcribe-proxy
 
-        # Run on custom port
-        agent-cli server transcribe-proxy --port 8080
+        # Run with OpenAI ASR via env vars
+        ASR_PROVIDER=openai OPENAI_API_KEY=sk-... agent-cli server transcribe-proxy
 
+        # Test with curl
+        curl -X POST http://localhost:61337/transcribe \\
+          -F "audio=@recording.wav" -F "cleanup=true"
     """
     _check_server_deps()
+    setup_rich_logging(log_level)
 
     console.print(
         f"[bold green]Starting Agent CLI transcription proxy on {host}:{port}[/bold green]",
     )
+    console.print(f"[dim]Log level: {log_level}[/dim]")
     if reload:
         console.print("[yellow]Auto-reload enabled for development[/yellow]")
 
@@ -471,7 +527,7 @@ def transcribe_proxy_cmd(
         host=host,
         port=port,
         reload=reload,
-        log_level="info",
+        log_level=log_level.lower(),
     )
 
 
@@ -483,14 +539,18 @@ def tts_cmd(  # noqa: PLR0915
         typer.Option(
             "--model",
             "-m",
-            help="Model name(s) to load. Piper: 'en_US-lessac-medium'. Kokoro: 'kokoro' (auto-downloads)",
+            help=(
+                "Model/voice(s) to load. Piper: `en_US-lessac-medium`, `en_GB-alan-medium`. "
+                "Kokoro: `af_heart`, `af_bella`, `am_adam`. "
+                "Auto-downloads on first use"
+            ),
         ),
     ] = None,
     default_model: Annotated[
         str | None,
         typer.Option(
             "--default-model",
-            help="Default model when not specified in request",
+            help=("Voice to use when client doesn't specify one. Must be in the `--model` list"),
         ),
     ] = None,
     device: Annotated[
@@ -498,35 +558,44 @@ def tts_cmd(  # noqa: PLR0915
         typer.Option(
             "--device",
             "-d",
-            help="Device: auto, cpu, cuda, mps (Piper is CPU-only, Kokoro supports GPU)",
+            help=(
+                "Compute device: `auto`, `cpu`, `cuda`, `mps`. "
+                "Piper is CPU-only; Kokoro supports GPU acceleration"
+            ),
         ),
     ] = "auto",
     cache_dir: Annotated[
         Path | None,
         typer.Option(
             "--cache-dir",
-            help="Model cache directory",
+            help="Custom directory for downloaded models (default: ~/.cache/agent-cli/tts/)",
         ),
     ] = None,
     ttl: Annotated[
         int,
         typer.Option(
             "--ttl",
-            help="Seconds before unloading idle model",
+            help=(
+                "Seconds of inactivity before unloading model from memory. "
+                "Set to 0 to keep loaded indefinitely"
+            ),
         ),
     ] = 300,
     preload: Annotated[
         bool,
         typer.Option(
             "--preload",
-            help="Load model(s) at startup and wait for completion",
+            help=(
+                "Load model(s) immediately at startup instead of on first request. "
+                "Useful for reducing first-request latency"
+            ),
         ),
     ] = False,
     host: Annotated[
         str,
         typer.Option(
             "--host",
-            help="Host to bind the server to",
+            help="Network interface to bind. Use `0.0.0.0` for all interfaces",
         ),
     ] = "0.0.0.0",  # noqa: S104
     port: Annotated[
@@ -534,44 +603,40 @@ def tts_cmd(  # noqa: PLR0915
         typer.Option(
             "--port",
             "-p",
-            help="HTTP API port",
+            help="Port for OpenAI-compatible HTTP API (`/v1/audio/speech`)",
         ),
     ] = 10201,
     wyoming_port: Annotated[
         int,
         typer.Option(
             "--wyoming-port",
-            help="Wyoming protocol port",
+            help="Port for Wyoming protocol (Home Assistant integration)",
         ),
     ] = 10200,
     no_wyoming: Annotated[
         bool,
         typer.Option(
             "--no-wyoming",
-            help="Disable Wyoming server",
+            help="Disable Wyoming protocol server (only run HTTP API)",
         ),
     ] = False,
     download_only: Annotated[
         bool,
         typer.Option(
             "--download-only",
-            help="Download model(s) and exit without starting server",
+            help="Download model(s)/voice(s) to cache and exit. Useful for Docker builds",
         ),
     ] = False,
-    log_level: Annotated[
-        str,
-        typer.Option(
-            "--log-level",
-            "-l",
-            help="Logging level: debug, info, warning, error",
-        ),
-    ] = "info",
+    log_level: opts.LogLevel = opts.SERVER_LOG_LEVEL,
     backend: Annotated[
         str,
         typer.Option(
             "--backend",
             "-b",
-            help="Backend: auto, piper, kokoro",
+            help=(
+                "TTS engine: `auto` (prefer Kokoro if available), "
+                "`piper` (CPU, many languages), `kokoro` (GPU, high quality)"
+            ),
         ),
     ] = "auto",
 ) -> None:
@@ -594,7 +659,8 @@ def tts_cmd(  # noqa: PLR0915
     Voices: af_heart, af_bella, am_adam, bf_emma, bm_george, etc.
     See https://huggingface.co/hexgrad/Kokoro-82M for all voices.
 
-    Examples:
+    **Examples:**
+
         # Run with Kokoro (auto-downloads model and voices)
         agent-cli server tts --backend kokoro
 
@@ -609,7 +675,6 @@ def tts_cmd(  # noqa: PLR0915
 
         # Download Piper model without starting server
         agent-cli server tts --backend piper --model en_US-lessac-medium --download-only
-
     """
     # Setup Rich logging for consistent output
     setup_rich_logging(log_level)
@@ -679,6 +744,7 @@ def tts_cmd(  # noqa: PLR0915
     console.print()
     console.print("[dim]Configuration:[/dim]")
     console.print(f"  Backend: [cyan]{resolved_backend}[/cyan]")
+    console.print(f"  Log level: [cyan]{log_level}[/cyan]")
     console.print()
     console.print("[dim]Endpoints:[/dim]")
     console.print(f"  HTTP API: [cyan]http://{host}:{port}[/cyan]")

agent_cli/server/proxy/api.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import logging
+import os
 from pathlib import Path
-from typing import Annotated, Any
+from typing import TYPE_CHECKING, Annotated, Any
 
 from fastapi import Depends, FastAPI, File, Form, HTTPException, Request, UploadFile
 from pydantic import BaseModel
@@ -26,6 +27,9 @@ from agent_cli.server.common import log_requests_middleware
 from agent_cli.services import asr
 from agent_cli.services.llm import process_and_update_clipboard
 
+if TYPE_CHECKING:
+    from typer.models import OptionInfo
+
 # Configure logging
 logging.basicConfig(level=logging.INFO)
 LOGGER = logging.getLogger(__name__)
@@ -37,6 +41,40 @@ app = FastAPI(
 )
 
 
+@app.on_event("startup")
+async def log_effective_config() -> None:
+    """Log effective configuration on startup to help debug env var issues."""
+    (
+        provider_cfg,
+        wyoming_cfg,
+        openai_asr_cfg,
+        gemini_asr_cfg,
+        ollama_cfg,
+        openai_llm_cfg,
+        gemini_llm_cfg,
+        _,
+    ) = _load_transcription_configs()
+
+    LOGGER.info("ASR provider: %s", provider_cfg.asr_provider)
+    if provider_cfg.asr_provider == "wyoming":
+        LOGGER.info("  Wyoming: %s:%d", wyoming_cfg.asr_wyoming_ip, wyoming_cfg.asr_wyoming_port)
+    elif provider_cfg.asr_provider == "openai":
+        LOGGER.info("  Model: %s", openai_asr_cfg.asr_openai_model)
+        LOGGER.info("  Base URL: %s", openai_asr_cfg.openai_base_url or "https://api.openai.com/v1")
+    elif provider_cfg.asr_provider == "gemini":
+        LOGGER.info("  Model: %s", gemini_asr_cfg.asr_gemini_model)
+
+    LOGGER.info("LLM provider: %s", provider_cfg.llm_provider)
+    if provider_cfg.llm_provider == "ollama":
+        LOGGER.info("  Model: %s", ollama_cfg.llm_ollama_model)
+        LOGGER.info("  Host: %s", ollama_cfg.llm_ollama_host)
+    elif provider_cfg.llm_provider == "openai":
+        LOGGER.info("  Model: %s", openai_llm_cfg.llm_openai_model)
+        LOGGER.info("  Base URL: %s", openai_llm_cfg.openai_base_url or "https://api.openai.com/v1")
+    elif provider_cfg.llm_provider == "gemini":
+        LOGGER.info("  Model: %s", gemini_llm_cfg.llm_gemini_model)
+
+
 @app.middleware("http")
 async def log_requests(request: Request, call_next) -> Any:  # type: ignore[no-untyped-def]  # noqa: ANN001
     """Log basic request information."""
@@ -83,6 +121,7 @@ async def health_check() -> HealthResponse:
 
 async def _transcribe_with_provider(
     audio_data: bytes,
+    filename: str,
     provider_cfg: config.ProviderSelection,
     wyoming_asr_cfg: config.WyomingASR,
     openai_asr_cfg: config.OpenAIASR,
@@ -90,6 +129,7 @@ async def _transcribe_with_provider(
 ) -> str:
     """Transcribe audio using the configured provider."""
     transcriber = asr.create_recorded_audio_transcriber(provider_cfg)
+    file_suffix = Path(filename).suffix.lower() or ".wav"
 
     if provider_cfg.asr_provider == "wyoming":
         return await transcriber(
@@ -102,12 +142,14 @@ async def _transcribe_with_provider(
             audio_data=audio_data,
             openai_asr_cfg=openai_asr_cfg,
             logger=LOGGER,
+            file_suffix=file_suffix,
         )
     if provider_cfg.asr_provider == "gemini":
         return await transcriber(
             audio_data=audio_data,
             gemini_asr_cfg=gemini_asr_cfg,
             logger=LOGGER,
+            file_suffix=file_suffix,
         )
     msg = f"Unsupported ASR provider: {provider_cfg.asr_provider}"
     raise NotImplementedError(msg)
@@ -153,6 +195,13 @@ def _validate_audio_file(audio: UploadFile) -> None:
         )
 
 
+def _cfg(key: str, defaults: dict[str, Any], opt: OptionInfo) -> Any:
+    """Get config with priority: env var > config file > option default."""
+    if opt.envvar and (env_val := os.environ.get(opt.envvar)):
+        return int(env_val) if isinstance(opt.default, int) else env_val
+    return defaults.get(key, opt.default)
+
+
 def _load_transcription_configs() -> tuple[
     config.ProviderSelection,
     config.WyomingASR,
@@ -163,41 +212,43 @@ def _load_transcription_configs() -> tuple[
     config.GeminiLLM,
     dict[str, Any],
 ]:
-    """Load and create all required configuration objects."""
+    """Load config objects. Priority: env var > config file > default."""
     loaded_config = config.load_config()
     wildcard_config = loaded_config.get("defaults", {})
     command_config = loaded_config.get("transcribe", {})
     defaults = {**wildcard_config, **command_config}
 
     provider_cfg = config.ProviderSelection(
-        asr_provider=defaults.get("asr_provider", opts.ASR_PROVIDER.default),  # type: ignore[attr-defined]
-        llm_provider=defaults.get("llm_provider", opts.LLM_PROVIDER.default),  # type: ignore[attr-defined]
-        tts_provider=opts.TTS_PROVIDER.default,  # type: ignore[attr-defined]
+        asr_provider=_cfg("asr_provider", defaults, opts.ASR_PROVIDER),
+        llm_provider=_cfg("llm_provider", defaults, opts.LLM_PROVIDER),
+        tts_provider=_cfg("tts_provider", defaults, opts.TTS_PROVIDER),
     )
     wyoming_asr_cfg = config.WyomingASR(
-        asr_wyoming_ip=defaults.get("asr_wyoming_ip", opts.ASR_WYOMING_IP.default),  # type: ignore[attr-defined]
-        asr_wyoming_port=defaults.get("asr_wyoming_port", opts.ASR_WYOMING_PORT.default),  # type: ignore[attr-defined]
+        asr_wyoming_ip=_cfg("asr_wyoming_ip", defaults, opts.ASR_WYOMING_IP),
+        asr_wyoming_port=_cfg("asr_wyoming_port", defaults, opts.ASR_WYOMING_PORT),
     )
     openai_asr_cfg = config.OpenAIASR(
-        asr_openai_model=defaults.get("asr_openai_model", opts.ASR_OPENAI_MODEL.default),  # type: ignore[attr-defined]
-        openai_api_key=defaults.get("openai_api_key", opts.OPENAI_API_KEY.default),  # type: ignore[attr-defined,union-attr]
+        asr_openai_model=_cfg("asr_openai_model", defaults, opts.ASR_OPENAI_MODEL),
+        openai_api_key=_cfg("openai_api_key", defaults, opts.OPENAI_API_KEY),
+        openai_base_url=_cfg("asr_openai_base_url", defaults, opts.ASR_OPENAI_BASE_URL),
+        asr_openai_prompt=_cfg("asr_openai_prompt", defaults, opts.ASR_OPENAI_PROMPT),
     )
     gemini_asr_cfg = config.GeminiASR(
-        asr_gemini_model=defaults.get("asr_gemini_model", opts.ASR_GEMINI_MODEL.default),  # type: ignore[attr-defined]
-        gemini_api_key=defaults.get("gemini_api_key", opts.GEMINI_API_KEY.default),  # type: ignore[attr-defined,union-attr]
+        asr_gemini_model=_cfg("asr_gemini_model", defaults, opts.ASR_GEMINI_MODEL),
+        gemini_api_key=_cfg("gemini_api_key", defaults, opts.GEMINI_API_KEY),
     )
     ollama_cfg = config.Ollama(
-        llm_ollama_model=defaults.get("llm_ollama_model", opts.LLM_OLLAMA_MODEL.default),  # type: ignore[attr-defined]
-        llm_ollama_host=defaults.get("llm_ollama_host", opts.LLM_OLLAMA_HOST.default),  # type: ignore[attr-defined]
+        llm_ollama_model=_cfg("llm_ollama_model", defaults, opts.LLM_OLLAMA_MODEL),
+        llm_ollama_host=_cfg("llm_ollama_host", defaults, opts.LLM_OLLAMA_HOST),
     )
     openai_llm_cfg = config.OpenAILLM(
-        llm_openai_model=defaults.get("llm_openai_model", opts.LLM_OPENAI_MODEL.default),  # type: ignore[attr-defined]
-        openai_api_key=defaults.get("openai_api_key", opts.OPENAI_API_KEY.default),  # type: ignore[attr-defined,union-attr]
-        openai_base_url=defaults.get("openai_base_url", opts.OPENAI_BASE_URL.default),  # type: ignore[attr-defined,union-attr]
+        llm_openai_model=_cfg("llm_openai_model", defaults, opts.LLM_OPENAI_MODEL),
+        openai_api_key=_cfg("openai_api_key", defaults, opts.OPENAI_API_KEY),
+        openai_base_url=_cfg("openai_base_url", defaults, opts.OPENAI_BASE_URL),
     )
     gemini_llm_cfg = config.GeminiLLM(
-        llm_gemini_model=defaults.get("llm_gemini_model", opts.LLM_GEMINI_MODEL.default),  # type: ignore[attr-defined]
-        gemini_api_key=defaults.get("gemini_api_key", opts.GEMINI_API_KEY.default),  # type: ignore[attr-defined,union-attr]
+        llm_gemini_model=_cfg("llm_gemini_model", defaults, opts.LLM_GEMINI_MODEL),
+        gemini_api_key=_cfg("gemini_api_key", defaults, opts.GEMINI_API_KEY),
     )
 
     return (
@@ -309,8 +360,14 @@ async def transcribe_audio(
             defaults,
         ) = _load_transcription_configs()
 
-        # Save uploaded file
+        # Read uploaded file
         audio_data = await audio_file.read()
+        LOGGER.info(
+            "Received audio: filename=%s, size=%d bytes, content_type=%s",
+            audio_file.filename,
+            len(audio_data),
+            audio_file.content_type,
+        )
 
         # Convert audio to Wyoming format if using local ASR
         if provider_cfg.asr_provider == "wyoming":
@@ -319,6 +376,7 @@ async def transcribe_audio(
         # Transcribe audio using the configured provider
         raw_transcript = await _transcribe_with_provider(
             audio_data,
+            audio_file.filename or "audio.wav",
             provider_cfg,
             wyoming_asr_cfg,
             openai_asr_cfg,