@elizaos/plugin-bedrock/README.md

Amazon Bedrock plugin for ElizaOS - integrates Claude, Titan, and other foundation models

# Amazon Bedrock Plugin for Eliza

This plugin integrates Amazon Bedrock's AI models (including Amazon Nova, Claude, Mistral, and others) into the Eliza framework.

## Features

- 🤖 **Multiple Model Support**: Amazon Nova (Micro, Lite, Pro, Premier), Claude, Mistral, and more
- 🌍 **Multi-Region Support**: Automatic inference profile selection for cross-region inference
- 📝 **Text Generation**: Support for both small and large language models
- 🖼️ **Multimodal**: Image generation, image understanding, and video understanding
- 🔊 **Embeddings**: Text embedding support for RAG applications
- 🧪 **Built-in Tests**: Comprehensive test suite for all capabilities

## Prerequisites

1. **AWS Account**: You need an AWS account with access to Amazon Bedrock
2. **AWS Credentials**: Configure your AWS credentials using one of these methods:
   - AWS CLI: `aws configure`
   - Environment variables: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
   - IAM role (when running on AWS infrastructure)
3. **Model Access**: Request access to the models you want to use in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/)

## Installation

```bash
bun install @elizaos/plugin-bedrock
```

## Configuration

### Environment Variables

Create a `.env` file in your project root:

```bash
# AWS Configuration
AWS_REGION=eu-north-1  # Your AWS region
AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here

# Optional: Use AWS profile instead of keys
# AWS_PROFILE=your_profile_name

# Optional: Override default models
# BEDROCK_SMALL_MODEL=amazon.nova-micro-v1:0
# BEDROCK_LARGE_MODEL=amazon.nova-pro-v1:0
# BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
# BEDROCK_IMAGE_MODEL=amazon.titan-image-generator-v2:0
# BEDROCK_IMAGE_DESCRIPTION_MODEL=mistral.pixtral-large-2411:0
```

### Regional Model Configuration

The plugin automatically selects the appropriate model IDs based on your AWS region:

- **US Regions**: Uses direct model IDs or US inference profiles
- **EU Regions**: Uses EU inference profiles for cross-region inference
- **Other Regions**: Uses direct model IDs

For example, in `eu-north-1`, the plugin will automatically use:

- `eu.amazon.nova-micro-v1:0` instead of `amazon.nova-micro-v1:0`
- `eu.amazon.nova-pro-v1:0` instead of `amazon.nova-pro-v1:0`

## Usage

### In your Eliza character configuration:

```typescript
import { bedrockPlugin } from '@elizaos/plugin-bedrock';

export const character = {
  name: 'Assistant',
  plugins: [bedrockPlugin],
  // ... other configuration
};
```

### Direct usage in code:

```typescript
import { bedrockPlugin } from '@elizaos/plugin-bedrock';

// The plugin will be initialized with the runtime
// and will use the configured models for text generation,
// embeddings, and other AI tasks
```

## Supported Models

### Text Generation

- **Small Models**: Amazon Nova Micro, Claude Haiku
- **Large Models**: Amazon Nova Pro, Claude Sonnet, Mistral models

### Embeddings

- Amazon Titan Text Embeddings V2
- Outputs 1024-dimensional vectors by default

### Image Generation

- Amazon Titan Image Generator V2
- Supports various sizes and styles

### Image Understanding

- Claude models with vision capabilities
- Mistral Pixtral for multimodal understanding

## Troubleshooting

### AccessDeniedException

If you see this error:

```
AccessDeniedException: You don't have access to the model with the specified model ID.
```

**Solutions:**

1. **Check Model Access**: Go to the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/) and request access to the models
2. **Verify Region**: Ensure you've requested model access in the same region specified in `AWS_REGION`
3. **Use Inference Profiles**: For regions like `eu-north-1`, the plugin automatically uses inference profiles

### ValidationException with Nova Models

If you see:

```
ValidationException: Invocation of model ID amazon.nova-pro-v1:0 with on-demand throughput isn't supported
```

This means the region requires inference profiles. The plugin handles this automatically, but ensure your `AWS_REGION` is set correctly.

### Embedding Model Access

For the error:

```
Error generating embedding: AccessDeniedException
```

1. Request access to `Amazon Titan Text Embeddings V2` in your region
2. Or set a different embedding model: `BEDROCK_EMBEDDING_MODEL=your-accessible-model`

### Timeout Issues

For large video or document processing, increase the SDK timeout:

```typescript
import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
import { Config } from '@aws-sdk/types';

const config: Config = {
  region: 'eu-north-1',
  maxAttempts: 3,
  requestHandler: {
    requestTimeout: 300000, // 5 minutes
  },
};
```

## Testing

Run the built-in tests to verify your configuration:

```bash
# Run all tests
bun test

# Run specific test suites
bun test -- --grep "bedrock"
```

## Model-Specific Notes

### Amazon Nova

- Supports text, image, and video understanding
- Automatic token estimation for multimedia content
- 1 FPS sampling for videos under 16 minutes

### Claude Models

- Excellent for complex reasoning and analysis
- Supports vision capabilities in newer versions
- Best for tasks requiring nuanced understanding

### Mistral Pixtral

- Specialized for multimodal tasks
- Good balance of performance and cost
- Supports image understanding

### Titan Embeddings

- 1024-dimensional vectors (configurable to 256 or 512)
- Optimized for RAG applications
- Multilingual support

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

## License

This plugin is part of the Eliza project. See the main project repository for license information.

## Support

- [Eliza Documentation](https://github.com/elizaos/eliza)
- [Amazon Bedrock Documentation](https://docs.aws.amazon.com/bedrock/)
- [AWS Support](https://aws.amazon.com/support/)