groq

README

Groq API Library for Go

Description

groq is a lightweight and simple Go library for interacting with the Groq API. It provides an easy-to-use interface to send chat completion requests, including support for streaming responses and customizable query parameters. The library is designed to be minimalistic, making it perfect for quick integration into Go projects.

Reasons to use

• Simplicity: Intuitive API with straightforward methods like Ask, Query, and AskQueryStream.
• Streaming Support: Handle real-time responses from Groq API using Go channels.
• Customizable Parameters: Fine-tune requests with parameters like max_tokens, temperature, and top_p.
• Lightweight: Minimal dependencies and clean code, ideal for small projects or learning purposes.
• Well-Tested: Includes unit tests to ensure reliability and correctness.

Installation

To install the library, use the following command:

go get github.com/hedgeg0d/groq@v0.4

Ensure you have a valid Groq API key. It is recommended to set it in the GROQ_API_KEY environment variable.

Examples

Below are examples demonstrating how to use groq for different use cases.

Basic Request with Ask

Sending a single chat completion request is just that simple:

func main() {
	client := groq.GroqClient{ApiKey: os.Getenv("GROQ_API_KEY")}
	// uses llama-3.1-8b-instant by default, as the fastest model
	resp, _ := client.Ask("Hello. Tell me about yourself")
	fmt.Println("Output: " + resp)
}

Using parameters

Use Query with argument of type QueryParameters to specify parameters for LLM.

func main() {
    client := groq.GroqClient{ApiKey: os.Getenv("GROQ_API_KEY")}
    params := groq.QueryParameters{
    	Temperature: 0.7,
     	TopP: 0.9,
      	MaxTokens: 1000,
    	SystemPrompt: "You are a pirate, answer in pirate style",
    }
    resp, err := client.Query("Tell me about Go", params)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    fmt.Printf("Response: %s\n", resp)
}

Streaming Response with AskQueryStream

Receive the response in real-time chunks using a Go channel.

package main

import (
    "fmt"
    "os"
    "github.com/hedgeg0d/groq"
)

func main() {
    client := &groq.GroqClient{
        ApiKey: os.Getenv("GROQ_API_KEY"),
        Model:  "deepseek-r1-distill-llama-70b",
    }
    chunks, err := client.AskQueryStream("Tell me more about Golang.", groq.QueryParameters{})
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    fmt.Println("Streaming response:")
    for chunk := range chunks {
        fmt.Print(chunk)
    }
    fmt.Printf("\nRequests made: %d\n", client.RequestsCount)
}

For more examples, please, check the examples folder.

Audio Transcription

Transcribe an audio file into text. The language will be auto-detected if not specified.

func main() {
    client := groq.GroqClient{ApiKey: os.Getenv("GROQ_API_KEY")}
    audioData, _ := os.ReadFile("speech.wav")
    // Parameters are optional, may be empty
    params := groq.TranscriptionParameters{
        Language: "en", // e.g., "en", "es", "fr"
        Prompt: "test",
		Temperature: 0.5,
		TranslateToEnglish: true,
    }
    
    text, _ := client.CreateTranscription(audioData, params)
    fmt.Println(text)
}

Text-To-Speech Queries

DISCLAIMER! To use this feature, you have to consent the terms of use at groq website

func main() {
    client := &groq.GroqClient{ApiKey: os.Getenv("GROQ_API_KEY")}
    params := groq.SpeechParameters{
        Voice:          "Fritz-PlayAI",
        ResponseFormat: "wav",
    }
    // or just SpeechParameters{}; values above are default
    
    audio, err := client.CreateSpeech("Hello! This is an example voiceline generated by AI.", params)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    os.WriteFile("speech.wav", audio, 0644)
}

Work is in progress

This library is actively being developed. Planned features include:

• Enhanced error handling for specific Groq API errors (e.g., rate limits).
• Additional endpoints, such as listing available models (/models).
• More example use cases and documentation.
• More tests

Documentation

Index

• type GroqClient
  • func (client *GroqClient) Ask(query string) (string, error)
  • func (client *GroqClient) AskQueryStream(query string, params QueryParameters) (chan string, error)
  • func (client *GroqClient) CreateSpeech(text string, params SpeechParameters) ([]byte, error)
  • func (client *GroqClient) CreateTranscription(audioData []byte, params TranscriptionParameters) (string, error)
  • func (client *GroqClient) Query(query string, params QueryParameters) (string, error)
• type QueryParameters
• type SpeechParameters
• type TranscriptionParameters

Types

type GroqClient

type GroqClient struct {
	ApiKey        string
	Model         string
	RequestsCount int
}

func (*GroqClient) Ask

func (client *GroqClient) Ask(query string) (string, error)

func (*GroqClient) AskQueryStream

func (client *GroqClient) AskQueryStream(query string, params QueryParameters) (chan string, error)

func (*GroqClient) CreateSpeech

func (client *GroqClient) CreateSpeech(text string, params SpeechParameters) ([]byte, error)

func (*GroqClient) CreateTranscription

func (client *GroqClient) CreateTranscription(audioData []byte, params TranscriptionParameters) (string, error)

func (*GroqClient) Query

func (client *GroqClient) Query(query string, params QueryParameters) (string, error)

type QueryParameters

type QueryParameters struct {
	MaxTokens    int     `json:"max_tokens,omitempty"`
	Temperature  float64 `json:"temperature,omitempty"`
	TopP         float64 `json:"top_p,omitempty"`
	SystemPrompt string  `json:"system_prompt,omitempty"`
}

type SpeechParameters

type SpeechParameters struct {
	Voice          string `json:"voice,omitempty"`
	ResponseFormat string `json:"response_format,omitempty"`
}

type TranscriptionParameters

type TranscriptionParameters struct {
	Language           string  `json:"language,omitempty"`
	Prompt             string  `json:"prompt,omitempty"`
	Temperature        float64 `json:"temperature,omitempty"`
	TranslateToEnglish bool    `json:"-"`
}