Getting Started

Minimal Steps

Install Dependencies Add the package and Symfony AI core to your Laravel project:
```
composer require symfony/ai-cerebras-platform symfony/ai
```

Configure the Client Create a service provider to bind the Cerebras client to Laravel’s container:

// app/Providers/CerebrasServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Symfony\Component\AI\Provider\CerebrasClient;

class CerebrasServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('cerebras.client', function ($app) {
            return new CerebrasClient(
                apiKey: env('CEREBRAS_API_KEY'),
                endpoint: env('CEREBRAS_ENDPOINT', 'https://inference.cerebras.ai/v1')
            );
        });
    }
}

'providers' => [
    // ...
    App\Providers\CerebrasServiceProvider::class,
],

First Use Case: Chat Completion Use the client in a controller or service:

use Illuminate\Support\Facades\App;

public function askCerebras(string $question)
{
    $client = App::make('cerebras.client');
    $response = $client->chat([
        'model' => 'cerebras/llama-3-70b',
        'messages' => [
            ['role' => 'user', 'content' => $question],
        ],
    ]);

    return response()->json($response);
}

Where to Look First

Cerebras API Docs for endpoint specifics.
Symfony AI Provider Abstraction for multi-provider patterns.
src/Provider/CerebrasClient.php in the package source for method signatures.

Implementation Patterns

Usage Patterns

Provider-Agnostic Workflows Use Symfony’s ModelClient to route requests dynamically:

// app/Services/AIService.php
use Symfony\Component\AI\ModelClient;
use Symfony\Component\AI\Provider\CerebrasClient;

class AIService
{
    public function __construct(
        private ModelClient $modelClient,
        private CerebrasClient $cerebrasClient
    ) {}

    public function generateResponse(string $prompt, string $model = 'default')
    {
        if ($model === 'cerebras') {
            return $this->cerebrasClient->chat([...]);
        }
        return $this->modelClient->chat([...]);
    }
}

Streaming Responses Adapt DeltaInterface streams to Laravel’s StreamedResponse:

use Symfony\Component\AI\Stream\ChatCompletionStream;
use Symfony\Component\HttpFoundation\StreamedResponse;

public function streamResponse(string $prompt)
{
    $client = App::make('cerebras.client');
    $stream = $client->chatStream([
        'model' => 'cerebras/llama-3-70b',
        'messages' => [['role' => 'user', 'content' => $prompt]],
    ]);

    return new StreamedResponse(
        fn () => $this->processStream($stream),
        200,
        ['Content-Type' => 'text/event-stream']
    );
}

private function processStream(ChatCompletionStream $stream): void
{
    foreach ($stream as $delta) {
        echo "data: {$delta->content}\n\n";
        ob_flush();
        flush();
    }
}

Structured Outputs Leverage Cerebras’ tool calling for deterministic responses:

$response = $client->chat([
    'model' => 'cerebras/llama-3-70b',
    'messages' => [['role' => 'user', 'content' => 'Extract entities from: "John Doe, 30, NYC"']],
    'tools' => [
        [
            'type' => 'function',
            'function' => [
                'name' => 'extract_entities',
                'parameters' => [
                    'type' => 'object',
                    'properties' => [
                        'name' => ['type' => 'string'],
                        'age' => ['type' => 'integer'],
                        'location' => ['type' => 'string'],
                    ],
                ],
            ],
        ],
    ],
    'tool_choice' => ['type' => 'function', 'function' => ['name' => 'extract_entities']],
]);

Workflows

Multi-Provider Routing Implement a ProviderRouter to switch between Cerebras and other backends:

// app/Services/ProviderRouter.php
use Symfony\Component\AI\Provider\ProviderInterface;

class ProviderRouter
{
    public function __construct(
        private array $providers,
        private string $defaultProvider = 'cerebras'
    ) {}

    public function getProvider(string $name = null): ProviderInterface
    {
        return $this->providers[$name ?? $this->defaultProvider];
    }
}

Async Processing with Queues Offload inference to Laravel queues:

// app/Jobs/ProcessCerebrasInference.php
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Symfony\Component\AI\Provider\CerebrasClient;

class ProcessCerebrasInference implements ShouldQueue
{
    use Queueable;

    public function __construct(
        private string $prompt,
        private string $model
    ) {}

    public function handle(CerebrasClient $client)
    {
        $response = $client->chat([
            'model' => $this->model,
            'messages' => [['role' => 'user', 'content' => $this->prompt]],
        ]);
        // Store or process response...
    }
}

Caching Responses Cache deterministic responses (e.g., FAQs):

use Illuminate\Support\Facades\Cache;

public function getCachedResponse(string $question)
{
    return Cache::remember("cerebras_{$question}", now()->addHours(1), function () {
        $client = App::make('cerebras.client');
        return $client->chat([
            'model' => 'cerebras/llama-3-70b',
            'messages' => [['role' => 'user', 'content' => $question]],
        ]);
    });
}

Integration Tips

Laravel Facades: Create a facade for cleaner syntax:

// app/Facades/Cerebras.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class Cerebras extends Facade
{
    protected static function getFacadeAccessor() { return 'cerebras.client'; }
}

Usage:

$response = Cerebras::chat([...]);

Error Handling: Use Laravel’s exception handling:

try {
    $response = Cerebras::chat([...]);
} catch (\Symfony\Component\AI\Exception\AIException $e) {
    report($e);
    return response()->json(['error' => 'AI service unavailable'], 503);
}

Environment Configuration: Store API keys in .env:

CEREBRAS_API_KEY=your_api_key_here
CEREBRAS_ENDPOINT=https://inference.cerebras.ai/v1

Gotchas and Tips

Pitfalls

Symfony vs. Laravel DI Conflicts
- Issue: Symfony’s Provider interface may clash with Laravel’s service container.
- Fix: Explicitly bind the Cerebras client as shown in the Getting Started section. Avoid autowiring Symfony’s ProviderInterface directly.
Streaming Response Quirks
- Issue: Laravel’s StreamedResponse may buffer data if not handled carefully.
- Fix: Use ob_flush() and flush() explicitly in streaming loops (see Implementation Patterns).
API Key Management
- Issue: Hardcoding API keys in config files.
- Fix: Use Laravel’s .env and validate keys on boot:
```
if (empty(env('CEREBRAS_API_KEY'))) {
    throw new \RuntimeException('Cerebras API key not configured.');
}
```

Rate Limiting

Issue: Cerebras may throttle requests without clear headers.

Fix: Implement middleware to track and enforce limits:

// app/Http/Middleware/CheckCerebrasRateLimit.php
use Illuminate\Http\Request;
use Symfony\Component\AI\Exception\RateLimitExceededException;

public function handle(Request $request, Closure $next)
{
    try {
        return $next($request);
    } catch (RateLimitExceededException $e) {
        return response()->json(['error' => 'Rate limit exceeded'], 429);
    }
}

**Structured Output Pars

Ai Cerebras Platform Laravel Package