Groq Php Laravel Package

Getting Started

Start by installing the package via Composer: composer require lucianotonet/groq-php. Next, configure your Groq API key in .env as GROQ_API_KEY=.... In Laravel, the client can be resolved via the service container (app(\LucianoTonet\Groq\GroqClient::class)) or bound manually. The first use case is typically chat completions — create a message payload and send it to a model like llama-3-8b-8192:

$client = app(\LucianoTonet\Groq\GroqClient::class);
$response = $client->chat()->create([
    'model' => 'llama-3-8b-8192',
    'messages' => [['role' => 'user', 'content' => 'Hello, Groq!']],
]);
echo $response->content(); // convenience method for text extraction

Check the examples/ folder in the repo for quick integration patterns.

Implementation Patterns

• Laravel Service Pattern: Bind GroqClient as a singleton in AppServiceProvider or use Laravel’s built-in binding via with() in config/app.php for type-hinted injection.
• Job/Queue Integration: Wrap Groq calls in queued jobs to offload long-running LLM inference, using the client’s async-friendly HTTP client (e.g., Guzzle/Promises).
• Request Builder Helpers: Use GroqClient::chat()->withSystemPrompt(...) and withTools(...) for structured, reusable message templates — avoids repetitive array construction.
• Typed Response Handling: Leverage response objects like ChatCompletion to access choices, usage stats, and token counts safely (e.g., $response->usage()->totalTokens).
• Testing: Mock GroqClient in unit tests; the client’s interface (GroqClientInterface) simplifies swapping in fakes or stubs with given() scenarios.

Gotchas and Tips

• Missing Model Names: Groq’s model names change frequently; hardcode only verified ones (e.g., llama3-70b-8192) or store them in config (config(groq.models.chat)) to avoid runtime failures on API upgrades.
• Token Limits Matter: Responses silently truncate if the prompt + output exceed the model’s token window (e.g., 8192 for Llama-3-8b); log usage() info for monitoring and fallback logic.
• Caching Strategy: The client does not include caching by default — integrate Laravel’s cache with the response’s id or created timestamp to avoid duplicate calls.
• HTTP Client Reuse: If you override the transport (e.g., custom Guzzle instance), ensure persistent connections are enabled for high-throughput apps.
• Error Handling: Catch \LucianoTonet\Groq\Exceptions\GroqException (not generic \Exception) to distinguish API errors (e.g., rate limits) from local bugs. Use $exception->response() to inspect raw HTTP response for debugging.