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

React components for Hashbrown AI

import { Chat, type ModelInput, s, type TransportOrFactory } from '@hashbrownai/core';
/**
 * Options for the `useStructuredChat` hook.
 *
 * @public
 * @typeParam Schema - The schema to use for the chat.
 * @typeParam Tools - The set of tool definitions available to the chat.
 * @typeParam Output - The type of the output from the chat.
 */
export interface UseStructuredChatOptions<Schema extends s.HashbrownType, Tools extends Chat.AnyTool, Output extends s.Infer<Schema> = s.Infer<Schema>> {
    /**
     * The LLM model to use for the chat.
     *
     */
    model: ModelInput;
    /**
     * The system message to use for the chat.
     */
    system: string;
    /**
     * The schema to use for the chat.
     */
    schema: Schema;
    /**
     * The initial messages for the chat.
     * default: 1.0
     */
    messages?: Chat.Message<Output, 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;
    /**
     * Whether this structured chat is expected to produce UI elements.
     */
    ui?: boolean;
    /**
     * Optional thread identifier used to load or continue an existing conversation.
     */
    threadId?: string;
}
/**
 * The result object-type returned by the `useStructuredChat` hook that provides functions and state for interacting with the chat.
 *
 * @public
 * @typeParam Output - The type of the output from the chat.
 * @typeParam Tools - The set of tool definitions available to the chat.
 */
export interface UseStructuredChatResult<Output, Tools extends Chat.AnyTool> {
    /**
     * An array of chat messages.
     */
    messages: Chat.Message<Output, Tools>[];
    /**
     * Function to update the chat messages.
     * @param messages - The new array of chat messages.
     */
    setMessages: (messages: Chat.Message<Output, Tools>[]) => void;
    /**
     * Function to send a new chat message.
     * @param message - The chat message to send.
     */
    sendMessage: (message: Chat.Message<Output, Tools>) => void;
    /**
     * Function to cause current messages to be resent.  Can be used after an error in chat.
     */
    resendMessages: () => 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.
     */
    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<Output, Tools> | undefined;
    /** Whether a thread load request is in flight. */
    isLoadingThread: boolean;
    /** Whether a thread save request is in flight. */
    isSavingThread: boolean;
    /** Error encountered while loading a thread. */
    threadLoadError: {
        error: string;
        stacktrace?: string;
    } | undefined;
    /** Error encountered while saving a thread. */
    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 receive messages and monitor the state of the chat.
 *
 * @public
 * @remarks
 * The `useStructuredChat` hook provides functionality for structured chats. Structured chats are used when you want to use the LLM to generate structured data according to a defined schema. This is particularly useful for:
 * - Generating typed data structures
 * - Creating form responses
 * - Building UI components
 * - Extracting information into a specific format
 *
 * @returns An object containing chat state and functions to interact with the chat.
 *
 * @example
 * In this example, the LLM will respond with a JSON object containing the translations of the input message into English, Spanish, and French.
 * ```tsx
 * const { messages, sendMessage } = useStructuredChat({
 *   model: 'gpt-4o',
 *   system: 'You are a helpful translator that provides accurate translations.',
 *   schema: s.object('Translations', {
 *     english: s.string('English translation'),
 *     spanish: s.string('Spanish translation'),
 *     french: s.string('French translation')
 *   }),
 * });
 * ```
 */
export declare function useStructuredChat<Schema extends s.HashbrownType, Tools extends Chat.AnyTool, Output extends s.Infer<Schema> = s.Infer<Schema>>(options: UseStructuredChatOptions<Schema, Tools, Output>): UseStructuredChatResult<Output, Tools>;