GroqGateway
class GroqGateway implements StepTextGateway, TranscriptionGateway
Traits
Methods
Add structured output requirements to the instructions.
Build the request body for the current text generation step.
Build the request body for the Chat Completions API.
Build the response format options for structured output.
Create an HTTP client with the provider's request options.
Select a boot-registered connection without retaining dynamic provider names.
Process a Chat Completions streaming response for a single turn and yield Hypervel stream events.
Map raw streaming tool call data to ToolCall DTOs.
Generate a lowercase UUID v7 for use as a stream event ID.
Map the given Hypervel attachments to Chat Completions content parts.
Decode a structured output payload, tolerating markdown code fences.
Parse a single Groq response into a StepResponse.
Extract and map the finish reason from the response.
Execute a callback with failoverable error handling.
Get the short Retry-After delay of a rate limited or overloaded response, if it has one.
Determine if the response is a 402, or a 429 insufficient credits or quota error rather than a rate limit.
The status codes that indicate Groq is transiently unavailable and the request should fail over.
Get the patterns used to detect insufficient credits or quota errors.
Get the error codes or types that indicate insufficient credits or quota on a 429 response.
Map the given Hypervel messages to Chat Completions messages format.
Map a user message to Chat Completions format.
Map an assistant message to Chat Completions format.
Map a tool result message to Chat Completions format.
Serialize a tool call DTO to Chat Completions array format.
Map a tool call or result ID to the provider's wire format.
Map a provider tool to a Groq built-in tool definition.
Parse an SSE stream body into decoded JSON data objects.
Read one line without waiting for a larger body buffer to fill.
Generate text for a single Chat Completions step.
Stream text for a single Chat Completions step.
Get the stream options sent with a streaming Chat Completions request.
Determine the appropriate filename for the audio file based on its MIME type.
Map a code execution tool to a Groq code interpreter definition.
Map a web search tool to a Groq browser search definition.
Generate text from the given audio.
Details
in
ComposesSchemaInstructions at line 14
protected string|null
composeInstructions(string|null $instructions, array|null $schema)
Add structured output requirements to the instructions.
in
BuildsTextRequests at line 23
protected array
buildStepBody(Provider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, StepContext $stepContext)
Build the request body for the current text generation step.
in
BuildsTextRequests at line 39
protected array
buildTextRequestBody(Provider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options)
Build the request body for the Chat Completions API.
in
BuildsTextRequests at line 96
protected array
buildResponseFormat(array $schema, bool $strict)
Build the response format options for structured output.
in
CreatesClient at line 21
protected PendingRequest
createClient(string $baseUrl, array $headers = [], array $configuredHeaders = [], int|null $timeout = 60, bool $throw = true)
Create an HTTP client with the provider's request options.
in
CreatesClient at line 43
protected string
httpConnection(Provider $provider)
Select a boot-registered connection without retaining dynamic provider names.
in
CreatesGroqClient at line 18
protected PendingRequest
client(Provider $provider, int|null $timeout = null)
Get an HTTP client for the Groq API.
in
CreatesGroqClient at line 31
protected string
baseUrl(Provider $provider)
Get the base URL for the Groq API.
in
HandlesTextStreaming at line 34
protected Generator
processTextStream(string $invocationId, Provider $provider, string $model, StreamInterface $streamBody)
Process a Chat Completions streaming response for a single turn and yield Hypervel stream events.
in
HandlesTextStreaming at line 231
protected array
mapStreamToolCalls(array $toolCalls)
Map raw streaming tool call data to ToolCall DTOs.
in
HandlesTextStreaming at line 244
protected string
generateEventId()
Generate a lowercase UUID v7 for use as a stream event ID.
in
MapsAttachments at line 24
protected array
mapAttachments(Collection $attachments)
Map the given Hypervel attachments to Chat Completions content parts.
in
MapsAttachments at line 64
protected bool
isImage(UploadedFile $attachment)
Determine if the given uploaded file is an image.
in
DecodesStructuredOutput at line 12
protected array
decodeStructuredOutput(string|null $text)
Decode a structured output payload, tolerating markdown code fences.
in
ParsesTextResponses at line 25
protected void
validateTextResponse(array $data)
Validate the Groq response data.
in
ParsesTextResponses at line 39
protected StepResponse
parseTextResponse(array $data, Provider $provider, bool $structured)
Parse a single Groq response into a StepResponse.
in
ParsesTextResponses at line 74
protected TextUsage
extractUsage(array $data)
Extract usage data from the response.
in
ParsesTextResponses at line 89
protected FinishReason
extractFinishReason(array $choice)
Extract and map the finish reason from the response.
in
HandlesFailoverErrors at line 26
protected mixed
withErrorHandling(string $providerName, Closure $callback)
Execute a callback with failoverable error handling.
in
HandlesFailoverErrors at line 91
protected int|null
retryAfterSeconds(Throwable $exception)
Get the short Retry-After delay of a rate limited or overloaded response, if it has one.
in
HandlesFailoverErrors at line 115
protected bool
isInsufficientCredits(RequestException $exception)
Determine if the response is a 402, or a 429 insufficient credits or quota error rather than a rate limit.
at line 99
protected array
overloadedStatusCodes()
The status codes that indicate Groq is transiently unavailable and the request should fail over.
in
HandlesFailoverErrors at line 148
protected array
insufficientCreditPatterns()
Get the patterns used to detect insufficient credits or quota errors.
in
HandlesFailoverErrors at line 158
protected array
insufficientCreditCodes()
Get the error codes or types that indicate insufficient credits or quota on a 429 response.
in
MapsChatCompletionMessages at line 19
protected array
mapMessagesToChat(array $messages, string|null $instructions = null)
Map the given Hypervel messages to Chat Completions messages format.
in
MapsChatCompletionMessages at line 46
protected void
mapUserMessage(UserMessage|Message $message, array $chatMessages)
Map a user message to Chat Completions format.
in
MapsChatCompletionMessages at line 69
protected void
mapAssistantMessage(AssistantMessage|Message $message, array $chatMessages)
Map an assistant message to Chat Completions format.
in
MapsChatCompletionMessages at line 89
protected void
mapToolResultMessage(ToolResultMessage|Message $message, array $chatMessages)
Map a tool result message to Chat Completions format.
in
MapsChatCompletionMessages at line 107
protected array
serializeToolCallToChat(ToolCall $toolCall)
Serialize a tool call DTO to Chat Completions array format.
in
MapsChatCompletionMessages at line 122
protected string
mapToolCallId(string $id)
Map a tool call or result ID to the provider's wire format.
in
MapsChatCompletionTools at line 22
protected array
mapTools(array $tools, Provider $provider)
Map the given tools to Chat Completions function definitions.
at line 55
protected array
mapProviderTool(ProviderTool $tool, Provider $provider)
Map a provider tool to a Groq built-in tool definition.
in
MapsChatCompletionTools at line 48
protected array
mapTool(Tool $tool)
Map a regular tool to a Chat Completions function definition.
in
MapsChatCompletionTools at line 76
protected string|array
mapToolChoice(ToolChoice $choice)
Map a tool choice to the Chat Completions tool_choice shape.
in
ParsesServerSentEvents at line 24
protected Generator
parseServerSentEvents(StreamInterface $streamBody)
Parse an SSE stream body into decoded JSON data objects.
in
ParsesServerSentEvents at line 52
protected string
readLine(StreamInterface $streamBody)
Read one line without waiting for a larger body buffer to fill.
in
PerformsChatCompletionSteps at line 19
StepResponse
generateTextStep(TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, int|null $timeout, StepContext $stepContext)
Generate text for a single Chat Completions step.
in
PerformsChatCompletionSteps at line 48
Generator
generateStreamStep(string $invocationId, TextProvider $provider, string $model, string|null $instructions, array $messages, array $tools, array|null $schema, TextGenerationOptions|null $options, int|null $timeout, StepContext $stepContext)
Stream text for a single Chat Completions step.
in
PerformsChatCompletionSteps at line 82
protected array|null
streamOptions(Provider $provider)
Get the stream options sent with a streaming Chat Completions request.
in
ResolvesAudioFilenames at line 15
protected string
audioFilename(TranscribableAudio $audio)
Determine the appropriate filename for the audio file based on its MIME type.
at line 48
__construct(Dispatcher $events)
Create a Groq gateway.
at line 67
protected array
mapCodeExecutionTool(CodeExecution $tool, Provider $provider)
Map a code execution tool to a Groq code interpreter definition.
at line 82
protected array
mapWebSearchTool(WebSearch $tool, Provider $provider)
Map a web search tool to a Groq browser search definition.
at line 111
TranscriptionResponse
generateTranscription(TranscriptionProvider $provider, string $model, TranscribableAudio $audio, string|null $language = null, bool $diarize = false, int $timeout = 30, array $providerOptions = [])
Generate text from the given audio.