supervoxtral 0.1.0__tar.gz

supervoxtral-0.1.0/.gitignore

@@ -0,0 +1,100 @@
+# -----------------------------------------------------------------------------
+# Python
+# -----------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Distribution / packaging
+.Python
+build/
+dist/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+
+# -----------------------------------------------------------------------------
+# Project artifacts
+# -----------------------------------------------------------------------------
+# Logs
+logs/
+!logs/.gitkeep
+
+# Audio recordings
+recordings/
+!recordings/.gitkeep
+
+# Transcripts (API responses)
+transcripts/
+!transcripts/.gitkeep
+
+# Prompts
+prompt/
+!prompt/.gitkeep
+
+# Local environment variables (use .env.example for template)
+.env
+.env.*
+!.env.example
+
+# OS / Editor cruft
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon?
+.Spotlight-V100
+.Trashes
+
+# IDEs
+.vscode/
+.idea/
+
+# Misc
+*.log
+*.tmp
+*.swp
+*.swo
+.python-version

supervoxtral-0.1.0/AGENTS.md

@@ -0,0 +1,88 @@
+# 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.
+
+### Project structure
+```
+supervoxtral/
+├── svx/                           # Python package
+│   ├── __init__.py
+│   ├── cli.py                     # Typer CLI entrypoint (orchestration only, uses Config and Pipeline)
+│   ├── core/                      # Core logic (audio, config, prompts, storage)
+│   │   ├── audio.py               # Recording, ffmpeg detection/conversion
+│   │   ├── config.py              # Structured Config dataclasses, loading, resolution, logging setup
+│   │   ├── pipeline.py            # Centralized RecordingPipeline for CLI/GUI unification
+│   │   ├── prompt.py              # Prompt resolution (via Config)
+│   │   └── storage.py             # Save transcripts and raw JSON (conditional on keep_transcript_files)
+│   ├── providers/                 # API integrations
+│   │   ├── __init__.py            # Provider registry (get_provider with Config support)
+│   │   ├── base.py                # Provider protocol + shared types
+│   │   └── mistral.py             # Mistral Voxtral implementation (init from Config)
+│   └── ui/                        # GUI (Qt-based MVP)
+│       └── qt_app.py              # RecorderWindow/Worker using Pipeline and Config
+
+├── recordings/                    # Audio files (WAV/MP3/Opus) (conditional)
+├── transcripts/                   # API responses (txt/json) (conditional)
+├── logs/                          # Application logs (conditional)
+├── pyproject.toml                 # Project metadata & deps
+├── .env.example                   # Template for secrets (unused; keys in config.toml)
+└── README.md                      # User guide
+```
+
+## Typical Execution Flow
+
+- **Entry**: `svx/cli.py` Typer `record` command parses args (e.g., --prompt, --save-all, --gui, --transcribe).
+- **Config & Prompt**: Load `Config` via `Config.load()` (`core/config.py`); if transcribe_mode, skip prompt resolution; else resolve prompt with `cfg.resolve_prompt()` (`core/prompt.py`).
+- **Pipeline**: Run `RecordingPipeline` (`core/pipeline.py`): record WAV/stop (`core/audio.py`), optional conversion (ffmpeg), get provider/init (`providers/__init__.py`, e.g., `mistral.py` from `cfg`); if transcribe_mode: no prompt, model override to voxtral-mini-latest (with warning if changed), pass transcribe_mode to provider.transcribe; transcribe, conditional save (`core/storage.py` based on `keep_*`/`save_all`), clipboard copy, logging setup.
+- **Cleanup**: Temp files auto-deleted (tempfile) if `keep_*=false`; dirs created only if persistence enabled.
+- **End**: Return `{"text": str, "raw": dict, "duration": float, "paths": dict}`; CLI prints result, GUI emits progress/updates via callback.
+
+## Build & test
+```bash
+# Setup
+uv pip install -e .
+
+# Lint & format
+black svx/
+ruff check svx/
+
+# Diagnostics (post-edits)
+# Use `diagnostics` tool or run locally to check errors/warnings in pipeline.py, config.py, etc.
+basedpyright svx
+
+# Run
+# Initialize user config (generates config.toml with zero-footprint defaults)
+svx config init
+
+# Record (provider/format configured in config.toml; tests zero-footprint)
+svx record --prompt "What's in this file?"
+
+# Test persistence
+svx record --save-all --prompt "Test persistence"
+
+# Test GUI
+svx record --gui
+```
+
+## Maintenance
+
+- use `uv` to install dependancies if needed
+- update `pyproject.toml` then run uv `pip install -e .`
+- 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
+- **Error handling**: Custom exceptions inherit from standard types, use `ProviderError` for API failures
+- **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.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vlebert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

