effect 4.0.0-beta.4 → 4.0.0-beta.41

package/src/unstable/ai/Chat.ts

@@ -53,6 +53,7 @@ import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Ref from "../../Ref.ts"
 import * as Schema from "../../Schema.ts"
+import * as Semaphore from "../../Semaphore.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
 import * as Stream from "../../Stream.ts"
 import type { NoExcessProperties } from "../../Types.ts"
@@ -198,14 +199,43 @@ export interface Service {
    * })
    * ```
    */
-  readonly generateText: <
-    Options extends NoExcessProperties<LanguageModel.GenerateTextOptions<any>, Options>,
-    Tools extends Record<string, Tool.Any> = {}
-  >(options: Options & LanguageModel.GenerateTextOptions<Tools>) => Effect.Effect<
-    LanguageModel.GenerateTextResponse<Tools>,
-    LanguageModel.ExtractError<Options>,
-    LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
-  >
+  readonly generateText: {
+    <Options extends NoExcessProperties<LanguageModel.GenerateTextOptions<{}>, Options>>(
+      options: Options & { readonly toolkit?: undefined } & LanguageModel.GenerateTextOptions<{}>
+    ): Effect.Effect<
+      LanguageModel.GenerateTextResponse<{}>,
+      LanguageModel.ExtractError<Options>,
+      LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
+    >
+    <
+      Tools extends Record<string, Tool.Any>,
+      Options extends NoExcessProperties<
+        LanguageModel.GenerateTextOptions<Tools> & { readonly toolkit: LanguageModel.ToolkitInput<Tools> },
+        Options
+      >
+    >(
+      options: Options & LanguageModel.GenerateTextOptions<Tools> & {
+        readonly toolkit: LanguageModel.ToolkitInput<Tools>
+      }
+    ): Effect.Effect<
+      LanguageModel.GenerateTextResponse<Tools>,
+      LanguageModel.ExtractError<Options>,
+      LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
+    >
+    <
+      Options extends {
+        readonly toolkit: LanguageModel.ToolkitOption<any>
+      } & NoExcessProperties<LanguageModel.GenerateTextOptions<any>, Options>
+    >(
+      options: Options & LanguageModel.GenerateTextOptions<LanguageModel.ExtractTools<Options>> & {
+        readonly toolkit: Options["toolkit"]
+      }
+    ): Effect.Effect<
+      LanguageModel.GenerateTextResponse<LanguageModel.ExtractTools<Options>>,
+      LanguageModel.ExtractError<Options>,
+      LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
+    >
+  }
 
   /**
    * Generate text using a language model with streaming output.
@@ -232,14 +262,43 @@ export interface Service {
    * })
    * ```
    */
-  readonly streamText: <
-    Options extends NoExcessProperties<LanguageModel.GenerateTextOptions<any>, Options>,
-    Tools extends Record<string, Tool.Any> = {}
-  >(options: Options & LanguageModel.GenerateTextOptions<Tools>) => Stream.Stream<
-    Response.StreamPart<Tools>,
-    LanguageModel.ExtractError<Options>,
-    LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
-  >
+  readonly streamText: {
+    <Options extends NoExcessProperties<LanguageModel.GenerateTextOptions<{}>, Options>>(
+      options: Options & { readonly toolkit?: undefined } & LanguageModel.GenerateTextOptions<{}>
+    ): Stream.Stream<
+      Response.StreamPart<{}>,
+      LanguageModel.ExtractError<Options>,
+      LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
+    >
+    <
+      Tools extends Record<string, Tool.Any>,
+      Options extends NoExcessProperties<
+        LanguageModel.GenerateTextOptions<Tools> & { readonly toolkit: LanguageModel.ToolkitInput<Tools> },
+        Options
+      >
+    >(
+      options: Options & LanguageModel.GenerateTextOptions<Tools> & {
+        readonly toolkit: LanguageModel.ToolkitInput<Tools>
+      }
+    ): Stream.Stream<
+      Response.StreamPart<Tools>,
+      LanguageModel.ExtractError<Options>,
+      LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
+    >
+    <
+      Options extends {
+        readonly toolkit: LanguageModel.ToolkitOption<any>
+      } & NoExcessProperties<LanguageModel.GenerateTextOptions<any>, Options>
+    >(
+      options: Options & LanguageModel.GenerateTextOptions<LanguageModel.ExtractTools<Options>> & {
+        readonly toolkit: Options["toolkit"]
+      }
+    ): Stream.Stream<
+      Response.StreamPart<LanguageModel.ExtractTools<Options>>,
+      LanguageModel.ExtractError<Options>,
+      LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
+    >
+  }
 
   /**
    * Generate a structured object using a language model and schema.
@@ -276,11 +335,12 @@ export interface Service {
    */
   readonly generateObject: <
     ObjectEncoded extends Record<string, any>,
