Metadata-Version: 2.1
Name: cdk-s3-vectors
Version: 0.3.0
Summary: A CDK construct library for Amazon S3 Vectors. This construct simplifies the creation of vector buckets, vector indexes with full configuration options, and Amazon Bedrock knowledge bases using S3 Vectors as the underlying vector store.
Home-page: https://github.com/bimnett/cdk-s3-vectors.git
Author: Bimnet Tesfamariam<bimnett@gmail.com>
License: Apache-2.0
Project-URL: Source, https://github.com/bimnett/cdk-s3-vectors.git
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Typing :: Typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved
Requires-Python: ~=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aws-cdk-lib<3.0.0,>=2.205.0
Requires-Dist: constructs<11.0.0,>=10.0.5
Requires-Dist: jsii<2.0.0,>=1.113.0
Requires-Dist: publication>=0.0.3
Requires-Dist: typeguard<4.3.0,>=2.13.3

# cdk-s3-vectors

![AWS CDK v2](https://img.shields.io/badge/AWS%20CDK-v2-orange.svg?style=for-the-badge)
![npm version](https://img.shields.io/npm/v/cdk-s3-vectors.svg?style=for-the-badge)
![PyPI version](https://img.shields.io/pypi/v/cdk-s3-vectors.svg?style=for-the-badge)
![NuGet version](https://img.shields.io/nuget/v/bimnett.CdkS3Vectors.svg?style=for-the-badge)
![Maven Central](https://img.shields.io/maven-central/v/io.github.bimnett/cdk-s3-vectors.svg?style=for-the-badge)

> **⚠️ Maintenance Notice**: This library is intended as a temporary solution and will only be maintained until AWS CloudFormation and CDK introduce native support for Amazon S3 Vectors. Once native support is available, users are encouraged to migrate to the official AWS constructs.

## Reference Documentation

[Amazon S3 Vectors User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html)

## Supported Languages

| Language | Package |
|----------|---------|
| ![Python Logo](https://docs.aws.amazon.com/cdk/api/latest/img/python32.png) Python | `cdk-s3-vectors` |
| ![TypeScript Logo](https://docs.aws.amazon.com/cdk/api/latest/img/typescript32.png) TypeScript | `cdk-s3-vectors` |
| ![Java Logo](https://docs.aws.amazon.com/cdk/api/latest/img/java32.png) Java | `io.github.bimnett:cdk-s3-vectors` |
| ![.NET Logo](https://docs.aws.amazon.com/cdk/api/latest/img/dotnet32.png) .NET | `bimnett.CdkS3Vectors` |

## Overview

Amazon S3 Vectors is in preview release and provides native vector storage and similarity search capabilities within Amazon S3.

This AWS CDK construct library provides high-level constructs for Amazon S3 Vectors, enabling you to create vector buckets, indexes, and knowledge bases for AI/ML applications.

The library includes three main constructs:

* **Bucket**: Creates S3 vector buckets with optional encryption
* **Index**: Creates vector indexes within buckets for similarity search
* **KnowledgeBase**: Creates Amazon Bedrock knowledge bases using S3 Vectors as the vector store

**IMPORTANT:** The `constructs` library version must be >= 10.0.5.

## Examples

For complete, deployable examples in all supported languages, see the [examples directory](examples/).

## Bucket Construct Props

| Name | Type | Description |
|------|------|-------------|
| `vectorBucketName` | `string` | The name of the vector bucket to create. |
| `encryptionConfiguration?` | `EncryptionConfiguration` | Optional encryption configuration for the vector bucket. Defaults to AES256. |

## Index Construct Props

| Name | Type | Description |
|------|------|-------------|
| `vectorBucketName` | `string` | The name of the vector bucket to create the index in. |
| `indexName` | `string` | The name of the vector index to create. |
| `dataType` | `'float32'` | The data type of the vectors in the index. |
| `dimension` | `number` | The dimensions of the vectors (1-4096). |
| `distanceMetric` | `'euclidean' \| 'cosine'` | The distance metric for similarity search. |
| `metadataConfiguration?` | `MetadataConfiguration` | Optional metadata configuration for the index. |

## KnowledgeBase Construct Props

| Name | Type | Description |
|------|------|-------------|
| `knowledgeBaseName` | `string` | The name of the knowledge base to create. |
| `knowledgeBaseConfiguration` | `KnowledgeBaseConfiguration` | Vector embeddings configuration details. |
| `vectorBucketArn` | `string` | The ARN of the S3 vector bucket. |
| `indexArn` | `string` | The ARN of the vector index. |
| `description?` | `string` | Optional description of the knowledge base. |
| `clientToken?` | `string` | Optional idempotency token (≥33 characters). |

## Pattern Properties

| Name | Type | Description |
|------|------|-------------|
| `vectorBucketName` | `string` | Returns the name of the created vector bucket |
| `vectorBucketArn` | `string` | Returns the ARN of the created vector bucket |
| `indexArn` | `string` | Returns the ARN of the created vector index |
| `indexName` | `string` | Returns the name of the created vector index |
| `knowledgeBaseId` | `string` | Returns the ID of the created knowledge base |
| `knowledgeBaseArn` | `string` | Returns the ARN of the created knowledge base |

## Default Settings

Out of the box implementation of the constructs without any override will set the following defaults:

### Amazon S3 Vector Bucket

* Server-side encryption with Amazon S3 managed keys (SSE-S3) using AES256
* Least privilege IAM permissions for vector operations
* Custom resource handlers for bucket lifecycle management

### Vector Index

* Support for float32 data type vectors
* Configurable dimensions (1-4096)
* Choice of euclidean or cosine distance metrics
* Optional metadata configuration for enhanced search capabilities

### Amazon Bedrock Knowledge Base

* Integration with S3 Vectors as the vector store
* Configurable embedding models
* IAM role with least privilege permissions
* Support for various embedding data types and dimensions

## Architecture

![Architecture Diagram](./architecture.png)

## License

This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) file for details.
