Skip to content

Chat

Stateful conversation sessions on top of a language model.

A Chat keeps Prompt history in a Ref and reuses it for text generation, streaming, and structured output. Each generation call combines the current history with the caller's new prompt, invokes the active language model, and appends the response parts back into history. Constructors create fresh sessions, seed sessions from prompts, restore exported history, or connect a chat to persistence.

12 exports Added in v4.0.0 Source

Constructors

empty

Added in v4.0.0 Source

Creates a new Chat service with empty conversation history.

When to use

Use when you need to start a fresh chat session without initial context or system prompts.

Signature

declare const empty: Effect.Effect<Service>;

fromExport

Added in v4.0.0 Source

Creates a Chat service from previously exported chat data.

Details

Restores a chat session from structured data that was previously exported using the export method. Useful for persisting and restoring conversation state.

Signature

declare function fromExport(data: unknown): Effect<Service, SchemaError>;

fromJson

Added in v4.0.0 Source

Creates a Chat service from previously exported JSON chat data.

Details

Restores a chat session from JSON string that was previously exported using the exportJson method. This is the most convenient way to persist and restore chat sessions to/from storage systems.

Signature

declare function fromJson(data: string): Effect<Service, SchemaError>;

fromPrompt

Added in v4.0.0 Source

Creates a new Chat service from an initial prompt.

Details

This is the primary constructor for creating chat instances. It initializes a new conversation with the provided prompt as the starting context.

Signature

declare function fromPrompt(prompt: RawInput): Effect<Service, never, never>;

makePersisted

Added in v4.0.0 Source

Creates a new chat persistence service.

When to use

Use when you need programmatic persisted chat creation and retrieval backed by the current BackingPersistence.

Details

The provided store identifier will be used to indicate which "store" the backing persistence should load chats from.

See

Signature

declare const makePersisted: (
  ...args: [
    options: {
      readonly storeId: string;
    },
  ]
) => Effect<Service, never, Scope | BackingPersistence>;

Errors

ChatNotFoundError

Added in v4.0.0 Source

Represents an error that occurs when attempting to retrieve a persisted Chat that does not exist in the backing persistence store.

When to use

Use to represent a missing persisted conversation when lookup by id cannot find stored history.

Signature

declare class ChatNotFoundError extends {
  readonly _tag: "ChatNotFoundError";
  readonly chatId: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ChatNotFoundError";
    readonly chatId: string;
  }, options?: MakeOptions]);
}

Layers

layerPersisted

Added in v4.0.0 Source

Creates a Layer for a new chat persistence service.

When to use

Use to provide Chat.Persistence from a configured BackingPersistence when your application needs persisted chat sessions backed by a named store.

Details

The provided store identifier will be used to indicate which "store" the backing persistence should load chats from.

See

  • makePersisted for the effect constructor when building the service directly instead of providing it as a layer

Signature

declare function layerPersisted(options: {
  readonly storeId: string;
}): Layer<Persistence, never, BackingPersistence>;

Models

Persisted interface

Added in v4.0.0 Source

Represents a Chat that is backed by persistence.

Details

When calling a text generation method (e.g. generateText), the previous chat history as well as the relevent response parts will be saved to the backing persistence store.

Signature

interface Persisted extends Service {
  readonly id: string;
  readonly save: Effect<void, PersistenceError | AiError>;
}

Service interface

Added in v4.0.0 Source

Represents the interface that the Chat service provides.

When to use

Use as the service contract for code that receives or constructs a stateful chat session and needs history, export, text generation, streaming, and structured-output operations.

See

  • Chat for the context tag that provides this service
  • Persisted for the persistence-backed extension

Signature