-    ObjectSchema extends Schema.Codec<any, ObjectEncoded, any, any>,
-    Options extends NoExcessProperties<LanguageModel.GenerateObjectOptions<any, ObjectSchema>, Options>,
-    Tools extends Record<string, Tool.Any> = {}
-  >(options: Options & LanguageModel.GenerateObjectOptions<Tools, ObjectSchema>) => Effect.Effect<
-    LanguageModel.GenerateObjectResponse<Tools, ObjectSchema["Type"]>,
+    ObjectSchema extends Schema.Encoder<ObjectEncoded, unknown>,
+    Options extends NoExcessProperties<LanguageModel.GenerateObjectOptions<any, ObjectSchema>, Options>
+  >(
+    options: Options & LanguageModel.GenerateObjectOptions<LanguageModel.ExtractTools<Options>, ObjectSchema>
+  ) => Effect.Effect<
+    LanguageModel.GenerateObjectResponse<LanguageModel.ExtractTools<Options>, ObjectSchema["Type"]>,
     LanguageModel.ExtractError<Options>,
     LanguageModel.ExtractServices<Options> | ObjectSchema["DecodingServices"] | LanguageModel.LanguageModel
   >
@@ -295,42 +355,8 @@ const encodeHistoryJson = Schema.encodeUnknownEffect(Schema.fromJsonString(Promp
 // Constructors
 // =============================================================================
 
-/**
- * Creates a new Chat service with empty conversation history.
- *
- * This is the most common way to start a fresh chat session without
- * any initial context or system prompts.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- * import { Chat } from "effect/unstable/ai"
- *
- * const freshChat = Effect.gen(function*() {
- *   const chat = yield* Chat.empty
- *
- *   const response = yield* chat.generateText({
- *     prompt: "Hello! Can you introduce yourself?"
- *   })
- *
- *   console.log(response.content)
- *
- *   return chat
- * })
- * ```
- *
- * @since 4.0.0
- * @category constructors
- */
-export const empty: Effect.Effect<Service> = Effect.gen(function*() {
-  const history = yield* Ref.make(Prompt.empty)
-  const services = yield* Effect.services<never>()
-  const semaphore = yield* Effect.makeSemaphore(1)
-
-  const provideContext = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
-    Effect.updateServices(effect, (existing) => ServiceMap.merge(services, existing))
-  const provideContextStream = <A, E, R>(stream: Stream.Stream<A, E, R>): Stream.Stream<A, E, R> =>
-    Stream.updateServices(stream, (existing) => ServiceMap.merge(services, existing))
+const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
+  const semaphore = Semaphore.makeUnsafe(1)
 
   return Chat.of({
     history,
@@ -367,10 +393,9 @@ export const empty: Effect.Effect<Service> = Effect.gen(function*() {
 
         return response
       },
-      provideContext,
       semaphore.withPermits(1),
       (effect) => Effect.withSpan(effect, "Chat.generateText", { captureStackTrace: false })
-    ),
+    ) as Service["generateText"],
     streamText: Effect.fnUntraced(
       function*(options) {
         let parts = Chunk.empty<Response.AnyPart>()
@@ -396,14 +421,13 @@ export const empty: Effect.Effect<Service> = Effect.gen(function*() {
               semaphore.release(1)
             )
         )).pipe(
-          provideContextStream,
           Stream.withSpan("Chat.streamText", {
             captureStackTrace: false
           })
         )
       },
       Stream.unwrap
-    ),
+    ) as Service["streamText"],
     generateObject: Effect.fnUntraced(
       function*(options) {
         const newPrompt = Prompt.make(options.prompt)
@@ -417,7 +441,6 @@ export const empty: Effect.Effect<Service> = Effect.gen(function*() {
 
         return response
       },
-      provideContext,
       semaphore.withPermits(1),
       (effect, options) =>
         Effect.withSpan(effect, "Chat.generateObject", {
@@ -428,7 +451,36 @@ export const empty: Effect.Effect<Service> = Effect.gen(function*() {
         })
     )
   })
-})
+}
+
+/**
+ * Creates a new Chat service with empty conversation history.
+ *
+ * This is the most common way to start a fresh chat session without
+ * any initial context or system prompts.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Chat } from "effect/unstable/ai"
+ *
+ * const freshChat = Effect.gen(function*() {
+ *   const chat = yield* Chat.empty
+ *
+ *   const response = yield* chat.generateText({
+ *     prompt: "Hello! Can you introduce yourself?"
+ *   })
+ *
+ *   console.log(response.content)
+ *
+ *   return chat
+ * })
+ * ```
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export const empty: Effect.Effect<Service> = Effect.sync(() => makeUnsafe(Ref.makeUnsafe(Prompt.empty)))
 
 /**
  * Creates a new Chat service from an initial prompt.
@@ -488,13 +540,8 @@ export const empty: Effect.Effect<Service> = Effect.gen(function*() {
  * @since 4.0.0
  * @category constructors
  */
-export const fromPrompt = Effect.fnUntraced(
-  function*(prompt: Prompt.RawInput) {
-    const chat = yield* empty
-    yield* Ref.set(chat.history, Prompt.make(prompt))
-    return chat
-  }
-)
+export const fromPrompt = (prompt: Prompt.RawInput) =>
+  Effect.sync(() => makeUnsafe(Ref.makeUnsafe(Prompt.make(prompt))))
 
 /**
  * Creates a Chat service from previously exported chat data.
@@ -533,8 +580,7 @@ export const fromPrompt = Effect.fnUntraced(
  */
 export const fromExport = (data: unknown): Effect.Effect<
   Service,
-  Schema.SchemaError,
-  LanguageModel.LanguageModel
+  Schema.SchemaError
 > => Effect.flatMap(decodeHistory(data), fromPrompt)
 
 /**
@@ -575,8 +621,7 @@ export const fromExport = (data: unknown): Effect.Effect<
  */
 export const fromJson = (data: string): Effect.Effect<
   Service,
-  Schema.SchemaError,
-  LanguageModel.LanguageModel
+  Schema.SchemaError
 > => Effect.flatMap(decodeHistoryJson(data), fromPrompt)
 
 // =============================================================================
@@ -627,7 +672,7 @@ export declare namespace Persistence {
      * the persistence store, a `ChatNotFoundError` will be returned.
      */
     readonly get: (chatId: string, options?: {
-      readonly timeToLive?: Duration.DurationInput | undefined
+      readonly timeToLive?: Duration.Input | undefined
     }) => Effect.Effect<Persisted, ChatNotFoundError | PersistenceError>
 
     /**
@@ -637,7 +682,7 @@ export declare namespace Persistence {
      * returned.
      */
     readonly getOrCreate: (chatId: string, options?: {
-      readonly timeToLive?: Duration.DurationInput | undefined
+      readonly timeToLive?: Duration.Input | undefined
     }) => Effect.Effect<Persisted, AiError.AiError | PersistenceError>
   }
 }
@@ -680,7 +725,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
   const store = yield* persistence.make(options.storeId)
 
   const toPersisted = Effect.fnUntraced(
-    function*(chatId: string, chat: Service, ttl: Duration.DurationInput | undefined) {
+    function*(chatId: string, chat: Service, ttl: Duration.Input | undefined) {
       const idGenerator = yield* Effect.serviceOption(IdGenerator.IdGenerator).pipe(
         Effect.map(Option.getOrElse(() => IdGenerator.defaultIdGenerator))
       )
@@ -712,7 +757,9 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
           yield* Ref.set(chat.history, history)
           // Export the chat history
           const exported = yield* Effect.orDie(chat.export)
-          const timeToLive = Predicate.isNotUndefined(ttl) ? Duration.fromDurationInput(ttl) : undefined
+          const timeToLive = Predicate.isNotUndefined(ttl)
+            ? Option.getOrUndefined(Duration.fromInput(ttl))
+            : undefined
           // Save the chat to the backing store
           yield* store.set(chatId, exported as object, timeToLive)
         }
@@ -727,7 +774,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
           return yield* chat.generateText(options).pipe(
             Effect.ensuring(Effect.orDie(saveChat(history)))
           )
-        }),
+        }) as Service["generateText"],
         generateObject: Effect.fnUntraced(function*(options) {
           const history = yield* Ref.get(chat.history)
           return yield* chat.generateObject(options).pipe(
@@ -740,7 +787,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
             Stream.ensuring(Effect.orDie(saveChat(history)))
           )
           return stream
-        }, Stream.unwrap)
+        }, Stream.unwrap) as Service["streamText"]
       }
 
       return persisted
