Ai Mistral Platform Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies:

   composer require symfony/ai-mistral-platform symfony/http-client
   

   (Laravel users: Ensure symfony/http-client is compatible with Laravel’s HTTP stack.)

2. Configure API Key: Add Mistral’s API key to Laravel’s .env:

   MISTRAL_API_KEY=your_mistral_api_key_here
   

3. Basic Chat Completion: Create a service to wrap the client:

   // app/Services/MistralService.php
   use Symfony\Component\Ai\Client\MistralClient;
   use Symfony\Component\Ai\Client\ChatClientInterface;
   
   class MistralService
   {
       public function __construct(private ChatClientInterface $chatClient) {}
   
       public function generateResponse(string $prompt): string
       {
           $response = $this->chatClient->complete($prompt);
           return $response->getContent();
       }
   }
   

4. Register the Client: Bind the MistralClient in AppServiceProvider:

   use Symfony\Component\Ai\Client\MistralClient;
   use Symfony\Component\HttpClient\HttpClient;
   
   public function register()
   {
       $this->app->singleton(MistralClient::class, function ($app) {
           return new MistralClient(
               HttpClient::create(['auth_bearer' => env('MISTRAL_API_KEY')])
           );
       });
   }
   

5. First Use Case: Call the service from a controller:

   use App\Services\MistralService;
   
   public function askMistral(Request $request, MistralService $mistral)
   {
       $prompt = $request->input('prompt');
       $response = $mistral->generateResponse($prompt);
       return response()->json(['response' => $response]);
   }
   

Where to Look First

• Symfony AI Documentation: https://symfony.com/doc/current/ai.html
• Mistral API Reference: https://docs.mistral.ai/api/
• Package Source: Focus on:
  • src/Client/MistralClient.php (core client logic).
  • src/Client/ChatClient.php (chat completions).
  • src/Client/EmbeddingClient.php (embeddings).

Implementation Patterns

Usage Patterns

1. Chat Completions Workflow

• Prompt Engineering: Use Symfony’s ChatClient for structured prompts:

  $response = $chatClient->complete([
      'model' => 'mistral-tiny', // or 'mistral-latest'
      'messages' => [
          ['role' => 'user', 'content' => 'Explain Laravel Eloquent.'],
      ],
  ]);
  

• Streaming Responses: Leverage DeltaInterface for real-time updates:

  $chatClient->streamComplete($prompt, function ($delta) {
      // Process each chunk (e.g., append to a view or queue)
      Log::info('Stream chunk:', ['content' => $delta->getContent()]);
  });
  

  Laravel Tip: Use Laravel Queues to store chunks in a database table (e.g., ai_responses) and stream via a job.

2. Embeddings for Semantic Search

• Batch Processing: Generate embeddings for documents:

  $embeddings = $embeddingClient->create([
      'model' => 'mistral-embed',
      'inputs' => ['document text 1', 'document text 2'],
  ]);
  

• Vector Storage: Store embeddings in a vector database (e.g., Meilisearch, PostgreSQL with pgvector):

  // Pseudocode for Laravel + Meilisearch
  $client->index('documents')->addDocuments([
      'id' => 1,
      'embedding' => $embeddings[0]['embedding'],
      'content' => 'document text 1',
  ]);
  

3. Multi-Provider Routing

• Dynamic Provider Selection: Use Symfony’s Provider abstraction to route requests:

  // config/ai.php
  'providers' => [
      'mistral' => [
          'class' => \Symfony\Component\Ai\Provider\MistralProvider::class,
          'model' => 'mistral-tiny',
      ],
      'fallback' => [
          'class' => \Symfony\Component\Ai\Provider\OpenAiProvider::class,
      ],
  ],
  

  Laravel Tip: Create a facade to switch providers dynamically:

  // app/Facades/AiProvider.php
  public static function get(string $providerName): ProviderInterface
  {
      return app(\Symfony\Component\Ai\Provider\ProviderRegistry::class)
          ->getProvider($providerName);
  }
  

4. Error Handling

• Uniform Exceptions: Catch Symfony\Component\Ai\Exception\AiException for Mistral-specific errors:

  try {
      $response = $chatClient->complete($prompt);
  } catch (AiException $e) {
      Log::error('Mistral API error:', ['error' => $e->getMessage()]);
      // Fallback to another provider
  }
  

• Retry Logic: Use Laravel’s retry helper or a package like spatie/laravel-retryable:

  retry(3, function () use ($chatClient, $prompt) {
      $chatClient->complete($prompt);
  }, function (AiException $e) {
      return $e instanceof \Symfony\Component\Ai\Exception\RateLimitException;
  });
  

Workflows

Generative UI (e.g., Chatbot)

1. User submits a prompt → Laravel controller.
2. Controller calls MistralService → ChatClient.
3. Stream chunks via DeltaInterface → Store in DB or broadcast via Laravel Echo.
4. Render real-time updates in the UI (e.g., Alpine.js + Livewire).

Semantic Search Pipeline

1. Ingest documents → Generate embeddings via EmbeddingClient.
2. Store embeddings in a vector DB.
3. Query DB for similar documents → Return results to user.

Multi-Model Workflow

1. Route request to mistral provider (default).
2. If Mistral fails, fall back to openai provider.
3. Cache responses with a TTL (e.g., 1 hour).

Integration Tips

• Laravel HTTP Client: Replace Symfony’s HttpClient with Laravel’s Http facade for consistency:

  $this->app->singleton(MistralClient::class, function ($app) {
      return new MistralClient(
          $app->make(\Illuminate\Http\Client\PendingRequest::class)
              ->withToken(env('MISTRAL_API_KEY'))
      );
  });
  

• Event-Driven Extensions: Extend Symfony’s AiEventDispatcher to dispatch Laravel events:

  // app/Providers/EventServiceProvider.php
  public function boot()
  {
      event(new \Symfony\Component\Ai\Event\AiEvent(
          $this->app->make(\Symfony\Component\Ai\Event\AiEventDispatcher::class)
      ));
  }
  

• Testing: Use Laravel’s HTTP tests to mock Mistral responses:

  public function test_mistral_chat()
  {
      $response = json_encode(['choices' => [['message' => ['content' => 'Test']]]]);
      Http::fake([
          'api.mistral.ai/*' => Http::response($response, 200),
      ]);
  
      $this->get('/chat')->assertSee('Test');
  }
  

Gotchas and Tips

Pitfalls

1. Streaming Chunks in Laravel:

   • Issue: DeltaInterface streams may timeout if not handled asynchronously.
   • Fix: Use Laravel Queues to process chunks:

     $chatClient->streamComplete($prompt, function ($delta) {
         ProcessStreamChunkJob::dispatch($delta->getContent());
     });
     

2. Token Usage Tracking:

   • Issue: Mistral’s tokenUsage may not be exposed uniformly in early versions.
   • Fix: Manually parse the response:

     $usage = json_decode($response->getContent(), true)['usage'] ?? null;
     

3. Model Name Typos:

   • Issue: Mistral model names (e.g., mistral-tiny vs. mistral-tiny-s) may change.
   • Fix: Validate against the Mistral API docs.

4. Rate Limiting:

   • Issue: Mistral’s rate limits (e.g., 60 requests/minute) can cause failures.
   • Fix: Implement exponential backoff:

     use Symfony\Component\Ai\