@effect/ai 0.14.1 → 0.16.0

package/src/AiChat.ts

@@ -2,264 +2,239 @@
  * @since 1.0.0
  */
 import * as Channel from "effect/Channel"
-import * as Chunk from "effect/Chunk"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import type { ParseError } from "effect/ParseResult"
 import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
-import type { Concurrency } from "effect/Types"
 import type { AiError } from "./AiError.js"
 import * as AiInput from "./AiInput.js"
-import { AiResponse, WithResolved } from "./AiResponse.js"
-import type * as AiToolkit from "./AiToolkit.js"
-import { Completions } from "./Completions.js"
+import * as AiLanguageModel from "./AiLanguageModel.js"
+import * as AiResponse from "./AiResponse.js"
+import type * as AiTool from "./AiTool.js"
 
 /**
  * @since 1.0.0
- * @category tags
+ * @category Context
  */
-export class AiChat extends Effect.Tag("@effect/ai/AiChat")<
+export class AiChat extends Context.Tag("@effect/ai/AiChat")<
   AiChat,
   AiChat.Service
 >() {}
 
 /**
  * @since 1.0.0
- * @category models
+ * @category Models
  */
 export declare namespace AiChat {
   /**
    * @since 1.0.0
-   * @category models
+   * @category Models
    */
   export interface Service {
+    /**
+     * The chat history.
+     */
     readonly history: Effect.Effect<AiInput.AiInput>
+
+    /**
+     * Exports the chat into a structured format.
+     */
     readonly export: Effect.Effect<unknown>
+
+    /**
+     * Exports the chat as a JSON string.
+     */
     readonly exportJson: Effect.Effect<string>
-    readonly send: (input: AiInput.Input) => Effect.Effect<AiResponse, AiError>
-    readonly stream: (input: AiInput.Input) => Stream.Stream<AiResponse, AiError>
-    readonly structured: {
-      <A, I, R>(options: {
-        readonly input: AiInput.Input
-        readonly schema: Completions.StructuredSchema<A, I, R>
-      }): Effect.Effect<A, AiError, R>
-      <A, I, R>(options: {
-        readonly input: AiInput.Input
-        readonly schema: Schema.Schema<A, I, R>
-        readonly toolCallId: string
-      }): Effect.Effect<A, AiError, R>
-    }
-    readonly toolkit: <Tools extends AiToolkit.Tool.AnySchema>(
-      options: {
-        readonly input: AiInput.Input
-        readonly tools: AiToolkit.Handlers<Tools>
-        readonly required?: Tools["_tag"] | boolean | undefined
-        readonly concurrency?: Concurrency | undefined
-      }
+
+    /**
+     * Generate text using a large language model for the specified `prompt`.
+     *
+     * If a `toolkit` is specified, the large language model will additionally
+     * be able to perform tool calls to augment its response.
+     *
+     * Both input and output messages will be added to the chat history.
+     */
+    readonly generateText: <Tools extends AiTool.Any, Options>(
+      options: Options & Omit<AiLanguageModel.GenerateTextOptions<Tools>, "system">
     ) => Effect.Effect<
-      WithResolved<AiToolkit.Tool.Success<Tools>>,
-      AiError | AiToolkit.Tool.Failure<Tools>,
-      AiToolkit.Tool.Context<Tools>
+      AiLanguageModel.ExtractSuccess<Options>,
+      AiLanguageModel.ExtractError<Options>,
+      AiLanguageModel.ExtractContext<Options>
     >
-    readonly toolkitStream: <Tools extends AiToolkit.Tool.AnySchema>(
-      options: {
-        readonly input: AiInput.Input
-        readonly tools: AiToolkit.Handlers<Tools>
-        readonly required?: Tools["_tag"] | boolean | undefined
-        readonly concurrency?: Concurrency | undefined
-      }
+
+    /**
+     * Generate text using a large language model for the specified `prompt`,
+     * streaming output from the model as soon as it is available.
+     *
+     * If a `toolkit` is specified, the large language model will additionally
+     * be able to perform tool calls to augment its response.
+     *
+     * Both input and output messages will be added to the chat history.
+     */
+    readonly streamText: <Tools extends AiTool.Any, Options>(
+      options: Options & Omit<AiLanguageModel.GenerateTextOptions<Tools>, "system">
     ) => Stream.Stream<
-      WithResolved<AiToolkit.Tool.Success<Tools>>,
-      AiError | AiToolkit.Tool.Failure<Tools>,
-      AiToolkit.Tool.Context<Tools>
+      AiLanguageModel.ExtractSuccess<Options>,
+      AiLanguageModel.ExtractError<Options>,
+      AiLanguageModel.ExtractContext<Options>
     >
+
+    /**
+     * Generate a structured object for the specified prompt and schema using a
+     * large language model.
+     *
+     * When using a `Schema` that does not have an `identifier` or `_tag`
+     * property, you must specify a `toolCallId` to properly associate the
+     * output of the model.
+     *
+     * Both input and output messages will be added to the chat history.
+     */
+    readonly generateObject: <A, I, R>(
+      options: Omit<AiLanguageModel.GenerateObjectOptions<A, I, R>, "system">
+    ) => Effect.Effect<AiResponse.WithStructuredOutput<A>, AiError, R>
   }
 }
 
 /**
  * @since 1.0.0
- * @category constructors
+ * @category Constructors
  */
-export const fromInput = Effect.fnUntraced(
-  function*(input: AiInput.Input) {
-    const completions = yield* Completions
-    const history = yield* Ref.make(AiInput.make(input))
-    const semaphore = yield* Effect.makeSemaphore(1)
+export const fromPrompt = Effect.fnUntraced(function*(options: {
+  readonly prompt: AiInput.Raw
+  readonly system?: string
+}) {
+  const languageModel = yield* AiLanguageModel.AiLanguageModel
+  const context = yield* Effect.context<never>()
+  const provideContext = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.mapInputContext(effect, (input) => Context.merge(context, input))
+  const provideContextStream = <A, E, R>(stream: Stream.Stream<A, E, R>): Stream.Stream<A, E, R> =>
+    Stream.mapInputContext(stream, (input) => Context.merge(context, input))
+  const history = yield* Ref.make<AiInput.AiInput>(AiInput.make(options.prompt))
+  const semaphore = yield* Effect.makeSemaphore(1)
+  const system = options.system
 
-    return AiChat.of({
-      history: Ref.get(history),
-      export: Ref.get(history).pipe(
-        Effect.flatMap(Schema.encode(AiInput.Schema)),
-        Effect.orDie
-      ),
-      exportJson: Ref.get(history).pipe(
-        Effect.flatMap(Schema.encode(AiInput.SchemaJson)),
-        Effect.orDie
-      ),
-      send(input) {
-        const newParts = AiInput.make(input)
-        return Ref.get(history).pipe(
-          Effect.flatMap((parts) => {
-            const allParts = Chunk.appendAll(parts, newParts)
-            return completions.create(allParts).pipe(
-              Effect.tap((response) => {
-                const responseParts = AiInput.make(response)
-                return Ref.set(history, Chunk.appendAll(allParts, responseParts))
-              })
-            )
-          }),
-          semaphore.withPermits(1),
-          Effect.withSpan("AiChat.send", {
-            attributes: { input },
-            captureStackTrace: false
-          })
-        )
-      },
-      stream(input) {
-        return Stream.suspend(() => {
-          let combined = AiResponse.empty
-          return Stream.fromChannel(Channel.acquireUseRelease(
-            semaphore.take(1).pipe(
-              Effect.zipRight(Ref.get(history)),
-              Effect.map(Chunk.appendAll(AiInput.make(input)))
-            ),
-            (parts) =>
-              completions.stream(parts).pipe(
-                Stream.map((chunk) => {
-                  combined = combined.concat(chunk)
-                  return chunk
-                }),
-                Stream.toChannel
-              ),
-            (parts) =>
-              Effect.zipRight(
-                Ref.set(history, Chunk.appendAll(parts, AiInput.make(combined))),
-                semaphore.release(1)
-              )
-          ))
-        }).pipe(Stream.withSpan("AiChat.stream", {
-          attributes: { input },
-          captureStackTrace: false
-        }))
-      },
-      structured(options) {
-        const newParts = AiInput.make(options.input)
-        return Ref.get(history).pipe(
-          Effect.flatMap((parts) => {
-            const allParts = Chunk.appendAll(parts, newParts)
-            return completions.structured({
+  return AiChat.of({
+    history: Ref.get(history),
+    export: Ref.get(history).pipe(
+      Effect.flatMap(Schema.encode(AiInput.AiInput)),
+      Effect.orDie
+    ),
+    exportJson: Ref.get(history).pipe(
+      Effect.flatMap(Schema.encode(AiInput.FromJson)),
+      Effect.orDie
+    ),
+    generateText(options) {
+      const newInput = AiInput.make(options.prompt)
+      return Ref.get(history).pipe(
+        Effect.flatMap((oldInput) => {
+          const input = AiInput.concat(oldInput, newInput)
+          return languageModel.generateText({
+            ...options,
+            system,
+            prompt: input
+          }).pipe(
+            Effect.tap((response) => {
+              const modelInput = AiInput.make(response)
+              return Ref.set(history, AiInput.concat(input, modelInput))
+            }),
+            provideContext
+          )
+        }),
+        semaphore.withPermits(1),
+        Effect.withSpan("AiChat.generateText", { captureStackTrace: false })
+      )
+    },
+    streamText(options) {
+      return Stream.suspend(() => {
+        let combined = AiResponse.empty
+        return Stream.fromChannel(Channel.acquireUseRelease(
+          semaphore.take(1).pipe(
+            Effect.zipRight(Ref.get(history)),
+            Effect.map((history) => AiInput.concat(history, AiInput.make(options.prompt)))
+          ),
+          (parts) =>
+            languageModel.streamText({
               ...options,
-              input: allParts
-            } as any).pipe(
-              Effect.flatMap((response) => {
-                const responseParts = AiInput.make(response)
-                return Effect.as(
-                  Ref.set(history, Chunk.appendAll(allParts, responseParts)),
-                  response.unsafeValue
-                )
-              })
-            )
-          }),
-          semaphore.withPermits(1),
-          Effect.withSpan("AiChat.structured", {
-            attributes: {
-              input: options.input,
-              schema: "toolCallId" in options
-                ? options.toolCallId
-                : "_tag" in options.schema
-                ? options.schema._tag
-                : options.schema.identifier
-            },
-            captureStackTrace: false
-          })
-        )
-      },
-      toolkit(options) {
-        const newParts = AiInput.make(options.input)
-        return Ref.get(history).pipe(
-          Effect.flatMap((parts) => {
-            const allParts = Chunk.appendAll(parts, newParts)
-            return completions.toolkit({
-              ...options,
-              input: allParts
+              system,
+              prompt: parts
             }).pipe(
-              Effect.tap((response) => {
-                const responseParts = AiInput.make(response)
-                return Ref.set(history, Chunk.appendAll(allParts, responseParts))
-              })
-            )
-          }),
-          semaphore.withPermits(1),
-          Effect.withSpan("AiChat.toolkit", {
-            attributes: { input: options.input },
-            captureStackTrace: false
-          })
-        )
-      },
-      toolkitStream<Tools extends AiToolkit.Tool.AnySchema>(options: {
-        readonly input: AiInput.Input
-        readonly tools: AiToolkit.Handlers<Tools>
-        readonly required?: Tools["_tag"] | boolean | undefined
-        readonly concurrency?: Concurrency | undefined
-      }): Stream.Stream<
-        WithResolved<AiToolkit.Tool.Success<Tools>>,
-        AiError | AiToolkit.Tool.Failure<Tools>,
-        AiToolkit.Tool.Context<Tools>
-      > {
-        return Stream.suspend(() => {
-          let combined = WithResolved.empty as WithResolved<AiToolkit.Tool.Success<Tools>>
-          return Stream.fromChannel(Channel.acquireUseRelease(
-            semaphore.take(1).pipe(
-              Effect.zipRight(Ref.get(history)),
-              Effect.map(Chunk.appendAll(AiInput.make(options.input)))
+              Stream.map((chunk) => {
+                combined = AiResponse.merge(combined, chunk)
+                return chunk
+              }),
+              Stream.toChannel
             ),
-            (parts) =>
-              completions.toolkitStream({
-                ...options,
-                input: parts
-              }).pipe(
-                Stream.map((chunk) => {
-                  combined = combined.concat(chunk)
-                  return chunk
-                }),
-                Stream.toChannel
-              ),
-            (parts) =>
-              Effect.zipRight(
-                Ref.set(history, Chunk.appendAll(parts, AiInput.make(combined))),
-                semaphore.release(1)
+          (parts) =>
+            Effect.zipRight(
+              Ref.set(history, AiInput.concat(parts, AiInput.make(combined))),
+              semaphore.release(1)
+            )
+        ))
+      }).pipe(
+        provideContextStream,
+        Stream.withSpan("AiChat.streamText", {
+          captureStackTrace: false
+        })
+      ) as any
+    },
+    generateObject(options) {
+      const newInput = AiInput.make(options.prompt)
+      return Ref.get(history).pipe(
+        Effect.flatMap((oldInput) => {
+          const input = AiInput.concat(oldInput, newInput)
+          return languageModel.generateObject({
+            ...options,
+            system,
+            prompt: input
+          } as any).pipe(
+            Effect.flatMap((response) => {
+              const modelInput = AiInput.make(response)
+              return Effect.as(
+                Ref.set(history, AiInput.concat(input, modelInput)),
+                response
               )
-          ))
-        }).pipe(Stream.withSpan("AiChat.toolkitStream", {
-          attributes: { input: options.input },
+            })
+          )
+        }),
+        provideContext,
+        semaphore.withPermits(1),
+        Effect.withSpan("AiChat.generateObject", {
+          attributes: {
+            toolCallId: "toolCallId" in options
+              ? options.toolCallId
+              : "_tag" in options.schema
+              ? options.schema._tag
+              : (options.schema as any).identifier ?? "generateObject"
+          },
           captureStackTrace: false
-        }))
-      }
-    })
-  }
-)
+        })
+      ) as any
+    }
+  })
+})
 
 /**
  * @since 1.0.0
- * @category constructors
+ * @category Constructors
  */
-export const empty: Effect.Effect<AiChat.Service, never, Completions> = fromInput(AiInput.empty)
+export const empty: Effect.Effect<AiChat.Service, never, AiLanguageModel.AiLanguageModel> = fromPrompt({ prompt: [] })
+
+const decodeUnknown = Schema.decodeUnknown(AiInput.AiInput)
 
 /**
  * @since 1.0.0
- * @category constructors
+ * @category Constructors
  */
-export const fromExport = (data: unknown): Effect.Effect<AiChat.Service, ParseError, Completions> =>
-  Schema.decodeUnknown(AiInput.Schema)(data).pipe(
-    Effect.flatMap(fromInput)
-  )
+export const fromExport = (data: unknown): Effect.Effect<AiChat.Service, ParseError, AiLanguageModel.AiLanguageModel> =>
+  Effect.flatMap(decodeUnknown(data), (prompt) => fromPrompt({ prompt }))
+
+const decodeJson = Schema.decode(AiInput.FromJson)
 
 /**
  * @since 1.0.0
- * @category constructors
+ * @category Constructors
  */
-export const fromJson = (data: string): Effect.Effect<AiChat.Service, ParseError, Completions> =>
-  Schema.decode(AiInput.SchemaJson)(data).pipe(
-    Effect.flatMap(fromInput)
-  )
+export const fromJson = (data: string): Effect.Effect<AiChat.Service, ParseError, AiLanguageModel.AiLanguageModel> =>
+  Effect.flatMap(decodeJson(data), (prompt) => fromPrompt({ prompt }))

package/src/{Embeddings.ts → AiEmbeddingModel.ts}

@@ -14,21 +14,20 @@ import { AiError } from "./AiError.js"
 
 /**
  * @since 1.0.0
- * @category tags
+ * @category Context
  */
-export class Embeddings extends Context.Tag("@effect/ai/Embeddings")<
-  Embeddings,
-  Embeddings.Service
+export class AiEmbeddingModel extends Context.Tag("@effect/ai/AiEmbeddingModel")<
+  AiEmbeddingModel,
+  AiEmbeddingModel.Service
 >() {}
 
 /**
  * @since 1.0.0
- * @category models
  */
-export declare namespace Embeddings {
+export declare namespace AiEmbeddingModel {
   /**
    * @since 1.0.0
-   * @category models
+   * @category Models
    */
   export interface Service {
     readonly embed: (input: string) => Effect.Effect<Array<number>, AiError>
@@ -36,7 +35,7 @@ export declare namespace Embeddings {
 
   /**
    * @since 1.0.0
-   * @category models
+   * @category Models
    */
   export interface Result {
     readonly index: number
@@ -44,14 +43,16 @@ export declare namespace Embeddings {
   }
 }
 
-class EmbeddingRequest extends Schema.TaggedRequest<EmbeddingRequest>()("EmbeddingRequest", {
+class EmbeddingRequest extends Schema.TaggedRequest<EmbeddingRequest>(
+  "@effect/ai/AiEmbeddingModel/Request"
+)("EmbeddingRequest", {
   failure: AiError,
   success: Schema.mutable(Schema.Array(Schema.Number)),
   payload: { input: Schema.String }
 }) {}
 
 const makeBatchedResolver = (
-  embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<Embeddings.Result>, AiError>
+  embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<AiEmbeddingModel.Result>, AiError>
 ) =>
   RequestResolver.makeBatched(
     (requests: ReadonlyArray<EmbeddingRequest>) =>
@@ -74,10 +75,10 @@ const makeBatchedResolver = (
 
 /**
  * @since 1.0.0
- * @category constructors
+ * @category Constructors
  */
 export const make = (options: {
-  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<Embeddings.Result>, AiError>
+  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<AiEmbeddingModel.Result>, AiError>
   readonly maxBatchSize?: number
   readonly cache?: {
     readonly capacity: number
@@ -103,10 +104,10 @@ export const make = (options: {
             Effect.withRequestCaching(true),
             Effect.withRequestCache(cache)
           )
-      }).pipe(Effect.withSpan("Embeddings.embed", { captureStackTrace: false }))
+      }).pipe(Effect.withSpan("AiEmbeddingModel.embed", { captureStackTrace: false }))
     }
 
-    return Embeddings.of({
+    return AiEmbeddingModel.of({
       embed
     })
   })
@@ -117,10 +118,10 @@ export const make = (options: {
  * requests, if specified) and execute them as a single batch.
  *
  * @since 1.0.0
- * @category constructors
+ * @category Constructors
  */
 export const makeDataLoader = (options: {
-  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<Embeddings.Result>, AiError>
+  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<AiEmbeddingModel.Result>, AiError>
   readonly window: Duration.DurationInput
   readonly maxBatchSize?: number
 }) =>
@@ -133,11 +134,11 @@ export const makeDataLoader = (options: {
 
     function embed(input: string) {
       return Effect.request(new EmbeddingRequest({ input }), resolverDelayed).pipe(
-        Effect.withSpan("Embeddings.embed", { captureStackTrace: false })
+        Effect.withSpan("AiEmbeddingModel.embed", { captureStackTrace: false })
       )
     }
 
-    return Embeddings.of({
+    return AiEmbeddingModel.of({
       embed
     })
   })

package/src/AiError.ts

@@ -1,13 +1,14 @@
 /**
  * @since 1.0.0
  */
+import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 
 /**
  * @since 1.0.0
  * @category type ids
  */
-export const TypeId: unique symbol = Symbol("@effect/ai/AiError")
+export const TypeId: unique symbol = Symbol.for("@effect/ai/AiError")
 
 /**
  * @since 1.0.0
@@ -25,6 +26,12 @@ export class AiError extends Schema.TaggedError<AiError>("@effect/ai/AiError")("
   description: Schema.String,
   cause: Schema.optional(Schema.Defect)
 }) {
+  /**
+   * @since 1.0.0
+   */
+  static is(u: unknown): u is AiError {
+    return Predicate.hasProperty(u, TypeId)
+  }
   /**
    * @since 1.0.0
    */