| 1 | import type * as s3vectors from "@distilled.cloud/aws/s3vectors"; |
| 2 | import type * as Effect from "effect/Effect"; |
| 3 | import * as Binding from "../../Binding.ts"; |
| 4 | import type { Index } from "./VectorIndex.ts"; |
| 5 | |
| 6 | /** Fields the binding injects from the bound {@link Index}. */ |
| 7 | type IndexRef = "vectorBucketName" | "indexName" | "indexArn"; |
| 8 | |
| 9 | export interface PutVectorsRequest extends Omit< |
| 10 | s3vectors.PutVectorsInput, |
| 11 | IndexRef |
| 12 | > {} |
| 13 | export interface DeleteVectorsRequest extends Omit< |
| 14 | s3vectors.DeleteVectorsInput, |
| 15 | IndexRef |
| 16 | > {} |
| 17 | |
| 18 | /** |
| 19 | * The write-only runtime client returned by binding an {@link Index} via |
| 20 | * {@link VectorsWrite}. All calls target the bound index (its ARN is |
| 21 | * injected); pass raw distilled request shapes minus the index identifier. |
| 22 | */ |
| 23 | export interface WriteVectorsClient { |
| 24 | /** Insert or overwrite vectors (keyed by `key`). */ |
| 25 | readonly put: ( |
| 26 | request: PutVectorsRequest, |
| 27 | ) => Effect.Effect<s3vectors.PutVectorsOutput, s3vectors.PutVectorsError>; |
| 28 | /** Delete vectors by key. */ |
| 29 | readonly delete: ( |
| 30 | request: DeleteVectorsRequest, |
| 31 | ) => Effect.Effect< |
| 32 | s3vectors.DeleteVectorsOutput, |
| 33 | s3vectors.DeleteVectorsError |
| 34 | >; |
| 35 | } |
| 36 | |
| 37 | /** |
| 38 | * Write-only runtime binding for the S3 Vectors data plane — insert and |
| 39 | * delete vectors in a bound {@link Index}. |
| 40 | * |
| 41 | * Grants only `s3vectors:PutVectors` and `s3vectors:DeleteVectors` on |
| 42 | * exactly the bound index's ARN — the least-privilege choice for ingestion |
| 43 | * pipelines that write embeddings but never query them. Provide the |
| 44 | * implementation with `Effect.provide(AWS.S3Vectors.VectorsWriteHttp)`. |
| 45 | * |
| 46 | * ### Writing Vectors |
| 47 | * **Example:** Insert Embeddings (write-only) |
| 48 | * ```typescript |
| 49 | * // init |
| 50 | * const vectors = yield* AWS.S3Vectors.VectorsWrite(index); |
| 51 | * |
| 52 | * // runtime |
| 53 | * yield* vectors.put({ |
| 54 | * vectors: [{ key: "doc-1", data: { float32: [0.1, 0.2, 0.3] } }], |
| 55 | * }); |
| 56 | * ``` |
| 57 | * |
| 58 | * @binding |
| 59 | */ |
| 60 | export interface VectorsWrite extends Binding.Service< |
| 61 | VectorsWrite, |
| 62 | "AWS.S3Vectors.VectorsWrite", |
| 63 | <I extends Index>(index: I) => Effect.Effect<WriteVectorsClient> |
| 64 | > {} |
| 65 | export const VectorsWrite = Binding.Service<VectorsWrite>( |
| 66 | "AWS.S3Vectors.VectorsWrite", |
| 67 | ); |