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

main
ts 345 lines 11.6 KB
Raw
1 import * as aiplatform from "@distilled.cloud/gcp/aiplatform_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 { tagRecord } from "alchemy/Tags";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11 import { GcpEnvironment } from "../Environment.ts";
12 import { hasAlchemyLabels } from "../Labels.ts";
13 import type { Providers } from "../Providers.ts";
14 import { isJobTerminal } from "./internal.ts";
15 import {
16 alchemyIdFilter,
17 createInternalLabels,
18 hasAlchemyPrefix,
19 listLocations,
20 locationOf,
21 lastSegment,
22 normalizeLocation,
23 projectOf,
24 stableJson,
25 toDisplayName,
26 toLabels,
27 userLabels,
28 } from "./names.ts";
29 import { waitForOperation } from "./operations.ts";
30
31 export type HyperparameterTuningJobProps = {
32 /**
33 * Vertex AI location. Immutable — changing it replaces the job.
34 * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
35 */
36 location?: string;
37 /**
38 * Display name (max 128 Unicode characters). Generated from the stack,
39 * stage, and logical id when omitted.
40 */
41 displayName?: string;
42 /**
43 * User labels. Alchemy ownership labels are merged in automatically.
44 */
45 labels?: Record<string, string>;
46 /**
47 * Desired total number of Trials.
48 */
49 maxTrialCount: number;
50 /**
51 * Desired number of Trials to run in parallel.
52 */
53 parallelTrialCount: number;
54 /**
55 * Number of failed Trials before the job fails. `0` lets Vertex decide.
56 */
57 maxFailedTrialCount?: number;
58 /**
59 * Study configuration (metrics and parameters).
60 */
61 studySpec: aiplatform.GoogleCloudAiplatformV1StudySpec;
62 /**
63 * Spec of the CustomJob backing each Trial.
64 */
65 trialJobSpec: aiplatform.GoogleCloudAiplatformV1CustomJobSpec;
66 /**
67 * Customer-managed encryption key. Immutable.
68 */
69 encryptionSpec?: aiplatform.GoogleCloudAiplatformV1EncryptionSpec;
70 };
71
72 export type HyperparameterTuningJob = Resource<
73 "GCP.AIPlatform.HyperparameterTuningJob",
74 HyperparameterTuningJobProps,
75 {
76 /** Full resource name. */
77 name: string;
78 /** Job id (last path segment). */
79 hyperparameterTuningJobId: string;
80 /** Project id. */
81 project: string;
82 /** Location id. */
83 location: string;
84 /** Display name. */
85 displayName: string | undefined;
86 /** User labels (Alchemy ownership labels stripped). */
87 labels: Record<string, string>;
88 /** Job state. */
89 state: string | undefined;
90 /** Desired total trial count. */
91 maxTrialCount: number | undefined;
92 /** Parallel trial count. */
93 parallelTrialCount: number | undefined;
94 /** RFC3339 creation timestamp. */
95 createTime: string | undefined;
96 /** RFC3339 start timestamp. */
97 startTime: string | undefined;
98 /** RFC3339 end timestamp. */
99 endTime: string | undefined;
100 },
101 never,
102 Providers
103 >;
104
105 /**
106 * A Vertex AI HyperparameterTuningJob that runs CustomJobs for each trial.
107 *
108 * The API assigns the job id. There is no update method — changing display
109 * name, labels, trial counts, or specs replaces the job. Delete cancels a
110 * running job first.
111 *
112 * ### Creating a HyperparameterTuningJob
113 * **Example:** Maximize accuracy
114 * ```typescript
115 * const job = yield* GCP.AIPlatform.HyperparameterTuningJob("Tune", {
116 * maxTrialCount: 2,
117 * parallelTrialCount: 1,
118 * studySpec: {
119 * metrics: [{ metricId: "accuracy", goal: "MAXIMIZE" }],
120 * parameters: [{
121 * parameterId: "lr",
122 * doubleValueSpec: { minValue: 0.001, maxValue: 0.1 },
123 * }],
124 * },
125 * trialJobSpec: {
126 * workerPoolSpecs: [{
127 * machineSpec: { machineType: "n1-standard-4" },
128 * replicaCount: "1",
129 * containerSpec: { imageUri: "gcr.io/cloud-aiplatform/training/tf-cpu.2-8:latest" },
130 * }],
131 * },
132 * });
133 * ```
134 *
135 * @resource
136 * @category AIPlatform
137 */
138 export const HyperparameterTuningJob = Resource<HyperparameterTuningJob>(
139 "GCP.AIPlatform.HyperparameterTuningJob",
140 );
141
142 export class HyperparameterTuningJobNotResolved extends Data.TaggedError(
143 "GCP.AIPlatform.HyperparameterTuningJobNotResolved",
144 )<{
145 resourceName: string;
146 }> {}
147
148 export class HyperparameterTuningJobStillExists extends Data.TaggedError(
149 "GCP.AIPlatform.HyperparameterTuningJobStillExists",
150 )<{
151 resourceName: string;
152 }> {}
153
154 const toAttrs = (
155 job: aiplatform.GoogleCloudAiplatformV1HyperparameterTuningJob,
156 project: string,
157 ) => {
158 const name = job.name ?? "";
159 return {
160 name,
161 hyperparameterTuningJobId: lastSegment(name),
162 project: projectOf(name, project),
163 location: locationOf(name),
164 displayName: job.displayName,
165 labels: userLabels(job.labels),
166 state: job.state,
167 maxTrialCount: job.maxTrialCount,
168 parallelTrialCount: job.parallelTrialCount,
169 createTime: job.createTime,
170 startTime: job.startTime,
171 endTime: job.endTime,
172 };
173 };
174
175 const getByName = (name: string) =>
176 aiplatform
177 .getProjectsLocationsHyperparameterTuningJobs({ name })
178 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
179
180 const listPage = (parent: string, filter?: string) =>
181 aiplatform.listProjectsLocationsHyperparameterTuningJobs
182 .pages({ parent, pageSize: 100, filter })
183 .pipe(
184 Stream.runCollect,
185 Effect.map((pages) =>
186 Array.from(pages).flatMap((page) => page.hyperparameterTuningJobs ?? []),
187 ),
188 Effect.catchTag("NotFound", () =>
189 Effect.succeed([] as aiplatform.GoogleCloudAiplatformV1HyperparameterTuningJob[]),
190 ),
191 );
192
193 const findOwned = (project: string, location: string, labels: Record<string, string>) =>
194 listPage(`projects/${project}/locations/${location}`, alchemyIdFilter(labels)).pipe(
195 Effect.map((items) => items.find((item) => hasAlchemyPrefix(item.labels)) ?? undefined),
196 );
197
198 const waitUntilGone = (name: string) =>
199 getByName(name).pipe(
200 Effect.filterOrFail(
201 (job) => job === undefined,
202 () => new HyperparameterTuningJobStillExists({ resourceName: name }),
203 ),
204 Effect.asVoid,
205 Effect.retry({
206 while: (error) => error._tag === "GCP.AIPlatform.HyperparameterTuningJobStillExists",
207 times: 10,
208 schedule: Schedule.spaced("2 seconds"),
209 }),
210 );
211
212 export const HyperparameterTuningJobProvider = () =>
213 Provider.succeed(HyperparameterTuningJob, {
214 stables: ["name", "hyperparameterTuningJobId", "project", "location", "createTime"],
215
216 diff: Effect.fn(function* ({ news, olds, output }) {
217 const env = yield* GcpEnvironment.current;
218 if (!isResolved(news)) return undefined;
219 const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
220 const nextLocation = normalizeLocation(
221 news.location ?? olds?.location ?? output?.location,
222 env.region,
223 );
224 const previousDisplay = olds?.displayName ?? output?.displayName;
225 const displayChanged =
226 news.displayName !== undefined &&
227 previousDisplay !== undefined &&
228 news.displayName !== previousDisplay;
229 const previousMax = olds?.maxTrialCount ?? output?.maxTrialCount;
230 const previousParallel = olds?.parallelTrialCount ?? output?.parallelTrialCount;
231 const specsChanged =
232 (olds !== undefined && stableJson(olds.studySpec) !== stableJson(news.studySpec)) ||
233 (olds !== undefined && stableJson(olds.trialJobSpec) !== stableJson(news.trialJobSpec));
234 if (
235 previousLocation !== nextLocation ||
236 displayChanged ||
237 (previousMax !== undefined && news.maxTrialCount !== previousMax) ||
238 (previousParallel !== undefined && news.parallelTrialCount !== previousParallel) ||
239 specsChanged
240 ) {
241 return { action: "replace" as const, deleteFirst: false };
242 }
243 return undefined;
244 }),
245
246 read: Effect.fn(function* ({ id, olds, output }) {
247 const env = yield* GcpEnvironment.current;
248 const location = normalizeLocation(olds?.location ?? output?.location, env.region);
249 const ownership = yield* createInternalLabels(id);
250 const existing =
251 (output?.name !== undefined ? yield* getByName(output.name) : undefined) ??
252 (yield* findOwned(env.project, location, ownership));
253 if (existing === undefined) return undefined;
254 const attrs = toAttrs(existing, env.project);
255 return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
256 }),
257
258 list: () =>
259 Effect.gen(function* () {
260 const env = yield* GcpEnvironment.current;
261 const pages = yield* Effect.forEach(
262 listLocations(env.region),
263 (location) => listPage(`projects/${env.project}/locations/${location}`),
264 { concurrency: 4 },
265 );
266 return pages
267 .flat()
268 .filter((job) => hasAlchemyPrefix(job.labels))
269 .map((job) => toAttrs(job, env.project));
270 }),
271
272 reconcile: Effect.fn(function* ({ id, news, output }) {
273 const env = yield* GcpEnvironment.current;
274 const location = normalizeLocation(news.location ?? output?.location, env.region);
275 const displayName = yield* toDisplayName(id, news.displayName, output?.displayName);
276 const desiredLabels = {
277 ...toLabels(news.labels),
278 ...(yield* createInternalLabels(id)),
279 };
280
281 let current =
282 (output?.name !== undefined ? yield* getByName(output.name) : undefined) ??
283 (yield* findOwned(env.project, location, desiredLabels));
284
285 if (current === undefined) {
286 const created = yield* aiplatform
287 .createProjectsLocationsHyperparameterTuningJobs({
288 parent: `projects/${env.project}/locations/${location}`,
289 body: {
290 displayName,
291 labels: desiredLabels,
292 maxTrialCount: news.maxTrialCount,
293 parallelTrialCount: news.parallelTrialCount,
294 maxFailedTrialCount: news.maxFailedTrialCount,
295 studySpec: news.studySpec,
296 trialJobSpec: news.trialJobSpec,
297 encryptionSpec: news.encryptionSpec,
298 },
299 })
300 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
301 current = created ?? (yield* findOwned(env.project, location, desiredLabels));
302 }
303
304 if (current === undefined || current.name === undefined) {
305 return yield* new HyperparameterTuningJobNotResolved({
306 resourceName: output?.name ?? `${location}/hyperparameterTuningJobs`,
307 });
308 }
309
310 return toAttrs(current, env.project);
311 }),
312
313 delete: Effect.fn(function* ({ output }) {
314 yield* aiplatform
315 .cancelProjectsLocationsHyperparameterTuningJobs({
316 name: output.name,
317 body: {},
318 })
319 .pipe(Effect.catchTag(["NotFound", "BadRequest", "Conflict"], () => Effect.void));
320 // Running jobs reject deletes; wait for the cancel to land.
321 yield* getByName(output.name).pipe(
322 Effect.repeat({
323 schedule: Schedule.spaced("4 seconds"),
324 until: (job) => job === undefined || isJobTerminal(job.state),
325 times: 45,
326 }),
327 );
328 const operation = yield* aiplatform
329 .deleteProjectsLocationsHyperparameterTuningJobs({
330 name: output.name,
331 })
332 .pipe(
333 Effect.retry({
334 while: (error) => error._tag === "Conflict",
335 times: 8,
336 schedule: Schedule.spaced("2 seconds"),
337 }),
338 Effect.catchTag("NotFound", () => Effect.undefined),
339 );
340 if (operation !== undefined) {
341 yield* waitForOperation(operation, { notFoundOk: true });
342 }
343 yield* waitUntilGone(output.name);
344 }),
345 });