sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Bedrock/ KnowledgeBase.ts

import * as bedrock from "@distilled.cloud/aws/bedrock-agent";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";

/**
 * The vector-store and embedding configuration of a knowledge base. Passed
 * through to the Bedrock API unchanged — see the AWS SDK
 * `KnowledgeBaseConfiguration` shape. The common case is a `VECTOR` type with
 * `vectorKnowledgeBaseConfiguration.embeddingModelArn` set.
 */
export type KnowledgeBaseConfiguration = bedrock.KnowledgeBaseConfiguration;

/**
 * The backing vector store (OpenSearch Serverless, Pinecone, RDS/pgvector,
 * S3 Vectors, ...). Passed through to the Bedrock API unchanged — see the AWS
 * SDK `StorageConfiguration` shape. Omit for a managed vector store.
 */
export type StorageConfiguration = bedrock.StorageConfiguration;

export interface KnowledgeBaseProps {
  /**
   * Name of the knowledge base (1-100 characters). If omitted, a
   * deterministic physical name is generated from the app, stage, and
   * logical ID. Changing the name triggers a replacement.
   */
  name?: string;
  /**
   * A description of the knowledge base.
   */
  description?: string;
  /**
   * The ARN of an IAM role Bedrock assumes to access the embedding model,
   * the vector store, and (via data sources) the source data. Must trust
   * `bedrock.amazonaws.com`.
   */
  roleArn: string;
  /**
   * The embedding + vector-store type configuration. Changing the type
   * triggers a replacement.
   */
  knowledgeBaseConfiguration: KnowledgeBaseConfiguration;
  /**
   * The backing vector store. Omit for a Bedrock-managed store.
   */
  storageConfiguration?: StorageConfiguration;
  /**
   * Tags to apply to the knowledge base. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface KnowledgeBase extends Resource<
  "AWS.Bedrock.KnowledgeBase",
  KnowledgeBaseProps,
  {
    /**
     * The unique identifier of the knowledge base.
     */
    knowledgeBaseId: string;
    /**
     * The ARN of the knowledge base.
     */
    knowledgeBaseArn: string;
    /**
     * Name of the knowledge base.
     */
    name: string;
    /**
     * The ARN of the execution role the knowledge base assumes to access the
     * embedding model and vector store.
     */
    roleArn: string;
  }
> {}

/**
 * An Amazon Bedrock knowledge base — a managed RAG index that embeds source
 * documents into a vector store for retrieval.
 *
 * `KnowledgeBase` owns the index configuration; attach one or more
 * {@link DataSource}s (e.g. an S3 bucket) to feed it documents, then trigger
 * ingestion. Query it at runtime with the {@link Retrieve} and
 * {@link RetrieveAndGenerate} bindings, or attach it to an {@link Agent}.
 *
 * The `roleArn` must grant Bedrock access to the embedding model, the vector
 * store, and the source data. The vector store (`storageConfiguration`) must
 * already exist — provision an OpenSearch Serverless collection (with a
 * vector index) or another supported store first.
 *
 * ### Creating Knowledge Bases
 * **Example:** OpenSearch Serverless Backed Knowledge Base
 * ```typescript
 * import * as Bedrock from "@alchemy.run/aws/Bedrock";
 *
 * const kb = yield* Bedrock.KnowledgeBase("docs", {
 *   roleArn: role.roleArn,
 *   knowledgeBaseConfiguration: {
 *     type: "VECTOR",
 *     vectorKnowledgeBaseConfiguration: {
 *       embeddingModelArn:
 *         "arn:aws:bedrock:us-west-2::foundation-model/amazon.titan-embed-text-v2:0",
 *     },
 *   },
 *   storageConfiguration: {
 *     type: "OPENSEARCH_SERVERLESS",
 *     opensearchServerlessConfiguration: {
 *       collectionArn: collection.arn,
 *       vectorIndexName: "bedrock-index",
 *       fieldMapping: {
 *         vectorField: "bedrock-vector",
 *         textField: "bedrock-text",
 *         metadataField: "bedrock-metadata",
 *       },
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const KnowledgeBase = Resource<KnowledgeBase>("AWS.Bedrock.KnowledgeBase");

/** KB status values indicating an in-flight transition to wait out. */
const KB_TRANSIENT = new Set(["CREATING", "UPDATING", "DELETING"]);

/**
 * A knowledge base with attached data sources rejects deletion with a
 * `ConflictException` until they are gone (the engine deletes them first, but
 * their teardown is eventually consistent). Bounded retry (~60s), wrapped in
 * an explicitly-typed helper so the `Effect.retry` return type does not widen
 * the provider layer's requirement to `unknown` (see PATTERNS §7).
 */
const retryWhileConflict = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ConflictException",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
  });