interface Service {
  readonly export: Effect<unknown, AiError>;
  readonly exportJson: Effect<string, AiError>;
  readonly generateObject: <
    ObjectEncoded extends Record<string, any>,
    ObjectSchema extends Encoder<ObjectEncoded, unknown>,
    Options extends NoExcessProperties<GenerateObjectOptions<any, ObjectSchema>, Options>,
  >(
    options: Options & GenerateObjectOptions<ExtractTools<Options>, ObjectSchema>,
  ) => Effect<
    GenerateObjectResponse<ExtractTools<Options>, ObjectSchema["Type"]>,
    ExtractError<Options>,
    LanguageModel | ExtractServices<Options> | ObjectSchema["DecodingServices"]
  >;
  readonly generateText: {
    <Options extends NoExcessProperties<GenerateTextOptions<{}>, Options>>(
      options: Options & {
        readonly toolkit?: undefined;
      } & GenerateTextOptions<{}>,
    ): Effect<
      GenerateTextResponse<{}>,
      ExtractError<Options>,
      LanguageModel | ExtractServices<Options>
    >;
    <
      Tools extends Record<string, Any>,
      Options extends NoExcessProperties<
        GenerateTextOptions<Tools> & {
          readonly toolkit: ToolkitInput<Tools>;
        },
        Options
      >,
    >(
      options: Options &
        GenerateTextOptions<Tools> & {
          readonly toolkit: ToolkitInput<Tools>;
        },
    ): Effect<
      GenerateTextResponse<Tools>,
      ExtractError<Options>,
      LanguageModel | ExtractServices<Options>
    >;
    <
      Options extends {
        readonly toolkit: WithHandler<any> | Effect<WithHandler<any>, never, any>;
      } & GenerateTextOptions<any> &
        Readonly<Record<Exclude<keyof Options, keyof GenerateTextOptions<any>>, never>>,
    >(
      options: Options &
        GenerateTextOptions<ExtractTools<Options>> & {
          readonly toolkit: Options["toolkit"];
        },
    ): Effect<
      GenerateTextResponse<ExtractTools<Options>>,
      ExtractError<Options>,
      LanguageModel | ExtractServices<Options>
    >;
  };
  readonly history: Ref<Prompt>;
  readonly streamText: {
    <Options extends NoExcessProperties<GenerateTextOptions<{}>, Options>>(
      options: Options & {
        readonly toolkit?: undefined;
      } & GenerateTextOptions<{}>,
    ): Stream<StreamPart<{}>, ExtractError<Options>, LanguageModel | ExtractServices<Options>>;
    <
      Tools extends Record<string, Any>,
      Options extends NoExcessProperties<
        GenerateTextOptions<Tools> & {
          readonly toolkit: ToolkitInput<Tools>;
        },
        Options
      >,
    >(
      options: Options &
        GenerateTextOptions<Tools> & {
          readonly toolkit: ToolkitInput<Tools>;
        },
    ): Stream<StreamPart<Tools>, ExtractError<Options>, LanguageModel | ExtractServices<Options>>;
    <
      Options extends {
        readonly toolkit: WithHandler<any> | Effect<WithHandler<any>, never, any>;
      } & GenerateTextOptions<any> &
        Readonly<Record<Exclude<keyof Options, keyof GenerateTextOptions<any>>, never>>,
    >(
      options: Options &
        GenerateTextOptions<ExtractTools<Options>> & {
          readonly toolkit: Options["toolkit"];
        },
    ): Stream<
      StreamPart<ExtractTools<Options>>,
      ExtractError<Options>,
      LanguageModel | ExtractServices<Options>
    >;
  };
}

Other

Persistence

Added in v4.0.0 Source

Namespace containing the service contract for chat persistence.

Services

Chat

Added in v4.0.0 Source

Service tag for stateful AI conversation sessions.

When to use

Use to access or provide conversational AI sessions through the Effect context.

Details

This tag provides access to chat functionality throughout your application, enabling persistent conversational AI interactions with full context management.

Signature

declare class Chat extends Shape<"effect/ai/Chat", Service, this> {
  constructor(_: never);
}

Persistence

Added in v4.0.0 Source

Service tag for persistence-backed AI conversation storage.

When to use

Use to provide the storage operations needed by persisted conversation sessions.

Signature

declare class Persistence extends Shape<"effect/ai/Chat/Persisted", Service, this> {
  constructor(_: never);
}