Groq Whisper Transcriptions
Relevant source files
The following files were used as context for generating this wiki page:
The Groq Whisper Transcription system within GentelmeN-CorE provides a robust interface for converting Telegram voice messages into text. By leveraging the Groq API and the whisper-large-v3 model, the system enables users to interact with the bot using natural speech. Transcribed text is either processed as a direct command (such as image generation) or passed to the primary AI chat interface for a conversational response.
Sources: core/commands.py:194-222, core/bot.py:20-21
System Architecture and Workflow
The transcription logic is primarily handled within the handle_voice function. When a user sends a voice note, the Telegram bot captures the file, downloads it to a temporary local storage, and transmits the binary data to the Groq Cloud API.
Transcription Data Flow
The following diagram illustrates the lifecycle of a voice message from receipt to processing:
The process ensures that sensitive audio data is purged from the local environment immediately after the transcription is completed or if an error occurs during processing.
Sources: core/commands.py:194-227, tests/test_commands.py:348-384
Implementation Details
Voice Handling Logic
The system uses the pyTelegramBotAPI (telebot) to register a specific handler for the voice content type.
| Component | Description |
|---|---|
| Storage | Uses tempfile.NamedTemporaryFile with a .ogg suffix for disk-safe handling. |
| API Client | Utilizes the Groq client initialized with GROQ_KEY. |
| Model | Hardcoded to whisper-large-v3 for high-accuracy results. |
| Cleanup | A finally block ensures os.remove() is called on the temporary path. |
Sources: core/commands.py:194-206, core/commands.py:223-227, core/bot.py:21, requirements.txt:3
Integration with Core Services
Once the text is extracted via transcription.text, the system performs conditional routing. If the transcription identifies a request for drawing (e.g., starting with "rysuj "), it prepends the /rysuj command to ensure the generate_image module handles it correctly. Otherwise, it defaults to ai_chat.
# snippet from core/commands.py
lowered = user_text.lower().strip()
if lowered.startswith("rysuj ") or lowered.startswith("/rysuj "):
parts = user_text.split(None, 1)
prompt = parts[1].strip() if len(parts) > 1 else ''
m.text = f"/rysuj {prompt}"
generate_image(m)
else:
ai_chat(m)
Sources: core/commands.py:213-222
Configuration and Dependencies
The transcription system relies on specific environment variables and external libraries to function.
| Variable | Source | Purpose |
|---|---|---|
GROQ_KEY | core/bot.py | Authentication for the Groq API services. |
TELEGRAM_TOKEN | core/bot.py | Connection to the Telegram Bot API. |
The necessary libraries for this module include groq for API interaction and pyTelegramBotAPI for message handling.
Sources: core/bot.py:11-21, requirements.txt:1-3
Error Handling and Testing
The transcription module includes mechanisms to handle network failures or API errors. It uses the inteligentna_odpowiedz helper to notify the user of errors such as "Błąd głosu".
Automated Tests
The tests/test_commands.py file contains comprehensive unit tests for the transcription flow, including:
- Cleanup verification: Ensuring temporary files are deleted even if transcription fails.
- Routing logic: Testing if "rysuj" triggers image generation vs. standard AI chat.
- Mocking: Using
unittest.mockto simulate Groq API responses and file downloads.
Sources: core/commands.py:222, core/helpers.py:1-16, tests/test_commands.py:348-422
The Groq Whisper Transcription module serves as a bridge between acoustic input and the bot's functional logic, providing a seamless hands-free experience for GentelmeN-CorE users while maintaining strict data hygiene through temporary file management.