Ai Meta Platform Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package Add to composer.json:

   composer require symfony/ai-meta-platform
   

   For Laravel, ensure compatibility with Symfony’s HttpClient via a facade or service provider.

2. Configure API Credentials Set Meta’s API key in .env (or config/services.php):

   META_LLAMA_API_KEY=your_api_key_here
   

3. Basic Prompt Usage Create a service to wrap the Meta client:

   use Symfony\Component\Ai\MetaPlatform\Client\MetaClient;
   use Symfony\Component\Ai\MetaPlatform\Prompt\Prompt;
   
   $client = new MetaClient('http://meta-api-endpoint', $apiKey);
   $prompt = new Prompt('Llama 3', 'Summarize this: {text}');
   $response = $client->complete($prompt->withVariables(['text' => 'Your input here']));
   

4. Laravel Integration (Quick Start) Create a facade or service provider to bridge Symfony’s MetaClient:

   // app/Providers/MetaServiceProvider.php
   namespace App\Providers;
   
   use Illuminate\Support\ServiceProvider;
   use Symfony\Component\Ai\MetaPlatform\Client\MetaClient;
   
   class MetaServiceProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->singleton('meta.client', function ($app) {
               return new MetaClient(
                   config('services.meta.endpoint'),
                   config('services.meta.api_key')
               );
           });
       }
   }
   

   Configure in config/services.php:

   'meta' => [
       'endpoint' => env('META_LLAMA_ENDPOINT', 'https://api.meta.com/llama/v1'),
       'api_key' => env('META_LLAMA_API_KEY'),
   ],
   

5. First Use Case: Dynamic Content Generation Use in a Laravel controller or command:

   use Illuminate\Support\Facades\Meta;
   
   public function generateSummary(Request $request)
   {
       $text = $request->input('text');
       $prompt = new \Symfony\Component\Ai\MetaPlatform\Prompt\Prompt('Llama 3', 'Summarize: {text}');
       $response = Meta::client()->complete($prompt->withVariables(['text' => $text]));
       return response()->json(['summary' => $response->getContent()]);
   }
   

Implementation Patterns

Core Workflows

1. Prompt Standardization

   • Use predefined prompt formats for Llama 3/3.2/3.3 (e.g., [INST] tokens).
   • Example:

     $prompt = new Prompt('Llama 3.2', '[INST] {instruction} [/INST]');
     $prompt->withVariables(['instruction' => 'Translate to French: Hello']);
     

2. Hybrid AI Pipelines

   • Combine with other Symfony AI clients (e.g., OpenAI) for multi-model workflows:

     $llamaResponse = $metaClient->complete($llamaPrompt);
     $openaiResponse = $openaiClient->complete($openaiPrompt);
     

3. Laravel Service Integration

   • Queue Jobs: Offload AI tasks to queues:

     use Illuminate\Bus\Queueable;
     use Illuminate\Contracts\Queue\ShouldQueue;
     
     class GenerateContentJob implements ShouldQueue
     {
         use Queueable;
     
         public function handle()
         {
             $response = Meta::client()->complete($this->prompt);
             // Store or process response
         }
     }
     

   • Events: Trigger AI actions via Laravel events:

     event(new ContentGenerated($response));
     

4. Dynamic Prompt Templates

   • Use Blade or Laravel’s string helpers to build prompts:

     $template = view('prompts.summary')->with(['text' => $input])->render();
     $prompt = new Prompt('Llama 3', $template);
     

5. Error Handling

   • Wrap API calls in try-catch blocks or use Laravel’s try-catch helpers:

     try {
         $response = Meta::client()->complete($prompt);
     } catch (\Symfony\Component\Ai\Exception\AiException $e) {
         Log::error('Meta API failed', ['error' => $e->getMessage()]);
         throw new \Exception('AI service unavailable');
     }
     

Integration Tips

• API Endpoint Flexibility: Configure multiple endpoints (e.g., local Ollama, Meta cloud) via Laravel’s config:

  'meta' => [
      'endpoints' => [
          'local' => 'http://localhost:11434',
          'cloud' => 'https://api.meta.com/llama/v1',
      ],
      'default' => env('META_LLAMA_ENDPOINT', 'local'),
  ],
  

• Rate Limiting: Use Laravel’s throttle middleware for API calls:

  Route::middleware(['throttle:10,1'])->group(function () {
      Route::post('/generate', [AIController::class, 'generate']);
  });
  

• Caching Responses: Cache frequent prompts/responses with Laravel’s cache:

  $cacheKey = 'ai_summary_' . md5($text);
  $response = Cache::remember($cacheKey, now()->addHours(1), function () use ($prompt) {
      return Meta::client()->complete($prompt);
  });
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency Overhead

   • Issue: The package assumes Symfony’s HttpClient, Messenger, or EventDispatcher.
   • Fix: Replace with Laravel equivalents:
     • Use Http facade or GuzzleHttp for HTTP calls.
     • Replace Messenger with Laravel’s Bus or Queue.
     • Avoid EventDispatcher unless critical; use Laravel’s Events.

2. Prompt Format Rigidity

   • Issue: Llama 3.x requires strict prompt formats (e.g., [INST] tokens). Deviations may break responses.
   • Fix: Validate prompts before sending:

     if (!str_contains($prompt->getContent(), '[INST]')) {
         throw new \InvalidArgumentException('Prompt must include [INST] for Llama 3');
     }
     

3. API Key Management

   • Issue: Hardcoding API keys in config or environment files.
   • Fix: Use Laravel’s Vault or encrypted .env:

     php artisan vault:make META_LLAMA_API_KEY
     

4. Token Limits

   • Issue: Llama models have strict token limits (e.g., 4096 tokens). Long inputs may fail.
   • Fix: Truncate or chunk inputs:

     $chunkedText = array_chunk($longText, 2000);
     foreach ($chunkedText as $chunk) {
         $response = Meta::client()->complete($prompt->withVariables(['text' => $chunk]));
     }
     

5. Local vs. Cloud Deployment

   • Issue: Local models (e.g., Ollama) may have different endpoints/behavior than cloud APIs.
   • Fix: Abstract endpoints in config and test both environments:

     $client = new MetaClient(config('services.meta.endpoints.' . env('META_ENV', 'cloud')));
     

Debugging Tips

1. Enable Verbose Logging Configure Symfony’s HttpClient to log requests/responses:

   $client = new MetaClient($endpoint, $apiKey, [
       'headers' => ['Accept' => 'application/json'],
       'debug' => true, // Enable debug mode
   ]);
   

2. Validate Prompt Structure Use a regex to check for required tokens:

   $pattern = '/\[INST\].*?\[\/INST\]/s';
   if (!preg_match($pattern, $prompt->getContent())) {
       throw new \RuntimeException('Invalid Llama 3 prompt format');
   }
   

3. Handle Rate Limits Gracefully Implement exponential backoff for retries:

   use Symfony\Component\Ai\Exception\RateLimitException;
   
   try {
       $response = $client->complete($prompt);
   } catch (RateLimitException $e) {
       sleep(2 ** $attempt); // Exponential backoff
       retry();
   }
   

4. Test with Minimal Prompts Start with simple prompts to isolate issues:

   $simplePrompt = new Prompt('Llama 3', '[INST] Hello [/INST]');
   $response = $client->complete($simplePrompt);
   

Extension Points

1. Custom Prompt Validators Extend the Prompt class to add validation:

   class CustomPrompt extends \Symfony\Component\Ai\MetaPlatform\Prompt\Prompt
   {
       public function