@effect/ai 0.26.0 → 0.27.0

package/src/EmbeddingModel.ts

@@ -0,0 +1,311 @@
+/**
+ * The `EmbeddingModel` module provides vector embeddings for text using AI
+ * models.
+ *
+ * This module enables efficient conversion of text into high-dimensional vector
+ * representations that capture semantic meaning. It supports batching, caching,
+ * and request optimization for production use cases like semantic search,
+ * document similarity, and clustering.
+ *
+ * @example
+ * ```ts
+ * import { EmbeddingModel } from "@effect/ai"
+ * import { Effect } from "effect"
+ *
+ * // Basic embedding usage
+ * const program = Effect.gen(function* () {
+ *   const embedding = yield* EmbeddingModel.EmbeddingModel
+ *
+ *   const vector = yield* embedding.embed("Hello world!")
+ *   console.log(vector) // [0.123, -0.456, 0.789, ...]
+ *
+ *   return vector
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { EmbeddingModel } from "@effect/ai"
+ * import { Effect, Duration } from "effect"
+ *
+ * declare const generateVectorFor: (text: string) => Array<number>
+ *
+ * // Create embedding service with batching and caching
+ * const embeddingService = EmbeddingModel.make({
+ *   embedMany: (texts) => Effect.succeed(
+ *     texts.map((text, index) => ({
+ *       index,
+ *       embeddings: generateVectorFor(text)
+ *     }))
+ *   ),
+ *   maxBatchSize: 50,
+ *   cache: {
+ *     capacity: 1000,
+ *     timeToLive: Duration.minutes(30)
+ *   }
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ */
+import { dataLoader } from "@effect/experimental/RequestResolver"
+import * as Context from "effect/Context"
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import { identity } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Request from "effect/Request"
+import * as RequestResolver from "effect/RequestResolver"
+import * as Schema from "effect/Schema"
+import type * as Types from "effect/Types"
+import * as AiError from "./AiError.js"
+
+/**
+ * The `EmbeddingModel` service tag for dependency injection.
+ *
+ * This tag provides access to vector embedding functionality throughout your application,
+ * enabling conversion of text to high-dimensional vectors for semantic analysis.
+ *
+ * @example
+ * ```ts
+ * import { EmbeddingModel } from "@effect/ai"
+ * import { Effect } from "effect"
+ *
+ * const useEmbeddings = Effect.gen(function* () {
+ *   const embedder = yield* EmbeddingModel
+ *
+ *   const documentVector = yield* embedder.embed("This is a sample document")
+ *   const queryVector = yield* embedder.embed("sample query")
+ *
+ *   const similarity = cosineSimilarity(documentVector, queryVector)
+ *   return similarity
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Context
+ */
+export class EmbeddingModel extends Context.Tag("@effect/ai/EmbeddingModel")<
+  EmbeddingModel,
+  Service
+>() {}
+
+/**
+ * The service interface for vector embedding operations.
+ *
+ * Defines the contract that all embedding model implementations must fulfill.
+ * The service provides text-to-vector conversion functionality.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface Service {
+  /**
+   * Converts a text string into a vector embedding.
+   */
+  readonly embed: (input: string) => Effect.Effect<Array<number>, AiError.AiError>
+  /**
+   * Converts a batch of text strings into a chunk of vector embeddings.
+   */
+  readonly embedMany: (input: ReadonlyArray<string>, options?: {
+    /**
+     * The concurrency level to use while batching requests.
+     */
+    readonly concurrency?: Types.Concurrency | undefined
+  }) => Effect.Effect<Array<Array<number>>, AiError.AiError>
+}
+
+/**
+ * Represents the result of a batch embedding operation.
+ *
+ * Used internally by the batching system to associate embeddings with their
+ * original request positions in the batch.
+ *
+ * @example
+ * ```ts
+ * import { EmbeddingModel } from "@effect/ai"
+ *
+ * const batchResults: EmbeddingModel.Result[] = [
+ *   { index: 0, embeddings: [0.1, 0.2, 0.3] },
+ *   { index: 1, embeddings: [0.4, 0.5, 0.6] },
+ *   { index: 2, embeddings: [0.7, 0.8, 0.9] }
+ * ]
+ *
+ * // Results correspond to input texts at positions 0, 1, 2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface Result {
+  /**
+   * The position index of this result in the original batch request.
+   */
+  readonly index: number
+
+  /**
+   * The vector embedding for the text at this index.
+   */
+  readonly embeddings: Array<number>
+}
+
+class EmbeddingRequest extends Schema.TaggedRequest<EmbeddingRequest>(
+  "@effect/ai/EmbeddingModel/Request"
+)("EmbeddingRequest", {
+  failure: AiError.AiError,
+  success: Schema.mutable(Schema.Array(Schema.Number)),
+  payload: { input: Schema.String }
+}) {}
+
+const makeBatchedResolver = (
+  embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<Result>, AiError.AiError>
+) =>
+  RequestResolver.makeBatched(
+    (requests: ReadonlyArray<EmbeddingRequest>) =>
+      embedMany(requests.map((request) => request.input)).pipe(
+        Effect.flatMap(
+          Effect.forEach(
+            ({ embeddings, index }) => Request.succeed(requests[index], embeddings),
+            { discard: true }
+          )
+        ),
+        Effect.catchAll((error) =>
+          Effect.forEach(
+            requests,
+            (request) => Request.fail(request, error),
+            { discard: true }
+          )
+        )
+      )
+  )
+
+/**
+ * Creates an EmbeddingModel service with batching and caching capabilities.
+ *
+ * This is the primary constructor for creating embedding services. It supports
+ * automatic batching of requests for efficiency and optional caching to reduce
+ * redundant API calls.
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const make = (options: {
+  /**
+   * A method which processes a batch of text inputs and returns embedding
+   * results.
+   */
+  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<Result>, AiError.AiError>
+  /**
+   * Optional maximum number of text inputs to process in one batch.
+   */
+  readonly maxBatchSize?: number
+  /**
+   * Optional configuration to control how batch request results are cached.
+   */
+  readonly cache?: {
+    /**
+     * The capacity of the cache.
+     */
+    readonly capacity: number
+    /**
+     * The time-to-live for items in the cache.
+     */
+    readonly timeToLive: Duration.DurationInput
+  }
+}) =>
+  Effect.gen(function*() {
+    const cache = yield* Option.fromNullable(options.cache).pipe(
+      Effect.flatMap((config) => Request.makeCache(config)),
+      Effect.optionFromOptional
+    )
+
+    const resolver = makeBatchedResolver(options.embedMany).pipe(
+      options.maxBatchSize ? RequestResolver.batchN(options.maxBatchSize) : identity
+    )
+
+    const embed = (input: string) => {
+      const request = Effect.request(new EmbeddingRequest({ input }), resolver)
+      return Option.match(cache, {
+        onNone: () => request,
+        onSome: (cache) =>
+          request.pipe(
+            Effect.withRequestCaching(true),
+            Effect.withRequestCache(cache)
+          )
+      })
+    }
+
+    const embedMany = (inputs: ReadonlyArray<string>, options?: {
+      readonly concurrency?: Types.Concurrency | undefined
+    }) =>
+      Effect.forEach(inputs, embed, {
+        batching: true,
+        concurrency: options?.concurrency
+      })
+
+    return EmbeddingModel.of({
+      embed: (input) =>
+        embed(input).pipe(
+          Effect.withSpan("EmbeddingModel.embed", { captureStackTrace: false })
+        ),
+      embedMany: (inputs) =>
+        embedMany(inputs).pipe(
+          Effect.withSpan("EmbeddingModel.embedMany", { captureStackTrace: false })
+        )
+    })
+  })
+
+/**
+ * Creates an EmbeddingModel service with time-window based batching.
+ *
+ * This constructor creates a service that uses a data loader pattern to batch
+ * embedding requests within a specified time window. This is optimal for
+ * high-throughput scenarios where you want to automatically batch requests that
+ * arrive within a short time period.
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const makeDataLoader = (options: {
+  /**
+   * A method which processes a batch of text inputs and returns embedding
+   * results.
+   */
+  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<Result>, AiError.AiError>
+  /**
+   * The duration between batch requests during which requests are collected and
+   * added to the current batch.
+   */
+  readonly window: Duration.DurationInput
+  /**
+   * Optional maximum number of requests to add to the batch before a batch
+   * request must be sent.
+   */
+  readonly maxBatchSize?: number
+}) =>
+  Effect.gen(function*() {
+    const resolver = makeBatchedResolver(options.embedMany)
+    const resolverDelayed = yield* dataLoader(resolver, {
+      window: options.window,
+      maxBatchSize: options.maxBatchSize
+    })
+
+    function embed(input: string) {
+      return Effect.request(new EmbeddingRequest({ input }), resolverDelayed).pipe(
+        Effect.withSpan("EmbeddingModel.embed", { captureStackTrace: false })
+      )
+    }
+
+    function embedMany(inputs: ReadonlyArray<string>, options?: {
+      readonly concurrency?: Types.Concurrency | undefined
+    }) {
+      return Effect.forEach(inputs, embed, { batching: true, concurrency: options?.concurrency }).pipe(
+        Effect.withSpan("EmbeddingModel.embedMany", { captureStackTrace: false })
+      )
+    }
+
+    return EmbeddingModel.of({
+      embed,
+      embedMany
+    })
+  })

