effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -13,7 +13,7 @@
  * - Stripping unsupported annotations and preserving only Anthropic-compatible
  *   formats and descriptions
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
 import * as JsonSchema from "../../JsonSchema.ts"
@@ -46,8 +46,8 @@ import * as Tool from "./Tool.ts"
  * If the schema is already compatible, the original codec is returned
  * unchanged.
  *
- * @since 1.0.0
  * @category Codec Transformation
+ * @since 4.0.0
  */
 export function toCodecAnthropic<T, E, RD, RE>(
   schema: Schema.Codec<T, E, RD, RE>

package/src/unstable/ai/Chat.ts

@@ -7,7 +7,8 @@
  * text generation. It integrates seamlessly with the Effect AI ecosystem,
  * providing type-safe conversational AI capabilities.
  *
- * @example
+ * **Example** (Creating a chat session)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { Chat } from "effect/unstable/ai"
@@ -27,7 +28,8 @@
  * })
  * ```
  *
- * @example
+ * **Example** (Streaming chat responses)
+ *
  * ```ts
  * import { Effect, Stream } from "effect"
  * import { Chat } from "effect/unstable/ai"
@@ -73,7 +75,8 @@ import type * as Tool from "./Tool.ts"
  * enabling persistent conversational AI interactions with full context
  * management.
  *
- * @example
+ * **Example** (Using the Chat service)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { Chat } from "effect/unstable/ai"
@@ -87,8 +90,8 @@ import type * as Tool from "./Tool.ts"
  * })
  * ```
  *
- * @since 4.0.0
  * @category services
+ * @since 4.0.0
  */
 export class Chat extends Context.Service<Chat, Service>()(
   "effect/ai/Chat"
@@ -97,8 +100,8 @@ export class Chat extends Context.Service<Chat, Service>()(
 /**
  * Represents the interface that the `Chat` service provides.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Service {
   /**
@@ -107,7 +110,8 @@ export interface Service {
    * Provides direct access to the conversation history for advanced use cases
    * like custom history manipulation or inspection.
    *
-   * @example
+   * **Example** (Inspecting chat history)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    * import { Chat } from "effect/unstable/ai"
@@ -128,7 +132,8 @@ export interface Service {
    * Returns the complete conversation history as a structured object
    * that can be stored, transmitted, or processed by other systems.
    *
-   * @example
+   * **Example** (Exporting chat history)
+   *
    * ```ts
    * import { Effect } from "effect"
    * import { Chat } from "effect/unstable/ai"
