Ai Bedrock Platform Laravel Package

Getting Started

Minimal Setup

1. Install the Package:

   composer require symfony/ai-bedrock-platform aws/aws-sdk-php
   

2. Publish Configuration:

   php artisan vendor:publish --provider="Symfony\AiBedrock\BedrockServiceProvider"
   

   This generates config/bedrock.php. Configure AWS credentials and default region:

   return [
       'aws' => [
           'region' => env('AWS_REGION', 'us-east-1'),
           'credentials' => [
               'key' => env('AWS_ACCESS_KEY_ID'),
               'secret' => env('AWS_SECRET_ACCESS_KEY'),
           ],
       ],
       'models' => [
           'default' => 'anthropic.claude-v2',
       ],
   ];
   

3. Register the Service Provider (in config/app.php):

   'providers' => [
       // ...
       Symfony\AiBedrock\BedrockServiceProvider::class,
   ],
   

4. First Use Case: Invoke a Model Use the BedrockClient facade or service container binding:

   use Symfony\AiBedrock\Client\BedrockClientInterface;
   
   // In a controller or service:
   $client = app(BedrockClientInterface::class);
   $response = $client->invokeModel('anthropic.claude-v2', [
       'prompt' => 'Explain Laravel dependency injection.',
       'max_tokens_to_sample' => 100,
   ]);
   

Implementation Patterns

Core Workflows

1. Model Invocation

• Basic Usage:

  $response = $client->invokeModel('anthropic.claude-v2', [
      'prompt' => 'Generate a blog post about Laravel AI.',
      'temperature' => 0.7,
  ]);
  

• Structured Output (Claude):

  $response = $client->invokeModel('anthropic.claude-v2', [
      'prompt' => 'Extract entities from: "John lives in New York."',
      'output_format' => 'json',
  ]);
  // Parse JSON response directly.
  

2. Model Routing (v0.8.0)

• Dynamically route requests based on business logic:

  $router = app(Symfony\AiBedrock\Router\ModelRouterInterface::class);
  $modelName = $router->route([
      'user_tier' => 'premium',
      'feature' => 'chatbot',
  ]);
  // Returns 'anthropic.claude-v3' for premium users.
  

3. Model Catalog Management

• List available models via CLI:

  php artisan ai:bedrock:list
  

• Cache the catalog in Laravel’s cache:

  $models = Cache::remember('bedrock_models', now()->addHours(1), function () {
      return $client->listFoundationModels();
  });
  

4. Integration with Laravel Facades

• Create a custom facade for cleaner syntax:

  // app/Facades/Bedrock.php
  namespace App\Facades;
  
  use Illuminate\Support\Facades\Facade;
  
  class Bedrock extends Facade
  {
      protected static function getFacadeAccessor() { return 'bedrock.client'; }
  }
  

• Usage:

  $response = Bedrock::invoke('amazon.titan-text-express', ['prompt' => '...']);
  

Advanced Patterns

1. Request/Response Transformation

• Use Laravel’s Macro to extend the client:

  $client->macro('generateChat', function ($messages, $model = 'anthropic.claude-v2') {
      return $this->invokeModel($model, [
          'messages' => $messages,
          'anthropic_version' => 'bedrock-2023-05-31',
      ]);
  });
  

• Usage:

  $response = $client->generateChat([['role' => 'user', 'content' => 'Hi!']]);
  

2. Middleware for AI Requests

• Log or validate AI requests:

  // app/Http/Middleware/LogAiRequests.php
  public function handle($request, Closure $next)
  {
      if ($request->route()->getName() === 'ai.generate') {
          Log::info('AI Request', ['prompt' => $request->prompt]);
      }
      return $next($request);
  }
  

3. Caching Responses

• Cache frequent responses (e.g., FAQs):

  $response = Cache::remember("ai_{$prompt}", now()->addMinutes(60), function () use ($client, $prompt) {
      return $client->invokeModel('amazon.titan-text-lite', ['prompt' => $prompt]);
  });
  

4. Fallback Logic

• Handle Bedrock failures gracefully:

  try {
      $response = $client->invokeModel('anthropic.claude-v2', $payload);
  } catch (\Aws\Bedrock\Exception\BedrockException $e) {
      $response = $client->invokeModel('amazon.titan-text-express', $payload);
  }
  

Laravel-Specific Tips

1. Service Container Binding

• Bind the client in AppServiceProvider:

  public function register()
  {
      $this->app->bind(BedrockClientInterface::class, function ($app) {
          return new BedrockClient(
              $app['config']['bedrock.aws'],
              new \Aws\Bedrock\BedrockClient([
                  'region' => $app['config']['bedrock.aws.region'],
                  'version' => 'latest',
              ])
          );
      });
  }
  

2. Configuration Validation

• Validate config/bedrock.php using Laravel’s validator:

  use Illuminate\Support\Facades\Validator;
  
  $validator = Validator::make(config('bedrock'), [
      'aws.region' => 'required|string',
      'aws.credentials.key' => 'required|string',
      'models.default' => 'required|string',
  ]);
  

3. Artisan Commands

• Extend the ai:bedrock:list command to sync models to a database:

  // app/Console/Commands/SyncBedrockModels.php
  use Symfony\Component\Console\Command\Command;
  use Symfony\Component\Console\Input\InputInterface;
  use Symfony\Component\Console\Output\OutputInterface;
  
  class SyncBedrockModels extends Command
  {
      protected function execute(InputInterface $input, OutputInterface $output)
      {
          $models = app(BedrockClientInterface::class)->listFoundationModels();
          Model::upsert($models, ['model_id'], ['name', 'provider']);
          $output->writeln('Synced ' . count($models) . ' models.');
      }
  }
  

4. Testing

• Mock the Bedrock client in tests:

  $this->app->instance(BedrockClientInterface::class, Mockery::mock(BedrockClientInterface::class));
  $mock->shouldReceive('invokeModel')
       ->once()
       ->andReturn(['content' => 'Mock response']);
  

Gotchas and Tips

Pitfalls

1. AWS Credentials Leaks

   • Issue: Hardcoding AWS keys in config/bedrock.php or environment files.
   • Fix: Use IAM roles (for EC2/Lambda) or Laravel’s env() with .env files. Never commit .env to version control.
   • Tip: Use php artisan config:clear after changing credentials to avoid caching issues.

2. Model-Specific Parameters

   • Issue: Incorrect parameters for a model (e.g., temperature for Claude vs. top_p for Llama).
   • Fix: Refer to Bedrock’s model documentation and validate payloads:

     $validator = Validator::make($payload, [
         'prompt' => 'required|string',
         'max_tokens_to_sample' => 'nullable|integer',
         'temperature' => 'nullable|numeric|min:0|max:1',
     ]);
     

3. Rate Limiting

   • Issue: Bedrock throttles requests (e.g., 5–10 RPS per model).
   • Fix: Implement Laravel’s throttle middleware or use a queue:

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

4. Cold Starts

   • Issue: First invocation of a model may take 1–2 seconds.
   • Fix: Pre-warm models during low-traffic periods or use a background job:

     // app/Console/Commands/WarmBedrockModels.php
     public function handle()
     {