Merge pull request #171 from Deep-Blue-2013/master

Add IContentGeneratingHook.

Author: Deep-Blue-2013

docs/architecture/hooks.md

@@ -5,25 +5,40 @@
 ## Agent Hook
 `IAgentHook`
 ```csharp
+// Triggered when agent is loading.
 bool OnAgentLoading(ref string id);
 bool OnInstructionLoaded(string template, Dictionary<string, object> dict);
 bool OnFunctionsLoaded(List<FunctionDef> functions);
 bool OnSamplesLoaded(ref string samples);
-Agent OnAgentLoaded();
+
+// Triggered when agent is loaded completely.
+void OnAgentLoaded(Agent agent);
 ```
 More information about agent hook please go to [Agent Hook](../agent/hook.md).
 
 ## Conversation Hook
 `IConversationHook`
 ```csharp
+// Triggered once for every new conversation.
+Task OnConversationInitialized(Conversation conversation);
 Task OnDialogsLoaded(List<RoleDialogModel> dialogs);
-Task BeforeCompletion();
+Task OnMessageReceived(RoleDialogModel message);
+
+// Triggered before LLM calls function.
 Task OnFunctionExecuting(RoleDialogModel message);
+
+// Triggered when the function calling completed.
 Task OnFunctionExecuted(RoleDialogModel message);
-Task AfterCompletion(RoleDialogModel message);
+Task OnResponseGenerated(RoleDialogModel message);
+
+// LLM detected the current task is completed.
+Task CurrentTaskEnding(RoleDialogModel conversation);
 
 // LLM detected the user's intention to end the conversation
 Task ConversationEnding(RoleDialogModel conversation);
+
+// LLM can't handle user's request or user requests human being to involve.
+Task HumanInterventionNeeded(RoleDialogModel conversation);
 ```
 More information about conversation hook please go to [Conversation Hook](../conversation/hook.md).
 

src/Infrastructure/BotSharp.Abstraction/Agents/IAgentHook.cs

@@ -8,13 +8,13 @@ public interface IAgentHook
     void SetAget(Agent agent);
 
     /// <summary>
-    /// Triggered before loading, you can change the returned id to switch agent.
+    /// Triggered when agent is loading.
+    /// Return different agent for redirection purpose.
     /// </summary>
     /// <param name="id">Agent Id</param>
     /// <returns></returns>
     bool OnAgentLoading(ref string id);
 
-
     bool OnInstructionLoaded(string template, Dictionary<string, object> dict);
 
     bool OnFunctionsLoaded(List<FunctionDef> functions);

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

@@ -36,7 +36,23 @@ public virtual Task OnStateChanged(string name, string preValue, string currentV
         return Task.CompletedTask;
     }
 
-    public virtual Task BeforeCompletion(RoleDialogModel message)
+    public virtual Task OnDialogsLoaded(List<RoleDialogModel> dialogs)
+    {
+        _dialogs = dialogs;
+        return Task.CompletedTask;
+    }
+
+    public virtual Task ConversationEnding(RoleDialogModel message)
+    {
+        return Task.CompletedTask;
+    }
+
+    public virtual Task CurrentTaskEnding(RoleDialogModel conversation)
+    {
+        return Task.CompletedTask;
+    }
+
+    public virtual Task HumanInterventionNeeded(RoleDialogModel conversation)
     {
         return Task.CompletedTask;
     }
@@ -51,18 +67,17 @@ public virtual Task OnFunctionExecuted(RoleDialogModel message)
         return Task.CompletedTask;
     }
 
-    public virtual Task AfterCompletion(RoleDialogModel message)
+    public virtual Task OnMessageReceived(RoleDialogModel message)
     {
         return Task.CompletedTask;
     }
 
-    public virtual Task OnDialogsLoaded(List<RoleDialogModel> dialogs)
+    public virtual Task OnResponseGenerated(RoleDialogModel message)
     {
-        _dialogs = dialogs;
         return Task.CompletedTask;
     }
 
-    public virtual Task ConversationEnding(RoleDialogModel message)
+    public virtual Task OnConversationInitialized(Conversation conversation)
     {
         return Task.CompletedTask;
     }

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