supervoxtral-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: supervoxtral
+Version: 0.1.0
+Summary: CLI/GUI audio recorder and transcription client using Mistral Voxtral (chat with audio and transcription).
+License: MIT
+License-File: LICENSE
+Keywords: audio,cli,gui,mistral,transcription,voxtral,whisper
+Requires-Python: >=3.11
+Requires-Dist: mistralai
+Requires-Dist: pyperclip
+Requires-Dist: python-dotenv
+Requires-Dist: rich
+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: ruff; extra == 'dev'
+Requires-Dist: types-python-dotenv; extra == 'dev'
+Provides-Extra: gui
+Requires-Dist: pyside6-essentials; extra == 'gui'

supervoxtral-0.1.0/README.md

@@ -0,0 +1,237 @@
+# supervoxtral
+
+A simple Python CLI/GUI tool to record audio from your microphone, optionally convert it (WAV/MP3/Opus), and send it to Mistral Voxtral transcription/chat APIs.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- ffmpeg (for MP3/Opus conversions)
+  - macOS: `brew install ffmpeg`
+  - Ubuntu/Debian: `sudo apt-get install ffmpeg`
+  - Windows: https://ffmpeg.org/download.html
+
+---
+
+## Installation
+
+1) Create and activate a virtual environment (example with venv):
+
+- macOS/Linux:
+  ```
+  python -m venv .venv
+  source .venv/bin/activate
+  ```
+
+- Windows (PowerShell):
+  ```
+  python -m venv .venv
+  .\.venv\Scripts\Activate.ps1
+  ```
+
+2) Install the package (editable mode during development is convenient):
+```
+pip install -e .
+```
+
+Optional extras:
+- Dev tools:
+  ```
+  pip install -e ".[dev]"
+  ```
+
+---
+
+## Configuration (API keys and prompts)
+
+API keys and default behavior are configured only in your user configuration file (config.toml), not via environment variables.
+
+- Location of the user config:
+  - macOS: ~/Library/Application Support/SuperVoxtral/config.toml
+  - Linux: ${XDG_CONFIG_HOME:-~/.config}/supervoxtral/config.toml
+  - Windows: %APPDATA%/SuperVoxtral/config.toml
+
+- Initialize your user config and user prompt file:
+
+  ```
+  svx config init
+  ```
+
+  This creates:
+
+  - config.toml (with sensible defaults, including zero-footprint mode)
+  - a user prompt file at: ~/Library/Application Support/SuperVoxtral/prompt/user.md (macOS)
+    - Linux: ${XDG_CONFIG_HOME:-~/.config}/supervoxtral/prompt/user.md
+    - Windows: %APPDATA%/SuperVoxtral/prompt/user.md
+
+**Key config sections (edit `config.toml`):**
+- **[defaults]**: provider (e.g., "mistral"), model, format (e.g., "opus"), language, rate, channels, device, copy (clipboard), keep_audio_files = false, keep_transcript_files = false, keep_log_files = false.
+  - Zero-footprint mode (defaults): When `keep_* = false`, files are handled in OS temporary directories (auto-cleaned, no project dirs created). Set to `true` for persistence (creates `recordings/`, etc.).
+- **[providers.mistral]**: api_key = "your_mistral_key_here", model (e.g., "voxtral-small-latest").
+- **[prompt]**: text (inline prompt), file (path to prompt.md).
+  - Resolution priority: CLI `--prompt`/`--prompt-file` > config.toml [prompt] > user.md fallback > "What's in this audio?".
+
+**Configuration is centralized via a structured `Config` object loaded from your user configuration file (`config.toml`). CLI arguments override select values (e.g., prompt, log level), but most defaults (provider, model, keep flags) come from `config.toml`. No environment variables are used for API keys or settings.**
+
+No `.env` or shell environment variables are used for API keys.
+
+
+---
+
+## Usage (CLI)
+
+Make sure your virtual environment is activated and the project is installed (`pip install -e .`).
+
+General command form:
+```
+svx record [OPTIONS]
+```
+
+**Unified entrypoint**: `svx record` handles both CLI and GUI modes via a centralized pipeline (`svx.core.pipeline.RecordingPipeline`). This ensures consistent behavior for recording, conversion, transcription, saving, clipboard copy, and logging across CLI and GUI.
+
+**Zero-footprint defaults**: No directories created; outputs to console/clipboard. Use `--save-all` or config `keep_* = true` for persistence.
+
+Note: the CLI now exposes a single recording entrypoint. Use `svx record --gui` to launch the GUI frontend. Most defaults (provider, format, model, language, rate, channels, device, keep_audio_files, copy) are configured via your user config (config.toml). The CLI only supports one-off overrides for: --prompt/--prompt-file, --log-level, --outfile-prefix, --gui, --save-all, --transcribe.
+
+Planned MVP commands:
+
+- Record with Mistral Voxtral (chat with audio) and a prompt (provider/format from config):
+  ```
+  svx record --prompt "What's in this file?"
+  ```
+  Tip: Outputs to console and clipboard (if copy=true in config). No files saved unless overridden.
+
+  Persist all outputs (one-off override):
+  ```
+  svx record --save-all --prompt "What's in this file?"
+  ```
+  Creates `recordings/`, `transcripts/`, `logs/` and saves files/logs.
+
+- Pure transcription mode with Mistral Voxtral (no prompt, dedicated endpoint):
+  ```
+  svx record --transcribe
+  ```
+  Note: Prompts are ignored in this mode. Combine with --save-all for persistence:
+  ```
+  svx record --transcribe --save-all
+  ```
+
+  To start the GUI frontend:
+  ```
+  svx record --gui
+  ```
+  The GUI uses the same pipeline and respects config + CLI overrides (e.g., `--gui --save-all` propagates persistence).
+
+  The CLI defaults have been unified to favour the previous GUI defaults (e.g. `--format opus`, `--copy` enabled, and `--no-keep-audio-files` by default). The final effective values still respect the precedence: CLI explicit > user config defaults (config.toml) > built-in defaults.
+
+### Advanced prompt management
+
+You can provide a user prompt, either inline or via a file:
+
+#### User prompt (inline)
+```
+svx record --user-prompt "Transcris puis résume ce qui est dit dans l'audio."
+```
+
+#### User prompt from file
+```
+svx record --user-prompt-file ~/Library/Application\ Support/SuperVoxtral/prompt/user.md
+```
+(Adjust the path for your OS; see “Configuration” for locations.)
+
+#### Resolution priority (no concatenation)
+Order of precedence for determining the final prompt:
+1) `--user-prompt` (inline)
+2) `--user-prompt-file` (explicit file)
+3) `config.toml` → `[prompt].text`
+4) `config.toml` → `[prompt].file`
+5) User prompt file in your user config dir (`.../SuperVoxtral/prompt/user.md`)
+6) Default fallback: "What's in this audio?"
+
+Note: the file and inline prompts are not concatenated; the first non-empty source wins. Uses `Config.resolve_prompt()` for unified resolution across CLI/GUI.
+
+If no user prompt is provided (by any of the above), it defaults to "What's in this audio?".
+
+A single user message is sent containing the audio and (optionally) text.
+
+  Flow:
+  - Starts recording WAV immediately.
+  - Press Enter to stop recording.
+  - Converts WAV to MP3 (if `--format mp3`) or Opus (if `--format opus`).
+  - Sends the audio to Mistral Voxtral as base64 input_audio plus your text prompt.
+  - Prints and saves the response to `transcripts/` (if keep_transcript_files=true or --save-all).
+
+  Flow:
+  - Starts recording WAV.
+  - Press Enter to stop.
+  - Sends the audio to Voxtral (transcription).
+  - Prints and saves the transcript.
+
+Config-driven options (set these in config.toml under [defaults]):
+- rate, channels, device
+- provider, model, format, language
+- keep_audio_files, copy
+
+One-off CLI overrides:
+- `--outfile-prefix mynote_2025-09-09` (custom file prefix)
+- `--log-level debug` (verbose logs)
+- `--user-prompt` (alias: `--prompt`; user prompt text, inline)
+- `--user-prompt-file` (alias: `--prompt-file`; path to user prompt markdown file in your user config dir)
+- `--transcribe` (pure transcription mode, ignores prompts)
+
+Alternative invocation (without console script):
+```
+python -m svx.cli record --prompt "..."
+```
+
+---
+
+## Provider details
+
+### Mistral Voxtral (chat with audio)
+- Model: `voxtral-small-latest` by default (configurable)
+- API: `mistralai` Python client
+- Request structure:
+  - Messages with `content` array containing:
+    - `{ "type": "input_audio", "input_audio": "<base64>" }`
+    - `{ "type": "text", "text": "<prompt>" }`
+- Output: text content from the chat response; saved to `transcripts/`.
+
+Recommended formats:
+- Opus reduces file size and upload time.
+
+Authentication:
+- Mistral: key read from `Config` (user config at `providers.mistral.api_key`).
+
+
+---
+
+## Recording formats and conversion
+
+- Recording happens in WAV (PCM 16-bit, mono, 16k/32k Hz).
+- Optional conversion via ffmpeg:
+  - WAV -> MP3:
+    ```
+    ffmpeg -y -i input.wav -codec:a libmp3lame -q:a 3 output.mp3
+    ```
+  - WAV -> Opus:
+    ```
+    ffmpeg -y -i input.wav -c:a libopus -b:a 24k output.opus
+    ```
+
+The tool will send the converted file if you set `--format mp3` or `--format opus`; otherwise it sends the raw WAV.
+
+---
+
+## macOS notes
+
+- Microphone permission: on first run, macOS will ask for microphone access. Approve it in System Settings > Privacy & Security > Microphone if needed.
+- If you face issues with device selection, we will add a `--device` flag to choose a specific input device.
+
+
+---
+
+## License
+
+MIT

