import * as textract from "@distilled.cloud/aws/textract";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
export interface AdapterProps {
/**
* Name of the adapter — 1-128 characters matching `[a-zA-Z0-9-_]+`. If
* omitted, a unique name is generated. The name is updatable in place
* (adapter identity is the server-assigned `adapterId`).
*/
adapterName?: string;
/**
* Description of the adapter, updatable in place. Once set, the Textract
* API cannot clear it back to empty — removing this prop leaves the last
* description in place.
*/
description?: string;
/**
* Feature types the adapter enhances. Textract currently supports only
* `["QUERIES"]`. Changing this replaces the adapter.
*/
featureTypes: textract.FeatureType[];
/**
* Whether Textract automatically retrains the adapter as the base model
* improves (`ENABLED` or `DISABLED`).
* @default "DISABLED"
*/
autoUpdate?: textract.AutoUpdate;
/**
* Tags to apply to the adapter. Internal alchemy ownership tags are always
* added.
*/
tags?: Record<string, string>;
}
export interface Adapter extends Resource<
"AWS.Textract.Adapter",
AdapterProps,
{
/**
* Server-assigned identifier of the adapter (its identity). Pass it in
* `AdaptersConfig` to `AnalyzeDocument` / `StartDocumentAnalysis`.
*/
adapterId: string;
/**
* ARN of the adapter. Textract uses a nonstandard resource path:
* `arn:aws:textract:{region}:{account}:/adapters/{adapterId}`.
*/
adapterArn: string;
/**
* Name of the adapter.
*/
adapterName: string;
/**
* Feature types the adapter enhances (currently only `QUERIES`).
*/
featureTypes: string[];
/**
* Whether the adapter auto-updates as the base model improves.
*/
autoUpdate: string | undefined;
/**
* Creation time of the adapter as an ISO-8601 string.
*/
creationTime: string | undefined;
},
never,
Providers
> {}
/**
* An Amazon Textract adapter — a container for custom, trained adapter
* versions that enhance the pre-trained Queries feature for your specific
* documents. The adapter itself is cheap metadata (name, feature types,
* auto-update, tags); versions are trained separately with
* `CreateAdapterVersion` against an annotated dataset.
*
* ### Managing Adapters
* **Example:** Create an adapter for the Queries feature
* ```typescript
* const adapter = yield* AWS.Textract.Adapter("InvoiceAdapter", {
* featureTypes: ["QUERIES"],
* description: "Tuned for invoice layouts",
* autoUpdate: "ENABLED",
* });
* ```
*
* **Example:** Analyze a document with a trained adapter version
* ```typescript
* const analyzeDocument = yield* AWS.Textract.AnalyzeDocument();
* const result = yield* analyzeDocument({
* Document: { S3Object: { Bucket: bucketName, Name: "invoice.pdf" } },
* FeatureTypes: ["QUERIES"],
* QueriesConfig: { Queries: [{ Text: "What is the invoice total?" }] },
* AdaptersConfig: {
* Adapters: [{ AdapterId: adapter.adapterId, Version: "1" }],
* },
* });
* ```
*
* @resource
*/
export const Adapter = Resource<Adapter>("AWS.Textract.Adapter");
const toAttributes = (
arn: string,
adapter: textract.GetAdapterResponse & { AdapterId: string },
) => ({
adapterId: adapter.AdapterId,
adapterArn: arn,
adapterName: adapter.AdapterName ?? "",
featureTypes: [...(adapter.FeatureTypes ?? [])],
autoUpdate: adapter.AutoUpdate,
creationTime: adapter.CreationTime?.toISOString(),
});
// Textract's adapter management APIs have very low default rates (~1 TPS);
// bounded backoff absorbs the short bursts the engine's read/diff/reconcile
// sequence emits.
const throttleRetry = <A, E extends { readonly _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
effect.pipe(
Effect.retry({
while: (e): boolean =>
e._tag === "ProvisionedThroughputExceededException" || e._tag === "ThrottlingException",
schedule: Schedule.exponential("1 second"),
times: 5,
}),
);
const normalizeTags = (
tags: { [key: string]: string | undefined } | undefined,
): Record<string, string> =>
Object.fromEntries(
Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
);
export const AdapterProvider = () =>
Provider.effect(
Adapter,
Effect.gen(function* () {
// Adapter names must match [a-zA-Z0-9-_]{1,128}; the engine-generated
// physical name (alphanumerics + dashes) already satisfies it.
const toName = (id: string, props: AdapterProps) =>
props.adapterName
? Effect.succeed(props.adapterName)
: createPhysicalName({ id, maxLength: 128 });
// Confirmed live: Textract adapter ARNs use a nonstandard resource
// path with a leading slash — `:/adapters/{adapterId}`.
const adapterArn = (adapterId: string) =>
Effect.gen(function* () {
const { accountId, region } = yield* AWSEnvironment.current;
return `arn:aws:textract:${region}:${accountId}:/adapters/${adapterId}`;
});
const getOne = (adapterId: string) =>
throttleRetry(textract.getAdapter({ AdapterId: adapterId })).pipe(
Effect.map((adapter) => ({ ...adapter, AdapterId: adapterId })),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
// Adapter ids are server-assigned, so recovery without persisted
// output falls back to a bounded name scan.
const findByName = (name: string) =>
Effect.gen(function* () {
let nextToken: string | undefined;
for (let page = 0; page < 25; page++) {
const res = yield* throttleRetry(textract.listAdapters({ NextToken: nextToken }));
const match = (res.Adapters ?? []).find((a) => a.AdapterName === name);
if (match?.AdapterId) return match.AdapterId;
nextToken = res.NextToken;
if (!nextToken) break;
}
return undefined;
});
return {
stables: ["adapterId", "adapterArn", "creationTime"],
diff: Effect.fn(function* ({ olds, news }) {
if (!isResolved(news)) return;
const oldFeatures = [...(olds?.featureTypes ?? [])].sort();
const newFeatures = [...news.featureTypes].sort();
if (
oldFeatures.length !== newFeatures.length ||
oldFeatures.some((f, i) => f !== newFeatures[i])
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const adapterId =
output?.adapterId ??
(yield* findByName(yield* toName(id, olds ?? { featureTypes: [] })));
if (!adapterId) return undefined;
const found = yield* getOne(adapterId);
if (!found) return undefined;
return toAttributes(yield* adapterArn(adapterId), found);
}),
list: () =>
Effect.gen(function* () {
const attrs: ReturnType<typeof toAttributes>[] = [];
let nextToken: string | undefined;
for (let page = 0; page < 25; page++) {
const res = yield* throttleRetry(textract.listAdapters({ NextToken: nextToken }));
for (const overview of res.Adapters ?? []) {
if (overview.AdapterId) {
const found = yield* getOne(overview.AdapterId);
if (found) {
attrs.push(toAttributes(yield* adapterArn(overview.AdapterId), found));
}
}
}
nextToken = res.NextToken;
if (!nextToken) break;
}
return attrs;
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = yield* toName(id, news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// Observe — cloud state is authoritative; `output` is only a
// cached id hint and may be stale.
let adapterId = output?.adapterId ?? (yield* findByName(name));
let observed = adapterId ? yield* getOne(adapterId) : undefined;
// Ensure — create when missing; a ConflictException means another
// writer won the race, so fall through to the name lookup.
if (!observed) {
const created = yield* throttleRetry(
textract.createAdapter({
AdapterName: name,
FeatureTypes: news.featureTypes,
Description: news.description,
AutoUpdate: news.autoUpdate,
Tags: desiredTags,
}),
).pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
adapterId = created?.AdapterId ?? (yield* findByName(name));
if (!adapterId) {
return yield* Effect.die(
new Error(`Textract adapter ${name} was neither created nor found`),
);
}
observed = yield* getOne(adapterId);
}
yield* session.note(adapterId!);
const arn = yield* adapterArn(adapterId!);
// Sync mutable settings — diff observed against desired and apply
// only the delta. UpdateAdapter treats omitted fields as unchanged.
const update: textract.UpdateAdapterRequest = {
AdapterId: adapterId!,
};
let dirty = false;
if (observed?.AdapterName !== name) {
update.AdapterName = name;
dirty = true;
}
if (news.description !== undefined && observed?.Description !== news.description) {
update.Description = news.description;
dirty = true;
}
if (news.autoUpdate !== undefined && observed?.AutoUpdate !== news.autoUpdate) {
update.AutoUpdate = news.autoUpdate;
dirty = true;
}
if (dirty) {
yield* throttleRetry(textract.updateAdapter(update));
}
// Sync tags — diff against the OBSERVED cloud tags (adoption may
// hand us foreign tags), not olds/output.
const { removed, upsert } = diffTags(normalizeTags(observed?.Tags), desiredTags);
if (upsert.length > 0) {
yield* throttleRetry(
textract.tagResource({
ResourceARN: arn,
Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
}),
);
}
if (removed.length > 0) {
yield* throttleRetry(
textract.untagResource({
ResourceARN: arn,
TagKeys: removed,
}),
);
}
const final = yield* getOne(adapterId!);
return toAttributes(arn, final ?? { AdapterId: adapterId!, AdapterName: name });
}),
delete: Effect.fn(function* ({ output }) {
// Idempotent — the adapter may already be gone.
yield* throttleRetry(textract.deleteAdapter({ AdapterId: output.adapterId })).pipe(
Effect.catchTag("ResourceNotFoundException", () => Effect.void),
);
}),
};
}),
);