Ai Decart Platform Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require symfony/ai symfony/ai-decart-platform
   

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

   DECART_API_KEY=your_api_key_here
   

3. Register Symfony AI Client in Laravel: In AppServiceProvider.php:

   use Symfony\Component\Ai\Client;
   use Symfony\Component\Ai\Decart\DecartProvider;
   
   public function register()
   {
       $this->app->singleton(Client::class, function ($app) {
           return new Client(
               new DecartProvider($app['config']['services.decart.api_key'])
           );
       });
   }
   

4. First Use Case: Text Generation Create a controller method:

   use Symfony\Component\Ai\Client;
   
   public function generateText(Client $aiClient)
   {
       $response = $aiClient->generateText(
           'What are the best Laravel packages for AI?',
           model: 'lucy'
       );
       return response()->json($response);
   }
   

Where to Look First

• Symfony AI Documentation for core concepts.
• Decart Platform Docs for model-specific parameters (e.g., Lucy’s capabilities).
• symfony/ai-decart-platform tests in the repo for usage patterns.

Implementation Patterns

Workflows

1. Model Routing (v0.8.0+) Use the Provider abstraction to route requests dynamically:

   $aiClient->setProvider(new DecartProvider($apiKey, route: 'lucy'));
   $response = $aiClient->generateText('Prompt...');
   

2. Streaming Responses Decart’s API may support streaming. Wrap Symfony’s AiClient to handle chunks:

   public function streamResponse(Client $aiClient)
   {
       $stream = $aiClient->streamText('Prompt...');
       foreach ($stream as $chunk) {
           echo $chunk;
       }
   }
   

3. Caching Strategies Cache responses in Laravel’s cache layer:

   $cacheKey = 'decart:lucy:prompt_hash';
   $response = Cache::remember($cacheKey, now()->addHours(1), function () use ($aiClient) {
       return $aiClient->generateText('Prompt...');
   });
   

Integration Tips

• Laravel Facade: Create a facade for cleaner syntax:

  // DecartFacade.php
  public static function generate($prompt, $model = 'lucy')
  {
      return app(Client::class)->generateText($prompt, model: $model);
  }
  

  Usage:

  $result = Decart::generate('What is Laravel?');
  

• Queue Jobs for Async Processing: Offload expensive calls to queues:

  DecartJob::dispatch('Generate complex report...')->onQueue('ai');
  

• Error Handling: Centralize API errors in a base exception handler:

  try {
      $aiClient->generateText('Prompt...');
  } catch (DecartApiException $e) {
      Log::error('Decart API failed:', ['error' => $e->getMessage()]);
      throw new \RuntimeException('AI service unavailable.');
  }
  

• Environment-Specific Config: Use Laravel’s config to switch providers:

  // config/ai.php
  'provider' => env('AI_PROVIDER', 'decart'),
  

Gotchas and Tips

Pitfalls

1. API Key Management:

   • Gotcha: Hardcoding keys in config files.
   • Fix: Use Laravel’s .env with encryption for sensitive keys:

     php artisan env:encrypt
     

2. Rate Limits:

   • Gotcha: Decart may throttle requests. Laravel’s throttle middleware can help:

     Route::middleware(['throttle:60,1'])->group(...);
     

3. Model-Specific Quirks:

   • Gotcha: Lucy’s input/output format may differ from other models (e.g., strict JSON).
   • Fix: Validate responses with Laravel’s Validator:

     $validator = Validator::make($response, [
         'choices' => 'required|array',
         'choices.*.text' => 'required|string',
     ]);
     

4. CORS/Proxy Issues:

   • Gotcha: Direct API calls may fail due to CORS or firewall rules.
   • Fix: Use Laravel’s HttpClient with a proxy:

     $client = new Client(new DecartProvider($apiKey), [
         'proxy' => 'http://your-proxy:port',
     ]);
     

5. Dependency Conflicts:

   • Gotcha: Symfony AI may conflict with Laravel’s HTTP client.
   • Fix: Explicitly require compatible versions in composer.json:

     "require": {
         "symfony/http-client": "^6.0",
         "symfony/ai": "^0.8"
     }
     

Debugging

• Log API Requests: Enable Symfony’s debug mode:

  $client = new Client(new DecartProvider($apiKey), [
      'debug' => true,
  ]);
  

• Mock Decart API: Use Laravel’s HttpClient with a mock server:

  $mock = new MockHttpClient();
  $mock->addResponse('{"choices":[{"text":"Mock response"}]}');
  $client = new Client(new DecartProvider($apiKey, httpClient: $mock));
  

• Check Headers: Decart may require custom headers (e.g., X-API-Version):

  $client = new Client(new DecartProvider($apiKey), [
      'headers' => ['X-API-Version' => 'v1'],
  ]);
  

Extension Points

1. Custom Provider: Extend the Provider interface for Decart-specific logic:

   class CustomDecartProvider extends DecartProvider
   {
       public function __construct($apiKey, array $options = [])
       {
           parent::__construct($apiKey, $options + ['custom_header' => 'value']);
       }
   }
   

2. Laravel Events: Trigger events for Decart responses:

   event(new DecartResponseGenerated($response));
   

3. Model Factories: Create Laravel factories for testing:

   // DecartResponseFactory.php
   public static function make()
   {
       return [
           'choices' => [['text' => 'Test response']],
       ];
   }
   

4. Telemetry: Track usage with Laravel’s telemetry package:

   Telemetry::log('ai.decart.usage', [
       'model' => 'lucy',
       'prompt_length' => strlen($prompt),
   ]);
   

Config Quirks

• Default Model: Decart’s default model (e.g., lucy) may not be configurable globally. Override per request:

  $aiClient->generateText('Prompt...', model: 'custom-model');
  

• Timeouts: Symfony’s HttpClient defaults to 30s. Adjust in Laravel’s config:

  $client = new Client(new DecartProvider($apiKey), [
      'timeout' => 60, // seconds
  ]);
  

• Retry Logic: Use Symfony’s retry strategy:

  $client = new Client(new DecartProvider($apiKey), [
      'retry' => [
          'max_attempts' => 3,
          'delay' => 100, // ms
      ],
  ]);