Interfaces

ChatConfig

Configuration object for the ChatClient.

interface ChatConfig {
  /** The LLM provider to use (string name or plugin instance) */
  provider: ProviderType | ProviderPlugin;
  /** The specific model to use (e.g., 'gpt-4o', 'claude-3-5-sonnet-latest') */
  model: string;
  /** API key for authentication (deprecated: use auth instead) */
  apiKey?: string;
  /** Authentication configuration */
  auth?: AuthConfig;
  /** Custom base URL for the provider API */
  baseUrl?: string;
  /** Optional conversation ID for continuing a conversation */
  conversationId?: string;
  /** Storage backend for conversation history (defaults to InMemoryStorage) */
  storage?: IStorage;
  /** Logger instance for structured logging (defaults to ConsoleLogger) */
  logger?: ILogger;
  /** Configuration for retry behavior */
  retryConfig?: RetryConfig;
  /** Configuration for rate limiting */
  rateLimitConfig?: RateLimitConfig;
  /** Tool registry for function calling */
  tools?: ToolRegistry;
  /** Use multi-step tool execution */
  agenticMode?: boolean;
  /** Max tool iterations (default: 10 for agentic, 5 for simple) */
  maxToolRounds?: number;
  /** Document store for RAG (enables context retrieval) */
  documentStore?: IDocumentStore;
  /** RAG configuration options */
  ragOptions?: RAGOptions;
  /** Default timeout for all requests in milliseconds */
  defaultTimeout?: number;
  /** Maximum image file size in bytes (default: 20MB) */
  maxImageSize?: number;
}

ChatOptions

Per-request options that override defaults.

interface ChatOptions {
  /** Sampling temperature (0-2, higher = more random) */
  temperature?: number;
  /** Maximum number of tokens to generate */
  maxTokens?: number;
  /** Nucleus sampling parameter (0-1) */
  topP?: number;
  /** Override the model for this request */
  model?: string;
  /** Maximum tool calling iterations */
  maxToolRounds?: number;
  /** Request timeout in milliseconds (overrides defaultTimeout) */
  timeout?: number;
  /** AbortSignal for cancelling the request */
  abortSignal?: AbortSignal;
  /** Image optimization settings (requires optional 'sharp' package) */
  imageOptimization?: ImageOptimizationOptions;
  /** Additional provider-specific options */
  [key: string]: unknown;
}

Message

type MessageRole = 'user' | 'assistant' | 'system' | 'tool';

interface Message {
  role: MessageRole;
  content: string | ContentPart[];
  name?: string;
  toolCallId?: string;
}

ContentPart

Multi-modal content parts for vision support.

type ContentPart = TextPart | ImagePart;

interface TextPart {
  type: 'text';
  text: string;
}

interface ImagePart {
  type: 'image';
  image: string; // URL or base64 data URL
}

ProviderPlugin

Interface for all LLM providers. All built-in providers (OpenAI, Anthropic, Google, Ollama) and custom providers implement this interface.

interface ProviderPlugin {
  /** Unique provider identifier (e.g., 'openai', 'anthropic') */
  readonly name: string;

  /** Provider capabilities declaration */
  readonly capabilities: ProviderCapabilities;

  /** Basic chat completion */
  chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;

  /** Streaming chat completion */
  stream(messages: Message[], options?: ChatOptions): AsyncIterableIterator<StreamChunk>;

  /** Chat with tool/function calling */
  chatWithTools(
    messages: Message[],
    tools: Record<string, Tool>,
    options?: ChatOptions
  ): Promise<ChatResponse>;

  /** Streaming chat with tool/function calling */
  streamWithTools(
    messages: Message[],
    tools: Record<string, Tool>,
    options?: ChatOptions
  ): AsyncIterableIterator<StreamChunk>;
}

TIP

The Tool type is from the Vercel AI SDK. See Tools & Agents for usage examples.

ProviderCapabilities

Declares what features a provider supports.

interface ProviderCapabilities {
  /** Basic chat completion */
  chat: boolean;
  /** Streaming responses */
  streaming: boolean;
  /** Function/tool calling */
  toolCalling: boolean;
  /** Image input support */
  vision: boolean;
  /** Audio input/output */
  audio: boolean;
}

IProvider

Minimal provider interface (methods only). ProviderPlugin extends this with name and capabilities.

interface IProvider {
  chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;
  stream(messages: Message[], options?: ChatOptions): AsyncIterableIterator<StreamChunk>;
  chatWithTools(messages: Message[], tools: Record<string, Tool>, options?: ChatOptions): Promise<ChatResponse>;
  streamWithTools(messages: Message[], tools: Record<string, Tool>, options?: ChatOptions): AsyncIterableIterator<StreamChunk>;
}

ImageOptimizationOptions

Options for optimizing images before encoding. Requires the optional sharp package.

interface ImageOptimizationOptions {
  /** Maximum width in pixels (default: 2048) */
  maxWidth?: number;
  /** Maximum height in pixels (default: 2048) */
  maxHeight?: number;
  /** Quality for JPEG/WebP output, 1-100 (default: 85) */
  quality?: number;
  /** Convert all images to this format */
  format?: 'jpeg' | 'png' | 'webp';
}

RAGOptions

Configuration for Retrieval-Augmented Generation.

interface RAGOptions {
  /** Number of chunks to retrieve (default: 3) */
  topK?: number;
  /** Minimum similarity score threshold (default: 0) */
  minScore?: number;
  /** Custom template for context injection */
  contextTemplate?: string;
  /** Throw error on RAG failure instead of continuing (default: false) */
  failOnError?: boolean;
  /** Callback invoked when RAG retrieval fails */
  onError?: (error: Error) => void | Promise<void>;
}

RetryConfig

Configuration for retry behavior on failed requests.

interface RetryConfig {
  /** Maximum number of retry attempts */
  maxAttempts: number;
  /** Initial backoff delay in milliseconds */
  initialBackoffMs: number;
  /** Maximum backoff delay in milliseconds */
  maxBackoffMs: number;
  /** Multiplier for exponential backoff */
  backoffMultiplier: number;
}

RateLimitConfig

Configuration for rate limiting API requests.

interface RateLimitConfig {
  /** Maximum requests allowed per minute */
  requestsPerMinute?: number;
}

AuthConfig

Authentication configuration for providers.

interface AuthConfig {
  type: 'api-key';
  apiKey: string;
}