bedrock-s3-vectors

Embed text with AWS Bedrock and read/write AWS S3 Vectors — a small, retry-aware, batched wrapper around the two AWS APIs.

Defaults to Cohere embed-v4 (1536-dimension output), since that's the Bedrock embedding model this package was built against, but both the model ID and output dimension are configurable per instance. Any Bedrock model that accepts Cohere-shaped input (texts / input_type / embedding_types / output_dimension) works out of the box; for a different request/response shape, subclass VectorUtility and override get_embeddings.

Install

pip install bedrock-s3-vectors

Usage

from bedrock_s3_vectors import VectorUtility

vectors = VectorUtility(
    vector_bucket="my-vectors",
    vector_index="my-vectors-index",
    # Optional — both default to Cohere embed-v4 / 1536 dimensions.
    model="cohere.embed-v4:0",
    dimension=1536,
)

# Embed and upload
vectors.put_vectors([{"key": "doc-1", "text": "..."}])

# Similarity search
results = vectors.query_vectors("some search query", topK=10)

# Fetch / delete by key
vectors.get_vectors(["doc-1"])
vectors.delete_vectors(["doc-1"])

Pass your own boto3.Session (e.g. to use a named profile locally) via the session kwarg; it defaults to boto3.Session().

Requirements

Your AWS credentials need bedrock:InvokeModel on the target model and s3vectors:* on the target vector bucket/index. Both bedrock-runtime and s3vectors clients are created from the session you pass in (or the default credential chain).

Development

uv sync
uv run ruff check . && uv run ruff format --check .
uv run pytest

Releasing

Bump version in pyproject.toml and merge to main. Merging alone publishes it: .github/workflows/publish-bedrock-s3-vectors.yml triggers automatically on any push to main that touches lib/bedrock_s3_vectors/**, builds, and publishes to PyPI via Trusted Publishing — no API token — and is a no-op if that version is already published. This is intentionally a separate workflow from cron/backend/frontend deploys (main.yml), so changing this package never depends on picking a deploy target and deploying crons never rebuilds/republishes this package.

After a release, also update the pin in terraform/glue.tf's local.glue_shared_modules so the Glue jobs pick up the new version.

Compatibility

Targets Python 3.9+ so it can run inside AWS Glue Python-shell jobs (which pin 3.9), in addition to any modern Python environment.