Groq

GroqTools allows an Agent to interact with the Groq API for performing fast audio transcription, translation, and text-to-speech (TTS).

Prerequisites

Before using GroqTools, ensure you have the groq library installed and your Groq API key configured.

Install dependencies:
```
1uv pip install -U groq
```
Set your API key: Obtain your API key from the Groq Console and set it as an environment variable.
```
1export GROQ_API_KEY="your-groq-api-key"
```
```
1setx GROQ_API_KEY "your-groq-api-key"
```

Initialization

Import GroqTools and add it to your Agent's tool list.

1from kern.agent import Agent
2from kern.tools.models.groq import GroqTools
3
4agent = Agent(
5    instructions=[
6        "You are a helpful assistant that can transcribe audio, translate text and generate speech."
7    ],
8    tools=[GroqTools()],
9    )

Usage Examples

1. Transcribing Audio

This example demonstrates how to transcribe an audio file hosted at a URL.

1import os
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4from kern.tools.models.groq import GroqTools
5
6audio_url = "https://kern-public.s3.amazonaws.com/demo_data/sample_conversation.wav"
7
8agent = Agent(
9    name="Groq Transcription Agent",
10    model=OpenAIResponses(id="gpt-5.2"),
11    tools=[GroqTools()],
12    )
13
14agent.print_response(f"Please transcribe the audio file located at '{audio_url}'")

2. Translating Audio and Generating Speech

This example shows how to translate an audio file (e.g., French) to English and then generate a new audio file from the translated text.

1from pathlib import Path
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4from kern.tools.models.groq import GroqTools
5from kern.utils.media import save_base64_data
6
7local_audio_path = "tmp/sample-fr.mp3"
8output_path = Path("tmp/sample-en.mp3")
9output_path.parent.mkdir(parents=True, exist_ok=True)
10
11agent = Agent(
12    name="Groq Translation Agent",
13    model=OpenAIResponses(id="gpt-5.2"),
14    tools=[GroqTools()],
15    )
16
17instruction = (
18    f"Translate the audio file at '{local_audio_path}' to English. "
19    f"Then, generate a new audio file using the translated English text."
20)
21response = agent.run(instruction)
22if response and response.audio:
23    save_base64_data(response.audio[0].base64_audio, output_path)

You can customize the underlying Groq models used for transcription, translation, and TTS during initialization:

1groq_tools = GroqTools(
2    transcription_model="whisper-large-v3",
3    translation_model="whisper-large-v3",
4    tts_model="playai-tts",
5    tts_voice="Chip-PlayAI"
6)

Toolkit Params

Parameter	Type	Default	Description
`api_key`	`Optional[str]`	`None`	Groq API key for authentication. If not provided, uses GROQ_API_KEY environment variable.
`transcription_model`	`str`	`"whisper-large-v3"`	Model to use for audio transcription.
`translation_model`	`str`	`"whisper-large-v3"`	Model to use for audio translation to English.
`tts_model`	`str`	`"playai-tts"`	Model to use for text-to-speech generation.
`tts_voice`	`str`	`"Chip-PlayAI"`	Voice to use for text-to-speech generation.
`enable_transcribe_audio`	`bool`	`True`	Enable the audio transcription function.
`enable_translate_audio`	`bool`	`True`	Enable the audio translation function.
`enable_generate_speech`	`bool`	`True`	Enable the text-to-speech generation function.
`all`	`bool`	`False`	Enable all available functions. When True, all enable flags are ignored.

Toolkit Functions

The GroqTools toolkit provides the following functions:

Function	Description
`transcribe_audio`	Transcribes audio from a local file path or a public URL using Groq Whisper.
`translate_audio`	Translates audio from a local file path or public URL to English using Groq.
`generate_speech`	Generates speech from text using Groq TTS.