@@ -152,7 +157,8 @@ export interface Service {
    * Provides a convenient way to serialize the entire conversation
    * for storage or transmission in JSON format.
    *
-   * @example
+   * **Example** (Exporting chat history as JSON)
+   *
    * ```ts
    * import { Effect } from "effect"
    * import { Chat } from "effect/unstable/ai"
@@ -179,7 +185,8 @@ export interface Service {
    * for function calling and enhanced capabilities. Both input and output
    * messages are automatically added to the chat history.
    *
-   * @example
+   * **Example** (Generating chat responses)
+   *
    * ```ts
    * import { Effect } from "effect"
    * import { Chat } from "effect/unstable/ai"
@@ -243,7 +250,8 @@ export interface Service {
    * Returns a stream of response parts that are emitted as soon as they're
    * available from the model. Supports tool calling and maintains chat history.
    *
-   * @example
+   * **Example** (Streaming chat responses)
+   *
    * ```ts
    * import { Effect, Stream } from "effect"
    * import { Chat } from "effect/unstable/ai"
@@ -307,7 +315,8 @@ export interface Service {
    * enabling structured data extraction and type-safe responses. The
    * conversation history is maintained across calls.
    *
-   * @example
+   * **Example** (Generating structured objects)
+   *
    * ```ts
    * import { Effect, Schema } from "effect"
    * import { Chat } from "effect/unstable/ai"
@@ -459,7 +468,8 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
  * This is the most common way to start a fresh chat session without
  * any initial context or system prompts.
  *
- * @example
+ * **Example** (Creating an empty chat)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { Chat } from "effect/unstable/ai"
@@ -477,8 +487,8 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const empty: Effect.Effect<Service> = Effect.sync(() => makeUnsafe(Ref.makeUnsafe(Prompt.empty)))
 
@@ -488,7 +498,8 @@ export const empty: Effect.Effect<Service> = Effect.sync(() => makeUnsafe(Ref.ma
  * This is the primary constructor for creating chat instances. It initializes
  * a new conversation with the provided prompt as the starting context.
  *
- * @example
+ * **Example** (Creating a chat from a system prompt)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { Chat } from "effect/unstable/ai"
@@ -507,7 +518,8 @@ export const empty: Effect.Effect<Service> = Effect.sync(() => makeUnsafe(Ref.ma
  * })
  * ```
  *
- * @example
+ * **Example** (Restoring chat history from a prompt)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { Chat } from "effect/unstable/ai"
@@ -537,8 +549,8 @@ export const empty: Effect.Effect<Service> = Effect.sync(() => makeUnsafe(Ref.ma
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromPrompt = (prompt: Prompt.RawInput) =>
   Effect.sync(() => makeUnsafe(Ref.makeUnsafe(Prompt.make(prompt))))
@@ -550,33 +562,44 @@ export const fromPrompt = (prompt: Prompt.RawInput) =>
  * using the `export` method. Useful for persisting and restoring conversation
  * state.
  *
- * @example
+ * **Example** (Restoring chat data)
+ *
  * ```ts
- * import { Effect } from "effect"
+ * import { Effect, Ref } from "effect"
  * import { Chat } from "effect/unstable/ai"
  *
- * declare const loadFromDatabase: (sessionId: string) => Effect.Effect<unknown>
- *
  * const restoreChat = Effect.gen(function*() {
- *   // Assume we have previously exported data
- *   const savedData = yield* loadFromDatabase("chat-session-123")
+ *   const originalChat = yield* Chat.fromPrompt([
+ *     {
+ *       role: "user",
+ *       content: "Which library are we using?"
+ *     },
+ *     {
+ *       role: "assistant",
+ *       content: "The project uses Effect."
+ *     }
+ *   ])
  *
- *   const restoredChat = yield* Chat.fromExport(savedData)
+ *   const exported = yield* originalChat.export
+ *   const restoredChat = yield* Chat.fromExport(exported)
+ *   const restoredHistory = yield* Ref.get(restoredChat.history)
  *
- *   // Continue the conversation from where it left off
- *   const response = yield* restoredChat.generateText({
- *     prompt: "Let's continue our discussion"
- *   })
- * }).pipe(
- *   Effect.catchTag("SchemaError", (error) => {
- *     console.log("Failed to restore chat:", error.message)
- *     return Effect.void
- *   })
- * )
+ *   console.log(restoredHistory.content.map((message) => message.role))
+ *   // ["user", "assistant"]
+ *
+ *   const restoredResponse = restoredHistory.content[1]
+ *   if (restoredResponse?.role === "assistant") {
+ *     const restoredText = restoredResponse.content[0]
+ *     if (restoredText?.type === "text") {
+ *       console.log(restoredText.text)
+ *       // "The project uses Effect."
+ *     }
+ *   }
+ * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromExport = (data: unknown): Effect.Effect<
   Service,
@@ -590,7 +613,8 @@ export const fromExport = (data: unknown): Effect.Effect<
  * using the `exportJson` method. This is the most convenient way to
  * persist and restore chat sessions to/from storage systems.
  *
- * @example
+ * **Example** (Restoring chat history from JSON)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { Chat } from "effect/unstable/ai"
@@ -616,8 +640,8 @@ export const fromExport = (data: unknown): Effect.Effect<
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromJson = (data: string): Effect.Effect<
   Service,
@@ -632,8 +656,8 @@ export const fromJson = (data: string): Effect.Effect<
  * An error that occurs when attempting to retrieve a persisted `Chat` that
  * does not exist in the backing persistence store.
  *
- * @since 4.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class ChatNotFoundError extends Schema.ErrorClass<ChatNotFoundError>(
   "effect/ai/Chat/ChatNotFoundError"
@@ -645,8 +669,8 @@ export class ChatNotFoundError extends Schema.ErrorClass<ChatNotFoundError>(
 /**
  * The context tag for chat persistence.
  *
- * @since 4.0.0
  * @category services
+ * @since 4.0.0
  */
 // @effect-diagnostics effect/leakingRequirements:off
 export class Persistence extends Context.Service<Persistence, Persistence.Service>()(
@@ -654,16 +678,18 @@ export class Persistence extends Context.Service<Persistence, Persistence.Servic
 ) {}
 
 /**
- * @since 4.0.0
+ * Namespace containing the service contract for chat persistence.
+ *
  * @category models
+ * @since 4.0.0
  */
 export declare namespace Persistence {
   /**
    * Represents the backing persistence for a persisted `Chat`. Allows for
    * creating and retrieving chats that have been saved to a persistence store.
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Service {
     /**
@@ -694,8 +720,8 @@ export declare namespace Persistence {
  * chat history as well as the relevent response parts will be saved to the
  * backing persistence store.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Persisted extends Service {
   /**
@@ -715,8 +741,8 @@ export interface Persisted extends Service {
  * The provided store identifier will be used to indicate which "store" the
  * backing persistence should load chats from.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makePersisted = Effect.fnUntraced(function*(options: {
   readonly storeId: string
@@ -868,8 +894,8 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
  * The provided store identifier will be used to indicate which "store" the
  * backing persistence should load chats from.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const layerPersisted = (options: {
   readonly storeId: string

package/src/unstable/ai/EmbeddingModel.ts

@@ -1,7 +1,8 @@
 /**
  * The `EmbeddingModel` module provides provider-agnostic text embedding capabilities.
  *
- * @example
+ * **Example** (Embedding text with a model)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { EmbeddingModel } from "effect/unstable/ai"
@@ -25,8 +26,8 @@ import * as AiError from "./AiError.ts"
 /**
  * Service tag for embedding model operations.
  *
- * @since 4.0.0
  * @category services
+ * @since 4.0.0
  */
 export class EmbeddingModel extends Context.Service<EmbeddingModel, Service>()(
   "effect/unstable/ai/EmbeddingModel"
@@ -35,8 +36,8 @@ export class EmbeddingModel extends Context.Service<EmbeddingModel, Service>()(
 /**
  * Service tag that provides the current embedding dimensions.
  *
- * @since 4.0.0
  * @category services
+ * @since 4.0.0
  */
 export class Dimensions extends Context.Service<Dimensions, number>()(
   "effect/unstable/ai/EmbeddingModel/Dimensions"
@@ -45,8 +46,8 @@ export class Dimensions extends Context.Service<Dimensions, number>()(
 /**
  * Token usage metadata for embedding operations.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class EmbeddingUsage extends Schema.Class<EmbeddingUsage>(
   "effect/ai/EmbeddingModel/EmbeddingUsage"
@@ -57,8 +58,8 @@ export class EmbeddingUsage extends Schema.Class<EmbeddingUsage>(
 /**
  * Response for a single embedding request.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class EmbedResponse extends Schema.Class<EmbedResponse>(
   "effect/ai/EmbeddingModel/EmbedResponse"
@@ -69,8 +70,8 @@ export class EmbedResponse extends Schema.Class<EmbedResponse>(
 /**
  * Response for multiple embeddings.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class EmbedManyResponse extends Schema.Class<EmbedManyResponse>(
   "effect/ai/EmbeddingModel/EmbedManyResponse"
@@ -82,8 +83,8 @@ export class EmbedManyResponse extends Schema.Class<EmbedManyResponse>(
 /**
  * Provider input options for embedding requests.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ProviderOptions {
   readonly inputs: ReadonlyArray<string>
@@ -92,8 +93,8 @@ export interface ProviderOptions {
 /**
  * Provider response for batch embedding requests.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ProviderResponse {
   readonly results: Array<Array<number>>
@@ -105,8 +106,8 @@ export interface ProviderResponse {
 /**
  * Tagged request used by request resolvers for embedding operations.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export class EmbeddingRequest extends Request.TaggedClass("EmbeddingRequest")<
   { readonly input: string },
@@ -117,8 +118,8 @@ export class EmbeddingRequest extends Request.TaggedClass("EmbeddingRequest")<
 /**
  * Service interface for embedding operations.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Service {
   readonly resolver: RequestResolver.RequestResolver<EmbeddingRequest>
@@ -136,8 +137,8 @@ const invalidProviderResponse = (description: string): AiError.AiError =>
 /**
  * Creates an EmbeddingModel service from a provider embedMany implementation.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make: (params: {
   readonly embedMany: (options: ProviderOptions) => Effect.Effect<ProviderResponse, AiError.AiError>

package/src/unstable/ai/IdGenerator.ts

@@ -5,7 +5,8 @@
  * This module offers a flexible and configurable approach to ID generation, supporting
  * custom alphabets, prefixes, separators, and sizes.
  *
- * @example
+ * **Example** (Generating IDs with the default service)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { IdGenerator } from "effect/unstable/ai"
@@ -22,7 +23,8 @@
  * ))
  * ```
  *
- * @example
+ * **Example** (Providing a custom ID generator)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { IdGenerator } from "effect/unstable/ai"
@@ -59,7 +61,8 @@ import * as Random from "../../Random.ts"
  * the application. It follows Effect's standard service pattern for type-safe
  * dependency injection.
  *
- * @example
+ * **Example** (Accessing the ID generator service)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { IdGenerator } from "effect/unstable/ai"
@@ -71,8 +74,8 @@ import * as Random from "../../Random.ts"
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class IdGenerator extends Context.Service<IdGenerator, Service>()(
   "@effect/ai/IdGenerator"
@@ -85,25 +88,27 @@ export class IdGenerator extends Context.Service<IdGenerator, Service>()(
  * The service provides a single method for generating unique identifiers
  * in an effectful context.
  *
- * @example
+ * **Example** (Implementing a custom ID generator)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import type { IdGenerator } from "effect/unstable/ai"
  *
- * // Custom implementation
+ * // Custom deterministic implementation
+ * let nextId = 0
  * const customService: IdGenerator.Service = {
- *   generateId: () => Effect.succeed(`custom_${Date.now()}`)
+ *   generateId: () => Effect.sync(() => `custom_${++nextId}`)
  * }
  *
  * const program = Effect.gen(function*() {
  *   const id = yield* customService.generateId()
- *   console.log(id) // "custom_1234567890"
+ *   console.log(id) // "custom_1"
  *   return id
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Service {
   readonly generateId: () => Effect.Effect<string>
@@ -112,7 +117,8 @@ export interface Service {
 /**
  * Configuration options for creating custom ID generators.
  *
- * @example
+ * **Example** (Configuring generated IDs)
+ *
  * ```ts
  * import type { IdGenerator } from "effect/unstable/ai"
  *
@@ -127,8 +133,8 @@ export interface Service {
  * // This will generate IDs like: "tool_A1B2C3D4"
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface MakeOptions {
   /**
@@ -181,7 +187,8 @@ const makeGenerator = ({
  * format "id_XXXXXXXXXXXXXXXX" where X represents random alphanumeric
  * characters.
  *
- * @example
+ * **Example** (Generating default IDs)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { IdGenerator } from "effect/unstable/ai"
@@ -201,8 +208,8 @@ const makeGenerator = ({
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const defaultIdGenerator: Service = {
   generateId: makeGenerator({ prefix: "id" })
@@ -214,7 +221,8 @@ export const defaultIdGenerator: Service = {
  * Validates the configuration to ensure the separator is not part of the
  * alphabet, which would cause ambiguity in parsing generated IDs.
  *
- * @example
+ * **Example** (Creating a custom generator)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { IdGenerator } from "effect/unstable/ai"
@@ -234,7 +242,8 @@ export const defaultIdGenerator: Service = {
  * })
  * ```
  *
- * @example
+ * **Example** (Handling invalid generator options)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { IdGenerator } from "effect/unstable/ai"
@@ -257,8 +266,8 @@ export const defaultIdGenerator: Service = {
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({
   alphabet = DEFAULT_ALPHABET,
@@ -286,7 +295,8 @@ export const make = Effect.fnUntraced(function*({
  * application. The layer will fail during construction if the configuration is
  * invalid.
  *
- * @example
+ * **Example** (Providing an ID generator layer)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { IdGenerator } from "effect/unstable/ai"
@@ -307,8 +317,8 @@ export const make = Effect.fnUntraced(function*({
  * }).pipe(Effect.provide(toolCallIdLayer))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const layer = (options: MakeOptions): Layer.Layer<IdGenerator, Cause.IllegalArgumentError> =>
   Layer.effect(IdGenerator)(make(options))