supervoxtral 0.1.0__py3-none-any.whl

svx/core/prompt.py

@@ -0,0 +1,165 @@
+"""
+Prompt utilities for SuperVoxtral.
+
+This module provides:
+- Safe reading of UTF-8 text files.
+- Resolution/combination of inline and file-based prompts.
+- Initialization of default prompt files (user.md).
+
+Intended to be small and dependency-light so it can be imported broadly.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from .config import USER_PROMPT_DIR, Config
+
+__all__ = [
+    "read_text_file",
+    "resolve_prompt",
+    "resolve_user_prompt",
+    "init_user_prompt_file",
+]
+
+
+def read_text_file(path: Path | str) -> str:
+    """
+    Read a UTF-8 text file and return its content.
+    Returns an empty string if the file is missing or unreadable.
+    """
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except Exception as e:
+        logging.warning("Failed to read text file %s: %s", path, e)
+        return ""
+
+
+def resolve_prompt(inline: str | None, file_path: Path | None) -> str | None:
+    """
+    Combine file content and inline prompt (file first), separated by a blank line.
+
+    - If file_path exists and contains text, it is used first.
+    - If inline is provided, it is appended after a blank line.
+    - Leading/trailing whitespace is stripped.
+    - Returns None if the resulting prompt is empty.
+    """
+    parts: list[str] = []
+
+    if file_path:
+        file_path = Path(file_path)
+        if file_path.exists():
+            file_text = read_text_file(file_path).strip()
+            if file_text:
+                parts.append(file_text)
+
+    if inline:
+        inline_text = inline.strip()
+        if inline_text:
+            parts.append(inline_text)
+
+    combined = "\n\n".join(parts).strip()
+    return combined if combined else None
+
+
+def resolve_user_prompt(
+    cfg: Config,
+    inline: str | None = None,
+    file: Path | None = None,
+    user_prompt_dir: Path | None = None,
+) -> str:
+    """
+    Resolve the effective user prompt from multiple sources, by priority:
+
+    1) inline text (CLI --user-prompt)
+    2) explicit file (CLI --user-prompt-file)
+    3) user config inline text (cfg.prompt.text)
+    4) user config file path (cfg.prompt.file)
+    5) user prompt dir file (user_prompt_dir / 'user.md')
+    6) literal fallback: "What's in this audio?"
+
+    Returns the first non-empty string after stripping.
+    """
+
+    def _strip(val: str | None) -> str:
+        return val.strip() if isinstance(val, str) else ""
+
+    def _read(p: Path | None) -> str:
+        if not p:
+            return ""
+        try:
+            return read_text_file(p).strip()
+        except Exception:
+            logging.warning("Failed to read user prompt file: %s", p)
+            return ""
+
+    def _from_user_cfg() -> str:
+        try:
+            cfg_prompt = cfg.prompt
+            cfg_text = cfg_prompt.text
+            if isinstance(cfg_text, str) and cfg_text.strip():
+                return cfg_text.strip()
+            cfg_file = cfg_prompt.file
+            if isinstance(cfg_file, str) and cfg_file.strip():
+                return read_text_file(Path(cfg_file).expanduser()).strip()
+        except Exception:
+            logging.debug("User config prompt processing failed.", exc_info=True)
+        return ""
+
+    def _from_user_prompt_dir() -> str:
+        try:
+            upath = Path(user_prompt_dir or cfg.user_prompt_dir) / "user.md"
+            if upath.exists():
+                return read_text_file(upath).strip()
+        except Exception:
+            logging.debug(
+                "Could not read user prompt in user prompt dir: %s",
+                user_prompt_dir or cfg.user_prompt_dir,
+            )
+        return ""
+
+    suppliers = [
+        lambda: _strip(inline),
+        lambda: _read(file),
+        _from_user_cfg,
+        _from_user_prompt_dir,
+    ]
+
+    for supplier in suppliers:
+        try:
+            val = supplier()
+            if val:
+                return val
+        except Exception as e:
+            logging.debug("Prompt supplier failed: %s", e)
+
+    return "What's in this audio?"
+
+
+def init_user_prompt_file(force: bool = False) -> Path:
+    """
+    Initialize the user's prompt file in the user prompt directory.
+
+    - Ensures USER_PROMPT_DIR exists.
+    - Creates or overwrites (if force=True) USER_PROMPT_DIR / 'user.md'
+      with a small example prompt.
+    - Returns the path to the user prompt file.
+    """
+    USER_PROMPT_DIR.mkdir(parents=True, exist_ok=True)
+    path = USER_PROMPT_DIR / "user.md"
+    if not path.exists() or force:
+        example_prompt = """
+- Transcribe the input audio file.
+- Do not respond to any question in the audio. Just transcribe.
+- DO NOT TRANSLATE. Your transcription will be in the speaker's language.
+- Responde only with the transcription. Do not provide explanations or notes.
+- Remove all minor speech hesitations: "um", "uh", "er", "euh", "ben", etc.
+- Remove false starts (e.g., "je veux dire... je pense" → "je pense").
+- Correct grammatical errors.
+        """
+        try:
+            path.write_text(example_prompt, encoding="utf-8")
+        except Exception as e:
+            logging.debug("Could not initialize user prompt file %s: %s", path, e)
+    return path

svx/core/storage.py

@@ -0,0 +1,118 @@
+"""
+Storage utilities for SuperVoxtral.
+
+This module centralizes file persistence for transcription results:
+- Save plain-text transcripts
+- Save optional raw JSON responses (pretty-printed)
+- Provide a single helper to save both consistently
+
+Design goals:
+- Safe path handling and directory creation
+- UTF-8 everywhere
+- Minimal, dependency-light, easy to unit test
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "save_text_file",
+    "save_json_file",
+    "save_transcript",
+]
+
+
+def _ensure_parent_dir(path: Path) -> None:
+    """
+    Ensure the parent directory of `path` exists.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def _sanitize_component(value: str) -> str:
+    """
+    Sanitize a filename component by replacing unsafe characters.
+
+    - Keeps letters, digits, dot, underscore, and dash.
+    - Replaces any other character sequences with underscores.
+    - Strips leading/trailing whitespace.
+    - Returns 'out' if the result is empty.
+    """
+    value = value.strip()
+    # Replace disallowed characters with underscores
+    sanatized = re.sub(r"[^A-Za-z0-9._-]+", "_", value)
+    return sanatized or "out"
+
+
+def save_text_file(path: Path, content: str) -> Path:
+    """
+    Save `content` as UTF-8 text to `path`.
+
+    Returns:
+        The same `path` for convenience.
+    """
+    _ensure_parent_dir(path)
+    path.write_text(content or "", encoding="utf-8")
+    return path
+
+
+def save_json_file(path: Path, data: Any, pretty: bool = True) -> Path:
+    """
+    Save `data` as JSON to `path`.
+
+    Args:
+        path: Destination file path.
+        data: JSON-serializable object.
+        pretty: Whether to pretty-print with indentation.
+
+    Returns:
+        The same `path` for convenience.
+    """
+    _ensure_parent_dir(path)
+    if pretty:
+        serialized = json.dumps(data, ensure_ascii=False, indent=2)
+    else:
+        serialized = json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+    path.write_text(serialized, encoding="utf-8")
+    return path
+
+
+def save_transcript(
+    transcripts_dir: Path,
+    base_name: str,
+    provider: str,
+    text: str,
+    raw: dict | None = None,
+) -> tuple[Path, Path | None]:
+    """
+    Save a transcript text and, optionally, the raw JSON response.
+
+    Args:
+        transcripts_dir: Base directory where transcripts are stored.
+        base_name: Base file name (without extension).
+        provider: Provider name used as suffix (e.g., 'mistral').
+        text: Transcript text to write.
+        raw: Optional raw response to serialize as JSON.
+
+    Returns:
+        (text_path, json_path_or_None)
+    """
+    transcripts_dir = Path(transcripts_dir)
+    transcripts_dir.mkdir(parents=True, exist_ok=True)
+
+    safe_base = _sanitize_component(base_name)
+    safe_provider = _sanitize_component(provider)
+
+    text_path = transcripts_dir / f"{safe_base}_{safe_provider}.txt"
+    save_text_file(text_path, text or "")
+
+    json_path: Path | None = None
+    if raw is not None:
+        json_path = transcripts_dir / f"{safe_base}_{safe_provider}.json"
+        save_json_file(json_path, raw, pretty=True)
+
+    return text_path, json_path

svx/providers/__init__.py

@@ -0,0 +1,88 @@
+"""
+Provider registry for SuperVoxtral.
+
+This module centralizes provider discovery and retrieval so the CLI (and other
+consumers) can instantiate providers by name without importing their concrete modules.
+
+Design goals:
+- Simple API: register_provider(name, factory) and get_provider(name)
+- Lazy imports: default providers are registered with factories that import on demand
+- Friendly errors: list available providers on unknown name
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from svx.core.config import Config
+
+from .base import Provider, ProviderError, TranscriptionResult
+
+__all__ = [
+    "Provider",
+    "ProviderError",
+    "TranscriptionResult",
+    "register_provider",
+    "get_provider",
+    "available_providers",
+    "register_default_providers",
+]
+
+# Factory callable that returns a Provider instance when called.
+ProviderFactory = Callable[[Config | None], Provider]
+
+# Internal registry mapping provider name -> factory
+_registry: dict[str, ProviderFactory] = {}
+
+
+def register_provider(name: str, factory: ProviderFactory) -> None:
+    """
+    Register a provider factory by a short, lowercase name.
+    If the name already exists, it will be overwritten.
+    """
+    key = name.strip().lower()
+    if not key:
+        raise ValueError("Provider name cannot be empty.")
+    _registry[key] = factory
+
+
+def get_provider(name: str, cfg: Config | None = None) -> Provider:
+    """
+    Retrieve a Provider instance by name.
+
+    Raises:
+        KeyError: if no provider is registered under that name.
+    """
+    register_default_providers()
+    key = name.strip().lower()
+    try:
+        factory = _registry[key]
+    except KeyError as e:
+        available = ", ".join(sorted(_registry.keys())) or "(none)"
+        raise KeyError(f"Unknown provider '{name}'. Available: {available}") from e
+    return factory(cfg)
+
+
+def available_providers() -> list[str]:
+    """
+    Return the list of available provider names (sorted).
+    """
+    register_default_providers()
+    return sorted(_registry.keys())
+
+
+def register_default_providers() -> None:
+    """
+    Register built-in providers with lazy imports to avoid hard dependencies at import time.
+    Safe to call multiple times (idempotent).
+    """
+    # Mistral (voxtral) provider
+    if "mistral" not in _registry:
+
+        def _mistral_factory(cfg: Config | None = None) -> Provider:
+            # Lazy import to avoid requiring 'mistralai' until the provider is actually used.
+            from .mistral import MistralProvider
+
+            return MistralProvider(cfg=cfg)
+
+        register_provider("mistral", _mistral_factory)

