The best way to control Claude Code, Codex and more from any computer or phone

main
ts 265 lines 9.33 KB
Raw
1 import * as vectorize from "@distilled.cloud/cloudflare/vectorize";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { isResourceOfType, Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import * as Stream from "effect/Stream";
8 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
9 import type { Providers } from "../Providers.ts";
10
11 const TypeId = "Cloudflare.VectorizeIndex" as const;
12 type TypeId = typeof TypeId;
13
14 export type DistanceMetric = "cosine" | "euclidean" | "dot-product";
15
16 export type Preset =
17 | "@cf/baai/bge-small-en-v1.5"
18 | "@cf/baai/bge-base-en-v1.5"
19 | "@cf/baai/bge-large-en-v1.5"
20 | "openai/text-embedding-ada-002"
21 | "cohere/embed-multilingual-v2.0"
22 // Keep the union open so new Cloudflare presets aren't blocked by stale types.
23 | (string & {});
24
25 const DEFAULT_METRIC: DistanceMetric = "cosine";
26
27 export type IndexProps = {
28 /**
29 * Name of the index. If omitted, a unique name will be generated.
30 * Must be lowercase alphanumeric with hyphens. Changing it triggers a
31 * replacement.
32 * @default ${app}-${stage}-${id}
33 */
34 name?: string;
35 /**
36 * Number of dimensions for each vector stored in the index. Required
37 * unless `preset` is provided. Cannot be changed after creation —
38 * updating this property triggers a replacement.
39 */
40 dimensions?: number;
41 /**
42 * Distance metric used for similarity search. Cannot be changed after
43 * creation — updating this property triggers a replacement.
44 * @default "cosine"
45 */
46 metric?: DistanceMetric;
47 /**
48 * A managed embedding model preset that fixes `dimensions` and `metric`
49 * to match the named model. Mutually exclusive with `dimensions`/`metric`.
50 * Cannot be changed after creation — updating this triggers a replacement.
51 */
52 preset?: Preset;
53 /**
54 * Human-readable description of the index. Vectorize has no update API,
55 * so changing the description triggers a replacement.
56 */
57 description?: string;
58 };
59
60 export type IndexAttributes = {
61 indexName: string;
62 dimensions: number | undefined;
63 metric: DistanceMetric | undefined;
64 description: string | undefined;
65 accountId: string;
66 createdOn: string | undefined;
67 modifiedOn: string | undefined;
68 };
69
70 export type Index = Resource<TypeId, IndexProps, IndexAttributes, never, Providers>;
71
72 /**
73 * A Cloudflare Vectorize index for storing and querying vector embeddings.
74 *
75 * Vectorize is a globally distributed vector database. Create an index as a
76 * resource, then bind it to a Worker to insert, upsert, and query vectors.
77 *
78 * A Vectorize index is identified by its name and is immutable: its
79 * dimensions, metric, preset, and description are all fixed at creation.
80 * Changing any of them triggers a replacement.
81 * ### Creating an Index
82 * **Example:** Index with explicit dimensions and metric
83 * ```typescript
84 * const index = yield* Cloudflare.Vectorize.Index("my-index", {
85 * dimensions: 768,
86 * metric: "cosine",
87 * });
88 * ```
89 *
90 * **Example:** Index from a managed embedding model preset
91 * A preset fixes the dimensions and metric to match the named model.
92 * ```typescript
93 * const index = yield* Cloudflare.Vectorize.Index("my-index", {
94 * preset: "@cf/baai/bge-base-en-v1.5",
95 * });
96 * ```
97 *
98 * **Example:** Index with a description
99 * ```typescript
100 * const index = yield* Cloudflare.Vectorize.Index("my-index", {
101 * dimensions: 1536,
102 * metric: "euclidean",
103 * description: "Product catalog embeddings",
104 * });
105 * ```
106 *
107 * ### Binding to a Worker
108 * **Example:** Querying an index inside a Worker
109 * ```typescript
110 * const index = yield* Cloudflare.Vectorize.SearchIndex(MyIndex);
111 *
112 * // Insert vectors
113 * yield* index.upsert([
114 * { id: "1", values: [0.1, 0.2, 0.3], metadata: { title: "doc" } },
115 * ]);
116 *
117 * // Query the nearest neighbors
118 * const matches = yield* index.query([0.1, 0.2, 0.3], { topK: 5 });
119 * ```
120 *
121 * @see https://developers.cloudflare.com/vectorize/
122 *
123 * @resource
124 * @product Vectorize
125 * @category AI
126 */
127 export const Index = Resource<Index>(TypeId);
128
129 /**
130 * Returns true if the given value is a Vectorize Index resource.
131 */
132 export const isIndex = (value: unknown): value is Index => isResourceOfType(value, TypeId);
133
134 export const IndexProvider = () =>
135 Provider.succeed(Index, {
136 stables: ["indexName", "accountId"],
137 diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
138 const { accountId } = yield* yield* CloudflareEnvironment;
139 if (!isResolved(news)) return undefined;
140 if ((output?.accountId ?? accountId) !== accountId) {
141 return { action: "replace" } as const;
142 }
143 const oldName = output?.indexName ?? (yield* createIndexName(id, olds.name));
144 // Auto-generated names are engine-owned: the deployed name stays
145 // authoritative even if the generator would name this id differently
146 // today. Only an explicit user-provided name can force a replace.
147 const name = news.name ?? oldName;
148 if (
149 oldName !== name ||
150 (news.preset ?? undefined) !== (olds.preset ?? undefined) ||
151 (news.dimensions ?? undefined) !== (olds.dimensions ?? undefined) ||
152 (news.metric ?? DEFAULT_METRIC) !== (olds.metric ?? DEFAULT_METRIC) ||
153 (news.description ?? undefined) !== (olds.description ?? undefined)
154 ) {
155 return { action: "replace" } as const;
156 }
157 return undefined;
158 }),
159 read: Effect.fn(function* ({ id, output, olds }) {
160 const { accountId } = yield* yield* CloudflareEnvironment;
161 const acct = output?.accountId ?? accountId;
162 const name = output?.indexName ?? (yield* createIndexName(id, olds?.name));
163 return yield* vectorize.getIndex({ accountId: acct, indexName: name }).pipe(
164 Effect.map((index) => toAttributes(index, name, acct)),
165 Effect.catchTag(["NotFound", "Gone"], () => Effect.undefined),
166 );
167 }),
168 reconcile: Effect.fn(function* ({ id, news = {}, output }) {
169 const { accountId } = yield* yield* CloudflareEnvironment;
170 // Prefer the deployed name: regenerating would target a different
171 // index if the generator's output for this id ever drifts.
172 const indexName = output?.indexName ?? (yield* createIndexName(id, news.name));
173
174 // Observe — read the live index by name. The name is the stable
175 // identifier; fall back through a NotFound to the create path so
176 // we recover from out-of-band deletes or partial state-persistence.
177 let observed = yield* vectorize
178 .getIndex({
179 accountId,
180 indexName,
181 })
182 .pipe(Effect.catchTag(["NotFound", "Gone"], () => Effect.undefined));
183
184 // Ensure — create if missing. Cloudflare returns 409 Conflict when
185 // an index with the same name already exists; tolerate the race by
186 // re-reading it.
187 if (!observed) {
188 observed = yield* vectorize
189 .createIndex({
190 accountId,
191 name: indexName,
192 config: buildConfig(news),
193 description: news.description,
194 })
195 .pipe(
196 Effect.catchTag("IndexAlreadyExists", () =>
197 vectorize.getIndex({ accountId, indexName }),
198 ),
199 );
200 }
201
202 return toAttributes(observed, indexName, accountId);
203 }),
204 delete: Effect.fn(function* ({ output }) {
205 yield* vectorize
206 .deleteIndex({
207 accountId: output.accountId,
208 indexName: output.indexName,
209 })
210 .pipe(Effect.catchTag(["NotFound", "Gone"], () => Effect.void));
211 }),
212 list: Effect.fn(function* () {
213 const { accountId } = yield* yield* CloudflareEnvironment;
214 return yield* vectorize.listIndexes.pages({ accountId }).pipe(
215 Stream.runCollect,
216 Effect.map((chunk) =>
217 Array.from(chunk).flatMap((page) =>
218 (page.result ?? [])
219 .filter(
220 (
221 index,
222 ): index is (typeof page.result)[number] & {
223 name: string;
224 } => index.name != null,
225 )
226 .map((index) => toAttributes(index, index.name, accountId)),
227 ),
228 ),
229 );
230 }),
231 });
232
233 const toAttributes = (
234 index: vectorize.GetIndexResponse | vectorize.CreateIndexResponse,
235 name: string,
236 accountId: string,
237 ): IndexAttributes => ({
238 indexName: index.name ?? name,
239 dimensions: index.config?.dimensions,
240 // Distilled widened generated string enums to open unions (`string & {}`).
241 metric: index.config?.metric as DistanceMetric | undefined,
242 description: index.description ?? undefined,
243 accountId,
244 createdOn: index.createdOn ?? undefined,
245 modifiedOn: index.modifiedOn ?? undefined,
246 });
247
248 const createIndexName = (id: string, name: string | undefined) =>
249 Effect.gen(function* () {
250 return name ?? (yield* createPhysicalName({ id, lowercase: true }));
251 });
252
253 const buildConfig = (news: IndexProps): vectorize.CreateIndexRequest["config"] =>
254 news.preset !== undefined
255 ? // `Preset` is intentionally open (`| (string & {})`) so
256 // new Cloudflare presets aren't blocked by stale types. The
257 // distilled type is the strict-at-release-time union; cast
258 // through for the API call.
259 ({
260 preset: news.preset as never,
261 } as vectorize.CreateIndexRequest["config"])
262 : {
263 dimensions: news.dimensions!,
264 metric: news.metric ?? DEFAULT_METRIC,
265 };