@mencraft/lore-headless/dist/index.d.ts

A headless library for chat streaming functionality

/**
 * Event types for the chat stream
 */
declare enum EventType {
    BatchDataIntermediate = "batch_data_intermediate",
    TextBatchIntermediate = "text_batch_intermediate",
    TextStreamIntermediate = "text_stream_intermediate",
    ToolCallIntermediate = "tool_call_intermediate",
    BatchDataOutput = "batch_data_output",
    TextBatchOutput = "text_batch_output",
    TextStreamOutput = "text_stream_output",
    ToolCallOutput = "tool_call_output",
    End = "end",
    Error = "error"
}
/**
 * Node output types
 */
declare enum LoreNodeOutputTypes {
    HYDE_PROMPT = "HydePromptNode",
    PROMPT = "PromptNode",
    BOOL_PROMPT = "BoolPromptNode",
    DEFAULT_RESPONSE = "DefaultResponseNode",
    QUERY = "QueryNode",
    ROUTER = "RouterNode",
    REACT = "ReactNode",
    CONDITIONAL = "ConditionalNode",
    SEARCH = "SearchNode"
}
/**
 * Metadata for stream events
 */
interface EventMetadata {
    timestamp: string;
}
/**
 * Stream event interface
 */
interface StreamEvent<T = any> {
    event_type: EventType;
    event_data: T | null;
    metadata: EventMetadata;
}
/**
 * Chat request interface
 */
interface ChatRequest {
    user: string;
    session: string;
    query: string;
    testNodeId?: string | undefined;
}
interface GraphChatRequest {
    user: string;
    session: string;
    query: string;
    testNodeId: string | undefined;
    flow: {
        nodes: any[];
        edges: any[];
        viewport: any;
    };
}
/**
 * Callbacks for chat stream
 */
interface ChatStreamCallbacks {
    graphId?: string;
    onTextStream?: (text: string) => void;
    onBatchData?: (data: NodeResult) => void;
    onTextBatch?: (data: NodeResult) => void;
    onToolCall?: (toolCall: any) => void;
    onBatchDataIntermediate?: (data: NodeResult) => void;
    onTextBatchIntermediate?: (data: NodeResult) => void;
    onTextStreamIntermediate?: (text: string) => void;
    onToolCallIntermediate?: (toolCall: any) => void;
    onEnd?: () => void;
    onError?: (error: Error) => void;
    onSystemMessage?: (text: string) => void;
    onEvent?: (event: StreamEvent) => void;
}
/**
 * Base node interface
 */
interface BaseNode {
    node_type: string;
    [key: string]: any;
}
/**
 * Query node interface
 */
interface QueryNode extends BaseNode {
    node_type: LoreNodeOutputTypes.QUERY;
    query_result: Record<string, any[]>;
}
/**
 * Image data interface
 */
interface ImageData {
    [key: string]: {
        image_name: string;
        storage_type: string;
        url: string;
        uuid: string;
    };
}
/**
 * Graph structure error response
 */
interface GraphStructureErrorResponse {
    validation_errors?: Array<{
        node_id: string;
        message: string;
        error_type: string;
    }>;
    test_failure?: boolean;
    too_many_graphs?: boolean;
    tests?: Array<{
        error?: boolean;
        error_text?: string;
        events?: StreamEvent[];
    }>;
}
/**
 * Feedback request interface
 */
interface FeedbackRequest {
    user: string;
    session: string;
    query: string;
    response: string;
    feedback: string;
    feedback_value: number;
}
/**
 * API response interface
 */
interface ApiResponse<T> {
    data?: T;
    status: number;
    statusText: string;
    headers: Headers;
}
interface NodeResult {
    identity?: Identity;
    node_type: LoreNodeTypes;
    node_id: string;
    node_results?: string | ConditionalNodeResult | ModelResult | ModelResultBool | HydeResult | Record<string, unknown> | RouterResult;
}
declare enum LoreNodeTypes {
    HYDE_PROMPT = "HydePromptNode",
    PROMPT = "PromptNode",
    BOOL_PROMPT = "BoolPromptNode",
    DEFAULT_RESPONSE = "DefaultResponseNode",
    QUERY = "QueryNode",
    ROUTER = "RouterNode",
    REACT = "ReactNode",
    CONDITIONAL = "ConditionalNode",
    SEARCH = "SearchNode"
}
type ConditionType = "equals" | "contains" | "greater_than" | "less_than" | "regex" | "llm" | "has_memory";
interface ConditionalNodeResult {
    condition_result: string;
    matched_condition: Condition;
    next_node_id: string;
}
interface ModelResult {
    input_prompt: Prompt;
    input_token_count?: number;
    llm_output?: string;
    llm_token_count?: number;
    model?: string;
    memory_prompt?: Prompt;
    system_prompt?: Prompt;
}
interface Condition {
    type: ConditionType;
    value?: string;
    prompt?: Prompt;
    target_node_id: string;
}
interface ModelResultBool extends ModelResult {
    bool_returned: boolean;
}
interface RouterResult extends ModelResult {
    next_node_id: string;
}
interface QueryNodeResult extends NodeResult {
    query_result: {
        [key: string]: string[];
    };
}
interface HydeResult {
    model_output: ModelResult;
    hyde_model_output: ModelResult;
}
type LoreOutput = {
    result: string;
    experiment_logs: NodeResult[];
    experiment_node_ids: string[];
};
interface Prompt {
    messages: Message[];
}
declare enum LLMRole {
    ASSISTANT = "assistant",
    USER = "user",
    SYSTEM = "system",
    DEVELOPER = "developer"
}
interface Message {
    role: LLMRole;
    content: string;
}
interface Identity {
    user_id: string;
    session_id: string;
    experiment: string;
    graph_id: string;
    client_id: string;
}
declare enum ToolParameterType {
    STRING = "string",
    NUMBER = "number",
    INTEGER = "integer",
    BOOLEAN = "boolean",
    OBJECT = "object",
    ARRAY = "array"
}
interface ToolParameter {
    name: string;
    type: ToolParameterType;
    description: string;
    required?: boolean;
    enum?: any[];
}
interface ToolConfig {
    name: string;
    description: string;
    parameters: ToolParameter[];
}
interface ToolCall {
    tool_name: string;
    str_ai_parameters?: string;
    error?: boolean;
    tool_id?: string;
    ai_parameters?: Record<string, any>;
}
interface ToolCallResult extends ToolCall {
    result?: Record<string, any> | any[];
    str_result?: string;
}

