Ai Decart Platform Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies

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

   Ensure your Laravel app uses PHP 8.2+ and Symfony 6.4+ components.

2. Configure Decart Credentials Add to .env:

   DECART_API_KEY=your_key_here
   DECART_API_URL=https://platform.decart.ai/api/v1
   

3. Register the Provider Create a service provider (e.g., App\Providers\DecartAIServiceProvider) and bind the Decart provider:

   use Symfony\Component\AI\Client\AiClient;
   use Decart\Provider;
   
   public function register(): void
   {
       $this->app->singleton(AiClient::class, function ($app) {
           $client = new AiClient();
           $client->addProvider(new Provider(
               $app['config']['decart.api_key'],
               $app['config']['decart.api_url']
           ));
           return $client;
       });
   }
   

4. First Use Case: Text Generation Inject AiClient into a controller or service:

   use Symfony\Component\AI\Client\AiClient;
   
   public function generateText(AiClient $aiClient)
   {
       $model = $aiClient->getModel('lucy');
       $response = $model->chat('Summarize this article: "..."');
       return $response->getContent();
   }
   

5. Verify with a Test Use Laravel’s HTTP tests to validate the integration:

   public function testDecartIntegration()
   {
       $response = $this->post('/generate', [
           'prompt' => 'Hello, Decart!'
       ]);
       $response->assertOk();
   }
   

Implementation Patterns

1. Provider Abstraction (v0.8.0)

Leverage the Provider abstraction to decouple Decart-specific logic from your business layer:

// Define a custom provider interface
interface AiProviderInterface
{
    public function getModel(string $modelName);
}

// Implement Decart-specific logic
class DecartProvider implements AiProviderInterface
{
    public function getModel(string $modelName): AiModel
    {
        return match ($modelName) {
            'lucy' => new LucyModel($this->client),
            default => throw new \InvalidArgumentException("Model {$modelName} not supported"),
        };
    }
}

2. Model Routing

Route requests to Decart models dynamically using Laravel’s service container:

// config/ai.php
return [
    'models' => [
        'lucy' => [
            'provider' => DecartProvider::class,
            'type' => 'chat',
        ],
    ],
];

3. Laravel Facade for Convenience

Create a facade to simplify usage in Blade or controllers:

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

use Illuminate\Support\Facades\Facade;

class DecartAI extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'ai.decart';
    }
}

Register the facade in config/app.php and bind the service:

'AiDecart' => function ($app) {
    return $app->make(AiClient::class)->getModel('lucy');
},

4. Queue-Based Async Processing

Offload long-running Decart calls to queues:

// app/Jobs/GenerateTextJob.php
use Symfony\Component\AI\Client\AiModel;

class GenerateTextJob implements ShouldQueue
{
    public function handle(AiModel $model)
    {
        $response = $model->chat($this->prompt);
        // Store or process response
    }
}

5. Caching Responses

Cache frequent Decart responses (e.g., embeddings) using Laravel’s cache:

public function getEmbedding(string $text)
{
    return Cache::remember(
        "decart_embedding_{$text}",
        now()->addHours(1),
        fn() => $this->aiClient->getModel('lucy')->embed($text)
    );
}

6. Error Handling and Retries

Use Laravel’s retry mechanism for transient failures:

use Illuminate\Support\Facades\Http;

public function callDecartApi()
{
    return Http::withOptions(['timeout' => 30])
        ->retry(3, 100)
        ->post('https://platform.decart.ai/api/v1/chat', [
            'prompt' => '...',
        ]);
}

7. Integration with Laravel Scout

For semantic search, integrate Decart embeddings with Scout:

use Laravel\Scout\Searchable;

class Product extends Model implements Searchable
{
    public function toSearchableArray()
    {
        return [
            'title' => $this->title,
            'embedding' => $this->aiClient->getModel('lucy')->embed($this->description),
        ];
    }
}

Gotchas and Tips

Pitfalls

1. API Key Management

   • Gotcha: Hardcoding API keys in config files or version control.
   • Fix: Use Laravel’s .env and env() helper. Rotate keys periodically via laravel-env-editor.

2. Rate Limiting

   • Gotcha: Decart may throttle requests during spikes.
   • Fix: Implement exponential backoff in retries:

     use Symfony\Component\AI\Exception\RateLimitExceededException;
     
     try {
         $response = $model->chat($prompt);
     } catch (RateLimitExceededException $e) {
         sleep(2 ** $attempt); // Exponential backoff
         retry();
     }
     

3. Model Availability

   • Gotcha: Decart models (e.g., lucy) may have downtime or regional restrictions.
   • Fix: Use a fallback model or local cache:

     try {
         return $model->chat($prompt);
     } catch (\Exception $e) {
         return Cache::get('fallback_response') ?: 'Service unavailable';
     }
     

4. Response Parsing

   • Gotcha: Decart’s API may return unexpected formats (e.g., nested JSON).
   • Fix: Validate responses with a schema:

     use JsonSchema\Validator;
     
     $validator = new Validator();
     $validator->validate($response->getContent(), (object) [
         'type' => 'object',
         'properties' => ['content' => ['type' => 'string']],
     ]);
     

5. Dependency Conflicts

   • Gotcha: symfony/ai may conflict with Laravel’s http-client or guzzle.
   • Fix: Use Laravel’s HttpClient as a drop-in replacement:

     $client = new \Symfony\Component\HttpClient\HttpClient([
         'base_uri' => config('decart.api_url'),
         'auth_bearer' => config('decart.api_key'),
     ]);
     

6. Streaming Quirks

   • Gotcha: Decart’s streaming responses may not support Laravel’s StreamedResponse.
   • Fix: Buffer chunks manually:

     $response = $model->chat($prompt)->stream();
     $buffer = '';
     while ($chunk = $response->getChunk()) {
         $buffer .= $chunk;
     }
     return response($buffer);
     

Debugging Tips

1. Log API Requests/Responses Use Laravel’s logging to inspect Decart calls:

   \Log::debug('Decart API Request', [
       'url' => $request->getUri(),
       'body' => $request->getContent(),
   ]);
   

2. Mock Decart in Tests Use Laravel’s HTTP mocking to avoid real API calls:

   Http::fake([
       'platform.decart.ai/api/v1/chat' => Http::response([
           'content' => 'Mocked response',
       ]),
   ]);
   

3. Monitor Performance Track Decart API latency with Laravel Telescope or custom metrics:

   $start = microtime(true);
   $response = $model->chat($prompt);
   \Log::info('Decart API latency', [
       'time' => microtime(true) - $start,
       'prompt' => $prompt,
   ]);
   

Extension Points

1. Custom Model Adapters Extend the AiModel interface to add Decart-specific features:

   class DecartModel extends AiModel
   {
       public function embed(string $text): array
       {
           return $this->client->postJson('/embed', ['text' => $text])->toArray();
       }
   }
   

2. Prompt Templates Create reusable prompt templates in Laravel’s config:

   // config/decart-prompts.php
   return [
       'summarize' => 'Summarize the following in 3 bullet points: {{text}}',
   ];
   

   Use them in services:

   $prompt = str_replace('{{text