Skip to content

Architecture

Overview

The library is built around Chats, Services, Tools, and Hooks.

ChatService
 ├── Chat (ChatInterface) - message history, hooks
 ├── ChunkStream (ChunkStreamInterface) - raw streaming chunks
 ├── ToolSuite (ToolSuiteInterface) - tool registration and dispatch
 └── send() - tool-call loop

Hooks
 ├── Stream hooks (via service.stream().hook()) - observe raw chunks
 ├── Chat hooks (via chat.hook()) - subscribe to messages
 ├── Tool hooks (via service.tools().hook()) - before, after, error
 └── JSON hooks - declarative hooks from `.json` files, auto-loaded at startup
  • Chat / ChatInterface - the public handle for building message histories and subscribing to chat events. Created by service.chat().
  • ChunkStream / ChunkStreamInterface - accumulates raw streaming chunks (content, reasoning, tool-call deltas, finish) during send(). Accessed via service.stream().
  • ChatService - abstract base class that manages the tool-call loop. It owns the Chat, ChunkStream, and tool registry. Call service.send() to start the request/response cycle.
  • Tool - abstract base class users extend to define custom tools.
  • ToolSuiteInterface - exposed via service.tools(), lets you add tools and attach hooks via .hook().before/after/error().do().
  • Hooks - four kinds: stream hooks (service.stream().hook().chunks().do()) for raw chunk observation, chat hooks (chat.hook().message().do()) for completed message observation, tool hooks (service.tools().hook().before/after/error().do()) for tool lifecycle events, and JSON hooks, declarative hooks defined in .json files that are auto-loaded at startup.

Providers (like OpenAIChatService) extend ChatService and implement createStream() to connect to a specific API.