@hashbrownai/react/src/hooks/use-chat.d.ts

React components for Hashbrown AI

import { type Chat, type ModelInput, type TransportOrFactory } from '@hashbrownai/core';
/**
 * Options for the `useChat` hook.
 *
 * @public
 * @typeParam Tools - The set of tool definitions available to the chat.
 */
export interface UseChatOptions<Tools extends Chat.AnyTool> {
    /**
     * The LLM model to use for the chat.
     *
     */
    model: ModelInput;
    /**
     * The system message to use for the chat.
     */
    system: string;
    /**
     * The initial messages for the chat.
     * default: 1.0
     */
    messages?: Chat.Message<string, Tools>[];
    /**
     * The tools to make available use for the chat.
     * default: []
     */
    tools?: Tools[];
    /**
     * The debounce time between sends to the endpoint.
     * default: 150
     */
    debounceTime?: number;
    /**
     * Number of retries if an error is received.
     * default: 0
     */
    retries?: number;
    /**
     * The name of the hook, useful for debugging.
     */
    debugName?: string;
    /**
     * Optional transport override for this hook.
     */
    transport?: TransportOrFactory;
    /**
     * Optional thread identifier used to load or continue an existing conversation.
     */
    threadId?: string;
}
/**
 * The result object-type returned by the `useChat` hook that provides functions and state for interacting with the chat.
 *
 * @public
 * @typeParam Tools - The set of tool definitions available to the chat.
 */
export interface UseChatResult<Tools extends Chat.AnyTool> {
    /**
     * An array of chat messages.
     */
    messages: Chat.Message<string, Tools>[];
    /**
     * Function to update the chat messages.
     * @param messages - The new array of chat messages.
     */
    setMessages: (messages: Chat.Message<string, Tools>[]) => void;
    /**
     * Function to send a new chat message.
     * @param message - The chat message to send.
     */
    sendMessage: (message: Chat.Message<string, Tools>) => void;
    /**
     * Function to stop the chat.
     */
    stop: (clearStreamingMessage?: boolean) => void;
    /**
     * Reload the chat, useful for retrying when an error occurs.
     */
    reload: () => void;
    /**
     * The error encountered during chat operations, if any.
     */
    error: Error | undefined;
    /**
     * Whether the chat is receiving a response.
     */
    isReceiving: boolean;
    /**
     * Whether the chat is sending a response.
     */
    isSending: boolean;
    /**
     * Whether the chat is currently generating (between start and finish/error frames).
     */
    isGenerating: boolean;
    /**
     * Whether the chat is running tool calls.
     */
    isRunningToolCalls: boolean;
    /**
     * Aggregate loading flag across transport, generation, tool-calls, and thread load/save.
     */
    isLoading: boolean;
    /**
     * Whether the current request has exhausted retries.
     */
    exhaustedRetries: boolean;
    /**
     * Transport/request failure before generation frames arrive.
     */
    sendingError: Error | undefined;
    /**
     * Error emitted during generation frames.
     */
    generatingError: Error | undefined;
    /**
     * The last assistant message.
     */
    lastAssistantMessage: Chat.AssistantMessage<string, Tools> | undefined;
    /**
     * Whether a thread load request is in flight.
     */
    isLoadingThread: boolean;
    /**
     * Whether a thread save request is in flight.
     */
    isSavingThread: boolean;
    /**
     * Thread loading error, if present.
     */
    threadLoadError: {
        error: string;
        stacktrace?: string;
    } | undefined;
    /**
     * Thread saving error, if present.
     */
    threadSaveError: {
        error: string;
        stacktrace?: string;
    } | undefined;
}
/**
 * This React hook creates a chat instance used to interact with the LLM.
 * The result object contains functions and state enabling you to send and recieve messages and monitor the state of the chat.
 *
 * The `useChat` hook provides the most basic functionality for un-structured chats.  Unstructured chats include things like general chats and natural language controls.
 *
 * @public
 * @returns An object containing chat state and functions to interact with the chat.
 * @typeParam Tools - The set of tool definitions available to the chat.
 * @example
 * This example demonstrates how to use the `useChat` hook to create a simple chat component.
 *
 * ```tsx
 * const MyChatComponent = () => {
 *   const { messages, sendMessage, status } = useChat({
 *     model: 'gpt-4o',
 *     system: 'You are a helpful assistant.',
 *     tools: [],
 *   });
 *
 *   const handleSendMessage = () => {
 *     sendMessage({ role: 'user', content: 'Hello, how are you?' });
 *   };
 *
 *   return (
 *     <div>
 *       <button onClick={handleSendMessage}>Send Message</button>
 *       <div>Status: {status}</div>
 *       <ul>
 *         {messages.map((msg, index) => (
 *           <li key={index}>{msg.content}</li>
 *         ))}
 *       </ul>
 *     </div>
 *   );
 * };
 * ```
 */
export declare function useChat<Tools extends Chat.AnyTool>(
/**
 * The options for the chat.
 */
options: UseChatOptions<Tools>): UseChatResult<Tools>;