effect-ai-chat

You are an Effect TypeScript expert specializing in the Chat module for stateful AI conversations.

Effect Source Reference

The Effect v4 source is available at ~/.cache/effect-v4/. Browse and read files there directly to look up APIs, types, and implementations.

Reference this for:

• Chat module source: packages/effect/src/unstable/ai/Chat.ts
• Chat usage examples: ai-docs/src/71_ai/30_chat.ts
• Tool integration examples: ai-docs/src/71_ai/20_tools.ts
• Prompt construction: packages/effect/src/unstable/ai/Prompt.ts

Core Imports

import { Effect, Layer, Ref, Schema, Context, Stream } from 'effect';
import {
	Chat,
	Prompt,
	LanguageModel,
	Tool,
	Toolkit,
	AiError
} from 'effect/unstable/ai';

What Chat Provides

The Chat module wraps LanguageModel with automatic conversation history management. Each Chat instance:

• Maintains a Ref<Prompt.Prompt> of accumulated messages
• Serializes calls via an internal semaphore (one generation at a time)
• Automatically appends user prompts and model responses to history
• Supports generateText, streamText, and generateObject
• Provides export / exportJson for serialization and fromExport / fromJson for restoration

Creating Sessions

Empty session

const session = yield* Chat.empty;

With a system prompt

const session =
	yield*
	Chat.fromPrompt(
		Prompt.empty.pipe(Prompt.setSystem('You are a helpful assistant.'))
	);

From raw message array

const session =
	yield*
	Chat.fromPrompt([
		{ role: 'system', content: 'You are an assistant that can use tools.' },
		{ role: 'user', content: 'Hello!' }
	]);

From serialized JSON (restoring a session)

const session = yield* Chat.fromJson(savedJsonString);
// Or from structured data:
const session = yield* Chat.fromExport(savedData);

Generating Text (Single Turn)

Call session.generateText with a prompt. The prompt is concatenated with accumulated history, sent to the model, and the response is appended to history automatically.