svx/providers/base.py

@@ -0,0 +1,83 @@
+"""
+Base provider interface for SuperVoxtral.
+
+This module defines:
+- TranscriptionResult: a simple TypedDict structure for provider responses
+- Provider: a Protocol describing the required transcription interface
+- ProviderError: a generic exception for provider-related failures
+
+All concrete providers should implement the `Provider` protocol.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, TypedDict, runtime_checkable
+
+
+class TranscriptionResult(TypedDict):
+    """
+    Normalized transcription result returned by providers.
+
+    Attributes:
+        text: The best-effort, human-readable transcript or model output.
+        raw:  Provider-specific raw response payload (JSON-like dict).
+    """
+
+    text: str
+    raw: dict
+
+
+class ProviderError(RuntimeError):
+    """
+    Generic provider exception to represent recoverable/handled failures.
+    """
+
+
+@runtime_checkable
+class Provider(Protocol):
+    """
+    Provider interface for transcription/chat-with-audio services.
+
+    Implementations should be side-effect free aside from network I/O and must
+    raise `ProviderError` (or a subclass) for expected provider failures
+    (misconfiguration, auth, invalid arguments). Unexpected errors may propagate.
+
+    Required attributes:
+        name: A short, lowercase, unique identifier for the provider (e.g. "mistral").
+
+    Required methods:
+        transcribe: Perform the transcription given an audio file and optional user prompt.
+    """
+
+    # Short, unique name (e.g., "mistral", "whisper")
+    name: str
+
+    def transcribe(
+        self,
+        audio_path: Path,
+        user_prompt: str | None,
+        model: str | None = None,
+        language: str | None = None,
+        transcribe_mode: bool = False,
+    ) -> TranscriptionResult:
+        """
+        Transcribe or process `audio_path` and return a normalized result.
+
+        Args:
+            audio_path: Path to an audio file (wav/mp3/opus...) to send to the provider.
+            user_prompt: Optional user prompt to guide the transcription or analysis.
+            model: Optional provider-specific model identifier.
+            language: Optional language hint/constraint (e.g., "en", "fr").
+            transcribe_mode: Optional bool to enable specialized modes like pure
+                             transcription (default False).
+
+        Returns:
+            TranscriptionResult including a human-readable `text` and
+            provider `raw` payload.
+
+        Raises:
+            ProviderError: For known/handled provider errors (e.g., missing API key).
+            Exception: For unexpected failures (network issues, serialization, etc.).
+        """
+        ...

svx/providers/mistral.py

@@ -0,0 +1,189 @@
+"""
+Mistral provider implementation for SuperVoxtral.
+
+This module provides a concrete Provider that uses Mistral's
+"chat with audio" capability (Voxtral) to process audio and return text.
+
+Requirements:
+- User config must define [providers.mistral].api_key in config.toml.
+- Package 'mistralai' installed and importable.
+
+The provider composes messages with:
+- User content including the audio (base64) and optional user prompt text.
+
+It returns a normalized TranscriptionResult: {"text": str, "raw": dict}.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from pathlib import Path
+from typing import Any, cast
+
+from svx.core.config import Config, ProviderConfig
+
+from .base import Provider, ProviderError, TranscriptionResult
+
+__all__ = ["MistralProvider"]
+
+
+def _read_file_as_base64(path: Path) -> str:
+    """
+    Read a file and return its base64-encoded string.
+    """
+    data = Path(path).read_bytes()
+    return base64.b64encode(data).decode("utf-8")
+
+
+def _extract_text_from_response(resp: Any) -> str:
+    """
+    Attempt to robustly extract the textual content from a Mistral response.
+
+    Handles both dict-like and attribute-like SDK response formats.
+    Falls back to str(resp) if extraction fails.
+    """
+    try:
+        # Get first choice
+        choice0 = resp["choices"][0] if isinstance(resp, dict) else resp.choices[0]  # type: ignore[index]
+        # Get message
+        message = choice0["message"] if isinstance(choice0, dict) else choice0.message
+        # Get content (could be str or list of segments)
+        content = message["content"] if isinstance(message, dict) else message.content
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts: list[str] = []
+            for c in content:
+                if isinstance(c, dict) and c.get("type") == "text":
+                    parts.append(c.get("text", ""))
+            return "\n".join(p for p in parts if p)
+        return str(content)
+    except Exception:
+        return str(resp)
+
+
+def _normalize_raw_response(resp: Any) -> dict[str, Any]:
+    """
+    Convert the response into a plain dict for persistence.
+
+    - If response is already a dict, use it as-is.
+    - If it has 'model_dump_json()', parse it.
+    - Else, try json.loads(str(resp)).
+    - Else, store as {"raw": str(resp)}.
+    """
+    if isinstance(resp, dict):
+        return resp
+    try:
+        # pydantic-like
+        if hasattr(resp, "model_dump_json"):
+            return json.loads(resp.model_dump_json())  # type: ignore[call-arg]
+    except Exception:
+        pass
+    try:
+        return json.loads(str(resp))
+    except Exception:
+        return {"raw": str(resp)}
+
+
+class MistralProvider(Provider):
+    """
+    Mistral Voxtral provider implementation.
+
+    Uses the Mistral Python SDK to call `chat.with_audio` endpoint.
+    """
+
+    name = "mistral"
+
+    def __init__(self, cfg: Config | None = None):
+        if cfg is None:
+            cfg = Config.load()
+        mistral_cfg = cfg.providers.get("mistral", ProviderConfig())
+        self.api_key = mistral_cfg.api_key
+        if not self.api_key:
+            raise ProviderError("Missing providers.mistral.api_key in user config (config.toml).")
+
+    def transcribe(
+        self,
+        audio_path: Path,
+        user_prompt: str | None,
+        model: str | None = "voxtral-small-latest",
+        language: str | None = None,
+        transcribe_mode: bool = False,
+    ) -> TranscriptionResult:
+        """
+        Transcribe/process audio using Mistral's chat-with-audio or transcription endpoint.
+
+        Args:
+            audio_path: Path to wav/mp3/opus file to send.
+            user_prompt: Optional user prompt to include with the audio
+                         (ignored in transcribe_mode).
+            model: Voxtral model identifier (default: "voxtral-small-latest" for chat,
+                   "voxtral-mini-latest" for transcribe).
+            language: Optional language hint for transcription (used only in
+                      transcribe_mode).
+            transcribe_mode: If True, use dedicated transcription endpoint without prompt.
+
+        Returns:
+            TranscriptionResult: {"text": text, "raw": raw_dict}
+
+        Raises:
+            ProviderError: for expected configuration/import errors.
+        """
+        try:
+            from mistralai import Mistral
+        except Exception as e:
+            raise ProviderError(
+                "Failed to import 'mistralai'. Ensure the 'mistralai' package is installed."
+            ) from e
+
+        if not Path(audio_path).exists():
+            raise ProviderError(f"Audio file not found: {audio_path}")
+
+        client = Mistral(api_key=self.api_key)
+
+        if transcribe_mode:
+            if user_prompt:
+                logging.warning("Transcribe mode: user_prompt is ignored.")
+            model_name = model or "voxtral-mini-latest"
+            logging.info(
+                "Calling Mistral transcription endpoint model=%s with audio=%s (%s), language=%s",
+                model_name,
+                Path(audio_path).name,
+                Path(audio_path).suffix,
+                language or "auto",
+            )
+            with open(audio_path, "rb") as f:
+                resp = client.audio.transcriptions.complete(
+                    model=model_name,
+                    file={"content": f, "file_name": Path(audio_path).name},
+                    language=language,
+                )
+            text = resp.text
+            raw = _normalize_raw_response(resp)
+        else:
+            audio_b64 = _read_file_as_base64(Path(audio_path))
+
+            # Compose messages (user only)
+            messages: list[dict[str, Any]] = []
+            user_content: list[dict[str, Any]] = [{"type": "input_audio", "input_audio": audio_b64}]
+            if user_prompt:
+                user_content.append({"type": "text", "text": user_prompt})
+            messages.append({"role": "user", "content": user_content})
+
+            # Execute request
+            model_name = model or "voxtral-small-latest"
+            logging.info(
+                "Calling Mistral chat-with-audio model=%s with audio=%s (%s)",
+                model_name,
+                Path(audio_path).name,
+                Path(audio_path).suffix,
+            )
+            resp = client.chat.complete(model=model_name, messages=cast(Any, messages))
+
+            # Extract normalized text and raw payload
+            text = _extract_text_from_response(resp)
+            raw = _normalize_raw_response(resp)
+
+        return TranscriptionResult(text=text, raw=raw)