groq

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 4, 2026 License: MIT Imports: 11 Imported by: 1

README

Groq Go SDK

Go Reference

The unofficial Go client library for the Groq Cloud API. This SDK provides idiomatic, high-performance Go access to Groq's LPU™ Inference Engine, enabling ultra-fast AI applications.

🚀 Features

  • Chat Completions: Standard request/response with support for all Groq models.
  • Streaming: Real-time token streaming with full usage statistics support.
  • JSON Mode: Enforce structured JSON outputs for reliable parsing.
  • Tool Calling: Native support for function calling (Agentic workflows).
  • Audio: Speech-to-Text (Whisper) and Text-to-Speech (TTS).
  • Configurable: Custom HTTP clients, timeouts, and base URLs.

📦 Installation

go get github.com/algolyzer/groq-go

⚙️ Configuration

Initialize the client with your API key. You can also configure the base URL or HTTP client if needed.

import "github.com/algolyzer/groq-go"

func main() {
// Basic initialization
client := groq.NewClient(os.Getenv("GROQ_API_KEY"))

// Advanced initialization (optional)
// client := groq.NewClient(
//     os.Getenv("GROQ_API_KEY"),
//     groq.WithBaseURL("[https://api.groq.com/openai/v1](https://api.groq.com/openai/v1)"),
//     groq.WithHTTPClient(&http.Client{Timeout: 60 * time.Second}),
// )
}

📖 Usage Examples

1. Chat Completion (Standard)

Generate a simple text response.

resp, err := client.CreateChatCompletion(context.Background(), groq.ChatCompletionRequest{
Model: "llama-3.3-70b-versatile",
Messages: []groq.ChatMessage{
{Role: groq.RoleUser, Content: "Explain quantum computing in 2 sentences."},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.Choices[0].Message.Content)
2. Streaming (Real-time)

Stream tokens as they are generated. Includes support for Usage Statistics at the end of the stream.

stream, err := client.CreateChatCompletionStream(context.Background(), groq.ChatCompletionRequest{
Model: "llama-3.3-70b-versatile",
Messages: []groq.ChatMessage{
{Role: groq.RoleUser, Content: "Write a haiku about code."},
},
// Request token usage stats (optional)
StreamOptions: &groq.StreamOptions{IncludeUsage: true},
})
if err != nil {
log.Fatal(err)
}
defer stream.Close()

for {
chunk, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
log.Fatal(err)
}

// Print content delta
if len(chunk.Choices) > 0 {
fmt.Print(chunk.Choices[0].Delta.Content)
}

// Check for final usage stats
if chunk.Usage != nil {
fmt.Printf("\n\n[Total Tokens: %d]\n", chunk.Usage.TotalTokens)
}
}
3. JSON Mode (Structured Output)

Force the model to output valid JSON.

resp, err := client.CreateChatCompletion(context.Background(), groq.ChatCompletionRequest{
Model: "llama-3.1-8b-instant",
Messages: []groq.ChatMessage{
{Role: groq.RoleSystem, Content: "You are a database api."},
{Role: groq.RoleUser, Content: "Return a user object for John Doe."},
},
// Enable JSON mode
Format: &groq.ResponseFormat{Type: "json_object"},
})

fmt.Println(resp.Choices[0].Message.Content)
// Output: { "name": "John Doe", "id": 12345, "role": "user" }
4. Tool Calling (Function Calling)

Define tools that the model can request to call.

// 1. Define the tool
tools := []groq.Tool{
{
Type: "function",
Function: groq.ToolFunction{
Name:        "get_weather",
Description: "Get the weather for a location",
Parameters: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"location": map[string]interface{}{"type": "string"},
},
"required": []string{"location"},
},
},
},
}

// 2. Send request
resp, _ := client.CreateChatCompletion(context.Background(), groq.ChatCompletionRequest{
Model:      "llama-3.3-70b-versatile",
Messages:   []groq.ChatMessage{{Role: groq.RoleUser, Content: "Weather in NY?"}},
Tools:      tools,
ToolChoice: "auto",
})

// 3. Check if model wants to call a tool
msg := resp.Choices[0].Message
if len(msg.ToolCalls) > 0 {
fmt.Printf("Tool to call: %s\n", msg.ToolCalls[0].Function.Name)
fmt.Printf("Arguments: %s\n", msg.ToolCalls[0].Function.Arguments)
}
5. Audio Transcription (Whisper)

Transcribe audio files using Groq's distil-whisper models.

