@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, 06:00 UTC

main
ts 343 lines 12.7 KB
Raw
1 import * as bedrock from "@distilled.cloud/aws/bedrock-agent";
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 } from "alchemy/Tags";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11
12 /**
13 * The vector-store and embedding configuration of a knowledge base. Passed
14 * through to the Bedrock API unchanged — see the AWS SDK
15 * `KnowledgeBaseConfiguration` shape. The common case is a `VECTOR` type with
16 * `vectorKnowledgeBaseConfiguration.embeddingModelArn` set.
17 */
18 export type KnowledgeBaseConfiguration = bedrock.KnowledgeBaseConfiguration;
19
20 /**
21 * The backing vector store (OpenSearch Serverless, Pinecone, RDS/pgvector,
22 * S3 Vectors, ...). Passed through to the Bedrock API unchanged — see the AWS
23 * SDK `StorageConfiguration` shape. Omit for a managed vector store.
24 */
25 export type StorageConfiguration = bedrock.StorageConfiguration;
26
27 export interface KnowledgeBaseProps {
28 /**
29 * Name of the knowledge base (1-100 characters). If omitted, a
30 * deterministic physical name is generated from the app, stage, and
31 * logical ID. Changing the name triggers a replacement.
32 */
33 name?: string;
34 /**
35 * A description of the knowledge base.
36 */
37 description?: string;
38 /**
39 * The ARN of an IAM role Bedrock assumes to access the embedding model,
40 * the vector store, and (via data sources) the source data. Must trust
41 * `bedrock.amazonaws.com`.
42 */
43 roleArn: string;
44 /**
45 * The embedding + vector-store type configuration. Changing the type
46 * triggers a replacement.
47 */
48 knowledgeBaseConfiguration: KnowledgeBaseConfiguration;
49 /**
50 * The backing vector store. Omit for a Bedrock-managed store.
51 */
52 storageConfiguration?: StorageConfiguration;
53 /**
54 * Tags to apply to the knowledge base. Merged with internal Alchemy tags.
55 */
56 tags?: Record<string, string>;
57 }
58
59 export interface KnowledgeBase extends Resource<
60 "AWS.Bedrock.KnowledgeBase",
61 KnowledgeBaseProps,
62 {
63 /**
64 * The unique identifier of the knowledge base.
65 */
66 knowledgeBaseId: string;
67 /**
68 * The ARN of the knowledge base.
69 */
70 knowledgeBaseArn: string;
71 /**
72 * Name of the knowledge base.
73 */
74 name: string;
75 /**
76 * The ARN of the execution role the knowledge base assumes to access the
77 * embedding model and vector store.
78 */
79 roleArn: string;
80 }
81 > {}
82
83 /**
84 * An Amazon Bedrock knowledge base — a managed RAG index that embeds source
85 * documents into a vector store for retrieval.
86 *
87 * `KnowledgeBase` owns the index configuration; attach one or more
88 * {@link DataSource}s (e.g. an S3 bucket) to feed it documents, then trigger
89 * ingestion. Query it at runtime with the {@link Retrieve} and
90 * {@link RetrieveAndGenerate} bindings, or attach it to an {@link Agent}.
91 *
92 * The `roleArn` must grant Bedrock access to the embedding model, the vector
93 * store, and the source data. The vector store (`storageConfiguration`) must
94 * already exist — provision an OpenSearch Serverless collection (with a
95 * vector index) or another supported store first.
96 *
97 * ### Creating Knowledge Bases
98 * **Example:** OpenSearch Serverless Backed Knowledge Base
99 * ```typescript
100 * import * as Bedrock from "@alchemy.run/aws/Bedrock";
101 *
102 * const kb = yield* Bedrock.KnowledgeBase("docs", {
103 * roleArn: role.roleArn,
104 * knowledgeBaseConfiguration: {
105 * type: "VECTOR",
106 * vectorKnowledgeBaseConfiguration: {
107 * embeddingModelArn:
108 * "arn:aws:bedrock:us-west-2::foundation-model/amazon.titan-embed-text-v2:0",
109 * },
110 * },
111 * storageConfiguration: {
112 * type: "OPENSEARCH_SERVERLESS",
113 * opensearchServerlessConfiguration: {
114 * collectionArn: collection.arn,
115 * vectorIndexName: "bedrock-index",
116 * fieldMapping: {
117 * vectorField: "bedrock-vector",
118 * textField: "bedrock-text",
119 * metadataField: "bedrock-metadata",
120 * },
121 * },
122 * },
123 * });
124 * ```
125 *
126 * @resource
127 */
128 export const KnowledgeBase = Resource<KnowledgeBase>("AWS.Bedrock.KnowledgeBase");
129
130 /** KB status values indicating an in-flight transition to wait out. */
131 const KB_TRANSIENT = new Set(["CREATING", "UPDATING", "DELETING"]);
132
133 /**
134 * A knowledge base with attached data sources rejects deletion with a
135 * `ConflictException` until they are gone (the engine deletes them first, but
136 * their teardown is eventually consistent). Bounded retry (~60s), wrapped in
137 * an explicitly-typed helper so the `Effect.retry` return type does not widen
138 * the provider layer's requirement to `unknown` (see PATTERNS §7).
139 */
140 const retryWhileConflict = <A, E extends { _tag: string }, R>(
141 self: Effect.Effect<A, E, R>,
142 ): Effect.Effect<A, E, R> =>
143 Effect.retry(self, {
144 while: (e) => e._tag === "ConflictException",
145 schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
146 });
147
148 export const KnowledgeBaseProvider = () =>
149 Provider.effect(
150 KnowledgeBase,
151 Effect.gen(function* () {
152 const createName = Effect.fn(function* (id: string, props: Pick<KnowledgeBaseProps, "name">) {
153 return props.name ?? (yield* createPhysicalName({ id, maxLength: 100 }));
154 });
155
156 const getKbOrUndefined = Effect.fn(function* (knowledgeBaseId: string) {
157 return yield* bedrock.getKnowledgeBase({ knowledgeBaseId }).pipe(
158 Effect.map((r) => r.knowledgeBase),
159 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
160 );
161 });
162
163 const findByName = Effect.fn(function* (name: string) {
164 const pages = yield* bedrock.listKnowledgeBases.pages({}).pipe(Stream.runCollect);
165 return Array.from(pages)
166 .flatMap((page) => page.knowledgeBaseSummaries ?? [])
167 .find((s) => s.name === name)?.knowledgeBaseId;
168 });
169
170 const fetchObservedTags = Effect.fn(function* (resourceArn: string) {
171 return yield* bedrock.listTagsForResource({ resourceArn }).pipe(
172 Effect.map((r) => (r.tags ?? {}) as Record<string, string>),
173 Effect.catchTag("ResourceNotFoundException", () =>
174 Effect.succeed({} as Record<string, string>),
175 ),
176 );
177 });
178
179 const waitForSettled = Effect.fn(function* (knowledgeBaseId: string) {
180 return yield* bedrock.getKnowledgeBase({ knowledgeBaseId }).pipe(
181 Effect.map((r) => r.knowledgeBase),
182 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
183 Effect.repeat({
184 schedule: Schedule.fixed("5 seconds"),
185 until: (kb) => kb === undefined || !KB_TRANSIENT.has(kb.status),
186 times: 60,
187 }),
188 );
189 });
190
191 return KnowledgeBase.Provider.of({
192 stables: ["knowledgeBaseId", "knowledgeBaseArn", "name"],
193
194 list: () =>
195 Effect.gen(function* () {
196 const pages = yield* bedrock.listKnowledgeBases.pages({}).pipe(Stream.runCollect);
197 const summaries = Array.from(pages).flatMap(
198 (page) => page.knowledgeBaseSummaries ?? [],
199 );
200 const results = yield* Effect.forEach(
201 summaries,
202 (s) =>
203 getKbOrUndefined(s.knowledgeBaseId).pipe(
204 Effect.map((kb) =>
205 kb === undefined
206 ? undefined
207 : {
208 knowledgeBaseId: kb.knowledgeBaseId,
209 knowledgeBaseArn: kb.knowledgeBaseArn,
210 name: kb.name,
211 roleArn: kb.roleArn,
212 },
213 ),
214 ),
215 { concurrency: 5 },
216 );
217 return results.filter((r): r is KnowledgeBase["Attributes"] => r !== undefined);
218 }),
219
220 read: Effect.fn(function* ({ id, olds, output }) {
221 const kbId =
222 output?.knowledgeBaseId ??
223 (yield* findByName(
224 output?.name ?? (yield* createName(id, olds ?? ({} as KnowledgeBaseProps))),
225 ));
226 if (kbId === undefined) return undefined;
227 const kb = yield* getKbOrUndefined(kbId);
228 if (kb === undefined || kb.status === "DELETING") return undefined;
229 const attrs = {
230 knowledgeBaseId: kb.knowledgeBaseId,
231 knowledgeBaseArn: kb.knowledgeBaseArn,
232 name: kb.name,
233 roleArn: kb.roleArn,
234 };
235 const tags = yield* fetchObservedTags(kb.knowledgeBaseArn);
236 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
237 }),
238
239 diff: Effect.fn(function* ({ id, news, olds }) {
240 if (!isResolved(news)) return undefined;
241 const oldName = yield* createName(id, olds ?? ({} as KnowledgeBaseProps));
242 const newName = yield* createName(id, news ?? ({} as KnowledgeBaseProps));
243 if (oldName !== newName) {
244 return { action: "replace" } as const;
245 }
246 if (
247 (olds?.knowledgeBaseConfiguration?.type ?? undefined) !==
248 (news?.knowledgeBaseConfiguration?.type ?? undefined)
249 ) {
250 return { action: "replace" } as const;
251 }
252 // description, role, and tags converge via update.
253 }),
254
255 reconcile: Effect.fn(function* ({ id, news = {} as KnowledgeBaseProps, output, session }) {
256 const name = output?.name ?? (yield* createName(id, news));
257 const internalTags = yield* createInternalTags(id);
258 const desiredTags = { ...news.tags, ...internalTags };
259
260 // 1. OBSERVE
261 let kb = output?.knowledgeBaseId
262 ? yield* getKbOrUndefined(output.knowledgeBaseId)
263 : undefined;
264 if (kb === undefined) {
265 const foundId = yield* findByName(name);
266 if (foundId !== undefined) {
267 kb = yield* getKbOrUndefined(foundId);
268 }
269 }
270
271 if (kb === undefined) {
272 // 2. ENSURE
273 const created = yield* bedrock.createKnowledgeBase({
274 name,
275 description: news.description,
276 roleArn: news.roleArn,
277 knowledgeBaseConfiguration: news.knowledgeBaseConfiguration,
278 storageConfiguration: news.storageConfiguration,
279 tags: desiredTags,
280 });
281 kb = created.knowledgeBase;
282 kb = (yield* waitForSettled(kb.knowledgeBaseId)) ?? kb;
283 } else {
284 // 3. SYNC — converge mutable settings.
285 kb = (yield* waitForSettled(kb.knowledgeBaseId)) ?? kb;
286 const drifted =
287 kb.description !== news.description ||
288 kb.roleArn !== news.roleArn ||
289 JSON.stringify(kb.knowledgeBaseConfiguration) !==
290 JSON.stringify(news.knowledgeBaseConfiguration) ||
291 JSON.stringify(kb.storageConfiguration ?? null) !==
292 JSON.stringify(news.storageConfiguration ?? null);
293 if (drifted) {
294 yield* bedrock.updateKnowledgeBase({
295 knowledgeBaseId: kb.knowledgeBaseId,
296 name,
297 description: news.description,
298 roleArn: news.roleArn,
299 knowledgeBaseConfiguration: news.knowledgeBaseConfiguration,
300 storageConfiguration: news.storageConfiguration,
301 });
302 kb = (yield* waitForSettled(kb.knowledgeBaseId)) ?? kb;
303 }
304 }
305
306 const knowledgeBaseId = kb.knowledgeBaseId;
307 const knowledgeBaseArn = kb.knowledgeBaseArn;
308
309 // 3b. SYNC TAGS against observed cloud tags.
310 const observedTags = yield* fetchObservedTags(knowledgeBaseArn);
311 const { upsert, removed } = diffTags(observedTags, desiredTags);
312 if (upsert.length > 0) {
313 yield* bedrock.tagResource({
314 resourceArn: knowledgeBaseArn,
315 tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
316 });
317 }
318 if (removed.length > 0) {
319 yield* bedrock.untagResource({
320 resourceArn: knowledgeBaseArn,
321 tagKeys: removed,
322 });
323 }
324
325 yield* session.note(knowledgeBaseArn);
326 return {
327 knowledgeBaseId,
328 knowledgeBaseArn,
329 name,
330 roleArn: news.roleArn,
331 };
332 }),
333
334 delete: Effect.fn(function* ({ output }) {
335 yield* retryWhileConflict(
336 bedrock.deleteKnowledgeBase({
337 knowledgeBaseId: output.knowledgeBaseId,
338 }),
339 ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
340 }),
341 });
342 }),
343 );