package/src/IdGenerator.ts

@@ -0,0 +1,320 @@
+/**
+ * The `IdGenerator` module provides a pluggable system for generating unique identifiers
+ * for tool calls and other items in the Effect AI SDKs.
+ *
+ * This module offers a flexible and configurable approach to ID generation, supporting
+ * custom alphabets, prefixes, separators, and sizes.
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ * import { Effect, Layer } from "effect"
+ *
+ * // Using the default ID generator
+ * const program = Effect.gen(function* () {
+ *   const idGen = yield* IdGenerator.IdGenerator
+ *   const toolCallId = yield* idGen.generateId()
+ *   console.log(toolCallId) // "id_A7xK9mP2qR5tY8uV"
+ *   return toolCallId
+ * }).pipe(
+ *   Effect.provide(Layer.succeed(
+ *     IdGenerator.IdGenerator,
+ *     IdGenerator.defaultIdGenerator
+ *   ))
+ * )
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ * import { Effect, Layer } from "effect"
+ *
+ * // Creating a custom ID generator for AI tool calls
+ * const customLayer = IdGenerator.layer({
+ *   alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
+ *   prefix: "tool_call",
+ *   separator: "-",
+ *   size: 12
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   const idGen = yield* IdGenerator.IdGenerator
+ *   const id = yield* idGen.generateId()
+ *   console.log(id) // "tool_call-A7XK9MP2QR5T"
+ *   return id
+ * }).pipe(
+ *   Effect.provide(customLayer)
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ */
+import * as Cause from "effect/Cause"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Predicate from "effect/Predicate"
+import * as Random from "effect/Random"
+
+/**
+ * The `IdGenerator` service tag for dependency injection.
+ *
+ * This tag is used to provide and access ID generation functionality throughout
+ * the application. It follows Effect's standard service pattern for type-safe
+ * dependency injection.
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ * import { Effect } from "effect"
+ *
+ * const useIdGenerator = Effect.gen(function* () {
+ *   const idGenerator = yield* IdGenerator.IdGenerator
+ *   const newId = yield* idGenerator.generateId()
+ *   return newId
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class IdGenerator extends Context.Tag("@effect/ai/IdGenerator")<
+  IdGenerator,
+  Service
+>() {}
+
+/**
+ * The service interface for ID generation.
+ *
+ * Defines the contract that all ID generator implementations must fulfill.
+ * The service provides a single method for generating unique identifiers
+ * in an effectful context.
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ * import { Effect } from "effect"
+ *
+ * // Custom implementation
+ * const customService: IdGenerator.Service = {
+ *   generateId: () => Effect.succeed(`custom_${Date.now()}`)
+ * }
+ *
+ * const program = Effect.gen(function* () {
+ *   const id = yield* customService.generateId()
+ *   console.log(id) // "custom_1234567890"
+ *   return id
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface Service {
+  readonly generateId: () => Effect.Effect<string>
+}
+
+/**
+ * Configuration options for creating custom ID generators.
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ *
+ * // Configuration for tool call IDs
+ * const toolCallOptions: IdGenerator.MakeOptions = {
+ *   alphabet: "0123456789ABCDEF",
+ *   prefix: "tool",
+ *   separator: "_",
+ *   size: 8
+ * }
+ *
+ * // This will generate IDs like: "tool_A1B2C3D4"
+ * ```
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface MakeOptions {
+  /**
+   * The character set to use for generating the random portion of IDs.
+   */
+  readonly alphabet: string
+  /**
+   * Optional prefix to prepend to generated IDs.
+   */
+  readonly prefix?: string | undefined
+  /**
+   * Character used to separate the prefix from the random portion.
+   */
+  readonly separator: string
+  /**
+   * Length of the random portion of the generated ID.
+   */
+  readonly size: number
+}
+
+const DEFAULT_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+const DEFAULT_SEPARATOR = "_"
+const DEFAULT_SIZE = 16
+
+const makeGenerator = ({
+  alphabet = DEFAULT_ALPHABET,
+  prefix,
+  separator = DEFAULT_SEPARATOR,
+  size = DEFAULT_SIZE
+}: Partial<MakeOptions>) => {
+  const alphabetLength = alphabet.length
+  return Effect.fnUntraced(function*() {
+    const chars = new Array(size)
+    for (let i = 0; i < size; i++) {
+      chars[i] = alphabet[((yield* Random.next) * alphabetLength) | 0]
+    }
+    const identifier = chars.join("")
+    if (Predicate.isUndefined(prefix)) {
+      return identifier
+    }
+    return `${prefix}${separator}${identifier}`
+  })
+}
+
+/**
+ * Default ID generator service implementation.
+ *
+ * Uses the standard configuration with "id" prefix and generates IDs in the
+ * format "id_XXXXXXXXXXXXXXXX" where X represents random alphanumeric
+ * characters.
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ * import { Effect, Layer } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const id = yield* IdGenerator.defaultIdGenerator.generateId()
+ *   console.log(id) // "id_A7xK9mP2qR5tY8uV"
+ *   return id
+ * })
+ *
+ * // Or provide it as a service
+ * const withDefault = program.pipe(
+ *   Effect.provideService(
+ *     IdGenerator.IdGenerator,
+ *     IdGenerator.defaultIdGenerator
+ *   )
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const defaultIdGenerator: Service = {
+  generateId: makeGenerator({ prefix: "id" })
+}
+
+/**
+ * Creates a custom ID generator service with the specified options.
+ *
+ * Validates the configuration to ensure the separator is not part of the
+ * alphabet, which would cause ambiguity in parsing generated IDs.
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   // Create a generator for AI assistant message IDs
+ *   const messageIdGen = yield* IdGenerator.make({
+ *     alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+ *     prefix: "msg",
+ *     separator: "-",
+ *     size: 10
+ *   })
+ *
+ *   const messageId = yield* messageIdGen.generateId()
+ *   console.log(messageId) // "msg-A7X9K2M5P8"
+ *   return messageId
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ * import { Effect } from "effect"
+ *
+ * // This will fail with IllegalArgumentException
+ * const invalidConfig = IdGenerator.make({
+ *   alphabet: "ABC123",
+ *   prefix: "test",
+ *   separator: "A", // Error: separator is part of alphabet
+ *   size: 8
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   const generator = yield* invalidConfig
+ *   return generator
+ * }).pipe(
+ *   Effect.catchAll(error =>
+ *     Effect.succeed(`Configuration error: ${error.message}`)
+ *   )
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const make = Effect.fnUntraced(function*({
+  alphabet = DEFAULT_ALPHABET,
+  prefix,
+  separator = DEFAULT_SEPARATOR,
+  size = DEFAULT_SIZE
+}: MakeOptions) {
+  if (alphabet.includes(separator)) {
+    const message = `The separator "${separator}" must not be part of the alphabet "${alphabet}".`
+    return yield* new Cause.IllegalArgumentException(message)
+  }
+
+  const generateId = makeGenerator({ alphabet, prefix, separator, size })
+
+  return {
+    generateId
+  } as const
+})
+
+/**
+ * Creates a Layer that provides the IdGenerator service with custom
+ * configuration.
+ *
+ * This is the recommended way to provide ID generation capabilities to your
+ * application. The layer will fail during construction if the configuration is
+ * invalid.
+ *
+ * @example
+ * ```ts
+ * import { IdGenerator } from "@effect/ai"
+ * import { Effect, Layer } from "effect"
+ *
+ * // Create a layer for generating AI tool call IDs
+ * const toolCallIdLayer = IdGenerator.layer({
+ *   alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+ *   prefix: "tool_call",
+ *   separator: "_",
+ *   size: 12
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   const idGen = yield* IdGenerator.IdGenerator
+ *   const toolCallId = yield* idGen.generateId()
+ *   console.log(toolCallId) // "tool_call_A7XK9MP2QR5T"
+ *   return toolCallId
+ * }).pipe(
+ *   Effect.provide(toolCallIdLayer)
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const layer = (options: MakeOptions): Layer.Layer<IdGenerator, Cause.IllegalArgumentException> =>
+  Layer.effect(IdGenerator, make(options))