@@ -4,14 +4,21 @@ public interface IConversationHook
 {
     int Priority { get; }
     Agent Agent { get; }
+    List<RoleDialogModel> Dialogs { get; }
     IConversationHook SetAgent(Agent agent);
 
     Conversation Conversation { get; }
     IConversationHook SetConversation(Conversation conversation);
 
-    List<RoleDialogModel> Dialogs { get; }
     /// <summary>
-    /// Triggered when dialog history is loaded
+    /// 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>
@@ -20,10 +27,43 @@ public interface IConversationHook
     Task OnStateLoaded(ConversationState state);
     Task OnStateChanged(string name, string preValue, string currentValue);
 
-    Task BeforeCompletion(RoleDialogModel message);
+    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 AfterCompletion(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 CurrentTaskEnding(RoleDialogModel conversation);
+
+    /// <summary>
+    /// LLM detected the whole conversation is going to be end.
+    /// </summary>
+    /// <param name="conversation"></param>
+    /// <returns></returns>
     Task ConversationEnding(RoleDialogModel conversation);
+
+    /// <summary>
+    /// LLM can't handle user's request or user requests human being to involve.
+    /// </summary>
+    /// <param name="conversation"></param>
+    /// <returns></returns>
+    Task HumanInterventionNeeded(RoleDialogModel conversation);
 }

src/Infrastructure/BotSharp.Abstraction/MLTasks/IContentGeneratingHook.cs

@@ -0,0 +1,19 @@
+namespace BotSharp.Abstraction.MLTasks;
+
+/// <summary>
+/// Model content generating hook, it can be used for logging, metrics and tracing.
+/// </summary>
+public interface IContentGeneratingHook
+{
+    /// <summary>
+    /// Before content generating.
+    /// </summary>
+    /// <returns></returns>
+    Task BeforeGenerating(Agent agent, List<RoleDialogModel> conversations) => Task.CompletedTask;
+
+    /// <summary>
+    /// After content generated.
+    /// </summary>
+    /// <returns></returns>
+    Task AfterGenerated(RoleDialogModel message, TokenStatsModel tokenStats) => Task.CompletedTask;
+}

src/Infrastructure/BotSharp.Core/Conversations/Services/ConversationService.SendMessage.cs

@@ -32,7 +32,7 @@ public async Task<bool> SendMessage(string agentId,
             hook.SetAgent(agent)
                 .SetConversation(conversation);
 
-            await hook.BeforeCompletion(incoming);
+            await hook.OnMessageReceived(incoming);
 
             // Interrupted by hook
             if (incoming.StopCompletion)
@@ -79,14 +79,6 @@ private async Task<Conversation> GetConversationRecord(string agentId)
 
     private async Task HandleAssistantMessage(RoleDialogModel message, Func<RoleDialogModel, Task> onMessageReceived)
     {
-        var hooks = _services.GetServices<IConversationHook>().ToList();
-
-        // After chat completion hook
-        foreach (var hook in hooks)
-        {
-            await hook.AfterCompletion(message);
-        }
-
         var routingSetting = _services.GetRequiredService<RoutingSettings>();
         var agentName = routingSetting.RouterId == message.CurrentAgentId ? 
             "Router" : 
@@ -101,6 +93,12 @@ private async Task HandleAssistantMessage(RoleDialogModel message, Func<RoleDial
         _logger.LogInformation(text);
 #endif
 
+        var hooks = _services.GetServices<IConversationHook>().ToList();
+        foreach (var hook in hooks)
+        {
+            await hook.OnResponseGenerated(message);
+        }
+
         await onMessageReceived(message);
 
         // Add to dialog history

src/Infrastructure/BotSharp.Core/Conversations/Services/ConversationService.cs

@@ -1,3 +1,4 @@
+using BotSharp.Abstraction.Conversations.Models;
 using BotSharp.Abstraction.Repositories;
 
 namespace BotSharp.Core.Conversations.Services;
@@ -64,6 +65,13 @@ public async Task<Conversation> NewConversation(Conversation sess)
         record.Title = "New Conversation";
 
         db.CreateNewConversation(record);
+
+        var hooks = _services.GetServices<IConversationHook>().ToList();
+        foreach (var hook in hooks)
+        {
+            await hook.OnConversationInitialized(record);
+        }
+
         return record;
     }
 

src/Infrastructure/BotSharp.Core/Routing/Handlers/ConversationEndRoutingHandler.cs

@@ -32,7 +32,7 @@ public async Task<RoleDialogModel> Handle(IRoutingService routing, FunctionCallF
 
         foreach (var hook in hooks)
         {
-            await hook.OnFunctionExecuting(result);
+            await hook.ConversationEnding(result);
         }
 
         return result;

src/Infrastructure/BotSharp.Core/Routing/Handlers/HumanInterventionNeededHandler.cs

@@ -0,0 +1,41 @@
+using BotSharp.Abstraction.Functions.Models;
+using BotSharp.Abstraction.Routing;
+using BotSharp.Abstraction.Routing.Settings;
+
+namespace BotSharp.Core.Routing.Handlers;
+
+public class HumanInterventionNeededHandler : RoutingHandlerBase, IRoutingHandler
+{
+    public string Name => "human_intervention_needed";
+
+    public string Description => "Reach out to a real human or customer representative.";
+
+    private readonly RoutingSettings _settings;
+
+    public HumanInterventionNeededHandler(IServiceProvider services, ILogger<HumanInterventionNeededHandler> logger, RoutingSettings settings)
+        : base(services, logger, settings)
+    {
+        _settings = settings;
+    }
+
+    public async Task<RoleDialogModel> Handle(IRoutingService routing, FunctionCallFromLlm inst)
+    {
+        var result = new RoleDialogModel(AgentRole.Assistant, inst.Response)
+        {
+            CurrentAgentId = _settings.RouterId,
+            FunctionName = inst.Function,
+            ExecutionData = inst
+        };
+
+        var hooks = _services.GetServices<IConversationHook>()
+            .OrderBy(x => x.Priority)
+            .ToList();
+
+        foreach (var hook in hooks)
+        {
+            await hook.HumanInterventionNeeded(result);
+        }
+
+        return result;
+    }
+}

src/Infrastructure/BotSharp.Core/Routing/Handlers/TaskEndRoutingHandler.cs

@@ -23,8 +23,24 @@ public TaskEndRoutingHandler(IServiceProvider services, ILogger<TaskEndRoutingHa
     {
     }
 
-    public Task<RoleDialogModel> Handle(IRoutingService routing, FunctionCallFromLlm inst)
+    public async Task<RoleDialogModel> Handle(IRoutingService routing, FunctionCallFromLlm inst)
     {
-        throw new NotImplementedException();
+        var result = new RoleDialogModel(AgentRole.Assistant, inst.Response)
+        {
+            CurrentAgentId = _settings.RouterId,
+            FunctionName = inst.Function,
+            ExecutionData = inst
+        };
+
+        var hooks = _services.GetServices<IConversationHook>()
+            .OrderBy(x => x.Priority)
+            .ToList();
+
+        foreach (var hook in hooks)
+        {
+            await hook.CurrentTaskEnding(result);
+        }
+
+        return result;
     }
 }