1import type * as Effect from "effect/Effect";
2import * as Binding from "../../Binding.ts";
3import type { Index } from "./VectorIndex.ts";
4import type { ReadVectorsClient } from "./VectorsRead.ts";
5import type { WriteVectorsClient } from "./VectorsWrite.ts";
6
7/**
8 * The read-write runtime data-plane client returned by binding an
9 * {@link Index}. All calls target the bound index (its ARN is injected);
10 * pass raw distilled request shapes minus the index identifier.
11 */
12export interface VectorsClient extends ReadVectorsClient, WriteVectorsClient {}
13
14/**
15 * Read-write runtime binding for the S3 Vectors data plane — read and write
16 * vectors in a bound {@link Index}.
17 *
18 * Bind an `Index` inside a function runtime to get a {@link VectorsClient}
19 * with `put` / `query` / `get` / `list` / `delete`. The binding grants
20 * read+write `s3vectors:*Vectors` actions scoped to exactly the bound index's
21 * ARN. This is the natural read/write pairing for a vector store — the key
22 * enabler for building embedding search and RAG retrieval on top of S3
23 * Vectors. For least privilege, prefer {@link VectorsRead} (query/get/list)
24 * or {@link VectorsWrite} (put/delete) where one direction suffices.
25 *
26 * ### Reading and Writing Vectors
27 * **Example:** Insert and Query Vectors
28 * ```typescript
29 * // init
30 * const vectors = yield* AWS.S3Vectors.Vectors(index);
31 *
32 * // runtime — insert
33 * yield* vectors.put({
34 * vectors: [
35 * { key: "doc-1", data: { float32: [0.1, 0.2, 0.3] } },
36 * ],
37 * });
38 *
39 * // runtime — query nearest neighbors
40 * const result = yield* vectors.query({
41 * topK: 5,
42 * queryVector: { float32: [0.1, 0.2, 0.3] },
43 * returnDistance: true,
44 * });
45 * ```
46 *
47 * @binding
48 */
49export interface Vectors extends Binding.Service<
50 Vectors,
51 "AWS.S3Vectors.Vectors",
52 <I extends Index>(index: I) => Effect.Effect<VectorsClient>
53> {}
54export const Vectors = Binding.Service<Vectors>("AWS.S3Vectors.Vectors");