resp, err := client.CreateTranscription(context.Background(), groq.AudioTranscriptionRequest{
FilePath: "meeting.m4a",
Model:    "whisper-large-v3",
Language: "en",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.Text)
6. Text-to-Speech (TTS)

Generate audio from text.

audioBytes, err := client.CreateSpeech(context.Background(), groq.CreateSpeechRequest{
Model: "playai-tts", // or other supported TTS models
Input: "The quick brown fox jumps over the lazy dog.",
Voice: "autumn",
})
if err != nil {
log.Fatal(err)
}

os.WriteFile("output.mp3", audioBytes, 0644)

To run the examples, navigate to the examples directory:

export GROQ_API_KEY="your_api_key_here"
go run examples/chat/main.go
go run examples/stream/main.go

📜 License

Distributed under the MIT License. See LICENSE for more information.

Documentation

Index

Constants

View Source 
const (
	RoleSystem    = "system"
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleTool      = "tool"
)

Constants for Roles

Variables

This section is empty.

Functions

func Bool 

func Bool(v bool) *bool

func Float64 

func Float64(v float64) *float64

func Int 

func Int(v int) *int

func String 

func String(v string) *string

Helper functions to create pointers for optional fields.

Types

type APIError 

type APIError struct {
	Message string `json:"message"`
	Type    string `json:"type"`
	Code    string `json:"code,omitempty"`
	Param   string `json:"param,omitempty"`
}

type AudioResponse 

type AudioResponse struct {
	Text string `json:"text"`
}

type AudioTranscriptionRequest 

type AudioTranscriptionRequest struct {
	FilePath       string
	Model          string   // e.g., "whisper-large-v3"
	Language       string   // Optional "en", "es", etc.
	Prompt         string   // Optional
	Temperature    *float64 // Optional
	ResponseFormat string   // "json", "text", "verbose_json"
}

type ChatCompletionRequest 

type ChatCompletionRequest struct {
	Model               string          `json:"model"`
	Messages            []ChatMessage   `json:"messages"`
	Temperature         *float64        `json:"temperature,omitempty"`
	MaxCompletionTokens int             `json:"max_completion_tokens,omitempty"` // Replaces MaxTokens
	MaxTokens           int             `json:"max_tokens,omitempty"`            // Deprecated but supported
	TopP                *float64        `json:"top_p,omitempty"`
	Stream              bool            `json:"stream,omitempty"`
	StreamOptions       *StreamOptions  `json:"stream_options,omitempty"` // Added for usage stats
	Stop                interface{}     `json:"stop,omitempty"`           // string or []string
	Seed                *int            `json:"seed,omitempty"`
	Format              *ResponseFormat `json:"response_format,omitempty"`
	Tools               []Tool          `json:"tools,omitempty"`
	ToolChoice          interface{}     `json:"tool_choice,omitempty"` // "auto", "none", "required", or specific object
	User                string          `json:"user,omitempty"`
	ServiceTier         string          `json:"service_tier,omitempty"` // "auto", "on_demand", "flex"
	ParallelToolCalls   *bool           `json:"parallel_tool_calls,omitempty"`
}

ChatCompletionRequest is the payload for /chat/completions.

type ChatCompletionResponse 

type ChatCompletionResponse struct {
	ID                string   `json:"id"`
	Object            string   `json:"object"`
	Created           int64    `json:"created"`
	Model             string   `json:"model"`
	SystemFingerprint string   `json:"system_fingerprint"`
	Choices           []Choice `json:"choices"`
	Usage             Usage    `json:"usage"`
}

ChatCompletionResponse is the standard response object.

type ChatCompletionStream 

type ChatCompletionStream struct {
	// contains filtered or unexported fields
}

ChatCompletionStream manages the stream connection.

func (*ChatCompletionStream) Close 

func (s *ChatCompletionStream) Close() error

func (*ChatCompletionStream) Recv 

func (s *ChatCompletionStream) Recv() (*StreamResponseChunk, error)

Recv receives the next chunk from the stream.

type ChatMessage 

type ChatMessage struct {
	Role       string     `json:"role"`
	Content    string     `json:"content"`                // Text content
	Name       string     `json:"name,omitempty"`         // Author name (optional)
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`   // For assistant to request tools
	ToolCallID string     `json:"tool_call_id,omitempty"` // For tool role to reference the call
}

ChatMessage represents a message in the conversation.

type Choice 

type Choice struct {
	Index        int         `json:"index"`
	Message      ChatMessage `json:"message"`
	FinishReason string      `json:"finish_reason"` // "stop", "length", "tool_calls"
}

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the main entry point for the Groq API.

func NewClient 

func NewClient(apiKey string, opts ...Option) *Client

NewClient creates a new Groq client.

func (*Client) CreateChatCompletion 

func (c *Client) CreateChatCompletion(ctx context.Context, req ChatCompletionRequest) (*ChatCompletionResponse, error)

CreateChatCompletion makes a blocking (non-streaming) chat request.

func (*Client) CreateChatCompletionStream 

func (c *Client) CreateChatCompletionStream(ctx context.Context, req ChatCompletionRequest) (*ChatCompletionStream, error)

CreateChatCompletionStream initiates a streaming request.

func (*Client) CreateSpeech 

func (c *Client) CreateSpeech(ctx context.Context, req CreateSpeechRequest) ([]byte, error)

CreateSpeech generates audio from text. Returns the raw audio bytes (e.g. MP3/WAV data).

func (*Client) CreateTranscription 

func (c *Client) CreateTranscription(ctx context.Context, req AudioTranscriptionRequest) (*AudioResponse, error)

CreateTranscription transcribes audio to the input language.

func (*Client) CreateTranslation 

func (c *Client) CreateTranslation(ctx context.Context, req AudioTranscriptionRequest) (*AudioResponse, error)

CreateTranslation translates audio into English.

func (*Client) ListModels 

func (c *Client) ListModels(ctx context.Context) (*ModelListResponse, error)

type CreateSpeechRequest 

type CreateSpeechRequest struct {
	Model          string  `json:"model"` // e.g., "playai-tts" or "whisper-v3" depending on availability
	Input          string  `json:"input"`
	Voice          string  `json:"voice"`
	ResponseFormat string  `json:"response_format,omitempty"` // mp3, wav, flac, etc.
	Speed          float64 `json:"speed,omitempty"`
}

type ErrorResponse 

type ErrorResponse struct {
	// We rename the field to 'GroqError' to avoid conflict with the Error() method.
	// The json tag remains "error" to match the API response.
	GroqError APIError `json:"error"`
}

ErrorResponse represents an error returned by the Groq API.

func (*ErrorResponse) Error 

func (e *ErrorResponse) Error() string

Error satisfies the Go error interface.

type Model 

type Model struct {
	ID            string `json:"id"`
	Object        string `json:"object"`
	OwnedBy       string `json:"owned_by"`
	Active        bool   `json:"active"`
	ContextWindow int    `json:"context_window"`
}

type ModelListResponse 

type ModelListResponse struct {
	Object string  `json:"object"`
	Data   []Model `json:"data"`
}

type Option 

type Option func(*Client)

Option allows configuring the client.

func WithBaseURL 

func WithBaseURL(url string) Option

WithBaseURL overrides the default API URL.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient allows passing a custom *http.Client.

type ResponseFormat 

type ResponseFormat struct {
	Type       string      `json:"type"`                  // "json_object", "json_schema", or "text"
	JSONSchema interface{} `json:"json_schema,omitempty"` // Structure for Strict Structured Outputs
}

ResponseFormat allows forcing JSON mode or JSON Schema.

type StreamChoice 

type StreamChoice struct {
	Index        int         `json:"index"`
	Delta        ChatMessage `json:"delta"` // Contains partial content or tool calls
	FinishReason *string     `json:"finish_reason"`
}

type StreamOptions 

type StreamOptions struct {
	IncludeUsage bool `json:"include_usage,omitempty"`
}

StreamOptions configuration for streaming responses.

type StreamResponseChunk 

type StreamResponseChunk struct {
	ID                string         `json:"id"`
	Object            string         `json:"object"`
	Created           int64          `json:"created"`
	Model             string         `json:"model"`
	SystemFingerprint string         `json:"system_fingerprint"`
	Choices           []StreamChoice `json:"choices"`
	Usage             *Usage         `json:"usage,omitempty"`  // Groq sends usage in the last chunk
	XGroq             *XGroq         `json:"x_groq,omitempty"` // Internal metadata
}

StreamResponseChunk represents a single chunk of data from the stream.

type Tool 

type Tool struct {
	Type     string       `json:"type"` // Currently only "function"
	Function ToolFunction `json:"function"`
}

Tool represents a tool that the model can call.

type ToolCall 

type ToolCall struct {
	ID       string           `json:"id"`
	Type     string           `json:"type"`
	Function ToolCallFunction `json:"function"`
}

ToolCall represents a request from the model to call a tool.

type ToolCallFunction 

type ToolCallFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"` // JSON string of arguments
}

type ToolFunction 

type ToolFunction struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Parameters  interface{} `json:"parameters,omitempty"` // JSON Schema object
}

type Usage 

type Usage struct {
	PromptTokens     int     `json:"prompt_tokens"`
	CompletionTokens int     `json:"completion_tokens"`
	TotalTokens      int     `json:"total_tokens"`
	QueueTime        float64 `json:"queue_time,omitempty"`
	PromptTime       float64 `json:"prompt_time,omitempty"`
	CompletionTime   float64 `json:"completion_time,omitempty"`
	TotalTime        float64 `json:"total_time,omitempty"`
}

Usage contains token usage statistics.

type XGroq 

type XGroq struct {
	ID    string `json:"id"`
	Usage *Usage `json:"usage"` // Sometimes usage is nested here
}

Source Files

View all Source files

Directories

Path Synopsis
examples
audio command
chat command
models command
speech command
stream command
tools command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.