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

main
ts 384 lines 13.5 KB
Raw
1 import * as sagemaker from "@distilled.cloud/aws/sagemaker";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, diffTags, hasAlchemyTags, type Tags } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import * as EffectStream from "effect/Stream";
12 import type { Providers } from "../Providers.ts";
13
14 export class FeatureGroupInvalidProps extends Data.TaggedError("FeatureGroupInvalidProps")<{
15 readonly message: string;
16 readonly cause?: unknown;
17 }> {}
18
19 export class FeatureGroupUnexpectedResponse extends Data.TaggedError(
20 "FeatureGroupUnexpectedResponse",
21 )<{
22 readonly message: string;
23 readonly cause?: unknown;
24 }> {}
25
26 export type FeatureGroupStatus = sagemaker.FeatureGroupStatus;
27
28 export interface FeatureGroupProps {
29 /**
30 * Name of the feature group. Maximum 64 characters, alphanumeric and
31 * hyphens.
32 * @default ${app}-${stage}-${id}
33 */
34 featureGroupName?: string;
35 /**
36 * The name of the feature whose value uniquely identifies a record. Must
37 * be one of the `featureDefinitions`.
38 */
39 recordIdentifierFeatureName: string;
40 /**
41 * The name of the feature that stores each record's event time (an ISO
42 * 8601 string or unix seconds). Must be one of the `featureDefinitions`.
43 */
44 eventTimeFeatureName: string;
45 /**
46 * The schema: every feature's name and type (`String`, `Integral`,
47 * `Fractional`).
48 */
49 featureDefinitions: sagemaker.FeatureDefinition[];
50 /**
51 * Enable the low-latency online store (required for
52 * `GetRecord`/`PutRecord` runtime bindings).
53 */
54 onlineStoreConfig?: sagemaker.OnlineStoreConfig;
55 /**
56 * Replicate writes to an S3-backed offline store (for training). Requires
57 * `roleArn`.
58 */
59 offlineStoreConfig?: sagemaker.OfflineStoreConfig;
60 /**
61 * Provisioned or on-demand read/write throughput for the online store.
62 */
63 throughputConfig?: sagemaker.ThroughputConfig;
64 /**
65 * ARN of the IAM role SageMaker assumes to write the offline store to S3.
66 * Only required when `offlineStoreConfig` is set.
67 */
68 roleArn?: string;
69 /**
70 * A description of the feature group.
71 */
72 description?: string;
73 /**
74 * Tags to associate with the feature group. Merged with internal Alchemy
75 * tags.
76 */
77 tags?: Record<string, string>;
78 }
79
80 export interface FeatureGroup extends Resource<
81 "AWS.SageMaker.FeatureGroup",
82 FeatureGroupProps,
83 {
84 /**
85 * The feature group's name.
86 */
87 featureGroupName: string;
88 /**
89 * ARN of the feature group.
90 */
91 featureGroupArn: string;
92 /**
93 * The record-identifier feature name.
94 */
95 recordIdentifierFeatureName: string;
96 /**
97 * The event-time feature name.
98 */
99 eventTimeFeatureName: string;
100 },
101 never,
102 Providers
103 > {}
104
105 /**
106 * An Amazon SageMaker Feature Store FeatureGroup — a typed, versioned table
107 * of ML features with an optional low-latency online store (for inference
108 * lookups) and an S3-backed offline store (for training).
109 *
110 * With the online store enabled, functions read and write records at runtime
111 * via the `AWS.SageMaker.GetRecord` / `AWS.SageMaker.PutRecord` bindings.
112 * ### Creating Feature Groups
113 * **Example:** Online-Store Feature Group
114 * ```typescript
115 * import * as AWS from "@alchemy.run/aws";
116 *
117 * const features = yield* AWS.SageMaker.FeatureGroup("UserFeatures", {
118 * recordIdentifierFeatureName: "user_id",
119 * eventTimeFeatureName: "event_time",
120 * featureDefinitions: [
121 * { FeatureName: "user_id", FeatureType: "String" },
122 * { FeatureName: "event_time", FeatureType: "String" },
123 * { FeatureName: "clicks", FeatureType: "Integral" },
124 * ],
125 * onlineStoreConfig: { EnableOnlineStore: true },
126 * });
127 * ```
128 *
129 * ### Runtime Access
130 * **Example:** Read and write records from a Lambda function
131 * ```typescript
132 * // init
133 * const putRecord = yield* AWS.SageMaker.PutRecord(features);
134 * const getRecord = yield* AWS.SageMaker.GetRecord(features);
135 *
136 * // runtime
137 * yield* putRecord({
138 * Record: [
139 * { FeatureName: "user_id", ValueAsString: "user-123" },
140 * { FeatureName: "event_time", ValueAsString: new Date().toISOString() },
141 * { FeatureName: "clicks", ValueAsString: "42" },
142 * ],
143 * });
144 * const { Record } = yield* getRecord({
145 * RecordIdentifierValueAsString: "user-123",
146 * });
147 * ```
148 *
149 * @resource
150 */
151 export const FeatureGroup = Resource<FeatureGroup>("AWS.SageMaker.FeatureGroup");
152
153 const createFeatureGroupName = (id: string, props: { featureGroupName?: string | undefined }) =>
154 props.featureGroupName
155 ? Effect.succeed(props.featureGroupName)
156 : createPhysicalName({ id, maxLength: 64 });
157
158 const fetchFeatureGroupTags = Effect.fn(function* (arn: string) {
159 const response = yield* sagemaker
160 .listTags({ ResourceArn: arn })
161 .pipe(Effect.catchTag("AccessDeniedException", () => Effect.undefined));
162 return Object.fromEntries(
163 (response?.Tags ?? []).flatMap((tag) =>
164 tag.Key !== undefined ? [[tag.Key, tag.Value ?? ""]] : [],
165 ),
166 );
167 });
168
169 const describeFeatureGroupOrUndefined = (name: string) =>
170 sagemaker
171 .describeFeatureGroup({ FeatureGroupName: name })
172 .pipe(Effect.catchTag("ResourceNotFound", () => Effect.undefined));
173
174 const toAttrs = (
175 described: sagemaker.DescribeFeatureGroupResponse,
176 ): FeatureGroup["Attributes"] => ({
177 featureGroupName: described.FeatureGroupName,
178 featureGroupArn: described.FeatureGroupArn,
179 recordIdentifierFeatureName: described.RecordIdentifierFeatureName,
180 eventTimeFeatureName: described.EventTimeFeatureName,
181 });
182
183 /**
184 * The feature group is still transitioning toward the awaited state —
185 * retried by the bounded wait schedule.
186 */
187 class FeatureGroupNotReady extends Data.TaggedError("FeatureGroupNotReady")<{
188 readonly featureGroupName: string;
189 readonly status: string | undefined;
190 }> {}
191
192 /**
193 * The feature group's asynchronous creation converged to the terminal
194 * `CreateFailed` status.
195 */
196 export class FeatureGroupCreateFailed extends Data.TaggedError("FeatureGroupCreateFailed")<{
197 readonly featureGroupName: string;
198 readonly message: string | undefined;
199 }> {}
200
201 // Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
202 // lifecycle code leaks `Retry.Return`'s conditional type into declaration
203 // emit and widens the provider layer to `unknown` for every consumer of
204 // `AWS.providers()`.
205 const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
206 self: Effect.Effect<A, E, R>,
207 ): Effect.Effect<A, E, R> =>
208 Effect.retry(self, {
209 while: (e) => e._tag === "FeatureGroupNotReady",
210 // Online-store creation typically converges in well under 2 minutes;
211 // offline-store (Glue) creation can take a few. Poll 5s up to ~5 min.
212 schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(60)]),
213 });
214
215 const waitForFeatureGroup = (name: string, target: "Created" | "Gone") =>
216 retryWhileNotReady(
217 Effect.gen(function* () {
218 const described = yield* describeFeatureGroupOrUndefined(name);
219 if (target === "Gone") {
220 if (described === undefined) return;
221 return yield* new FeatureGroupNotReady({
222 featureGroupName: name,
223 status: described.FeatureGroupStatus,
224 });
225 }
226 if (described?.FeatureGroupStatus === "Created") return;
227 if (
228 described?.FeatureGroupStatus === "CreateFailed" ||
229 described?.FeatureGroupStatus === "DeleteFailed"
230 ) {
231 return yield* new FeatureGroupCreateFailed({
232 featureGroupName: name,
233 message: described.FailureReason,
234 });
235 }
236 return yield* new FeatureGroupNotReady({
237 featureGroupName: name,
238 status: described?.FeatureGroupStatus,
239 });
240 }),
241 );
242
243 export const FeatureGroupProvider = () =>
244 Provider.effect(
245 FeatureGroup,
246 Effect.gen(function* () {
247 return {
248 stables: [
249 "featureGroupName",
250 "featureGroupArn",
251 "recordIdentifierFeatureName",
252 "eventTimeFeatureName",
253 ],
254 list: () =>
255 Effect.gen(function* () {
256 const summaries = yield* sagemaker.listFeatureGroups.pages({}).pipe(
257 EffectStream.runCollect,
258 Effect.map((chunk) =>
259 Array.from(chunk).flatMap((page) => page.FeatureGroupSummaries ?? []),
260 ),
261 );
262 const hydrated = yield* Effect.forEach(
263 summaries.flatMap((s) =>
264 s.FeatureGroupName !== undefined ? [s.FeatureGroupName] : [],
265 ),
266 (name) =>
267 describeFeatureGroupOrUndefined(name).pipe(
268 Effect.map((d) => (d === undefined ? undefined : toAttrs(d))),
269 ),
270 { concurrency: 5 },
271 );
272 return hydrated.filter(
273 (attrs): attrs is FeatureGroup["Attributes"] => attrs !== undefined,
274 );
275 }),
276 read: Effect.fn(function* ({ id, olds, output }) {
277 const name = output?.featureGroupName ?? (yield* createFeatureGroupName(id, olds ?? {}));
278 const described = yield* describeFeatureGroupOrUndefined(name);
279 if (!described || described.FeatureGroupStatus === "Deleting") {
280 return undefined;
281 }
282 const attrs = toAttrs(described);
283 const tags = yield* fetchFeatureGroupTags(attrs.featureGroupArn);
284 return (yield* hasAlchemyTags(id, tags as Tags)) ? attrs : Unowned(attrs);
285 }),
286 diff: Effect.fn(function* ({ id, news, olds }) {
287 if (!isResolved(news)) return;
288 if (olds === undefined) return;
289 // The feature group schema and stores are fixed at creation —
290 // everything except tags replaces.
291 const identity = (props: FeatureGroupProps) => [
292 props.recordIdentifierFeatureName,
293 props.eventTimeFeatureName,
294 props.featureDefinitions,
295 props.onlineStoreConfig,
296 props.offlineStoreConfig,
297 props.throughputConfig,
298 props.roleArn,
299 props.description,
300 ];
301 const oldName = yield* createFeatureGroupName(id, olds);
302 const newName = yield* createFeatureGroupName(id, news);
303 if (
304 oldName !== newName ||
305 JSON.stringify(identity(olds)) !== JSON.stringify(identity(news))
306 ) {
307 return { action: "replace" } as const;
308 }
309 }),
310 reconcile: Effect.fn(function* ({ id, news, output, session }) {
311 if (!news) {
312 return yield* new FeatureGroupInvalidProps({
313 message: "SageMaker FeatureGroup requires props",
314 });
315 }
316 const name = output?.featureGroupName ?? (yield* createFeatureGroupName(id, news));
317 const internalTags = yield* createInternalTags(id);
318 const desiredTags = { ...internalTags, ...news.tags };
319
320 // Observe.
321 let described = yield* describeFeatureGroupOrUndefined(name);
322
323 // Ensure — create if missing; tolerate the already-exists race.
324 if (described === undefined) {
325 yield* sagemaker
326 .createFeatureGroup({
327 FeatureGroupName: name,
328 RecordIdentifierFeatureName: news.recordIdentifierFeatureName,
329 EventTimeFeatureName: news.eventTimeFeatureName,
330 FeatureDefinitions: news.featureDefinitions,
331 OnlineStoreConfig: news.onlineStoreConfig,
332 OfflineStoreConfig: news.offlineStoreConfig,
333 ThroughputConfig: news.throughputConfig,
334 RoleArn: news.roleArn,
335 Description: news.description,
336 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
337 Key,
338 Value,
339 })),
340 })
341 .pipe(Effect.catchTag("ResourceInUse", () => Effect.void));
342 yield* session.note(`Creating feature group ${name}...`);
343 }
344
345 // Converge to Created (creation is asynchronous).
346 yield* waitForFeatureGroup(name, "Created");
347 described = yield* describeFeatureGroupOrUndefined(name);
348 if (described === undefined) {
349 return yield* new FeatureGroupUnexpectedResponse({
350 message: `failed to read reconciled feature group ${name}`,
351 });
352 }
353 const attrs = toAttrs(described);
354
355 // Sync tags — diff against OBSERVED cloud tags.
356 const currentTags = yield* fetchFeatureGroupTags(attrs.featureGroupArn);
357 const { removed, upsert } = diffTags(currentTags, desiredTags);
358 if (removed.length > 0) {
359 yield* sagemaker.deleteTags({
360 ResourceArn: attrs.featureGroupArn,
361 TagKeys: removed,
362 });
363 }
364 if (upsert.length > 0) {
365 yield* sagemaker.addTags({
366 ResourceArn: attrs.featureGroupArn,
367 Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
368 });
369 }
370
371 yield* session.note(attrs.featureGroupArn);
372 return attrs;
373 }),
374 delete: Effect.fn(function* ({ output }) {
375 yield* sagemaker
376 .deleteFeatureGroup({
377 FeatureGroupName: output.featureGroupName,
378 })
379 .pipe(Effect.catchTag("ResourceNotFound", () => Effect.void));
380 yield* waitForFeatureGroup(output.featureGroupName, "Gone");
381 }),
382 };
383 }),
384 );