supervoxtral-0.1.0/logs/.gitkeep

@@ -0,0 +1,3 @@
+# This file ensures the 'logs' directory is tracked by version control.
+# Log files produced by the application will be stored here.
+# Safe to keep empty; do not remove if you want the directory in the repo.

supervoxtral-0.1.0/notes.md

@@ -0,0 +1,8 @@
+todo
+
+- localisation reccording dans config
+- paste directement ?
+- nettoyer xml réponse (option)
+- post prompt
+- dépendance ffmpeg
+- fichier ? ou sont il meme si suppr ? possible record en opus direct ?

supervoxtral-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "supervoxtral"
+version = "0.1.0"
+description = "CLI/GUI audio recorder and transcription client using Mistral Voxtral (chat with audio and transcription)."
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = [
+  "transcription",
+  "audio",
+  "mistral",
+  "voxtral",
+  "whisper",
+  "cli",
+  "gui",
+]
+dependencies = [
+  "typer",
+  "rich",
+  "sounddevice",
+  "soundfile",
+  "python-dotenv",
+  "pyperclip",
+  "mistralai",
+]
+
+[project.optional-dependencies]
+gui = ["PySide6-Essentials"]
+dev = ["black", "ruff", "mypy", "types-python-dotenv", "pytest"]
+
+[project.scripts]
+svx = "svx.cli:app"
+
+[tool.black]
+line-length = 100
+target-version = ["py310"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["svx"]
+
+[tool.basedpyright]
+typeCheckingMode = "standard"  # "basic" | "standard" | "strict" (défaut: "standard")
+# reportUnknownArgumentType = false
+# reportUnknownVariableType = false
+# reportUnusedCallResult = false
+# reportUnannotatedClassAttribute = false

supervoxtral-0.1.0/recordings/.gitkeep

@@ -0,0 +1,3 @@
+# This file ensures the 'recordings' directory is tracked by version control.
+# Audio recordings (WAV/MP3/Opus) generated by the CLI will be stored here.
+# Safe to keep empty; do not remove if you want the directory in the repo.

supervoxtral-0.1.0/svx/__init__.py

@@ -0,0 +1,28 @@
+"""
+SuperVoxtral package.
+
+CLI/TUI tool to record audio and send it to transcription/chat providers
+(e.g., Mistral Voxtral "chat with audio").
+
+Expose package version via __version__.
+"""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+except Exception:  # pragma: no cover - very old Python fallback
+    # Fallback for environments that might not have importlib.metadata
+    # (not expected with Python 3.10+)
+    PackageNotFoundError = Exception  # type: ignore
+
+    def version(distribution_name: str) -> str:  # type: ignore
+        return "0.0.0"
+
+
+try:
+    __version__ = version("supervoxtral")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]