Ai Bedrock Platform Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package

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

   Ensure aws/aws-sdk-php is installed for AWS Bedrock API interactions.

2. Configure AWS Credentials Add AWS credentials to your .env file:

   AWS_ACCESS_KEY_ID=your_access_key
   AWS_SECRET_ACCESS_KEY=your_secret_key
   AWS_DEFAULT_REGION=us-east-1  # or your Bedrock region
   

3. Publish Configuration Publish the default configuration:

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

   This creates a config/bedrock.php file. Update it to define your default model and AWS settings:

   return [
       'models' => [
           'default' => 'anthropic.claude-v2', // Default model to use
       ],
       'aws' => [
           'region' => env('AWS_DEFAULT_REGION'),
       ],
   ];
   

4. Register the Service Provider In config/app.php, add the Bedrock service provider to the providers array:

   Symfony\AiBedrock\BedrockServiceProvider::class,
   

5. First Invocation Use the Bedrock client in a Laravel controller or service:

   use Symfony\AiBedrock\Client\BedrockClientInterface;
   use Symfony\AiBedrock\Client\ModelClient;
   
   public function generateText(BedrockClientInterface $bedrockClient)
   {
       $modelClient = new ModelClient($bedrockClient, 'anthropic.claude-v2');
   
       $response = $modelClient->invoke([
           'prompt' => 'Write a Laravel assessment for symfony/ai-bedrock-platform.',
           'max_tokens_to_sample' => 100,
       ]);
   
       return $response->getContent();
   }
   

6. List Available Models (Optional) Use the CLI command to list available Bedrock models:

   php artisan ai:bedrock:list
   

   This syncs the model catalog with the Bedrock API.

Implementation Patterns

Workflows

1. Model Invocation Workflow

• Use Case: Generating text, chat responses, or structured data using Bedrock models.
• Pattern:
  • Instantiate a ModelClient for a specific model (e.g., anthropic.claude-v2).
  • Define the payload with model-specific parameters (e.g., prompt, max_tokens_to_sample).
  • Invoke the model and handle the response.
• Example:

  $bedrockClient = app(BedrockClientInterface::class);
  $claudeClient = new ModelClient($bedrockClient, 'anthropic.claude-v2');
  
  $response = $claudeClient->invoke([
      'prompt' => 'Explain Laravel dependency injection in simple terms.',
      'max_tokens_to_sample' => 150,
      'temperature' => 0.7,
  ]);
  
  $content = $response->getContent();
  

2. Model Routing Workflow (v0.8.0+)

• Use Case: Dynamically route requests to different models based on business logic (e.g., cost, performance, or user tier).
• Pattern:
  • Define a Provider abstraction to encapsulate model-specific logic.
  • Use the BedrockClientInterface to route requests based on conditions.
• Example:

  // Define a provider for Claude
  $claudeProvider = new class implements ProviderInterface {
      public function supports(string $modelId): bool
      {
          return str_starts_with($modelId, 'anthropic.claude');
      }
  
      public function getClient(BedrockClientInterface $bedrockClient, string $modelId): ModelClient
      {
          return new ModelClient($bedrockClient, $modelId);
      }
  };
  
  // Register the provider with the Bedrock client
  $bedrockClient->addProvider($claudeProvider);
  
  // Route a request to Claude
  $modelClient = $bedrockClient->getModelClient('anthropic.claude-v2');
  

3. Structured Output Workflow

• Use Case: Extracting structured data (e.g., JSON) from Claude or other models supporting structured output.
• Pattern:
  • Use the ClaudeModelClient for models like Anthropic Claude that support structured output.
  • Define a schema for the expected output.
• Example:

  use Symfony\AiBedrock\Client\ClaudeModelClient;
  
  $claudeClient = new ClaudeModelClient($bedrockClient, 'anthropic.claude-v2');
  
  $response = $claudeClient->invoke([
      'prompt' => 'Generate a JSON summary of this Laravel assessment.',
      'max_tokens_to_sample' => 200,
      'anthropic_version' => 'bedrock-2023-05-31',
      'output_format' => [
          'type' => 'json_object',
      ],
  ]);
  
  $structuredData = json_decode($response->getContent(), true);
  

4. Batch Processing Workflow

• Use Case: Processing multiple prompts efficiently (e.g., generating embeddings or summaries for a dataset).
• Pattern:
  • Loop through prompts and invoke the model for each.
  • Use Laravel’s queue system to avoid timeouts or high latency.
• Example:

  use Illuminate\Support\Facades\Queue;
  
  Queue::later(now()->addMinutes(5), function () use ($bedrockClient, $prompts) {
      foreach ($prompts as $prompt) {
          $modelClient = new ModelClient($bedrockClient, 'amazon.titan-text-express');
          $response = $modelClient->invoke([
              'inputText' => $prompt,
              'textGenerationConfig' => [
                  'maxTokenCount' => 100,
                  'stopSequences' => ['\n\n'],
              ],
          ]);
          // Store or process the response
      }
  });
  

Integration Tips

1. Laravel Service Container Bind the BedrockClientInterface to a concrete implementation in AppServiceProvider:

   public function register()
   {
       $this->app->bind(BedrockClientInterface::class, function ($app) {
           return new BedrockClient($app['config']['bedrock']);
       });
   }
   

2. Facades for Clean Syntax Create a facade to simplify Bedrock interactions:

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

   Register the facade in AppServiceProvider:

   Facade::register(BedrockFacade::class, Bedrock::class);
   

3. Model Catalog Caching Cache the list of available models to avoid repeated API calls:

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

4. Error Handling Wrap Bedrock calls in try-catch blocks to handle AWS-specific exceptions:

   try {
       $response = $modelClient->invoke($payload);
   } catch (\Aws\Bedrock\Exception\BedrockException $e) {
       Log::error('Bedrock error: ' . $e->getMessage());
       // Fallback logic or retry
   }
   

5. Environment-Specific Config Use Laravel’s environment-specific configurations to switch models or AWS regions:

   // config/bedrock.php
   return [
       'models' => [
           'default' => env('BEDROCK_DEFAULT_MODEL', 'anthropic.claude-v2'),
           'staging' => 'amazon.titan-text-lite',
       ],
       'aws' => [
           'region' => env('BEDROCK_REGION', 'us-east-1'),
       ],
   ];
   

Gotchas and Tips

Pitfalls

1. AWS Credentials and Permissions

   • Issue: Missing or incorrect IAM permissions can cause BedrockExceptions.
   • Fix: Ensure the IAM role/user has bedrock:InvokeModel and bedrock:ListFoundationModels permissions. Example policy:

     {
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Effect": "Allow",
                 "Action": [
                     "bedrock:InvokeModel",
                     "bedrock:ListFoundationModels"
                 ],
                 "Resource": "*"
             }
         ]
     }
     

2. Model-Specific Payload Requirements

   • Issue: Not all models support the same parameters. For example, Claude requires anthropic_version, while Titan uses textGenerationConfig.
   • Fix: Refer to the [Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/APIReference