BotSharp/src/Infrastructure/BotSharp.Abstraction/Conversations/IConversationHook.cs

namespace BotSharp.Abstraction.Conversations;

public interface IConversationHook
{
    int Priority { get; }
    Agent Agent { get; }
    List<RoleDialogModel> Dialogs { get; }
    IConversationHook SetAgent(Agent agent);

    Conversation Conversation { get; }
    IConversationHook SetConversation(Conversation conversation);

    /// <summary>
    /// Triggered once for every new conversation.
    /// </summary>
    /// <param name="conversation"></param>
    /// <returns></returns>
    Task OnConversationInitialized(Conversation conversation);

    /// <summary>
    /// Triggered when dialog history is loaded.
    /// </summary>
    /// <param name="dialogs"></param>
    /// <returns></returns>
    Task OnDialogsLoaded(List<RoleDialogModel> dialogs);

    Task OnStateLoaded(ConversationState state);
    Task OnStateChanged(string name, string preValue, string currentValue);

    Task OnMessageReceived(RoleDialogModel message);

    /// <summary>
    /// Triggered before LLM calls function.
    /// </summary>
    /// <param name="message"></param>
    /// <returns></returns>
    Task OnFunctionExecuting(RoleDialogModel message);

    /// <summary>
    /// Triggered when the function calling completed.
    /// </summary>
    /// <param name="message"></param>
    /// <returns></returns>
    Task OnFunctionExecuted(RoleDialogModel message);

    Task OnResponseGenerated(RoleDialogModel message);

    /// <summary>
    /// LLM detected the current task is completed.
    /// It's useful for the situation of multiple tasks in the same conversation.
    /// </summary>
    /// <param name="conversation"></param>
    /// <returns></returns>
    Task OnCurrentTaskEnding(RoleDialogModel message);

    /// <summary>
    /// LLM detected the whole conversation is going to be end.
    /// </summary>
    /// <param name="conversation"></param>
    /// <returns></returns>
    Task OnConversationEnding(RoleDialogModel message);

    /// <summary>
    /// LLM can't handle user's request or user requests human being to involve.
    /// </summary>
    /// <param name="conversation"></param>
    /// <returns></returns>
    Task OnHumanInterventionNeeded(RoleDialogModel message);
}