@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 312 lines 11.5 KB
Raw
1 import * as textract from "@distilled.cloud/aws/textract";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { createInternalTags, diffTags } from "alchemy/Tags";
7 import * as Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
9 import { AWSEnvironment } from "../Environment.ts";
10 import type { Providers } from "../Providers.ts";
11
12 export interface AdapterProps {
13 /**
14 * Name of the adapter — 1-128 characters matching `[a-zA-Z0-9-_]+`. If
15 * omitted, a unique name is generated. The name is updatable in place
16 * (adapter identity is the server-assigned `adapterId`).
17 */
18 adapterName?: string;
19 /**
20 * Description of the adapter, updatable in place. Once set, the Textract
21 * API cannot clear it back to empty — removing this prop leaves the last
22 * description in place.
23 */
24 description?: string;
25 /**
26 * Feature types the adapter enhances. Textract currently supports only
27 * `["QUERIES"]`. Changing this replaces the adapter.
28 */
29 featureTypes: textract.FeatureType[];
30 /**
31 * Whether Textract automatically retrains the adapter as the base model
32 * improves (`ENABLED` or `DISABLED`).
33 * @default "DISABLED"
34 */
35 autoUpdate?: textract.AutoUpdate;
36 /**
37 * Tags to apply to the adapter. Internal alchemy ownership tags are always
38 * added.
39 */
40 tags?: Record<string, string>;
41 }
42
43 export interface Adapter extends Resource<
44 "AWS.Textract.Adapter",
45 AdapterProps,
46 {
47 /**
48 * Server-assigned identifier of the adapter (its identity). Pass it in
49 * `AdaptersConfig` to `AnalyzeDocument` / `StartDocumentAnalysis`.
50 */
51 adapterId: string;
52 /**
53 * ARN of the adapter. Textract uses a nonstandard resource path:
54 * `arn:aws:textract:{region}:{account}:/adapters/{adapterId}`.
55 */
56 adapterArn: string;
57 /**
58 * Name of the adapter.
59 */
60 adapterName: string;
61 /**
62 * Feature types the adapter enhances (currently only `QUERIES`).
63 */
64 featureTypes: string[];
65 /**
66 * Whether the adapter auto-updates as the base model improves.
67 */
68 autoUpdate: string | undefined;
69 /**
70 * Creation time of the adapter as an ISO-8601 string.
71 */
72 creationTime: string | undefined;
73 },
74 never,
75 Providers
76 > {}
77
78 /**
79 * An Amazon Textract adapter — a container for custom, trained adapter
80 * versions that enhance the pre-trained Queries feature for your specific
81 * documents. The adapter itself is cheap metadata (name, feature types,
82 * auto-update, tags); versions are trained separately with
83 * `CreateAdapterVersion` against an annotated dataset.
84 *
85 * ### Managing Adapters
86 * **Example:** Create an adapter for the Queries feature
87 * ```typescript
88 * const adapter = yield* AWS.Textract.Adapter("InvoiceAdapter", {
89 * featureTypes: ["QUERIES"],
90 * description: "Tuned for invoice layouts",
91 * autoUpdate: "ENABLED",
92 * });
93 * ```
94 *
95 * **Example:** Analyze a document with a trained adapter version
96 * ```typescript
97 * const analyzeDocument = yield* AWS.Textract.AnalyzeDocument();
98 * const result = yield* analyzeDocument({
99 * Document: { S3Object: { Bucket: bucketName, Name: "invoice.pdf" } },
100 * FeatureTypes: ["QUERIES"],
101 * QueriesConfig: { Queries: [{ Text: "What is the invoice total?" }] },
102 * AdaptersConfig: {
103 * Adapters: [{ AdapterId: adapter.adapterId, Version: "1" }],
104 * },
105 * });
106 * ```
107 *
108 * @resource
109 */
110 export const Adapter = Resource<Adapter>("AWS.Textract.Adapter");
111
112 const toAttributes = (
113 arn: string,
114 adapter: textract.GetAdapterResponse & { AdapterId: string },
115 ) => ({
116 adapterId: adapter.AdapterId,
117 adapterArn: arn,
118 adapterName: adapter.AdapterName ?? "",
119 featureTypes: [...(adapter.FeatureTypes ?? [])],
120 autoUpdate: adapter.AutoUpdate,
121 creationTime: adapter.CreationTime?.toISOString(),
122 });
123
124 // Textract's adapter management APIs have very low default rates (~1 TPS);
125 // bounded backoff absorbs the short bursts the engine's read/diff/reconcile
126 // sequence emits.
127 const throttleRetry = <A, E extends { readonly _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
128 effect.pipe(
129 Effect.retry({
130 while: (e): boolean =>
131 e._tag === "ProvisionedThroughputExceededException" || e._tag === "ThrottlingException",
132 schedule: Schedule.exponential("1 second"),
133 times: 5,
134 }),
135 );
136
137 const normalizeTags = (
138 tags: { [key: string]: string | undefined } | undefined,
139 ): Record<string, string> =>
140 Object.fromEntries(
141 Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
142 );
143
144 export const AdapterProvider = () =>
145 Provider.effect(
146 Adapter,
147 Effect.gen(function* () {
148 // Adapter names must match [a-zA-Z0-9-_]{1,128}; the engine-generated
149 // physical name (alphanumerics + dashes) already satisfies it.
150 const toName = (id: string, props: AdapterProps) =>
151 props.adapterName
152 ? Effect.succeed(props.adapterName)
153 : createPhysicalName({ id, maxLength: 128 });
154
155 // Confirmed live: Textract adapter ARNs use a nonstandard resource
156 // path with a leading slash — `:/adapters/{adapterId}`.
157 const adapterArn = (adapterId: string) =>
158 Effect.gen(function* () {
159 const { accountId, region } = yield* AWSEnvironment.current;
160 return `arn:aws:textract:${region}:${accountId}:/adapters/${adapterId}`;
161 });
162
163 const getOne = (adapterId: string) =>
164 throttleRetry(textract.getAdapter({ AdapterId: adapterId })).pipe(
165 Effect.map((adapter) => ({ ...adapter, AdapterId: adapterId })),
166 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
167 );
168
169 // Adapter ids are server-assigned, so recovery without persisted
170 // output falls back to a bounded name scan.
171 const findByName = (name: string) =>
172 Effect.gen(function* () {
173 let nextToken: string | undefined;
174 for (let page = 0; page < 25; page++) {
175 const res = yield* throttleRetry(textract.listAdapters({ NextToken: nextToken }));
176 const match = (res.Adapters ?? []).find((a) => a.AdapterName === name);
177 if (match?.AdapterId) return match.AdapterId;
178 nextToken = res.NextToken;
179 if (!nextToken) break;
180 }
181 return undefined;
182 });
183
184 return {
185 stables: ["adapterId", "adapterArn", "creationTime"],
186 diff: Effect.fn(function* ({ olds, news }) {
187 if (!isResolved(news)) return;
188 const oldFeatures = [...(olds?.featureTypes ?? [])].sort();
189 const newFeatures = [...news.featureTypes].sort();
190 if (
191 oldFeatures.length !== newFeatures.length ||
192 oldFeatures.some((f, i) => f !== newFeatures[i])
193 ) {
194 return { action: "replace" } as const;
195 }
196 }),
197 read: Effect.fn(function* ({ id, olds, output }) {
198 const adapterId =
199 output?.adapterId ??
200 (yield* findByName(yield* toName(id, olds ?? { featureTypes: [] })));
201 if (!adapterId) return undefined;
202 const found = yield* getOne(adapterId);
203 if (!found) return undefined;
204 return toAttributes(yield* adapterArn(adapterId), found);
205 }),
206 list: () =>
207 Effect.gen(function* () {
208 const attrs: ReturnType<typeof toAttributes>[] = [];
209 let nextToken: string | undefined;
210 for (let page = 0; page < 25; page++) {
211 const res = yield* throttleRetry(textract.listAdapters({ NextToken: nextToken }));
212 for (const overview of res.Adapters ?? []) {
213 if (overview.AdapterId) {
214 const found = yield* getOne(overview.AdapterId);
215 if (found) {
216 attrs.push(toAttributes(yield* adapterArn(overview.AdapterId), found));
217 }
218 }
219 }
220 nextToken = res.NextToken;
221 if (!nextToken) break;
222 }
223 return attrs;
224 }),
225 reconcile: Effect.fn(function* ({ id, news, output, session }) {
226 const name = yield* toName(id, news);
227 const internalTags = yield* createInternalTags(id);
228 const desiredTags = { ...news.tags, ...internalTags };
229
230 // Observe — cloud state is authoritative; `output` is only a
231 // cached id hint and may be stale.
232 let adapterId = output?.adapterId ?? (yield* findByName(name));
233 let observed = adapterId ? yield* getOne(adapterId) : undefined;
234
235 // Ensure — create when missing; a ConflictException means another
236 // writer won the race, so fall through to the name lookup.
237 if (!observed) {
238 const created = yield* throttleRetry(
239 textract.createAdapter({
240 AdapterName: name,
241 FeatureTypes: news.featureTypes,
242 Description: news.description,
243 AutoUpdate: news.autoUpdate,
244 Tags: desiredTags,
245 }),
246 ).pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
247 adapterId = created?.AdapterId ?? (yield* findByName(name));
248 if (!adapterId) {
249 return yield* Effect.die(
250 new Error(`Textract adapter ${name} was neither created nor found`),
251 );
252 }
253 observed = yield* getOne(adapterId);
254 }
255
256 yield* session.note(adapterId!);
257 const arn = yield* adapterArn(adapterId!);
258
259 // Sync mutable settings — diff observed against desired and apply
260 // only the delta. UpdateAdapter treats omitted fields as unchanged.
261 const update: textract.UpdateAdapterRequest = {
262 AdapterId: adapterId!,
263 };
264 let dirty = false;
265 if (observed?.AdapterName !== name) {
266 update.AdapterName = name;
267 dirty = true;
268 }
269 if (news.description !== undefined && observed?.Description !== news.description) {
270 update.Description = news.description;
271 dirty = true;
272 }
273 if (news.autoUpdate !== undefined && observed?.AutoUpdate !== news.autoUpdate) {
274 update.AutoUpdate = news.autoUpdate;
275 dirty = true;
276 }
277 if (dirty) {
278 yield* throttleRetry(textract.updateAdapter(update));
279 }
280
281 // Sync tags — diff against the OBSERVED cloud tags (adoption may
282 // hand us foreign tags), not olds/output.
283 const { removed, upsert } = diffTags(normalizeTags(observed?.Tags), desiredTags);
284 if (upsert.length > 0) {
285 yield* throttleRetry(
286 textract.tagResource({
287 ResourceARN: arn,
288 Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
289 }),
290 );
291 }
292 if (removed.length > 0) {
293 yield* throttleRetry(
294 textract.untagResource({
295 ResourceARN: arn,
296 TagKeys: removed,
297 }),
298 );
299 }
300
301 const final = yield* getOne(adapterId!);
302 return toAttributes(arn, final ?? { AdapterId: adapterId!, AdapterName: name });
303 }),
304 delete: Effect.fn(function* ({ output }) {
305 // Idempotent — the adapter may already be gone.
306 yield* throttleRetry(textract.deleteAdapter({ AdapterId: output.adapterId })).pipe(
307 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
308 );
309 }),
310 };
311 }),
312 );