Ai Scaleway Platform Laravel Package

Getting Started

Minimal Setup for Laravel

1. Install Dependencies:

   composer require symfony/ai symfony/ai-scaleway-platform spatie/laravel-ai
   

   • spatie/laravel-ai bridges Symfony AI with Laravel (v1.0+ required).

2. Configure Scaleway API Key: Add to .env:

   SCALEWAY_API_KEY=your_api_key_here
   SCALEWAY_REGION=fr-par  # Adjust to your region
   

3. Basic Chat Example:

   use Symfony\Component\AI\Client;
   use Symfony\Component\AI\Scaleway\ScalewayClient;
   
   // In a Laravel service or controller
   $client = new Client(new ScalewayClient(
       apiKey: env('SCALEWAY_API_KEY'),
       region: env('SCALEWAY_REGION')
   ));
   
   $response = $client->chat()->create([
       'model' => 'gpt-4o', // or 'qwen-3'
       'messages' => [
           ['role' => 'user', 'content' => 'Hello, world!'],
       ],
   ]);
   

4. Embeddings Example:

   $embeddings = $client->embeddings()->create([
       'model' => 'qwen-3-embedding',
       'input' => ['Your text here'],
   ]);
   

First Use Case: AI-Powered Chatbot

• Replace OpenAI calls in a Laravel route with Scaleway’s client.
• Use spatie/laravel-ai's AiService facade if integrated:

  use Spatie\LaravelAi\Facades\Ai;
  
  $response = Ai::chat()->create([...]);
  

Implementation Patterns

Provider Abstraction (v0.8.0)

Leverage Symfony AI’s Provider interface to switch between Scaleway and OpenAI dynamically:

// config/ai.php
'providers' => [
    'scaleway' => [
        'class' => \Symfony\Component\AI\Scaleway\ScalewayClient::class,
        'api_key' => env('SCALEWAY_API_KEY'),
        'region' => env('SCALEWAY_REGION'),
    ],
    'openai' => [
        'class' => \Symfony\Component\AI\OpenAI\OpenAIClient::class,
        'api_key' => env('OPENAI_API_KEY'),
    ],
],

// Route based on config or runtime logic
$provider = config('ai.providers.scaleway');
$client = new Client($provider);

Model Routing

Use Scaleway’s models (e.g., qwen-3) alongside OpenAI-compatible names:

// Map Scaleway-specific models to your app's logic
$modelMap = [
    'gpt-4o' => 'gpt-4o',       // Scaleway's OpenAI-compatible
    'qwen-3' => 'qwen-3',       // Scaleway's native
    'text-embedding-ada' => 'qwen-3-embedding',
];

$model = $modelMap[$request->model] ?? $request->model;
$response = $client->chat()->create(['model' => $model, ...]);

Streaming Responses

Handle real-time streams with Laravel’s event system:

use Symfony\Component\AI\Streaming\DeltaInterface;

$stream = $client->chat()->stream([
    'model' => 'gpt-4o',
    'messages' => [...],
]);

$stream->onDelta(function (DeltaInterface $delta) {
    // Process chunks (e.g., log, update UI)
    Log::info('Stream chunk:', ['content' => $delta->getContent()]);
});

$stream->onCompletion(function ($response) {
    Log::info('Stream completed:', $response->toArray());
});

Embeddings Workflow

Batch embeddings for Laravel apps (e.g., semantic search):

$batch = ['text1', 'text2', 'text3'];
$embeddings = $client->embeddings()->create([
    'model' => 'qwen-3-embedding',
    'input' => $batch,
]);

// Store in Laravel DB
Embedding::insert($embeddings->getEmbeddings());

Tool Calls Integration

Use Scaleway’s tool calls for workflow automation:

$response = $client->chat()->create([
    'model' => 'gpt-4o',
    'messages' => [...],
    'tools' => [
        [
            'type' => 'function',
            'function' => [
                'name' => 'fetch_user_data',
                'description' => 'Fetch user data from the database',
                'parameters' => [
                    'type' => 'object',
                    'properties' => ['user_id' => ['type' => 'string']],
                    'required' => ['user_id'],
                ],
            ],
        ],
    ],
]);

// Handle tool calls in Laravel
if ($response->hasToolCalls()) {
    foreach ($response->getToolCalls() as $call) {
        if ($call->getFunction()->getName() === 'fetch_user_data') {
            $userData = User::find($call->getFunction()->getArguments()['user_id']);
            // Return data to Scaleway for completion
        }
    }
}

Caching Responses

Cache frequent queries (e.g., embeddings) with Laravel’s cache:

$cacheKey = 'embeddings:' . md5(serialize($input));
$embeddings = Cache::remember($cacheKey, now()->addHours(1), function () use ($client, $input) {
    return $client->embeddings()->create(['model' => 'qwen-3-embedding', 'input' => $input]);
});

Gotchas and Tips

Pitfalls

1. Model Name Conflicts:

   • Scaleway’s gpt-4o may behave differently than OpenAI’s. Tip: Test with a small dataset first and compare outputs.
   • Fix: Maintain a model_mapping array in config to alias names.

2. Token Usage Quirks:

   • Embeddings may return unexpected token counts (fixed in v0.7.0). Tip: Log token usage for cost tracking:

     $embeddings = $client->embeddings()->create([...]);
     Log::info('Token usage:', ['total_tokens' => $embeddings->getUsage()->getTotalTokens()]);
     

3. Streaming Edge Cases:

   • DeltaInterface may emit partial or malformed chunks. Tip: Validate chunks before processing:

     $stream->onDelta(function (DeltaInterface $delta) {
         if (empty($delta->getContent())) return;
         // Process
     });
     

4. Region-Specific Models:

   • Not all models are available in every region. Tip: Validate availability in Scaleway’s docs before deployment.

5. Rate Limits:

   • Scaleway’s defaults may differ from OpenAI. Tip: Implement retries with Laravel’s spatie/laravel-http-middlewares:

     use Spatie\HttpMiddleware\RetryOnRateLimit;
     
     $client->getHttpClient()->addMiddleware(new RetryOnRateLimit());
     

6. Tool Call Arguments:

   • Tool calls without arguments may fail (bug fixed in v0.7.0). Tip: Always validate tool call payloads:

     if (empty($call->getFunction()->getArguments())) {
         throw new \RuntimeException('Tool call missing arguments');
     }
     

Debugging Tips

1. Enable Verbose Logging:

   $client->getHttpClient()->on(
       'request' => function ($request) {
           Log::debug('Scaleway Request:', $request->getBody());
       },
       'response' => function ($response) {
           Log::debug('Scaleway Response:', $response->getContent());
       }
   );
   

2. Mock Scaleway for Testing: Use Symfony AI’s MockClient:

   $mockClient = new Client(new MockClient());
   $mockClient->chat()->create([...]); // Returns predefined responses
   

3. Validate API Keys:

   • Test with a dummy key first to catch auth errors early:

     try {
         $client->chat()->create([...]);
     } catch (\Symfony\Component\AI\Exception\AuthenticationException) {
         Log::error('Invalid Scaleway API key');
     }
     

Extension Points

1. Custom Providers: Extend Symfony\Component\AI\Provider\ProviderInterface for Scaleway-specific logic:

   class CustomScalewayProvider extends ScalewayClient
   {
       public function customMethod(): array
       {
           return $this->request('POST', '/custom-endpoint', [...]);
       }
   }
   

2. Laravel Service Provider: Bind Scaleway client globally:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->