@frakment/ai

First-party deterministic chat engine for Frakment AI interfaces.

The engine powers the chat and agent primitives in the Frakment registry (message-animated, trace, chain-of-thought). It wraps the Vercel AI SDK with a deterministic event contract so UI components can render stable, replayable state.

Install

npm install @frakment/ai ai

Or with your package manager of choice:

pnpm add @frakment/ai ai
yarn add @frakment/ai ai
bun add @frakment/ai ai

Peer dependency: ai >= 7.

Quick start

import { createChat } from "@frakment/ai";

// Build a deterministic transcript.
const chat = createChat()
  .user("Hello")
  .assistant("Hi! How can I help?")
  .user("Show me a trace.");

// Read turns back.
const messages = chat.get();
const last = messages.at(-1);

// Stream the next reply over HTTP.
const transport = chat.transport();
const response = transport.create({ messages });

Public API

• createChat(options?) -> AiSdkChat. Factory for a deterministic chat instance.
• getMessageText(message) -> concatenated text parts of a UIMessage.
• createAiSdkAdapter() -> adapter bridging AI SDK transport shapes.
• getToolCalls(message) -> pending tool calls from a message.

All event types (ChatEvent, ChatEventEnvelope, UIMessageChunk, ToolHandle, ...) are exported for consumers that build custom renderers.

Used by

• Chat primitives: message-animated, bubble, message, message-scroller.
• Agent primitives: trace, chain-of-thought, plan, reasoning, tool, subagent.

Documentation

• Engine guide: https://www.arrafi.dev/frakment/docs/libraries/ai
• Registry: https://www.arrafi.dev/frakment/docs/ai-elements

License

MIT licensed. See LICENSE.