@@ -748,13 +795,15 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
   )
 
   const createChat = Effect.fnUntraced(
-    function*(chatId: string, ttl: Duration.DurationInput | undefined) {
+    function*(chatId: string, ttl: Duration.Input | undefined) {
       // Create an empty chat
       const chat = yield* empty
       // Export the chat history
       const history = yield* Effect.orDie(chat.export)
       // Save the history for the newly created chat
-      const timeToLive = Predicate.isNotUndefined(ttl) ? Duration.fromDurationInput(ttl) : undefined
+      const timeToLive = Predicate.isNotUndefined(ttl)
+        ? Option.getOrUndefined(Duration.fromInput(ttl))
+        : undefined
       yield* store.set(chatId, history as object, timeToLive)
       // Convert the chat to a persisted chat
       return yield* toPersisted(chatId, chat, ttl)
@@ -762,7 +811,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
   )
 
   const getChat = Effect.fnUntraced(
-    function*(chatId: string, ttl: Duration.DurationInput | undefined) {
+    function*(chatId: string, ttl: Duration.Input | undefined) {
       // Create an empty chat
       const chat = yield* empty
       // Attempt to retrieve the previous history from the store
@@ -783,7 +832,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
 
   const get = Effect.fnUntraced(
     function*(chatId: string, options?: {
-      readonly timeToLive?: Duration.DurationInput | undefined
+      readonly timeToLive?: Duration.Input | undefined
     }) {
       return yield* getChat(chatId, options?.timeToLive)
     },
@@ -795,7 +844,7 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
 
   const getOrCreate = Effect.fnUntraced(
     function*(chatId: string, options?: {
-      readonly timeToLive?: Duration.DurationInput | undefined
+      readonly timeToLive?: Duration.Input | undefined
     }) {
       return yield* getChat(chatId, options?.timeToLive).pipe(
         Effect.catchTag("ChatNotFoundError", () => createChat(chatId, options?.timeToLive))

package/src/unstable/ai/EmbeddingModel.ts

@@ -0,0 +1,209 @@
+/**
+ * The `EmbeddingModel` module provides provider-agnostic text embedding capabilities.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { EmbeddingModel } from "effect/unstable/ai"
+ *
+ * const program = Effect.gen(function*() {
+ *   const model = yield* EmbeddingModel.EmbeddingModel
+ *   return yield* model.embed("hello world")
+ * })
+ * ```
+ *
+ * @since 4.0.0
+ */
+import * as Effect from "../../Effect.ts"
+import * as Exit from "../../Exit.ts"
+import * as Request from "../../Request.ts"
+import * as RequestResolver from "../../RequestResolver.ts"
+import * as Schema from "../../Schema.ts"
+import * as ServiceMap from "../../ServiceMap.ts"
+import * as AiError from "./AiError.ts"
+
+/**
+ * Service tag for embedding model operations.
+ *
+ * @since 4.0.0
+ * @category services
+ */
+export class EmbeddingModel extends ServiceMap.Service<EmbeddingModel, Service>()(
+  "effect/unstable/ai/EmbeddingModel"
+) {}
+
+/**
+ * Service tag that provides the current embedding dimensions.
+ *
+ * @since 4.0.0
+ * @category services
+ */
+export class Dimensions extends ServiceMap.Service<Dimensions, number>()(
+  "effect/unstable/ai/EmbeddingModel/Dimensions"
+) {}
+
+/**
+ * Token usage metadata for embedding operations.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export class EmbeddingUsage extends Schema.Class<EmbeddingUsage>(
+  "effect/ai/EmbeddingModel/EmbeddingUsage"
+)({
+  inputTokens: Schema.UndefinedOr(Schema.Finite)
+}) {}
+
+/**
+ * Response for a single embedding request.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export class EmbedResponse extends Schema.Class<EmbedResponse>(
+  "effect/ai/EmbeddingModel/EmbedResponse"
+)({
+  vector: Schema.Array(Schema.Finite)
+}) {}
+
+/**
+ * Response for multiple embeddings.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export class EmbedManyResponse extends Schema.Class<EmbedManyResponse>(
+  "effect/ai/EmbeddingModel/EmbedManyResponse"
+)({
+  embeddings: Schema.Array(EmbedResponse),
+  usage: EmbeddingUsage
+}) {}
+
+/**
+ * Provider input options for embedding requests.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface ProviderOptions {
+  readonly inputs: ReadonlyArray<string>
+}
+
+/**
+ * Provider response for batch embedding requests.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface ProviderResponse {
+  readonly results: Array<Array<number>>
+  readonly usage: {
+    readonly inputTokens: number | undefined
+  }
+}
+
+/**
+ * Tagged request used by request resolvers for embedding operations.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export class EmbeddingRequest extends Request.TaggedClass("EmbeddingRequest")<
+  { readonly input: string },
+  EmbedResponse,
+  AiError.AiError
+> {}
+
+/**
+ * Service interface for embedding operations.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface Service {
+  readonly resolver: RequestResolver.RequestResolver<EmbeddingRequest>
+  readonly embed: (input: string) => Effect.Effect<EmbedResponse, AiError.AiError>
+  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<EmbedManyResponse, AiError.AiError>
+}
+
+const invalidProviderResponse = (description: string): AiError.AiError =>
+  AiError.make({
+    module: "EmbeddingModel",
+    method: "embedMany",
+    reason: new AiError.InvalidOutputError({ description })
+  })
+
+/**
+ * Creates an EmbeddingModel service from a provider embedMany implementation.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export const make: (params: {
+  readonly embedMany: (options: ProviderOptions) => Effect.Effect<ProviderResponse, AiError.AiError>
+}) => Effect.Effect<Service> = Effect.fnUntraced(function*(params) {
+  const resolver = RequestResolver.make<EmbeddingRequest>((entries) =>
+    Effect.flatMap(
+      params.embedMany({
+        inputs: entries.map((entry) => entry.request.input)
+      }),
+      (response) =>
+        Effect.map(mapProviderResults(entries.length, response.results), (embeddings) => {
+          for (let i = 0; i < entries.length; i++) {
+            entries[i].completeUnsafe(Exit.succeed(embeddings[i]))
+          }
+        })
+    )
+  ).pipe(
+    RequestResolver.withSpan("EmbeddingModel.resolver")
+  )
+
+  return EmbeddingModel.of({
+    resolver,
+    embed: (input) =>
+      Effect.request(new EmbeddingRequest({ input }), resolver).pipe(
+        Effect.withSpan("EmbeddingModel.embed")
+      ),
+    embedMany: (input) =>
+      (input.length === 0
+        ? Effect.succeed(
+          new EmbedManyResponse({
+            embeddings: [],
+            usage: new EmbeddingUsage({ inputTokens: undefined })
+          })
+        )
+        : params.embedMany({ inputs: input }).pipe(
+          Effect.flatMap((response) =>
+            mapProviderResults(input.length, response.results).pipe(
+              Effect.map((embeddings) =>
+                new EmbedManyResponse({
+                  embeddings,
+                  usage: new EmbeddingUsage({
+                    inputTokens: response.usage.inputTokens
+                  })
+                })
+              )
+            )
+          )
+        )).pipe(Effect.withSpan("EmbeddingModel.embedMany"))
+  })
+})
+
+const mapProviderResults = (
+  inputLength: number,
+  results: Array<Array<number>>
+): Effect.Effect<Array<EmbedResponse>, AiError.AiError> => {
+  const embeddings = new Array<EmbedResponse>(inputLength)
+  if (results.length !== inputLength) {
+    return Effect.fail(
+      invalidProviderResponse(
+        `Provider returned ${results.length} embeddings but expected ${inputLength}`
+      )
+    )
+  }
+  for (let i = 0; i < results.length; i++) {
+    const vector = results[i]
+    embeddings[i] = new EmbedResponse({ vector })
+  }
+  return Effect.succeed(embeddings)
+}