sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Vectorize/ VectorizeIndex.ts

import * as vectorize from "@distilled.cloud/cloudflare/vectorize";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { isResourceOfType, Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.VectorizeIndex" as const;
type TypeId = typeof TypeId;

export type DistanceMetric = "cosine" | "euclidean" | "dot-product";

export type Preset =
  | "@cf/baai/bge-small-en-v1.5"
  | "@cf/baai/bge-base-en-v1.5"
  | "@cf/baai/bge-large-en-v1.5"
  | "openai/text-embedding-ada-002"
  | "cohere/embed-multilingual-v2.0"
  // Keep the union open so new Cloudflare presets aren't blocked by stale types.
  | (string & {});

const DEFAULT_METRIC: DistanceMetric = "cosine";

export type IndexProps = {
  /**
   * Name of the index. If omitted, a unique name will be generated.
   * Must be lowercase alphanumeric with hyphens. Changing it triggers a
   * replacement.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Number of dimensions for each vector stored in the index. Required
   * unless `preset` is provided. Cannot be changed after creation —
   * updating this property triggers a replacement.
   */
  dimensions?: number;
  /**
   * Distance metric used for similarity search. Cannot be changed after
   * creation — updating this property triggers a replacement.
   * @default "cosine"
   */
  metric?: DistanceMetric;
  /**
   * A managed embedding model preset that fixes `dimensions` and `metric`
   * to match the named model. Mutually exclusive with `dimensions`/`metric`.
   * Cannot be changed after creation — updating this triggers a replacement.
   */
  preset?: Preset;
  /**
   * Human-readable description of the index. Vectorize has no update API,
   * so changing the description triggers a replacement.
   */
  description?: string;
};

export type IndexAttributes = {
  indexName: string;
  dimensions: number | undefined;
  metric: DistanceMetric | undefined;
  description: string | undefined;
  accountId: string;
  createdOn: string | undefined;
  modifiedOn: string | undefined;
};

export type Index = Resource<TypeId, IndexProps, IndexAttributes, never, Providers>;

/**
 * A Cloudflare Vectorize index for storing and querying vector embeddings.
 *
 * Vectorize is a globally distributed vector database. Create an index as a
 * resource, then bind it to a Worker to insert, upsert, and query vectors.
 *
 * A Vectorize index is identified by its name and is immutable: its
 * dimensions, metric, preset, and description are all fixed at creation.
 * Changing any of them triggers a replacement.
 * ### Creating an Index
 * **Example:** Index with explicit dimensions and metric
 * ```typescript
 * const index = yield* Cloudflare.Vectorize.Index("my-index", {
 *   dimensions: 768,
 *   metric: "cosine",
 * });
 * ```
 *
 * **Example:** Index from a managed embedding model preset
 * A preset fixes the dimensions and metric to match the named model.
 * ```typescript
 * const index = yield* Cloudflare.Vectorize.Index("my-index", {
 *   preset: "@cf/baai/bge-base-en-v1.5",
 * });
 * ```
 *
 * **Example:** Index with a description
 * ```typescript
 * const index = yield* Cloudflare.Vectorize.Index("my-index", {
 *   dimensions: 1536,
 *   metric: "euclidean",
 *   description: "Product catalog embeddings",
 * });
 * ```
 *
 * ### Binding to a Worker
 * **Example:** Querying an index inside a Worker
 * ```typescript
 * const index = yield* Cloudflare.Vectorize.SearchIndex(MyIndex);
 *
 * // Insert vectors
 * yield* index.upsert([
 *   { id: "1", values: [0.1, 0.2, 0.3], metadata: { title: "doc" } },
 * ]);
 *
 * // Query the nearest neighbors
 * const matches = yield* index.query([0.1, 0.2, 0.3], { topK: 5 });
 * ```
 *
 * @see https://developers.cloudflare.com/vectorize/
 *
 * @resource
 * @product Vectorize
 * @category AI
 */
export const Index = Resource<Index>(TypeId);

/**
 * Returns true if the given value is a Vectorize Index resource.
 */
export const isIndex = (value: unknown): value is Index => isResourceOfType(value, TypeId);

export const IndexProvider = () =>
  Provider.succeed(Index, {
    stables: ["indexName", "accountId"],
    diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      const oldName = output?.indexName ?? (yield* createIndexName(id, olds.name));
      // Auto-generated names are engine-owned: the deployed name stays
      // authoritative even if the generator would name this id differently
      // today. Only an explicit user-provided name can force a replace.
      const name = news.name ?? oldName;
      if (
        oldName !== name ||
        (news.preset ?? undefined) !== (olds.preset ?? undefined) ||
        (news.dimensions ?? undefined) !== (olds.dimensions ?? undefined) ||
        (news.metric ?? DEFAULT_METRIC) !== (olds.metric ?? DEFAULT_METRIC) ||
        (news.description ?? undefined) !== (olds.description ?? undefined)
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const name = output?.indexName ?? (yield* createIndexName(id, olds?.name));
      return yield* vectorize.getIndex({ accountId: acct, indexName: name }).pipe(
        Effect.map((index) => toAttributes(index, name, acct)),
        Effect.catchTag(["NotFound", "Gone"], () => Effect.undefined),
      );
    }),
    reconcile: Effect.fn(function* ({ id, news = {}, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Prefer the deployed name: regenerating would target a different
      // index if the generator's output for this id ever drifts.
      const indexName = output?.indexName ?? (yield* createIndexName(id, news.name));

      // Observe — read the live index by name. The name is the stable
      // identifier; fall back through a NotFound to the create path so
      // we recover from out-of-band deletes or partial state-persistence.
      let observed = yield* vectorize
        .getIndex({
          accountId,
          indexName,
        })
        .pipe(Effect.catchTag(["NotFound", "Gone"], () => Effect.undefined));

      // Ensure — create if missing. Cloudflare returns 409 Conflict when
      // an index with the same name already exists; tolerate the race by
      // re-reading it.
      if (!observed) {
        observed = yield* vectorize
          .createIndex({
            accountId,
            name: indexName,
            config: buildConfig(news),
            description: news.description,
          })
          .pipe(
            Effect.catchTag("IndexAlreadyExists", () =>
              vectorize.getIndex({ accountId, indexName }),
            ),
          );
      }

      return toAttributes(observed, indexName, accountId);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* vectorize
        .deleteIndex({
          accountId: output.accountId,
          indexName: output.indexName,
        })
        .pipe(Effect.catchTag(["NotFound", "Gone"], () => Effect.void));
    }),
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* vectorize.listIndexes.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .filter(
                (
                  index,
                ): index is (typeof page.result)[number] & {
                  name: string;
                } => index.name != null,
              )
              .map((index) => toAttributes(index, index.name, accountId)),
          ),
        ),
      );
    }),
  });

const toAttributes = (
  index: vectorize.GetIndexResponse | vectorize.CreateIndexResponse,
  name: string,
  accountId: string,
): IndexAttributes => ({
  indexName: index.name ?? name,
  dimensions: index.config?.dimensions,
  // Distilled widened generated string enums to open unions (`string & {}`).
  metric: index.config?.metric as DistanceMetric | undefined,
  description: index.description ?? undefined,
  accountId,
  createdOn: index.createdOn ?? undefined,
  modifiedOn: index.modifiedOn ?? undefined,
});

const createIndexName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });

const buildConfig = (news: IndexProps): vectorize.CreateIndexRequest["config"] =>
  news.preset !== undefined
    ? // `Preset` is intentionally open (`| (string & {})`) so
      // new Cloudflare presets aren't blocked by stale types. The
      // distilled type is the strict-at-release-time union; cast
      // through for the API call.
      ({
        preset: news.preset as never,
      } as vectorize.CreateIndexRequest["config"])
    : {
        dimensions: news.dimensions!,
        metric: news.metric ?? DEFAULT_METRIC,
      };