export const KnowledgeBaseProvider = () =>
  Provider.effect(
    KnowledgeBase,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: Pick<KnowledgeBaseProps, "name">) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 100 }));
      });

      const getKbOrUndefined = Effect.fn(function* (knowledgeBaseId: string) {
        return yield* bedrock.getKnowledgeBase({ knowledgeBaseId }).pipe(
          Effect.map((r) => r.knowledgeBase),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );
      });

      const findByName = Effect.fn(function* (name: string) {
        const pages = yield* bedrock.listKnowledgeBases.pages({}).pipe(Stream.runCollect);
        return Array.from(pages)
          .flatMap((page) => page.knowledgeBaseSummaries ?? [])
          .find((s) => s.name === name)?.knowledgeBaseId;
      });

      const fetchObservedTags = Effect.fn(function* (resourceArn: string) {
        return yield* bedrock.listTagsForResource({ resourceArn }).pipe(
          Effect.map((r) => (r.tags ?? {}) as Record<string, string>),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({} as Record<string, string>),
          ),
        );
      });

      const waitForSettled = Effect.fn(function* (knowledgeBaseId: string) {
        return yield* bedrock.getKnowledgeBase({ knowledgeBaseId }).pipe(
          Effect.map((r) => r.knowledgeBase),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
          Effect.repeat({
            schedule: Schedule.fixed("5 seconds"),
            until: (kb) => kb === undefined || !KB_TRANSIENT.has(kb.status),
            times: 60,
          }),
        );
      });

      return KnowledgeBase.Provider.of({
        stables: ["knowledgeBaseId", "knowledgeBaseArn", "name"],

        list: () =>
          Effect.gen(function* () {
            const pages = yield* bedrock.listKnowledgeBases.pages({}).pipe(Stream.runCollect);
            const summaries = Array.from(pages).flatMap(
              (page) => page.knowledgeBaseSummaries ?? [],
            );
            const results = yield* Effect.forEach(
              summaries,
              (s) =>
                getKbOrUndefined(s.knowledgeBaseId).pipe(
                  Effect.map((kb) =>
                    kb === undefined
                      ? undefined
                      : {
                          knowledgeBaseId: kb.knowledgeBaseId,
                          knowledgeBaseArn: kb.knowledgeBaseArn,
                          name: kb.name,
                          roleArn: kb.roleArn,
                        },
                  ),
                ),
              { concurrency: 5 },
            );
            return results.filter((r): r is KnowledgeBase["Attributes"] => r !== undefined);
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const kbId =
            output?.knowledgeBaseId ??
            (yield* findByName(
              output?.name ?? (yield* createName(id, olds ?? ({} as KnowledgeBaseProps))),
            ));
          if (kbId === undefined) return undefined;
          const kb = yield* getKbOrUndefined(kbId);
          if (kb === undefined || kb.status === "DELETING") return undefined;
          const attrs = {
            knowledgeBaseId: kb.knowledgeBaseId,
            knowledgeBaseArn: kb.knowledgeBaseArn,
            name: kb.name,
            roleArn: kb.roleArn,
          };
          const tags = yield* fetchObservedTags(kb.knowledgeBaseArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds ?? ({} as KnowledgeBaseProps));
          const newName = yield* createName(id, news ?? ({} as KnowledgeBaseProps));
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          if (
            (olds?.knowledgeBaseConfiguration?.type ?? undefined) !==
            (news?.knowledgeBaseConfiguration?.type ?? undefined)
          ) {
            return { action: "replace" } as const;
          }
          // description, role, and tags converge via update.
        }),

        reconcile: Effect.fn(function* ({ id, news = {} as KnowledgeBaseProps, output, session }) {
          const name = output?.name ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE
          let kb = output?.knowledgeBaseId
            ? yield* getKbOrUndefined(output.knowledgeBaseId)
            : undefined;
          if (kb === undefined) {
            const foundId = yield* findByName(name);
            if (foundId !== undefined) {
              kb = yield* getKbOrUndefined(foundId);
            }
          }

          if (kb === undefined) {
            // 2. ENSURE
            const created = yield* bedrock.createKnowledgeBase({
              name,
              description: news.description,
              roleArn: news.roleArn,
              knowledgeBaseConfiguration: news.knowledgeBaseConfiguration,
              storageConfiguration: news.storageConfiguration,
              tags: desiredTags,
            });
            kb = created.knowledgeBase;
            kb = (yield* waitForSettled(kb.knowledgeBaseId)) ?? kb;
          } else {
            // 3. SYNC — converge mutable settings.
            kb = (yield* waitForSettled(kb.knowledgeBaseId)) ?? kb;
            const drifted =
              kb.description !== news.description ||
              kb.roleArn !== news.roleArn ||
              JSON.stringify(kb.knowledgeBaseConfiguration) !==
                JSON.stringify(news.knowledgeBaseConfiguration) ||
              JSON.stringify(kb.storageConfiguration ?? null) !==
                JSON.stringify(news.storageConfiguration ?? null);
            if (drifted) {
              yield* bedrock.updateKnowledgeBase({
                knowledgeBaseId: kb.knowledgeBaseId,
                name,
                description: news.description,
                roleArn: news.roleArn,
                knowledgeBaseConfiguration: news.knowledgeBaseConfiguration,
                storageConfiguration: news.storageConfiguration,
              });
              kb = (yield* waitForSettled(kb.knowledgeBaseId)) ?? kb;
            }
          }

          const knowledgeBaseId = kb.knowledgeBaseId;
          const knowledgeBaseArn = kb.knowledgeBaseArn;

          // 3b. SYNC TAGS against observed cloud tags.
          const observedTags = yield* fetchObservedTags(knowledgeBaseArn);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* bedrock.tagResource({
              resourceArn: knowledgeBaseArn,
              tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
            });
          }
          if (removed.length > 0) {
            yield* bedrock.untagResource({
              resourceArn: knowledgeBaseArn,
              tagKeys: removed,
            });
          }

          yield* session.note(knowledgeBaseArn);
          return {
            knowledgeBaseId,
            knowledgeBaseArn,
            name,
            roleArn: news.roleArn,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* retryWhileConflict(
            bedrock.deleteKnowledgeBase({
              knowledgeBaseId: output.knowledgeBaseId,
            }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      });
    }),
  );