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

main
ts 441 lines 15.2 KB
Raw
1 import * as discoveryengine from "@distilled.cloud/gcp/discoveryengine_v1";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
9 import { GcpEnvironment } from "../Environment.ts";
10 import type { Providers } from "../Providers.ts";
11 import {
12 collectionParent,
13 dataStoreIdOf,
14 DEFAULT_COLLECTION,
15 normalizeCollection,
16 normalizeLocation,
17 parseResourceName,
18 sameJson,
19 sameStringList,
20 toResourceId,
21 } from "./internal.ts";
22 import { waitForOperation } from "./operations.ts";
23
24 export type CollectionsEngineSearchEngineConfig = {
25 /**
26 * Search feature tier. Defaults to `SEARCH_TIER_STANDARD`.
27 */
28 searchTier?: discoveryengine.GoogleCloudDiscoveryengineV1EngineSearchEngineConfigSearchTierEnum;
29 /**
30 * Search add-ons enabled on this engine.
31 */
32 searchAddOns?: discoveryengine.GoogleCloudDiscoveryengineV1EngineSearchEngineConfigSearchAddOnsItemEnumList;
33 /**
34 * Required subscription tier. Immutable after create.
35 */
36 requiredSubscriptionTier?: discoveryengine.GoogleCloudDiscoveryengineV1EngineSearchEngineConfigRequiredSubscriptionTierEnum;
37 };
38
39 export type CollectionsEngineCommonConfig = {
40 /**
41 * Company or entity associated with the engine. Setting this may help
42 * LLM features.
43 */
44 companyName?: string;
45 };
46
47 export type CollectionsEngineProps = {
48 /**
49 * Engine id (the `{engine}` segment of the resource name). If omitted,
50 * a unique RFC-1034 id is generated. Immutable — changing it replaces
51 * the engine.
52 */
53 engineId?: string;
54 /**
55 * Location (`global`, `us`, `eu`, …). Immutable — changing it replaces
56 * the engine.
57 * @default "global"
58 */
59 location?: string;
60 /**
61 * Collection id. Immutable — changing it replaces the engine.
62 * @default "default_collection"
63 */
64 collectionId?: string;
65 /**
66 * User-facing display name.
67 * @default the engine id
68 */
69 displayName?: string;
70 /**
71 * Solution type. Immutable — changing it replaces the engine.
72 * @default "SOLUTION_TYPE_SEARCH"
73 */
74 solutionType?: discoveryengine.GoogleCloudDiscoveryengineV1EngineSolutionTypeEnum;
75 /**
76 * Industry vertical. Must match the linked data store. Immutable.
77 * @default "GENERIC"
78 */
79 industryVertical?: discoveryengine.GoogleCloudDiscoveryengineV1EngineIndustryVerticalEnum;
80 /**
81 * Data store ids to attach. For search and recommendation engines at
82 * most one id is allowed. Values may be ids or full resource names.
83 */
84 dataStoreIds?: string[];
85 /**
86 * Search-engine configuration. Applied when `solutionType` is
87 * `SOLUTION_TYPE_SEARCH`.
88 */
89 searchEngineConfig?: CollectionsEngineSearchEngineConfig;
90 /**
91 * Common metadata (company name).
92 */
93 commonConfig?: CollectionsEngineCommonConfig;
94 /**
95 * Chat-engine configuration. One-time consumed at create.
96 */
97 chatEngineConfig?: discoveryengine.GoogleCloudDiscoveryengineV1EngineChatEngineConfig;
98 /**
99 * Media recommendation configuration.
100 */
101 mediaRecommendationEngineConfig?: discoveryengine.GoogleCloudDiscoveryengineV1EngineMediaRecommendationEngineConfig;
102 /**
103 * Disable analytics for searches on this engine.
104 * @default false
105 */
106 disableAnalytics?: boolean;
107 /**
108 * Application type. Immutable.
109 */
110 appType?: discoveryengine.GoogleCloudDiscoveryengineV1EngineAppTypeEnum;
111 };
112
113 export type CollectionsEngine = Resource<
114 "GCP.DiscoveryEngine.CollectionsEngine",
115 CollectionsEngineProps,
116 {
117 /** Full resource name. */
118 name: string;
119 /** Engine id (last path segment). */
120 engineId: string;
121 /** Project id. */
122 project: string;
123 /** Location id. */
124 location: string;
125 /** Collection id. */
126 collectionId: string;
127 /** Display name. */
128 displayName: string | undefined;
129 /** Solution type. */
130 solutionType: string | undefined;
131 /** Industry vertical. */
132 industryVertical: string | undefined;
133 /** Attached data store ids. */
134 dataStoreIds: string[];
135 /** Whether analytics are disabled. */
136 disableAnalytics: boolean;
137 /** Company name from common config. */
138 companyName: string | undefined;
139 /** RFC3339 creation timestamp. */
140 createTime: string | undefined;
141 /** RFC3339 last-update timestamp. */
142 updateTime: string | undefined;
143 },
144 never,
145 Providers
146 >;
147
148 /**
149 * A Discovery Engine Engine under a collection — serves Search,
150 * Recommendation, or Chat from one or more DataStores.
151 *
152 * Without labels, ownership rests on the deterministic id: `read` reports a
153 * resource it finds without prior state as unowned (adopt it with `--adopt`).
154 * Parent is
155 * `projects/{project}/locations/{location}/collections/{collection}`. Id,
156 * location, collection, solution type, and vertical are immutable; display
157 * name, analytics flag, and common config update in place.
158 *
159 * ### Creating an Engine
160 * **Example:** Search engine over a data store
161 * ```typescript
162 * const store = yield* GCP.DiscoveryEngine.DataStore("Docs", {});
163 * const engine = yield* GCP.DiscoveryEngine.CollectionsEngine("Search", {
164 * dataStoreIds: [store.dataStoreId],
165 * displayName: "docs search",
166 * });
167 * ```
168 *
169 * ### Updating an Engine
170 * **Example:** Rename
171 * ```typescript
172 * // Same logical id as before; only the changed props differ.
173 * const engine = yield* GCP.DiscoveryEngine.CollectionsEngine("Search", {
174 * dataStoreIds: [store.dataStoreId],
175 * displayName: "docs search prod",
176 * });
177 * ```
178 *
179 * @resource
180 * @category DiscoveryEngine
181 */
182 export const CollectionsEngine = Resource<CollectionsEngine>(
183 "GCP.DiscoveryEngine.CollectionsEngine",
184 );
185
186 export class CollectionsEngineNotResolved extends Data.TaggedError(
187 "GCP.DiscoveryEngine.CollectionsEngineNotResolved",
188 )<{
189 resourceName: string;
190 }> {}
191
192 export class CollectionsEngineStillExists extends Data.TaggedError(
193 "GCP.DiscoveryEngine.CollectionsEngineStillExists",
194 )<{
195 resourceName: string;
196 }> {}
197
198 const resourceName = (project: string, location: string, collectionId: string, engineId: string) =>
199 `${collectionParent(project, location, collectionId)}/engines/${engineId}`;
200
201 const solutionOf = (
202 value: discoveryengine.GoogleCloudDiscoveryengineV1EngineSolutionTypeEnum | undefined,
203 ) => value ?? "SOLUTION_TYPE_SEARCH";
204
205 const verticalOf = (
206 value: discoveryengine.GoogleCloudDiscoveryengineV1EngineIndustryVerticalEnum | undefined,
207 ) => value ?? "GENERIC";
208
209 const idsOf = (values: readonly string[] | undefined) => (values ?? []).map(dataStoreIdOf);
210
211 const getByName = (name: string) =>
212 discoveryengine
213 .getProjectsLocationsCollectionsEngines({ name })
214 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
215
216 const toAttrs = (engine: discoveryengine.GoogleCloudDiscoveryengineV1Engine, project: string) => {
217 const name = engine.name ?? "";
218 const parsed = parseResourceName(name, "engines");
219 return {
220 name,
221 engineId: parsed.id,
222 project: parsed.project || project,
223 location: parsed.location,
224 collectionId: parsed.collectionId || DEFAULT_COLLECTION,
225 displayName: engine.displayName,
226 solutionType: engine.solutionType,
227 industryVertical: engine.industryVertical,
228 dataStoreIds: [...(engine.dataStoreIds ?? [])],
229 disableAnalytics: engine.disableAnalytics === true,
230 companyName: engine.commonConfig?.companyName,
231 createTime: engine.createTime,
232 updateTime: engine.updateTime,
233 };
234 };
235
236 const waitUntilExists = (name: string) =>
237 getByName(name).pipe(
238 Effect.flatMap((engine) =>
239 engine
240 ? Effect.succeed(engine)
241 : Effect.fail(new CollectionsEngineNotResolved({ resourceName: name })),
242 ),
243 Effect.retry({
244 while: (error) => error._tag === "GCP.DiscoveryEngine.CollectionsEngineNotResolved",
245 times: 8,
246 schedule: Schedule.spaced("1 second"),
247 }),
248 );
249
250 const waitUntilGone = (name: string) =>
251 getByName(name).pipe(
252 Effect.flatMap((engine) =>
253 engine === undefined
254 ? Effect.void
255 : Effect.fail(new CollectionsEngineStillExists({ resourceName: name })),
256 ),
257 Effect.retry({
258 while: (error) => error._tag === "GCP.DiscoveryEngine.CollectionsEngineStillExists",
259 times: 10,
260 schedule: Schedule.spaced("2 seconds"),
261 }),
262 );
263
264 export const CollectionsEngineProvider = () =>
265 Provider.succeed(CollectionsEngine, {
266 stables: [
267 "name",
268 "engineId",
269 "project",
270 "location",
271 "collectionId",
272 "solutionType",
273 "industryVertical",
274 "createTime",
275 ],
276
277 diff: Effect.fn(function* ({ news, olds, output }) {
278 if (!isResolved(news)) return undefined;
279 const previousId = olds?.engineId ?? output?.engineId;
280 const nextId = news.engineId ?? previousId;
281 const previousLocation = normalizeLocation(olds?.location ?? output?.location);
282 const nextLocation = normalizeLocation(news.location ?? olds?.location ?? output?.location);
283 const previousCollection = normalizeCollection(olds?.collectionId ?? output?.collectionId);
284 const nextCollection = normalizeCollection(
285 news.collectionId ?? olds?.collectionId ?? output?.collectionId,
286 );
287 const previousSolution = solutionOf(
288 olds?.solutionType ?? (output?.solutionType as CollectionsEngineProps["solutionType"]),
289 );
290 const nextSolution = solutionOf(
291 news.solutionType ?? (output?.solutionType as CollectionsEngineProps["solutionType"]),
292 );
293 const previousVertical = verticalOf(
294 olds?.industryVertical ??
295 (output?.industryVertical as CollectionsEngineProps["industryVertical"]),
296 );
297 const nextVertical = verticalOf(
298 news.industryVertical ??
299 (output?.industryVertical as CollectionsEngineProps["industryVertical"]),
300 );
301 const replace =
302 (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
303 previousLocation !== nextLocation ||
304 previousCollection !== nextCollection ||
305 previousSolution !== nextSolution ||
306 previousVertical !== nextVertical;
307 if (!replace) return undefined;
308 return {
309 action: "replace" as const,
310 deleteFirst:
311 previousLocation === nextLocation &&
312 previousCollection === nextCollection &&
313 previousId !== undefined &&
314 nextId === previousId,
315 };
316 }),
317
318 read: Effect.fn(function* ({ id, olds, output }) {
319 const env = yield* GcpEnvironment.current;
320 const engineId = yield* toResourceId(id, olds?.engineId, output?.engineId);
321 const location = normalizeLocation(olds?.location ?? output?.location);
322 const collectionId = normalizeCollection(olds?.collectionId ?? output?.collectionId);
323 const existing = yield* getByName(
324 output?.name ?? resourceName(env.project, location, collectionId, engineId),
325 );
326 if (existing === undefined) return undefined;
327 const attrs = toAttrs(existing, env.project);
328 // No labels field: without prior state it may not be ours.
329 return output !== undefined ? attrs : Unowned(attrs);
330 }),
331
332 reconcile: Effect.fn(function* ({ id, news, output }) {
333 const env = yield* GcpEnvironment.current;
334 const location = normalizeLocation(news.location ?? output?.location);
335 const collectionId = normalizeCollection(news.collectionId ?? output?.collectionId);
336 const engineId = yield* toResourceId(id, news.engineId, output?.engineId);
337 const displayName = news.displayName ?? engineId;
338 const solutionType = solutionOf(news.solutionType);
339 const industryVertical = verticalOf(news.industryVertical);
340 const dataStoreIds = idsOf(news.dataStoreIds ?? output?.dataStoreIds);
341 const parent = collectionParent(env.project, location, collectionId);
342 const fallbackName =
343 output?.name ?? resourceName(env.project, location, collectionId, engineId);
344 const searchEngineConfig =
345 solutionType === "SOLUTION_TYPE_SEARCH"
346 ? (news.searchEngineConfig ?? {})
347 : news.searchEngineConfig;
348 const disableAnalytics = news.disableAnalytics === true;
349
350 let current = yield* getByName(fallbackName);
351
352 if (current === undefined) {
353 const created = yield* discoveryengine
354 .createProjectsLocationsCollectionsEngines({
355 parent,
356 engineId,
357 body: {
358 displayName,
359 solutionType,
360 industryVertical,
361 dataStoreIds,
362 searchEngineConfig,
363 commonConfig: news.commonConfig,
364 chatEngineConfig: news.chatEngineConfig,
365 mediaRecommendationEngineConfig: news.mediaRecommendationEngineConfig,
366 disableAnalytics: disableAnalytics ? true : undefined,
367 appType: news.appType,
368 },
369 })
370 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
371 if (created !== undefined) {
372 yield* waitForOperation(created);
373 }
374 current = yield* waitUntilExists(fallbackName);
375 }
376
377 if (current === undefined) {
378 return yield* new CollectionsEngineNotResolved({ resourceName: fallbackName });
379 }
380
381 const name = current.name ?? fallbackName;
382 const displayNameChanged = (current.displayName ?? "") !== displayName;
383 const analyticsChanged = (current.disableAnalytics === true) !== disableAnalytics;
384 const companyChanged =
385 (current.commonConfig?.companyName ?? "") !== (news.commonConfig?.companyName ?? "");
386 const searchChanged =
387 searchEngineConfig !== undefined &&
388 !sameJson(current.searchEngineConfig, searchEngineConfig);
389 const dataStoresChanged = !sameStringList(current.dataStoreIds, dataStoreIds);
390
391 if (
392 displayNameChanged ||
393 analyticsChanged ||
394 companyChanged ||
395 searchChanged ||
396 dataStoresChanged
397 ) {
398 current = yield* discoveryengine.patchProjectsLocationsCollectionsEngines({
399 name,
400 updateMask: [
401 displayNameChanged ? "display_name" : undefined,
402 analyticsChanged ? "disable_analytics" : undefined,
403 companyChanged ? "common_config" : undefined,
404 searchChanged ? "search_engine_config" : undefined,
405 dataStoresChanged ? "data_store_ids" : undefined,
406 ]
407 .filter((field): field is string => field !== undefined)
408 .join(","),
409 body: {
410 name,
411 displayName,
412 disableAnalytics,
413 commonConfig: news.commonConfig,
414 searchEngineConfig,
415 dataStoreIds,
416 },
417 });
418 }
419
420 return toAttrs(current, env.project);
421 }),
422
423 delete: Effect.fn(function* ({ output }) {
424 const existing = yield* getByName(output.name);
425 if (existing === undefined) return;
426 const operation = yield* discoveryengine
427 .deleteProjectsLocationsCollectionsEngines({ name: output.name })
428 .pipe(
429 Effect.retry({
430 while: (error) => error._tag === "Conflict",
431 times: 8,
432 schedule: Schedule.spaced("2 seconds"),
433 }),
434 Effect.catchTag("NotFound", () => Effect.undefined),
435 );
436 if (operation !== undefined) {
437 yield* waitForOperation(operation, { notFoundOk: true });
438 }
439 yield* waitUntilGone(output.name);
440 }),
441 });