1import type * as s3vectors from "@distilled.cloud/aws/s3vectors";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { Index } from "./VectorIndex.ts";
5
6/** Fields the binding injects from the bound {@link Index}. */
7type IndexRef = "vectorBucketName" | "indexName" | "indexArn";
8
9export interface QueryVectorsRequest extends Omit<
10 s3vectors.QueryVectorsInput,
11 IndexRef
12> {}
13export interface GetVectorsRequest extends Omit<
14 s3vectors.GetVectorsInput,
15 IndexRef
16> {}
17export interface ListVectorsRequest extends Omit<
18 s3vectors.ListVectorsInput,
19 IndexRef
20> {}
21
22/**
23 * The read-only runtime client returned by binding an {@link Index} via
24 * {@link VectorsRead}. All calls target the bound index (its ARN is
25 * injected); pass raw distilled request shapes minus the index identifier.
26 */
27export interface ReadVectorsClient {
28 /** Nearest-neighbor similarity query. */
29 readonly query: (
30 request: QueryVectorsRequest,
31 ) => Effect.Effect<s3vectors.QueryVectorsOutput, s3vectors.QueryVectorsError>;
32 /** Fetch vectors by key. */
33 readonly get: (
34 request: GetVectorsRequest,
35 ) => Effect.Effect<s3vectors.GetVectorsOutput, s3vectors.GetVectorsError>;
36 /** List vectors (paginated / segmented scan). */
37 readonly list: (
38 request: ListVectorsRequest,
39 ) => Effect.Effect<s3vectors.ListVectorsOutput, s3vectors.ListVectorsError>;
40}
41
42/**
43 * Read-only runtime binding for the S3 Vectors data plane — query, get, and
44 * list vectors in a bound {@link Index}.
45 *
46 * Grants only `s3vectors:QueryVectors`, `s3vectors:GetVectors`, and
47 * `s3vectors:ListVectors` on exactly the bound index's ARN — the
48 * least-privilege choice for retrieval-only consumers (e.g. a RAG search
49 * endpoint that never writes embeddings). Provide the implementation with
50 * `Effect.provide(AWS.S3Vectors.VectorsReadHttp)`.
51 *
52 * ### Reading Vectors
53 * **Example:** Query Nearest Neighbors (read-only)
54 * ```typescript
55 * // init
56 * const vectors = yield* AWS.S3Vectors.VectorsRead(index);
57 *
58 * // runtime
59 * const result = yield* vectors.query({
60 * topK: 5,
61 * queryVector: { float32: [0.1, 0.2, 0.3] },
62 * returnDistance: true,
63 * });
64 * ```
65 *
66 * @binding
67 */
68export interface VectorsRead extends Binding.Service<
69 VectorsRead,
70 "AWS.S3Vectors.VectorsRead",
71 <I extends Index>(index: I) => Effect.Effect<ReadVectorsClient>
72> {}
73export const VectorsRead = Binding.Service<VectorsRead>(
74 "AWS.S3Vectors.VectorsRead",
75);