supervoxtral 0.1.5__tar.gz → 0.3.0__tar.gz

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/.gitignore

@@ -98,3 +98,5 @@ Icon?
 *.swp
 *.swo
 .python-version
+.aider*
+notes.md

supervoxtral-0.3.0/AGENTS.md

@@ -0,0 +1,104 @@
+# SuperVoxtral — Agent Guide
+
+## Project overview
+Python CLI/GUI for audio recording + transcription via APIs (Mistral Voxtral). MVP: manual stop, API-based, zero-footprint defaults (temp files, no persistent dirs unless overridden), results in `transcripts/` when persisted.
+
+### Core Design Principles
+
+1. **Centralized Pipeline**: All recording/transcription flows through `RecordingPipeline` (svx/core/pipeline.py) for consistency between CLI and GUI
+2. **Config-driven**: Structured `Config` dataclass (svx/core/config.py) loaded from user's config.toml; CLI args override specific values
+3. **Zero-footprint defaults**: Temp files auto-deleted unless `keep_*` flags or `--save-all` enabled; no project directories created by default
+4. **Provider abstraction**: `Provider` protocol (svx/providers/base.py) for pluggable transcription services
+
+### Module Structure
+
+- **svx/cli.py**: Typer CLI entrypoint; orchestration only, delegates to Config and Pipeline
+- **svx/core/**:
+  - `config.py`: Config dataclasses, TOML loading, prompt resolution (supports multiple prompts via [prompt.key] sections), logging setup
+  - `pipeline.py`: RecordingPipeline class - records, converts (ffmpeg), transcribes, saves conditionally, copies to clipboard
+  - `audio.py`: WAV recording (sounddevice), ffmpeg detection/conversion to MP3/Opus
+  - `prompt.py`: Multi-prompt resolution from config dict (key-based: "default", "test", etc.)
+  - `storage.py`: Save transcripts/JSON conditionally based on keep_transcript_files
+  - `clipboard.py`: Cross-platform clipboard copy
+- **svx/providers/**:
+  - `base.py`: Provider protocol, TranscriptionResult TypedDict, ProviderError
+  - `mistral.py`: Mistral Voxtral implementation (dedicated transcription endpoint + text-based LLM chat)
+  - `openai.py`: OpenAI Whisper implementation
+  - `__init__.py`: Provider registry (get_provider)
+- **svx/ui/**:
+  - `qt_app.py`: PySide6 GUI (RecorderWindow/Worker) using Pipeline; dynamic buttons per prompt key
+
+### Execution Flow
+
+1. **Entry**: CLI parses args (--prompt, --save-all, --gui, --transcribe)
+2. **Config Load**: Config.load() reads config.toml (supports [prompt.default], [prompt.other], etc.); `chat_model` for text LLM; API keys in [providers.mistral] or [providers.openai]
+3. **Context Bias**: Optional `context_bias` list in `[defaults]` (up to 100 items) — passed to Mistral's transcription endpoint to improve recognition of specific vocabulary (proper nouns, technical terms). Stored in `DefaultsConfig`, read by `MistralProvider.__init__`.
+4. **Prompt Resolution**:
+   - CLI: Uses "default" prompt key unless --prompt/--prompt-file overrides
+   - GUI: Dynamic buttons for each [prompt.key]; "Transcribe" button bypasses prompt
+   - Priority: CLI arg > config [prompt.key] > user prompt file > fallback
+5. **Pipeline Execution** (RecordingPipeline) — 2-step pipeline:
+   - record(): WAV recording via sounddevice, temp file if keep_audio_files=false
+   - process(): Optional ffmpeg conversion, then:
+     - Step 1 (Transcription): audio → text via provider.transcribe() (dedicated endpoint, always)
+     - Step 2 (Transformation): text + prompt → text via provider.chat() (text LLM, only when prompt provided)
+   - Uses `cfg.defaults.model` for transcription, `cfg.defaults.chat_model` for transformation
+   - Conditional save_transcript (+ raw transcript file when transformation applied), clipboard copy
+   - clean(): Temp file cleanup
+6. **Transcribe Mode** (CLI only):
+   - --transcribe flag: No prompt, step 1 only (dedicated transcription endpoint)
+   - GUI: --transcribe ignored (warning); use "Transcribe" button instead
+7. **Output**: CLI prints result; GUI emits via callback; temp files auto-deleted unless keep_* enabled
+
+## Build
+```bash
+# Setup (creates .venv, editable install, lockfile-based)
+uv sync --extra dev --extra gui
+```
+
+## Linting and Type Checking
+```bash
+# Lint & format
+uv run ruff check svx/
+
+# Type checker
+uv run basedpyright svx
+```
+
+## Running the Application
+```bash
+# CLI: Record with prompt
+svx record --prompt "Transcribe this audio"
+
+# CLI: Pure transcription (no prompt)
+svx record --transcribe
+
+# GUI: Launch interactive recorder
+svx record --gui
+
+# Config management
+svx config init    # Create default config.toml
+svx config open    # Open config directory
+svx config show    # Display current config
+```
+
+## Maintenance
+
+- use `uv sync --extra dev --extra gui` to install/update dependencies
+- after updating `pyproject.toml`, run `uv sync --extra dev --extra gui` to refresh the environment
+- When adding modules: Propagate Config instance; use RecordingPipeline for recording flows; handle temp files via keep_* flags.
+- Test temp cleanup: Verify no leftovers in default mode (keep_*=false).
+
+
+## Code style
+- **Imports**: `from __future__ import annotations` first, then stdlib, third-party, local
+- **Formatting**: Black (100 line length), ruff for linting (E, F, I, UP rules)
+- **Types**: Full type hints required, use `TypedDict` for data structures, `Protocol` for interfaces (e.g., Provider protocol, Config dataclasses with type hints)
+- **Naming**: snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
+- **Docstrings**: Google-style with clear purpose/dependencies/`__all__` exports
+
+## Security
+- API keys are configured in the user config file (`config.toml`), under provider-specific sections.
+- Mistral: define `[providers.mistral].api_key`
+- Environment variables are not used for API keys.
+- Validate user inputs (e.g., paths in Config, prompt resolution).

supervoxtral-0.3.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: supervoxtral
-Version: 0.1.5
-Summary: CLI/GUI audio recorder and transcription client using Mistral Voxtral (chat with audio and transcription).
+Version: 0.3.0
+Summary: CLI/GUI audio recorder with 2-step pipeline: transcription (Voxtral) then text transformation (LLM).
 License: MIT
 License-File: LICENSE
 Keywords: audio,cli,gui,mistral,transcription,voxtral,whisper
@@ -14,10 +14,7 @@ Requires-Dist: sounddevice
 Requires-Dist: soundfile
 Requires-Dist: typer
 Provides-Extra: dev
-Requires-Dist: black; extra == 'dev'
-Requires-Dist: mypy; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: basedpyright; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
-Requires-Dist: types-python-dotenv; extra == 'dev'
 Provides-Extra: gui
 Requires-Dist: pyside6-essentials; extra == 'gui'

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/README.md

@@ -2,9 +2,9 @@
 
 ![Supervoxtral](supervoxtral.gif)
 
-SuperVoxtral is a lightweight Python CLI/GUI utility for recording microphone audio and integrate with Mistral's Voxtral APIs for transcription or audio-enabled chat.
+SuperVoxtral is a lightweight Python CLI/GUI utility for recording microphone audio and processing it via a 2-step pipeline using Mistral's APIs.
 
-Voxtral models, such as `voxtral-mini-latest` and `voxtral-small-latest`, deliver fast inference times, high transcription accuracy across languages and accents, and minimal API costs. Voxtral supports two modes: pure transcription via a dedicated endpoint (no prompts needed) or chat mode, where audio input combines with text prompts for refined outputs—like error correction or contextual summarization—without invoking a separate LLM.
+The pipeline works in two stages: (1) **Transcription** — audio is converted to text using Voxtral's dedicated transcription endpoint (`voxtral-mini-latest`), which delivers fast inference, high accuracy across languages, and minimal API costs; (2) **Transformation** — the raw transcript is refined by a text-based LLM (e.g., `mistral-small-latest`) using a configurable prompt for tasks like error correction, summarization, or reformatting. In pure transcription mode (`--transcribe`), only step 1 is performed.
 
 For instance, use a prompt like: "_Transcribe this audio precisely and remove all minor speech hesitations: "um", "uh", "er", "euh", "ben", etc._"
 
@@ -65,10 +65,15 @@ This installs the `svx` command within the virtual environment. Make sure to act
 
 **For development** (local editing):
 1. Clone the repo and navigate to the project root.
-2. Create/activate a virtual environment:
-   - macOS/Linux: `python -m venv .venv && source .venv/bin/activate`
-   - Windows: `python -m venv .venv && .\.venv\Scripts\Activate.ps1`
-3. Install in editable mode: `pip install -e .` (or `pip install -e ".[dev]"` for dev tools).
+2. Install dependencies (creates `.venv` automatically, editable mode, lockfile-based):
+   ```
+   uv sync --extra dev --extra gui
+   ```
+3. Run linting and type checking:
+   ```
+   uv run ruff check svx/
+   uv run basedpyright svx
+   ```
 
 ## Quick Start
 
@@ -144,12 +149,20 @@ provider = "mistral"
 # Recording is always WAV; conversion is applied if "mp3" or "opus"
 format = "opus"
 
-# Model to use on the provider side (example for Mistral Voxtral)
+# Model for audio transcription (dedicated endpoint)
 model = "voxtral-mini-latest"
 
+# Model for text transformation via LLM (applied after transcription when a prompt is used)
+chat_model = "mistral-small-latest"
+
 # Language hint (may help the provider)
 language = "fr"
 
+# Context bias: up to 100 words/phrases to help recognize specific vocabulary
+# (proper nouns, technical terms, brand names, etc.)
+# context_bias = ["SuperVoxtral", "Mistral AI", "Voxtral"]
+context_bias = []
+
 # Audio recording parameters
 rate = 16000
 channels = 1
@@ -234,6 +247,8 @@ By default in CLI, uses the 'default' prompt from config.toml [prompt.default].
 
 ## Changelog
 
+- 0.3.0: Add `context_bias` support for Mistral Voxtral transcription — a list of up to 100 words/phrases to help the model recognize specific vocabulary (proper nouns, technical terms, brand names). Configurable in `config.toml` under `[defaults]`.
+- 0.2.0: 2-step pipeline (transcription → transformation). Replaces chat-with-audio by dedicated transcription endpoint + text-based LLM. New `chat_model` config option. Raw transcript saved separately when transformation is applied.
 - 0.1.5: Fix bug on prompt selecting
 - 0.1.4: Support for multiple prompts in config.toml with dynamic GUI buttons for each prompt key
 - 0.1.3: Minor style update

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supervoxtral"
-version = "0.1.5"
-description = "CLI/GUI audio recorder and transcription client using Mistral Voxtral (chat with audio and transcription)."
+version = "0.3.0"
+description = "CLI/GUI audio recorder with 2-step pipeline: transcription (Voxtral) then text transformation (LLM)."
 requires-python = ">=3.11"
 license = { text = "MIT" }
 keywords = [
@@ -29,15 +29,11 @@ dependencies = [
 
 [project.optional-dependencies]
 gui = ["PySide6-Essentials"]
-dev = ["black", "ruff", "mypy", "types-python-dotenv", "pytest"]
+dev = ["ruff", "basedpyright"]
 
 [project.scripts]
 svx = "svx.cli:app"
 
-[tool.black]
-line-length = 100
-target-version = ["py310"]
-
 [tool.ruff]
 line-length = 100
 target-version = "py310"
@@ -51,6 +47,7 @@ packages = ["svx"]
 
 [tool.basedpyright]
 typeCheckingMode = "standard"  # "basic" | "standard" | "strict" (défaut: "standard")
+reportUnknownParameterType = true
 # reportUnknownArgumentType = false
 # reportUnknownVariableType = false
 # reportUnusedCallResult = false

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/svx/cli.py

@@ -162,10 +162,14 @@ def record(
     ),
 ):
     """
-    Record audio from the microphone and send it to the selected provider.
+    Record audio from the microphone and process it via a 2-step pipeline.
+
+    Pipeline:
+    1. Transcription: audio -> text via dedicated transcription endpoint (always).
+    2. Transformation: text + prompt -> text via text-based LLM (when a prompt is provided).
 
     This CLI accepts only a small set of runtime flags. Most defaults (provider, format,
-    model, language, sample rate, channels, device,
+    model, chat_model, language, sample rate, channels, device,
     file retention, copy-to-clipboard)
     must be configured in the user's `config.toml` under [defaults].
 
@@ -178,11 +182,12 @@ def record(
     Flow:
     - Records WAV until you press Enter (CLI mode).
     - Optionally converts to MP3/Opus depending on config.
-    - Sends the file per provider rules.
+    - Transcribes via dedicated endpoint (step 1).
+    - If a prompt is provided, transforms the transcript via LLM (step 2).
     - Prints and saves the result.
 
     Note: In --transcribe mode, prompts (--user-prompt or --user-prompt-file) are ignored,
-    as it uses a dedicated transcription endpoint without prompting.
+    and only step 1 (transcription) is performed.
     """
     cfg = Config.load(log_level=log_level)
 

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/svx/core/audio.py

@@ -22,6 +22,7 @@ from pathlib import Path
 from threading import Event, Thread
 from typing import Any
 
+import numpy as np
 import sounddevice as sd
 import soundfile as sf
 
@@ -149,7 +150,12 @@ def record_wav(
     writer_stop = Event()
     start_time = time.time()
 
-    def audio_callback(indata, frames, time_info, status):
+    def audio_callback(
+        indata: np.ndarray[Any, np.dtype[np.int16]],
+        frames: int,
+        time_info: sd.CallbackFlags,
+        status: sd.CallbackFlags,
+    ) -> None:
         if status:
             logging.warning("SoundDevice status: %s", status)
         q.put(indata.copy())

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/svx/core/config.py

@@ -220,10 +220,17 @@ def init_user_config(force: bool = False, prompt_file: Path | None = None) -> Pa
         '# File format sent to the provider: "wav" | "mp3" | "opus"\n'
         '# Recording is always WAV; conversion is applied if "mp3" or "opus"\n'
         'format = "opus"\n\n'
-        "# Model to use on the provider side (example for Mistral Voxtral)\n"
+        "# Model for audio transcription (dedicated endpoint)\n"
         'model = "voxtral-mini-latest"\n\n'
+        "# Model for text transformation via LLM\n"
+        "# (applied after transcription when a prompt is used)\n"
+        'chat_model = "mistral-small-latest"\n\n'
         "# Language hint (may help the provider)\n"
         'language = "fr"\n\n'
+        "# Context bias: up to 100 words/phrases to help recognize specific vocabulary\n"
+        "# (proper nouns, technical terms, brand names, etc.)\n"
+        '# context_bias = ["SuperVoxtral", "Mistral AI", "Voxtral"]\n'
+        "context_bias = []\n\n"
         "# Audio recording parameters\n"
         "rate = 16000\n"
         "channels = 1\n"
@@ -271,7 +278,9 @@ class DefaultsConfig:
     provider: str = "mistral"
     format: str = "opus"
     model: str = "voxtral-mini-latest"
+    chat_model: str = "mistral-small-latest"
     language: str | None = None
+    context_bias: list[str] = field(default_factory=list)
     rate: int = 16000
     channels: int = 1
     device: str | None = None
@@ -315,7 +324,11 @@ class Config:
             "provider": str(user_defaults_raw.get("provider", "mistral")),
             "format": str(user_defaults_raw.get("format", "opus")),
             "model": str(user_defaults_raw.get("model", "voxtral-mini-latest")),
+            "chat_model": str(user_defaults_raw.get("chat_model", "mistral-small-latest")),
             "language": user_defaults_raw.get("language"),
+            "context_bias": list(user_defaults_raw.get("context_bias", []))
+            if isinstance(user_defaults_raw.get("context_bias"), list)
+            else [],
             "rate": int(user_defaults_raw.get("rate", 16000)),
             "channels": int(user_defaults_raw.get("channels", 1)),
             "device": user_defaults_raw.get("device"),
@@ -335,6 +348,9 @@ class Config:
         format_ = defaults_data["format"]
         if format_ not in {"wav", "mp3", "opus"}:
             raise ValueError("format must be one of wav|mp3|opus")
+        context_bias = defaults_data["context_bias"]
+        if len(context_bias) > 100:
+            raise ValueError("context_bias cannot contain more than 100 items (Mistral API limit)")
         defaults = DefaultsConfig(**defaults_data)
         # Conditional output directories
         if defaults.keep_audio_files:

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/svx/core/pipeline.py

@@ -12,18 +12,23 @@ import svx.core.config as config
 from svx.core.audio import convert_audio, record_wav, timestamp
 from svx.core.clipboard import copy_to_clipboard
 from svx.core.config import Config
-from svx.core.storage import save_transcript
+from svx.core.storage import save_text_file, save_transcript
 from svx.providers import get_provider
 
 
 class RecordingPipeline:
     """
-    Centralized pipeline for recording audio, transcribing via provider, saving outputs,
-    and copying to clipboard. Handles temporary files when not keeping audio.
+    Centralized pipeline for recording audio, transcribing via provider, optionally
+    transforming with a text LLM, saving outputs, and copying to clipboard.
 
+    Pipeline steps:
+    1. Transcription: audio -> text via dedicated transcription endpoint (always)
+    2. Transformation: text + prompt -> text via text-based LLM (when a prompt is provided)
+
+    Handles temporary files when not keeping audio.
     Supports runtime overrides like save_all for keeping all files and adding log handlers.
     Optional progress_callback for status updates (e.g., for GUI).
-    Supports transcribe_mode for pure transcription without prompt using dedicated endpoint.
+    Supports transcribe_mode for pure transcription without prompt (step 1 only).
     """
 
     def __init__(
@@ -136,31 +141,26 @@ class RecordingPipeline:
         self, wav_path: Path, duration: float, transcribe_mode: bool, user_prompt: str | None = None
     ) -> dict[str, Any]:
         """
-        Process recorded audio: convert if needed, transcribe, save, copy.
+        Process recorded audio: convert if needed, transcribe, optionally transform, save, copy.
+
+        Pipeline:
+        1. Transcription: audio -> text via dedicated endpoint (always)
+        2. Transformation: text + prompt -> text via LLM (when prompt is provided)
 
         Args:
             wav_path: Path to the recorded WAV file.
             duration: Recording duration in seconds.
-            transcribe_mode: Whether to use pure transcription mode.
-            user_prompt: User prompt to use (None for transcribe_mode).
+            transcribe_mode: Whether to use pure transcription mode (step 1 only).
+            user_prompt: User prompt to use for transformation (None for transcribe_mode).
 
         Returns:
-            Dict with 'text' (str), 'raw' (dict), 'duration' (float),
-            'paths' (dict of Path or None).
+            Dict with 'text' (str), 'raw_transcript' (str), 'raw' (dict),
+            'duration' (float), 'paths' (dict of Path or None).
         """
         # Resolve parameters
         provider = self.cfg.defaults.provider
         audio_format = self.cfg.defaults.format
         model = self.cfg.defaults.model
-        original_model = model
-        if transcribe_mode:
-            model = "voxtral-mini-latest"
-            if original_model != "voxtral-mini-latest":
-                logging.warning(
-                    "Transcribe mode: model override from '%s' to 'voxtral-mini-latest'\n"
-                    "(optimized for transcription).",
-                    original_model,
-                )
         language = self.cfg.defaults.language
         if wav_path.stem.endswith(".wav"):
             base = wav_path.stem.replace(".wav", "")
@@ -176,9 +176,9 @@ class RecordingPipeline:
                 final_user_prompt = self.cfg.resolve_prompt(self.user_prompt, self.user_prompt_file)
             else:
                 final_user_prompt = user_prompt
-            self._status("Transcribe mode not activated: using prompt.")
+            self._status("Prompt mode: transcription then transformation.")
         else:
-            self._status("Transcribe mode activated: no prompt used.")
+            self._status("Transcribe mode: transcription only, no prompt.")
 
         logging.debug(f"Applied prompt: {final_user_prompt or 'None (transcribe mode)'}")
 
@@ -194,18 +194,22 @@ class RecordingPipeline:
             paths["converted"] = to_send_path
             _converted = True
 
-        # Transcribe
+        # Step 1: Transcription (always)
         self._status("Transcribing...")
         prov = get_provider(provider, cfg=self.cfg)
-        result = prov.transcribe(
-            to_send_path,
-            user_prompt=final_user_prompt,
-            model=model,
-            language=language,
-            transcribe_mode=transcribe_mode,
-        )
-        text = result["text"]
-        raw = result["raw"]
+        result = prov.transcribe(to_send_path, model=model, language=language)
+        raw_transcript = result["text"]
+
+        # Step 2: Transformation (if prompt)
+        if not transcribe_mode and final_user_prompt:
+            self._status("Applying prompt...")
+            chat_model = self.cfg.defaults.chat_model
+            chat_result = prov.chat(raw_transcript, final_user_prompt, model=chat_model)
+            text = chat_result["text"]
+            raw = {"transcription": result["raw"], "transformation": chat_result["raw"]}
+        else:
+            text = raw_transcript
+            raw = result["raw"]
 
         # Save if keeping transcripts
         if keep_transcript:
@@ -215,6 +219,12 @@ class RecordingPipeline:
             )
             paths["txt"] = txt_path
             paths["json"] = json_path
+
+            # Save raw transcript separately when transformation was applied
+            if not transcribe_mode and final_user_prompt:
+                raw_txt_path = self.cfg.transcripts_dir / f"{base}_{provider}_raw.txt"
+                save_text_file(raw_txt_path, raw_transcript)
+                paths["raw_txt"] = raw_txt_path
         else:
             paths["txt"] = None
             paths["json"] = None
@@ -230,6 +240,7 @@ class RecordingPipeline:
         logging.info("Processing finished (%.2fs)", duration)
         return {
             "text": text,
+            "raw_transcript": raw_transcript,
             "raw": raw,
             "duration": duration,
             "paths": paths,
@@ -263,8 +274,8 @@ class RecordingPipeline:
             stop_event: Optional event to signal recording stop (e.g., for GUI).
 
         Returns:
-            Dict with 'text' (str), 'raw' (dict), 'duration' (float),
-            'paths' (dict of Path or None).
+            Dict with 'text' (str), 'raw_transcript' (str), 'raw' (dict),
+            'duration' (float), 'paths' (dict of Path or None).
 
         Raises:
             Exception: On recording, conversion, or transcription errors.

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/svx/core/prompt.py

@@ -158,7 +158,7 @@ def resolve_user_prompt(
             logging.debug("Prompt supplier '%s' failed: %s", name, e)
 
     # Final fallback
-    fallback = "What's in this audio?"
+    fallback = "Clean up this transcription. Keep the original language."
     logging.info("resolve_user_prompt: no supplier provided a prompt, using fallback: %s", fallback)
     return fallback
 
@@ -176,13 +176,14 @@ def init_user_prompt_file(force: bool = False) -> Path:
     path = USER_PROMPT_DIR / "user.md"
     if not path.exists() or force:
         example_prompt = """
-- Transcribe the input audio file. If the audio if empty, just respond "no audio detected".
-- Do not respond to any question in the audio. Just transcribe.
-- DO NOT TRANSLATE.
-- Responde only with the transcription. Do not provide explanations or notes.
+You receive a raw transcription of a voice recording. Clean it up:
+- DO NOT TRANSLATE. Keep the original language.
+- Do not respond to any question in the text. Just clean the transcription.
+- Respond only with the cleaned text. 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.
+- If the transcription is empty, respond "no audio detected".
         """
         try:
             path.write_text(example_prompt, encoding="utf-8")

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/svx/core/storage.py

@@ -86,7 +86,7 @@ def save_transcript(
     base_name: str,
     provider: str,
     text: str,
-    raw: dict | None = None,
+    raw: dict[str, Any] | None = None,
 ) -> tuple[Path, Path | None]:
     """
     Save a transcript text and, optionally, the raw JSON response.

{supervoxtral-0.1.5 → supervoxtral-0.3.0}/svx/providers/base.py

@@ -3,7 +3,7 @@ Base provider interface for SuperVoxtral.
 
 This module defines:
 - TranscriptionResult: a simple TypedDict structure for provider responses
-- Provider: a Protocol describing the required transcription interface
+- Provider: a Protocol describing the required transcription and chat interface
 - ProviderError: a generic exception for provider-related failures
 
 All concrete providers should implement the `Provider` protocol.
@@ -37,7 +37,7 @@ class ProviderError(RuntimeError):
 @runtime_checkable
 class Provider(Protocol):
     """
-    Provider interface for transcription/chat-with-audio services.
+    Provider interface for transcription and text transformation services.
 
     Implementations should be side-effect free aside from network I/O and must
     raise `ProviderError` (or a subclass) for expected provider failures
@@ -47,7 +47,8 @@ class Provider(Protocol):
         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.
+        transcribe: Perform audio transcription via a dedicated endpoint.
+        chat: Transform text with a prompt via a text-based LLM.
     """
 
     # Short, unique name (e.g., "mistral", "whisper")
@@ -56,21 +57,16 @@ class Provider(Protocol):
     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.
+        Transcribe `audio_path` using a dedicated transcription endpoint.
 
         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
@@ -81,3 +77,27 @@ class Provider(Protocol):
             Exception: For unexpected failures (network issues, serialization, etc.).
         """
         ...
+
+    def chat(
+        self,
+        text: str,
+        prompt: str,
+        model: str | None = None,
+    ) -> TranscriptionResult:
+        """
+        Transform `text` using a text-based LLM with the given `prompt`.
+
+        Args:
+            text: Input text (e.g., raw transcription) to process.
+            prompt: System prompt guiding the transformation.
+            model: Optional provider-specific model identifier for the chat LLM.
+
+        Returns:
+            TranscriptionResult including the transformed `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.).
+        """
+        ...