Getting Started

Minimal Setup

Installation:
```
composer require async-aws/bedrock-runtime
```
Ensure your project uses PHP 8.2+ (minimum requirement).

Basic Usage: Initialize the client in config/services.php:

'bedrock' => [
    'client' => AsyncAws\BedrockRuntime\BedrockRuntimeClient::class,
    'region' => env('AWS_REGION', 'us-east-1'),
    'version' => 'latest',
],

First API Call (Invoke Model):

use AsyncAws\BedrockRuntime\BedrockRuntimeClient;
use AsyncAws\BedrockRuntime\Enum\ModelId;

$client = app(BedrockRuntimeClient::class);
$response = $client->invokeModel([
    'modelId' => ModelId::ANTHROPIC_CLARKE,
    'body' => json_encode(['prompt' => 'Hello, world!']),
]);

Key Resources:
- AsyncAws BedrockRuntime Docs
- AWS Bedrock Runtime API Reference

Implementation Patterns

Core Workflows

Streaming Responses (Bidirectional Streams): Use InvokeModelWithBidirectionalStream for real-time input/output (requires HTTP/2):

$stream = $client->invokeModelWithBidirectionalStream([
    'modelId' => ModelId::ANTHROPIC_CLARKE,
    'body' => json_encode(['prompt' => 'Stream me!']),
]);
foreach ($stream as $chunk) {
    echo $chunk['body'];
}

Guardrails for Harmful Content: Configure guardrails in the request:

$response = $client->invokeModel([
    'modelId' => ModelId::ANTHROPIC_CLARKE,
    'body' => json_encode([
        'prompt' => 'Explain quantum computing',
        'guardrails' => [
            'harmfulContent' => 'BLOCK',
        ],
    ]),
]);

Service Tier Support: Specify service tier for cost optimization:

$response = $client->invokeModel([
    'modelId' => ModelId::ANTHROPIC_CLARKE,
    'serviceTier' => 'RESERVED', // or 'ON_DEMAND'
    'body' => json_encode(['prompt' => 'Optimized query']),
]);

Integration Tips

Laravel Queues: Wrap API calls in jobs for async processing:

use AsyncAws\BedrockRuntime\BedrockRuntimeClient;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;

class GenerateResponseJob implements ShouldQueue
{
    use Queueable;

    public function handle(BedrockRuntimeClient $client)
    {
        $client->invokeModel([...]);
    }
}

Caching Responses: Cache frequent queries with Laravel’s cache:

$cacheKey = 'bedrock:clarke:prompt';
$response = cache()->remember($cacheKey, now()->addHours(1), function () use ($client) {
    return $client->invokeModel([...]);
});

Error Handling: Use AsyncAws’s exceptions for granular handling:

try {
    $client->invokeModel([...]);
} catch (\AsyncAws\Core\Exception\BedrockRuntimeException $e) {
    if ($e->getStatusCode() === 400) {
        // Handle bad request
    }
}

Gotchas and Tips

Common Pitfalls

HTTP/2 Requirement for Streaming:
- Bidirectional streams (InvokeModelWithBidirectionalStream) require HTTP/2.
- Ensure your server (e.g., Nginx, Apache) supports HTTP/2 and AsyncAws is configured to use it:
```
$client = new BedrockRuntimeClient([
    'http_client' => new AsyncAws\Core\Http\GuzzleHttpClient([
        'http2' => true,
    ]),
]);
```
Model ID Enums:
- Always use AsyncAws\BedrockRuntime\Enum\ModelId for model IDs (e.g., ModelId::ANTHROPIC_CLARKE).
- Avoid hardcoding strings like 'anthropic.clarke-v1' to prevent typos and ensure IDE autocompletion.

Payload Size Limits:

Bedrock has payload size limits (~5MB for input). Validate payloads:

$body = json_encode(['prompt' => 'Long prompt...']);
if (strlen($body) > 5_000_000) {
    throw new \RuntimeException('Payload exceeds Bedrock limits.');
}

Guardrails Misconfiguration:

Incorrect guardrail settings (e.g., harmfulContent: 'BLOCK') may fail silently. Test with:

$response = $client->invokeModel([
    'body' => json_encode([
        'prompt' => 'Test guardrail',
        'guardrails' => ['harmfulContent' => 'BLOCK'],
    ]),
]);
if ($response->getContentType() === 'application/json') {
    $data = json_decode($response->getBody(), true);
    if (isset($data['error'])) {
        // Handle guardrail rejection
    }
}

Debugging Tips

Enable AsyncAws Logging: Add to config/logging.php:

'channels' => [
    'async_aws' => [
        'driver' => 'single',
        'path' => storage_path('logs/async_aws.log'),
        'level' => 'debug',
    ],
],

Then configure the client:

$client = new BedrockRuntimeClient([
    'logger' => \Monolog\Logger::get('async_aws'),
]);

Validate AWS Credentials: Use AWS_ACCESS_KEY_ID/AWS_SECRET_KEY env vars or the ~/.aws/credentials file. Test with:
```
$client->describeModel(['modelId' => ModelId::ANTHROPIC_CLARKE]);
```
A 403 Forbidden indicates credential issues.

Unknown API Responses: If the API returns an unrecognized enum value, use UNKNOWN_TO_SDK as a fallback:

$status = $response->getStatusCode();
if ($status === \AsyncAws\BedrockRuntime\Enum\StatusCode::UNKNOWN_TO_SDK) {
    // Handle unknown status
}

Extension Points

Custom Middleware: Add middleware to transform requests/responses:

$client = new BedrockRuntimeClient([
    'middleware' => [
        new class implements \AsyncAws\Core\Middleware {
            public function __invoke(callable $next) {
                return function ($request) use ($next) {
                    // Modify request
                    $response = $next($request);
                    // Modify response
                    return $response;
                };
            }
        },
    ],
]);

Event Dispatching: Dispatch Laravel events for key actions (e.g., model invocation):
```
event(new \App\Events\BedrockModelInvoked($modelId, $prompt));
```

Testing: Use AsyncAws’s mock client for unit tests:

use AsyncAws\BedrockRuntime\BedrockRuntimeClient;
use AsyncAws\Core\MockClient;

$mock = new MockClient();
$client = new BedrockRuntimeClient(['http_client' => $mock]);
$mock->shouldReceive('send')
     ->once()
     ->withArgs(function ($request) {
         return $request->getUri() === 'https://bedrock.runtime/...';
     });

Bedrock Runtime Laravel Package