/**
 * Authentication credentials
 */
interface AuthCredentials {
    clientId: string;
    token: string;
}
/**
 * API client for making requests
 */
declare class LoreClient {
    private chatUrl;
    private validationUrl;
    /**
     * Creates an instance of the LoreClient
     * @param mode The mode to use for the API client. One of 'production', 'staging', or 'development'.
     * @param customChatUrl Optional custom chat URL to use instead of the default based on the mode.
     * @param customValidationUrl Optional custom validation URL to use instead of the default based on the mode.
     * @throws Error if customChatUrl or customValidationUrl is provided but the other is not.
     */
    constructor(mode?: 'production' | 'staging' | 'development', customChatUrl?: string, customValidationUrl?: string);
    /**
     * Make a POST request to the API
     * @param endpoint API endpoint
     * @param auth Authentication credentials
     * @param body Request body
     * @param options Request options
     * @returns API response
     */
    post<T>(endpoint: string, auth: AuthCredentials, body?: any, options?: RequestInit & {
        headers?: Record<string, string>;
        useValidationUrl?: boolean;
    }): Promise<ApiResponse<T>>;
    /**
     * Make a chat POST request to the API
     * @param endpoint API endpoint
     * @param auth Authentication credentials
     * @param body Request body
     * @param options Request options
     * @returns API response
     */
    chatPost<T>(endpoint: string, auth: AuthCredentials, body?: any, options?: RequestInit & {
        headers?: Record<string, string>;
    }): Promise<ApiResponse<T>>;
    /**
     * Make an admin POST request to the API
     * @param endpoint API endpoint
     * @param clientId Client ID
     * @param firebaseIdToken Firebase ID token
     * @param body Request body
     * @param options Request options
     * @returns API response
     */
    adminPost<T>(endpoint: string, auth: AuthCredentials, body?: any, options?: RequestInit & {
        headers?: Record<string, string>;
        useValidationUrl?: boolean;
    }): Promise<ApiResponse<T>>;
}

/**
 * Chat stream manager for handling chat streams
 */
declare class ChatStreamManager {
    private loreClient;
    private readerRef;
    private callbacks;
    private auth;
    /**
     * Create a new chat stream manager
     * @param loreClient Lore client
     * @param auth Authentication credentials
     * @param callbacks Callbacks for stream events
     */
    constructor(loreClient: LoreClient, auth: AuthCredentials, callbacks?: ChatStreamCallbacks);
    /**
     * Set callbacks for stream events
     * @param callbacks Callbacks for stream events
     */
    setCallbacks(callbacks: ChatStreamCallbacks): void;
    /**
     * Process a chat stream
     * @param stream Readable stream
     */
    private processChatStream;
    /**
     * Handle graph validation errors
     * @param response Graph structure error response
     * @returns boolean indicating if validation passed (true) or failed (false)
     */
    private handleGraphValidationErrors;
    /**
     * Process a stream event
     * @param event Stream event
     */
    private processEvent;
    /**
     * Start a chat stream
     * @param request Chat request
     * @param graphId Graph ID
     * @param skipValidation Skip graph validation
     * @deprecated since version 0.1.10 - Use startChatStream instead.
     */
    startGraphChatStream(request: ChatRequest, graphId: string, skipValidation?: boolean): Promise<void>;
    startChatStream(request: GraphChatRequest | ChatRequest, graphId: string, useAdminServer?: boolean): Promise<void>;
    /**
     * Cancel the current stream
     */
    cancelStream(): void;
    /**
     * Send feedback for a chat
     * @param feedback Feedback request
     * @param graphId Graph ID
     */
    sendFeedback(feedback: FeedbackRequest, graphId?: string): Promise<any>;
    /**
     * Validate a graph structure with a test query
     * @param query Test query to validate with
     * @param graphId Graph ID to validate
     * @returns Promise<boolean> True if validation passed, false otherwise
     */
    validateGraph(request: ChatRequest, graphId: string): Promise<boolean>;
}

export { ApiResponse, AuthCredentials, BaseNode, ChatRequest, ChatStreamCallbacks, ChatStreamManager, Condition, ConditionType, ConditionalNodeResult, EventMetadata, EventType, FeedbackRequest, GraphChatRequest, GraphStructureErrorResponse, HydeResult, Identity, ImageData, LLMRole, LoreClient, LoreNodeOutputTypes, LoreNodeTypes, LoreOutput, Message, ModelResult, ModelResultBool, NodeResult, Prompt, QueryNode, QueryNodeResult, RouterResult, StreamEvent, ToolCall, ToolCallResult, ToolConfig, ToolParameter, ToolParameterType };