or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

audio.mdbatches.mdchat-completions.mdembeddings.mdfiles.mdindex.mdmodels.md
tile.json

tessl/pypi-groq

The official Python library for the groq API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/groq@0.31.x

To install, run

npx @tessl/cli install tessl/pypi-groq@0.31.0

index.mddocs/

Groq

The official Python library for the Groq API, providing access to Groq's high-performance language models and services. Groq enables fast inference for large language models with comprehensive support for chat completions, embeddings, audio processing, and more.

Package Information

  • Package Name: groq
  • Language: Python
  • Installation: pip install groq
  • Python Version: >=3.8

Core Imports

import groq

Standard client usage:

from groq import Groq

Async client usage:

from groq import AsyncGroq

Type imports:

from groq import types

Basic Usage

import os
from groq import Groq

# Initialize client with API key from environment
client = Groq(api_key=os.environ.get("GROQ_API_KEY"))

# Create a chat completion
completion = client.chat.completions.create(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello! How are you?"}
    ],
    model="llama3-8b-8192",
    max_tokens=100,
    temperature=0.7
)

print(completion.choices[0].message.content)

# Stream a chat completion
stream = client.chat.completions.create(
    messages=[
        {"role": "user", "content": "Write a short poem about Python"}
    ],
    model="llama3-8b-8192",
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

Architecture

The Groq library follows a structured client-resource pattern:

  • Client Classes: Groq (sync) and AsyncGroq (async) serve as entry points
  • Resource APIs: Organized by functionality (chat, audio, embeddings, models, batches, files)
  • Streaming Support: Real-time response streaming for compatible endpoints
  • Type Safety: Comprehensive type definitions for all request parameters and response fields
  • Error Handling: Structured exception hierarchy for different error scenarios
  • Response Wrappers: Raw response access and streaming response handling

Capabilities

Chat Completions

High-performance chat completions with streaming support, function calling, tool usage, and advanced features like reasoning modes and search integration.

def create(
    messages: Iterable[ChatCompletionMessageParam],
    model: str,
    max_tokens: Optional[int] = None,
    temperature: Optional[float] = None,
    stream: Optional[bool] = None,
    tools: Optional[Iterable[ChatCompletionToolParam]] = None,
    **kwargs
) -> ChatCompletion | Stream[ChatCompletionChunk]: ...

Chat Completions

Text Embeddings

Generate high-quality vector embeddings for text inputs, supporting both single strings and batch processing.

def create(
    input: Union[str, List[str]],
    model: Union[str, Literal["nomic-embed-text-v1_5"]],
    **kwargs  
) -> CreateEmbeddingResponse: ...

Text Embeddings

Audio Processing

Comprehensive audio capabilities including speech-to-text transcription, translation, and text-to-speech synthesis.

# client.audio.transcriptions.create()
def create(model: str, file: FileTypes, **kwargs) -> Transcription: ...
# client.audio.translations.create()  
def create(model: str, file: FileTypes, **kwargs) -> Translation: ...
# client.audio.speech.create()
def create(input: str, model: str, voice: str, **kwargs) -> bytes: ...

Audio Processing

Model Management

Access model information, list available models, and manage model lifecycle operations.

def list(**kwargs) -> ModelListResponse: ...
def retrieve(model: str, **kwargs) -> Model: ...
def delete(model: str, **kwargs) -> ModelDeleted: ...

Model Management

File Operations

Upload, manage, and organize files for use with various Groq services and batch processing.

def create(file: FileTypes, purpose: str, **kwargs) -> FileCreateResponse: ...
def list(**kwargs) -> FileListResponse: ...
def retrieve(file_id: str, **kwargs) -> FileInfoResponse: ...
def delete(file_id: str, **kwargs) -> FileDeleteResponse: ...

File Operations

Batch Processing

Submit and manage batch jobs for processing large volumes of requests efficiently.

def create(input_file_id: str, endpoint: str, completion_window: str, **kwargs) -> BatchCreateResponse: ...
def retrieve(batch_id: str, **kwargs) -> BatchRetrieveResponse: ...
def cancel(batch_id: str, **kwargs) -> BatchCancelResponse: ...
def list(**kwargs) -> BatchListResponse: ...

Batch Processing

Client Configuration

class Groq:
    def __init__(
        self,
        api_key: str | None = None,
        base_url: str | httpx.URL | None = None,
        timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
        max_retries: int = DEFAULT_MAX_RETRIES,
        default_headers: Mapping[str, str] | None = None,
        default_query: Mapping[str, object] | None = None,
        http_client: httpx.Client | None = None,
        _strict_response_validation: bool = False
    ): ...

class AsyncGroq:
    def __init__(
        self,
        api_key: str | None = None,
        base_url: str | httpx.URL | None = None,
        timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
        max_retries: int = DEFAULT_MAX_RETRIES,
        default_headers: Mapping[str, str] | None = None,
        default_query: Mapping[str, object] | None = None,
        http_client: httpx.AsyncClient | None = None,
        _strict_response_validation: bool = False
    ): ...

Error Handling

class GroqError(Exception): ...
class APIError(GroqError): ...
class APIStatusError(APIError): ...
class APITimeoutError(APIConnectionError): ...
class APIConnectionError(APIError): ...
class APIResponseValidationError(APIError): ...
class BadRequestError(APIStatusError): ...
class AuthenticationError(APIStatusError): ...
class PermissionDeniedError(APIStatusError): ...
class NotFoundError(APIStatusError): ...
class ConflictError(APIStatusError): ...
class UnprocessableEntityError(APIStatusError): ...
class RateLimitError(APIStatusError): ...
class InternalServerError(APIStatusError): ...

Core Types

class BaseModel: ...
class NotGiven: ...
NOT_GIVEN: NotGiven
class Timeout: ...
class RequestOptions: ...

# Response wrappers
class APIResponse: ...
class AsyncAPIResponse: ...
class Stream: ...
class AsyncStream: ...

# HTTP clients
class DefaultHttpxClient: ...
class DefaultAsyncHttpxClient: ...
class DefaultAioHttpClient: ...

Constants

DEFAULT_TIMEOUT: httpx.Timeout
DEFAULT_MAX_RETRIES: int
DEFAULT_CONNECTION_LIMITS: httpx.Limits

Utilities

def file_from_path(path: str) -> FileTypes: ...