conversationalist 0.0.1 → 0.0.3

package/README.md

@@ -1,47 +1,121 @@
 # Conversationalist
 
-A TypeScript library for managing LLM conversation state with immutable data structures and type-safe APIs.
+A TypeScript-first library for managing LLM conversation state with **immutable updates**, **type-safe APIs**, and **provider-agnostic adapters**.
+
+[![Tests](https://github.com/stevekinney/conversationalist/actions/workflows/test.yml/badge.svg)](https://github.com/stevekinney/conversationalist/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is Conversationalist?
+
+**Conversationalist** is a state engine for LLM-driven applications. While most libraries focus on making the API calls themselves, Conversationalist focuses on the **state** that lives between those calls. It provides a unified, model-agnostic representation of a conversation that can be easily stored, serialized, and adapted for any major LLM provider (OpenAI, Anthropic, Gemini).
+
+In a modern AI application, a conversation is more than just a list of strings. It involves:
+
+- **Tool Use**: Pairing function calls with their results and ensuring they stay in sync.
+- **Hidden Logic**: Internal "thought" messages or snapshots that should be saved but never sent to the provider.
+- **Metadata**: Tracking tags, custom IDs, and tokens across different steps.
+- **Streaming**: Gracefully handling partial messages in a UI without messy state transitions.
+
+Conversationalist handles these complexities through a robust, type-safe API that treats your conversation as the "Single Source of Truth."
+
+## Why Use It?
+
+Managing LLM conversations manually often leads to "provider lock-in" or fragile glue code. Conversationalist solves this by:
+
+- **Decoupling Logic from Providers**: Write your business logic once using Conversationalist's message model, and use adapters to talk to OpenAI, Anthropic, or Gemini.
+- **Built-in Context Management**: Automatically handle context window limits by truncating history while preserving critical system instructions or recent messages.
+- **Type Safety Out-of-the-Box**: Built with Zod and TypeScript, ensuring that your conversation data is valid at runtime and compile-time.
+- **Unified Serialization**: One standard format (`ConversationJSON`) for your database, your frontend, and your backend.
+
+## The Immutable Advantage
+
+At its core, Conversationalist is **strictly immutable**. Every change to a conversation—whether appending a message, updating a stream, or redacting sensitive data—returns a _new_ conversation object.
+
+This approach offers several critical advantages for modern application development:
+
+1.  **React/Redux Friendly**: Because updates return new references, they trigger re-renders naturally and work seamlessly with state management libraries.
+2.  **Concurrency Safe**: You can safely pass a conversation to multiple functions or async tasks without worrying about one part of your app mutating it out from under another.
+3.  **Easy Branching & Replay**: Want to let a user "undo" an AI response or branch a conversation into two different paths? Simply keep a reference to the previous immutable state. No complex cloning required.
+4.  **Auditability**: Timestamps and message positions are automatically managed and preserved, making it easy to reconstruct the exact state of a chat at any point in time.
+
+## Real-World Use Cases
+
+- **Multi-Model Chatbots**: Build a UI where users can switch between GPT-4o and Claude 3.5 Sonnet mid-conversation without losing history.
+- **Chain-of-Thought Workflows**: Use `hidden` messages to store internal reasoning or intermediate steps that the AI uses to reach a final answer, without cluttering the user's view.
+- **Agentic Workflows**: Track complex tool-use loops where multiple functions are called in sequence, ensuring every result is correctly paired with its corresponding call ID.
+- **Token Budgeting**: Automatically trim old messages when a conversation gets too long, ensuring your API costs stay predictable and you never hit provider limits.
+- **Deterministic Testing**: Use the custom `environment` parameter to mock IDs and timestamps, allowing you to write 100% deterministic tests for your chat logic.
+
+---
 
 ## Installation
 
 ```bash
-bun add conversationalist
-npm add conversationalist
+bun add conversationalist zod
+npm add conversationalist zod
+pnpm add conversationalist zod
 ```
 
-## Core Concepts
-
-### Conversation
+This package is ESM-only. Use `import` syntax. Zod is a peer dependency and must be installed by your application.
 
-A conversation is an immutable data structure containing messages, metadata, and timestamps:
+## Quick Start
 
-```typescript
+```ts
 import {
-  createConversation,
-  appendUserMessage,
   appendAssistantMessage,
+  appendUserMessage,
+  createConversation,
+  serializeConversation,
 } from 'conversationalist';
+import { toOpenAIMessages } from 'conversationalist/openai';
+
+// 1. Create a conversation
+let conversation = createConversation({
+  title: 'Order Support',
+  metadata: { userId: 'user_123' },
+});
 
-let conversation = createConversation({ title: 'My Chat' });
+// 2. Add messages (returns a new conversation object)
+conversation = appendUserMessage(conversation, 'Where is my order?');
+conversation = appendAssistantMessage(conversation, 'Let me check that for you.');
 
-conversation = appendUserMessage(conversation, 'Hello!');
-conversation = appendAssistantMessage(conversation, 'Hi there!');
+// 3. Adapt for a provider
+const openAIMessages = toOpenAIMessages(conversation);
+// [{ role: 'user', content: 'Where is my order?' }, ...]
+
+// 4. Save to your database
+const data = serializeConversation(conversation);
+// db.save(data.id, JSON.stringify(data));
 ```
 
-### Messages
+## Core Concepts
 
-Messages have roles (`user`, `assistant`, `system`, `tool-use`, `tool-result`, `developer`, `snapshot`) and can contain text or multi-modal content:
+### Conversations
 
-```typescript
-import { appendMessages } from 'conversationalist';
+A conversation is an immutable record with metadata, tags, timestamps, and ordered messages.
 
-// Text message
-conversation = appendMessages(conversation, {
-  role: 'user',
-  content: 'What is in this image?',
+```ts
+import { createConversation } from 'conversationalist';
+
+const conversation = createConversation({
+  title: 'My Chat',
+  status: 'active',
+  metadata: { customerId: 'cus_123' },
+  tags: ['support', 'vip'],
 });
+```
+
+### Messages
+
+Messages have roles and can contain text or multi-modal content. Optional fields include
+`metadata`, `hidden`, `tokenUsage`, `toolCall`, `toolResult`, and `goalCompleted`.
+
+**Roles**: `user`, `assistant`, `system`, `developer`, `tool-use`, `tool-result`, `snapshot`.
+The `snapshot` role is for internal state and is skipped by adapters.
+
+```ts
+import { appendMessages } from 'conversationalist';
 
-// Multi-modal message with image
 conversation = appendMessages(conversation, {
   role: 'user',
   content: [
@@ -51,307 +125,582 @@ conversation = appendMessages(conversation, {
 });
 ```
 
+**Hidden messages** remain in history but are skipped by default when querying or adapting to
+providers. This is perfect for internal logging or "thinking" steps.
+
 ### Tool Calls
 
-Tool use is supported with linked tool calls and results:
+Tool calls are represented as paired `tool-use` and `tool-result` messages. Tool results
+are validated to ensure the referenced call exists.
 
-```typescript
+```ts
 conversation = appendMessages(
   conversation,
   {
     role: 'tool-use',
     content: '',
-    toolCall: { id: 'call_123', name: 'get_weather', arguments: '{"city":"NYC"}' },
+    toolCall: { id: 'call_123', name: 'getWeather', arguments: { city: 'NYC' } },
   },
   {
     role: 'tool-result',
     content: '',
-    toolResult: { callId: 'call_123', outcome: 'success', content: '72°F, sunny' },
+    toolResult: {
+      callId: 'call_123',
+      outcome: 'success',
+      content: { tempF: 72, condition: 'sunny' },
+    },
   },
 );
 ```
 
-## API Reference
+### Streaming
 
-### Creating Conversations
+Streaming helpers let you append a placeholder, update it as chunks arrive, and finalize
+when done.
 
-```typescript
-createConversation(options?: {
-  id?: string;
-  title?: string;
-  status?: 'active' | 'archived' | 'deleted';
-  metadata?: Record<string, unknown>;
-  tags?: string[];
-}): Conversation
-```
+```ts
+import {
+  appendStreamingMessage,
+  finalizeStreamingMessage,
+  updateStreamingMessage,
+} from 'conversationalist';
+
+let { conversation, messageId } = appendStreamingMessage(conversation, 'assistant');
+let content = '';
 
-### Appending Messages
+for await (const chunk of stream) {
+  content += chunk;
+  conversation = updateStreamingMessage(conversation, messageId, content);
+}
 
-```typescript
-appendMessages(conversation: Conversation, ...inputs: MessageInput[]): Conversation
-appendUserMessage(conversation: Conversation, content: string | MultiModalContent[]): Conversation
-appendAssistantMessage(conversation: Conversation, content: string | MultiModalContent[]): Conversation
-appendSystemMessage(conversation: Conversation, content: string): Conversation
-prependSystemMessage(conversation: Conversation, content: string): Conversation
-replaceSystemMessage(conversation: Conversation, content: string): Conversation
+conversation = finalizeStreamingMessage(conversation, messageId, {
+  tokenUsage: { prompt: 100, completion: 50, total: 150 },
+});
 ```
 
-### Querying Messages
+### Context Window Management
 
-```typescript
-getConversationMessages(conversation: Conversation, options?: { includeHidden?: boolean }): Message[]
-getMessageAtPosition(conversation: Conversation, position: number): Message | undefined
-getMessageByIdentifier(conversation: Conversation, id: string): Message | undefined
-searchConversationMessages(conversation: Conversation, predicate: (m: Message) => boolean): Message[]
-```
+Automatically trim history to fit token budgets or to keep only recent messages.
 
-### System Messages
+```ts
+import { simpleTokenEstimator, truncateToTokenLimit } from 'conversationalist';
 
-```typescript
-hasSystemMessage(conversation: Conversation): boolean
-getFirstSystemMessage(conversation: Conversation): Message | undefined
-getSystemMessages(conversation: Conversation): Message[]
-collapseSystemMessages(conversation: Conversation): Conversation
+conversation = truncateToTokenLimit(conversation, 4000, {
+  preserveSystemMessages: true,
+  preserveLastN: 2,
+});
 ```
 
-### Utilities
+#### Custom Token Counters
 
-```typescript
-computeConversationStatistics(conversation: Conversation): {
-  total: number;
-  byRole: Record<string, number>;
-  hidden: number;
-  withImages: number;
-}
+You can provide a custom token estimator (e.g. using `tiktoken` or `anthropic-tokenizer`) by passing it in the options or by binding it to your environment.
 
-redactMessageAtPosition(conversation: Conversation, position: number, placeholder?: string): Conversation
-```
+```ts
+import { truncateToTokenLimit } from 'conversationalist';
+// import { get_encoding } from 'tiktoken';
 
-### Serialization
+const tiktokenEstimator = (message) => {
+  // Your logic here...
+  return 100;
+};
+
+// 1. Pass directly in options
+conversation = truncateToTokenLimit(conversation, 4000, {
+  estimateTokens: tiktokenEstimator,
+});
 
-```typescript
-serializeConversation(conversation: Conversation): ConversationJSON
-deserializeConversation(json: ConversationJSON): Conversation
-toChatMessages(conversation: Conversation): ExternalMessage[]
+// 2. Or bind to a history instance/environment
+const history = new ConversationHistory(conversation, {
+  estimateTokens: tiktokenEstimator,
+});
+
+const boundTruncate = history.bind(truncateToTokenLimit);
+boundTruncate(4000); // Uses tiktokenEstimator automatically
 ```
 
-### Builder Pattern
+## Plugins
 
-For fluent API style:
+**Conversationalist** supports a plugin system that allows you to transform messages as they are appended to a conversation. Plugins are functions that take a `MessageInput` and return a modified `MessageInput`.
 
-```typescript
-import { createConversation } from 'conversationalist';
-import { withConversation, pipeConversation } from 'conversationalist';
-import { simpleTokenEstimator } from 'conversationalist';
+### PII Redaction Plugin
 
-// Draft pattern with callback
-const conversation = withConversation(createConversation(), (draft) => {
-  draft
-    .appendSystemMessage('You are a helpful assistant.')
-    .appendUserMessage('Hello!')
-    .appendAssistantMessage('Hi there!');
-});
+The library includes a built-in `piiRedactionPlugin` that can automatically redact emails, phone numbers, and common API key patterns.
 
-// Streaming with the draft pattern
-const streamedConversation = withConversation(createConversation(), (draft) => {
-  const { draft: d, messageId } = draft.appendStreamingMessage('assistant');
-  d.updateStreamingMessage(messageId, 'Partial response...').finalizeStreamingMessage(
-    messageId,
-    { tokenUsage: { prompt: 10, completion: 5, total: 15 } },
-  );
-});
+```ts
+import {
+  appendUserMessage,
+  createConversation,
+  piiRedactionPlugin,
+} from 'conversationalist';
 
-// Context window management with the draft pattern
-const truncatedConversation = withConversation(conversation, (draft) => {
-  draft.truncateToTokenLimit(4000, simpleTokenEstimator, { preserveLastN: 2 });
-});
+// 1. Enable by adding to your environment
+const env = {
+  plugins: [piiRedactionPlugin],
+};
 
-// Pipe pattern
-const conversation = pipeConversation(
-  createConversation(),
-  (c) => appendSystemMessage(c, 'You are helpful.'),
-  (c) => appendUserMessage(c, 'Hello!'),
+// 2. Use the environment when appending messages
+let conversation = createConversation({}, env);
+conversation = appendUserMessage(
+  conversation,
+  'Contact me at test@example.com',
+  undefined,
+  env,
 );
+
+console.log(conversation.messages[0].content);
+// "Contact me at [EMAIL_REDACTED]"
 ```
 
-The `ConversationDraft` provides all conversation manipulation methods:
+When using `ConversationHistory`, you only need to provide the plugin once during initialization:
 
-- **Message appending**: `appendMessages`, `appendUserMessage`, `appendAssistantMessage`, `appendSystemMessage`
-- **System messages**: `prependSystemMessage`, `replaceSystemMessage`, `collapseSystemMessages`
-- **Modification**: `redactMessageAtPosition`
-- **Streaming**: `appendStreamingMessage`, `updateStreamingMessage`, `finalizeStreamingMessage`, `cancelStreamingMessage`
-- **Context window**: `truncateFromPosition`, `truncateToTokenLimit`
+```ts
+const history = new ConversationHistory(createConversation(), {
+  plugins: [piiRedactionPlugin],
+});
+
+const appendUser = history.bind(appendUserMessage);
+appendUser('My key is sk-12345...'); // Automatically redacted
+```
 
-### Tool Call Pairing
+## Provider Adapters
 
-```typescript
-import { pairToolCallsWithResults } from 'conversationalist';
+Convert the same conversation into provider-specific formats. Adapters automatically skip hidden/snapshot messages and map roles correctly.
 
-const pairs = pairToolCallsWithResults(conversation.messages);
-// Returns: [{ call: ToolCall, result?: ToolResult }, ...]
+```ts
+import { toOpenAIMessages } from 'conversationalist/openai';
+import { toAnthropicMessages } from 'conversationalist/anthropic';
+import { toGeminiMessages } from 'conversationalist/gemini';
 ```
 
-## Provider Adapters
+- **OpenAI**: Supports `toOpenAIMessages` and `toOpenAIMessagesGrouped` (which groups consecutive tool calls).
+- **Anthropic**: Maps system messages and tool blocks to Anthropic's specific format.
+- **Gemini**: Handles Gemini's unique content/part structure.
 
-Convert conversations to provider-specific formats using subpath exports:
+### Provider-Specific Examples
 
-### OpenAI
+#### OpenAI (with Tool Calls)
 
-```typescript
+```ts
+import { appendAssistantMessage, appendMessages } from 'conversationalist';
 import { toOpenAIMessages } from 'conversationalist/openai';
 
-const messages = toOpenAIMessages(conversation);
 const response = await openai.chat.completions.create({
-  model: 'gpt-4',
-  messages,
+  model: 'gpt-4o',
+  messages: toOpenAIMessages(conversation),
+  tools: [{ type: 'function', function: { name: 'getWeather', ... } }],
 });
+
+const toolCalls = response.choices[0]?.message?.tool_calls ?? [];
+for (const call of toolCalls) {
+  conversation = appendMessages(conversation, {
+    role: 'tool-use',
+    content: '',
+    toolCall: { id: call.id, name: call.function.name, arguments: call.function.arguments },
+  });
+
+  const result = await getWeather(JSON.parse(call.function.arguments));
+  conversation = appendMessages(conversation, {
+    role: 'tool-result',
+    content: '',
+    toolResult: { callId: call.id, outcome: 'success', content: result },
+  });
+}
 ```
 
-### Anthropic
+#### Anthropic (with Tool Calls)
 
-```typescript
+```ts
+import { appendAssistantMessage, appendMessages } from 'conversationalist';
 import { toAnthropicMessages } from 'conversationalist/anthropic';
 
 const { system, messages } = toAnthropicMessages(conversation);
 const response = await anthropic.messages.create({
-  model: 'claude-3-opus-20240229',
+  model: 'claude-3-5-sonnet-20240620',
   system,
   messages,
+  tools: [{ name: 'getWeather', ... }],
 });
+
+for (const block of response.content) {
+  if (block.type !== 'tool_use') continue;
+  conversation = appendMessages(conversation, {
+    role: 'tool-use',
+    content: '',
+    toolCall: { id: block.id, name: block.name, arguments: block.input },
+  });
+
+  const result = await getWeather(block.input);
+  conversation = appendMessages(conversation, {
+    role: 'tool-result',
+    content: '',
+    toolResult: { callId: block.id, outcome: 'success', content: result },
+  });
+}
 ```
 
-### Google Gemini
+#### Gemini (with Tool Calls)
 
-```typescript
+```ts
+import { appendMessages } from 'conversationalist';
 import { toGeminiMessages } from 'conversationalist/gemini';
 
 const { systemInstruction, contents } = toGeminiMessages(conversation);
 const response = await model.generateContent({
   systemInstruction,
   contents,
+  tools: [{ functionDeclarations: [{ name: 'getWeather', ... }] }],
 });
-```
 
-## Streaming Support
+const parts = response.response.candidates?.[0]?.content?.parts ?? [];
+for (const part of parts) {
+  if (!('functionCall' in part)) continue;
+  const callId = crypto.randomUUID(); // Gemini doesn't provide IDs, so we generate one
+  const args = part.functionCall.args;
 
-Handle streaming responses with pending message utilities:
+  conversation = appendMessages(conversation, {
+    role: 'tool-use',
+    content: '',
+    toolCall: { id: callId, name: part.functionCall.name, arguments: args },
+  });
 
-```typescript
-import {
-  appendStreamingMessage,
-  updateStreamingMessage,
-  finalizeStreamingMessage,
-  cancelStreamingMessage,
-  isStreamingMessage,
-  getStreamingMessage,
-} from 'conversationalist';
+  const result = await getWeather(args);
+  conversation = appendMessages(conversation, {
+    role: 'tool-result',
+    content: '',
+    toolResult: { callId, outcome: 'success', content: result },
+  });
+}
+```
 
-// Start a streaming message
-let { conversation, messageId } = appendStreamingMessage(conversation, 'assistant');
+## Builder Pattern (Fluent API)
 
-// Update content as chunks arrive
-for await (const chunk of stream) {
-  accumulatedContent += chunk;
-  conversation = updateStreamingMessage(conversation, messageId, accumulatedContent);
-}
+If you prefer a more fluent style, use `withConversation` or `pipeConversation`. These allow you to "mutate" a draft within a scope while still resulting in an immutable object.
 
-// Finalize when complete
-conversation = finalizeStreamingMessage(conversation, messageId, {
-  tokenUsage: { prompt: 100, completion: 50, total: 150 },
+```ts
+import { withConversation, createConversation } from 'conversationalist';
+
+const conversation = withConversation(createConversation(), (draft) => {
+  draft
+    .appendSystemMessage('You are a helpful assistant.')
+    .appendUserMessage('Hello!')
+    .appendAssistantMessage('Hi there!');
 });
+```
+
+`pipeConversation` allows you to chain multiple transformation functions together:
 
-// Or cancel if needed
-conversation = cancelStreamingMessage(conversation, messageId);
+```ts
+import {
+  createConversation,
+  pipeConversation,
+  appendSystemMessage,
+  appendUserMessage,
+} from 'conversationalist';
+
+const conversation = pipeConversation(
+  createConversation(),
+  (c) => appendSystemMessage(c, 'You are a helpful assistant.'),
+  (c) => appendUserMessage(c, 'Hello!'),
+  (c) => appendAssistantMessage(c, 'Hi there!'),
+);
 ```
 
-## Context Window Utilities
+## Conversation History (Undo/Redo)
 
-Manage token limits and message truncation:
+Use the `ConversationHistory` class to manage a stack of conversation states. Because every change returns a new immutable object, supporting undo/redo is built into the architecture.
 
-```typescript
+````ts
 import {
-  getRecentMessages,
-  truncateFromPosition,
-  truncateToTokenLimit,
-  estimateConversationTokens,
-  simpleTokenEstimator,
+  ConversationHistory,
+  createConversation,
+  appendUserMessage,
 } from 'conversationalist';
 
-// Get last N messages (excluding system by default)
-const recent = getRecentMessages(conversation, 10);
+const history = new ConversationHistory(createConversation());
 
-// Truncate to messages from position onwards
-const truncated = truncateFromPosition(conversation, 5);
+// You can use convenience methods that automatically track state
+history.appendUserMessage('Hello!');
+history.appendAssistantMessage('How are you?');
 
-// Truncate to fit token limit
-const fitted = truncateToTokenLimit(conversation, 4000, simpleTokenEstimator, {
-  preserveSystemMessages: true,
-  preserveLastN: 2,
+history.undo(); // State reverts to just "Hello!"
+history.redo(); // State advances back to "How are you?"
+
+// Convenience methods for all library utilities are built-in
+history.appendUserMessage('Another message');
+history.redactMessageAtPosition(0);
+history.truncateToTokenLimit(4000);
+
+// Query methods work on the current state
+const messages = history.getMessages();
+const stats = history.getStatistics();
+const tokens = history.estimateTokens();
+```
+
+### Event Subscription
+
+`ConversationHistory` implements `EventTarget` and follows the Svelte store contract. You can listen for changes using standard DOM events or the `subscribe` method.
+
+#### Using DOM Events
+
+```ts
+const history = new ConversationHistory(createConversation());
+
+// addEventListener returns a convenient unsubscribe function
+const unsubscribe = history.addEventListener('change', (event) => {
+  const { type, conversation } = event.detail;
+  console.log(`History updated via ${type}`);
 });
 
-// Estimate total tokens
-const tokens = estimateConversationTokens(conversation, simpleTokenEstimator);
+history.appendUserMessage('Hello!'); // Fires 'push' and 'change' events
+
+unsubscribe(); // Clean up when done
 ```
 
-## Types
-
-```typescript
-import type {
-  Conversation,
-  ConversationJSON,
-  ConversationStatus,
-  Message,
-  MessageInput,
-  MessageJSON,
-  MessageRole,
-  TokenUsage,
-  ToolCall,
-  ToolResult,
-  MultiModalContent,
-  TextContent,
-  ImageContent,
-} from 'conversationalist';
+#### Using the Store Contract
+
+```ts
+// Subscribe returns an unsubscribe function and calls the callback immediately
+const unsubscribe = history.subscribe((conversation) => {
+  console.log('Current conversation state:', conversation);
+});
 ```
 
-## Validation Schemas
+You can also use an `AbortSignal` for automatic cleanup:
 
-Zod schemas are exported for runtime validation:
+```ts
+const controller = new AbortController();
+history.addEventListener('change', (e) => { ... }, { signal: controller.signal });
 
-```typescript
-import {
-  conversationSchema,
-  messageInputSchema,
-  messageJSONSchema,
-  messageRoleSchema,
-  multiModalContentSchema,
-  tokenUsageSchema,
-  toolCallSchema,
-  toolResultSchema,
-} from 'conversationalist';
+// Later...
+controller.abort();
+```
+
+### Conversation Branching
+
+The `ConversationHistory` class supports branching. When you undo to a previous state and push a new update, it creates an alternate path instead of deleting the old history.
+
+```ts
+const history = new ConversationHistory(createConversation());
+
+history.push(appendUserMessage(history.current, 'Path A'));
+history.undo();
+
+history.push(appendUserMessage(history.current, 'Path B'));
+
+console.log(history.branchCount); // 2
+console.log(history.current.messages[0].content); // "Path B"
+
+history.switchToBranch(0);
+console.log(history.current.messages[0].content); // "Path A"
+```
+
+### Serialization
+
+You can serialize the entire history tree (including all branches) to JSON and reconstruct it later.
+
+```ts
+// 1. Save to JSON
+const json = history.toJSON();
+// localStorage.setItem('chat_history', JSON.stringify(json));
+
+// 2. Restore from JSON
+const restored = ConversationHistory.from(json);
+
+// You can also provide a new environment (e.g. with fresh token counters)
+const restoredWithEnv = ConversationHistory.from(json, {
+  estimateTokens: myNewEstimator,
+});
+```
+
+## Integration
+
+### Using with React
+
+Because **Conversationalist** is immutable, it works perfectly with React's `useState` or `useReducer`. Every update returns a new reference, which automatically triggers a re-render.
+
+```tsx
+import { useState } from 'react';
+import { createConversation, appendUserMessage } from 'conversationalist';
+
+export function ChatApp() {
+  const [conversation, setConversation] = useState(() => createConversation());
 
-const result = messageInputSchema.safeParse(data);
+  const handleSend = (text: string) => {
+    // The new conversation object is set into state
+    setConversation((prev) => appendUserMessage(prev, text));
+  };
+
+  return (
+    <div>
+      {conversation.messages.map((m) => (
+        <div key={m.id}>{String(m.content)}</div>
+      ))}
+      <button onClick={() => handleSend('Hello!')}>Send</button>
+    </div>
+  );
+}
 ```
 
-## Error Handling
+#### Custom React Hook Example
 
-Custom error types with codes:
+For more complex applications, you can wrap the logic into a custom hook. This example uses `addEventListener` to sync the history with local React state and returns the unsubscribe function for easy cleanup in `useEffect`.
 
-```typescript
+```tsx
+import { useState, useCallback, useEffect } from 'react';
 import {
-  ConversationalistError,
-  createInvalidInputError,
-  createInvalidPositionError,
-  createNotFoundError,
-  createValidationError,
+  createConversation,
+  ConversationHistory,
+  toChatMessages,
 } from 'conversationalist';
 
-try {
-  // ...
-} catch (error) {
-  if (error instanceof ConversationalistError) {
-    console.log(error.code); // e.g., 'INVALID_POSITION'
-  }
+export function useChat(initialTitle?: string) {
+  // 1. Initialize history (this could also come from context or props)
+  const [history] = useState(
+    () => new ConversationHistory(createConversation({ title: initialTitle })),
+  );
+
+  // 2. Sync history with local state for reactivity
+  const [conversation, setConversation] = useState(history.current);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    // addEventListener returns a cleanup function!
+    return history.addEventListener('change', (e) => {
+      setConversation(e.detail.conversation);
+    });
+  }, [history]);
+
+  const sendMessage = useCallback(
+    async (text: string) => {
+      history.appendUserMessage(text);
+      setLoading(true);
+
+      try {
+        const response = await fetch('/api/chat', {
+          method: 'POST',
+          body: JSON.stringify({
+            messages: history.toChatMessages(),
+          }),
+        });
+        const data = await response.json();
+        history.appendAssistantMessage(data.answer);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [history],
+  );
+
+  return {
+    conversation,
+    messages: conversation.messages,
+    loading,
+    sendMessage,
+    undo: () => history.undo(),
+    redo: () => history.redo(),
+  };
+}
+```
+
+> **Note**: `ConversationHistory.addEventListener()` returns an unsubscribe function, which is ideal for cleaning up effects in React (`useEffect`) or Svelte.
+
+### Using with Redux
+
+Redux requires immutable state updates, making **Conversationalist** an ideal companion. You can store the conversation object directly in your store.
+
+```ts
+import { createSlice, PayloadAction } from '@reduxjs/toolkit';
+import { createConversation, appendUserMessage, Conversation } from 'conversationalist';
+
+interface ChatState {
+  conversation: Conversation;
 }
+
+const chatSlice = createSlice({
+  name: 'chat',
+  initialState: {
+    conversation: createConversation(),
+  } as ChatState,
+  reducers: {
+    userMessageReceived: (state, action: PayloadAction<string>) => {
+      // Redux Toolkit's createSlice uses Immer, but since appendUserMessage
+      // returns a new object, we can just replace the property.
+      state.conversation = appendUserMessage(state.conversation, action.payload);
+    },
+  },
+});
+```
+
+### Using with Svelte (Runes)
+
+In Svelte 5, you can manage conversation state using the `$state` rune. Since **Conversationalist** is immutable, you update the state by re-assigning the variable with a new conversation object.
+
+```svelte
+<script lang="ts">
+  import { createConversation, appendUserMessage } from 'conversationalist';
+
+  let conversation = $state(createConversation());
+
+  function handleSend(text: string) {
+    conversation = appendUserMessage(conversation, text);
+  }
+</script>
+
+<div>
+  {#each conversation.messages as m (m.id)}
+    <div>{String(m.content)}</div>
+  {/each}
+  <button onclick={() => handleSend('Hello!')}>Send</button>
+</div>
+```
+
+#### Custom Svelte Rune Example
+
+Svelte 5's runes pair perfectly with **Conversationalist**. You can use the `ConversationHistory` class directly as a store, or wrap it in a class with runes.
+
+```svelte
+<script lang="ts">
+  import { ConversationHistory, createConversation } from 'conversationalist';
+
+  // history implements the Svelte store contract
+  const history = new ConversationHistory(createConversation());
+</script>
+
+<div>
+  {#each $history.messages as m (m.id)}
+    <div>{String(m.content)}</div>
+  {/each}
+  <button onclick={() => history.appendUserMessage('Hello!')}>
+    Send
+  </button>
+</div>
+```
+
+> **Note**: `ConversationHistory.addEventListener()` returns an unsubscribe function, which is ideal for cleaning up reactive effects in Svelte 5 or React hooks.
+
+## API Overview
+
+| Category         | Key Functions                                                                                            |
+| :--------------- | :------------------------------------------------------------------------------------------------------- |
+| **Creation**     | `createConversation`, `serializeConversation`, `deserializeConversation`                                 |
+| **Appending**    | `appendUserMessage`, `appendAssistantMessage`, `appendSystemMessage`, `appendMessages`                   |
+| **Streaming**    | `appendStreamingMessage`, `updateStreamingMessage`, `finalizeStreamingMessage`, `cancelStreamingMessage` |
+| **Modification** | `redactMessageAtPosition`, `replaceSystemMessage`, `collapseSystemMessages`                              |
+| **Context**      | `truncateToTokenLimit`, `getRecentMessages`, `estimateConversationTokens`                                |
+| **Querying**     | `getConversationMessages`, `getMessageByIdentifier`, `computeConversationStatistics`                     |
+| **History**      | `ConversationHistory`, `bindToConversationHistory`                                                       |
+
+## Deterministic Environments (Testing)
+
+Pass a custom environment to control timestamps and IDs, making your tests 100% predictable.
+
+```ts
+const testEnv = {
+  now: () => '2024-01-01T00:00:00.000Z',
+  randomId: () => 'fixed-id',
+};
+
+let conversation = createConversation({ title: 'Test' }, testEnv);
 ```
 
 ## Development
@@ -359,11 +708,6 @@ try {
 ```bash
 bun install
 bun test
-bun run typecheck
-bun run lint
 bun run build
 ```
-
-## License
-
-MIT
+````