merge latest code

Directory.Build.props

@@ -1,9 +1,9 @@
 <Project>
     <PropertyGroup>
         <TargetFramework>net8.0</TargetFramework>
-        <LangVersion>12.0</LangVersion>
-        <BotSharpVersion>1.0.1</BotSharpVersion>
-        <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
+        <LangVersion>10.0</LangVersion>
+        <BotSharpVersion>1.2.1</BotSharpVersion>
+        <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
         <GenerateDocumentationFile>false</GenerateDocumentationFile>
     </PropertyGroup>
 </Project>

README.md

@@ -3,7 +3,6 @@
 
 [![Discord](https://img.shields.io/discord/1106946823282761851?label=Discord)](https://discord.com/channels/1106946823282761851/1106947212459642991)
 [![QQ群聊](https://img.shields.io/static/v1?label=QQ&message=群聊&color=brightgreen)](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=sN9VVMwbWjs5L0ATpizKKxOcZdEPMrp8&authKey=RLDw41bLTrEyEgZZi%2FzT4pYk%2BwmEFgFcrhs8ZbkiVY7a4JFckzJefaYNW6Lk4yPX&noverify=0&group_code=985366726)
-[![Join the chat at https://gitter.im/publiclab/publiclab](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/sci-sharp/community) 
 [![Apache 2.0](https://img.shields.io/hexpm/l/plug.svg)](https://raw.githubusercontent.com/Oceania2018/BotSharp/master/LICENSE) 
 [![NuGet](https://img.shields.io/nuget/dt/BotSharp.Core.svg)](https://www.nuget.org/packages/BotSharp.Core) 
 [![Build status](https://ci.appveyor.com/api/projects/status/qx2dx5ca5hjqodm5?svg=true)](https://ci.appveyor.com/project/Haiping-Chen/botsharp)
@@ -88,6 +87,7 @@ BotSharp uses component design, the kernel is kept to a minimum, and business fu
 - BotSharp.Plugin.HuggingFace
 - BotSharp.Plugin.LLamaSharp
 - BotSharp.Plugin.SemanticKernel
+- BotSharp.Plugin.SparkDesk
 
 #### Messaging / Channel
 - BotSharp.OpenAPI

docs/llm/function.md

@@ -2,4 +2,32 @@
 
 A **calling function** is a function that is passed as an argument to another function and is executed after a specific event or action occurs. In the context of **large language models (LLMs)**, calling functions can be used to hook into various stages of an LLM application. They are useful for tasks such as logging, monitoring, streaming, and more. For example, in the **BotSharp** framework, calling functions can be used to log information, monitor the progress of an LLM application, or perform other tasks. The BotSharp provides a `callbacks` argument that allows developers to interactive with external systems.
 
-The use of calling functions in LLM applications provides flexibility and extensibility. Developers can customize the behavior of their applications by defining callback handlers that implement specific methods. These handlers can be used for tasks like logging, error handling, or interacting with external systems. The function will be triggered by LLM based on the conversation context.
+The use of calling functions in LLM applications provides flexibility and extensibility. Developers can customize the behavior of their applications by defining callback handlers that implement specific methods. These handlers can be used for tasks like logging, error handling, or interacting with external systems. The function will be triggered by LLM based on the conversation context.
+
+## Hide Function
+
+In order to more flexibly control whether the Agent is allowed to use a certain function, there is a Visibility Expression property in the function definition that can be used to control display or hiding. When we input prompt into LLM, although we can use state variables in the system instruction file to control the rendering content, LLM will still take the definition of the function into consideration. If the related functions are not hidden at the same time, LLM will still be It is possible to call related functions, bringing unexpected results. Because we need to control system instruction and function definition at the same time to make them consistent.
+
+```json
+{
+    "name": "make_payment",
+    "description": "call this function to make payment",
+    "visibility_expression": "{% if states.order_number != empty %}visible{% endif %}",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "order_number": {
+                "type": "string",
+                "description": "order number."
+            },
+            "total_amount": {
+                "type": "string",
+                "description": "total amount."
+            }
+        },
+        "required": ["order_number", "total_amount"]
+    }
+}
+```
+
+The above is an example. The system will parse the liquid template of Visibility Expression `{% if states.order_number != empty %}visible{% endif %}`. When "visible" is returned, the system will allow the Agent to use this function. In liquid In expressions, we can use `states.name` to reference the state value in the conversation.

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

@@ -1,3 +1,4 @@
+using BotSharp.Abstraction.Functions.Models;
 using BotSharp.Abstraction.Plugins.Models;
 using BotSharp.Abstraction.Repositories.Filters;
 
@@ -23,6 +24,8 @@ public interface IAgentService
 
     string RenderedTemplate(Agent agent, string templateName);
 
+    bool RenderFunction(Agent agent, FunctionDef def);
+
     /// <summary>
     /// Get agent detail without trigger any hook.
     /// </summary>

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

@@ -29,7 +29,7 @@ public IConversationHook SetConversation(Conversation conversation)
     public virtual Task OnStateLoaded(ConversationState state)
         => Task.CompletedTask;
 
-    public virtual Task OnStateChanged(string name, string preValue, string currentValue)
+    public virtual Task OnStateChanged(StateChangeModel stateChange)
         => Task.CompletedTask;
 
     public virtual Task OnDialogRecordLoaded(RoleDialogModel dialog)

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

@@ -43,7 +43,7 @@ public interface IConversationHook
     Task OnDialogRecordLoaded(RoleDialogModel dialog);
 
     Task OnStateLoaded(ConversationState state);
-    Task OnStateChanged(string name, string preValue, string currentValue);
+    Task OnStateChanged(StateChangeModel stateChange);
 
     Task OnMessageReceived(RoleDialogModel message);
     Task OnPostbackMessageReceived(RoleDialogModel message, PostbackMessageModel replyMsg);

src/Infrastructure/BotSharp.Abstraction/Conversations/Models/StateChangeModel.cs

@@ -0,0 +1,25 @@
+namespace BotSharp.Abstraction.Conversations.Models;
+
+public class StateChangeModel
+{
+    [JsonPropertyName("conversation_id")]
+    public string ConversationId { get; set; }
+
+    [JsonPropertyName("message_id")]
+    public string MessageId { get; set; }
+
+    [JsonPropertyName("name")]
+    public string Name { get; set; }
+
+    [JsonPropertyName("before_value")]
+    public string BeforeValue { get; set; }
+
+    [JsonPropertyName("before_active_rounds")]
+    public int? BeforeActiveRounds { get; set; }
+
+    [JsonPropertyName("after_value")]
+    public string AfterValue { get; set; }
+
+    [JsonPropertyName("after_active_rounds")]
+    public int? AfterActiveRounds { get; set; }
+}

src/Infrastructure/BotSharp.Abstraction/Functions/Models/FunctionCallingResponse.cs

@@ -18,4 +18,9 @@ public class FunctionCallingResponse
 
     [JsonPropertyName("args")]
     public JsonDocument? Args { get; set; }
+
+    public override string ToString()
+    {
+        return $"{FunctionName}({JsonSerializer.Serialize(Args)}) => {Content}";
+    }
 }

src/Infrastructure/BotSharp.Abstraction/Functions/Models/FunctionDef.cs

@@ -5,6 +5,9 @@ public class FunctionDef
     public string Name { get; set; }
     public string Description { get; set; }
 
+    [JsonPropertyName("visibility_expression")]
+    public string? VisibilityExpression { get; set; }
+
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public string? Impact { get; set; }
 

src/Infrastructure/BotSharp.Abstraction/Infrastructures/Enums/StateConst.cs

@@ -0,0 +1,9 @@
+namespace BotSharp.Abstraction.Infrastructures.Enums;
+
+public class StateConst
+{
+    public const string EXPECTED_ACTION_AGENT = "expected_next_action_agent";
+    public const string EXPECTED_GOAL_AGENT = "expected_user_goal_agent";
+    public const string NEXT_ACTION_AGENT = "next_action_agent";
+    public const string USER_GOAL_AGENT = "user_goal_agent";
+}

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

@@ -28,4 +28,13 @@ public interface IContentGeneratingHook
     /// </summary>
     /// <returns></returns>
     Task AfterGenerated(RoleDialogModel message, TokenStatsModel tokenStats) => Task.CompletedTask;
+
+    /// <summary>
+    /// Rdndering template
+    /// </summary>
+    /// <param name="agent"></param>
+    /// <param name="name"></param>
+    /// <param name="content"></param>
+    /// <returns></returns>
+    Task OnRenderingTemplate(Agent agent, string name, string content) => Task.CompletedTask;
 }

src/Infrastructure/BotSharp.Abstraction/Loggers/Models/AgentQueueChangedLogModel.cs

@@ -0,0 +1,13 @@
+namespace BotSharp.Abstraction.Loggers.Models;
+
+public class AgentQueueChangedLogModel
+{
+    [JsonPropertyName("conversation_id")]
+    public string ConversationId { get; set; }
+
+    [JsonPropertyName("log")]
+    public string Log { get; set; }
+
+    [JsonPropertyName("created_at")]
+    public DateTime CreateTime { get; set; }
+}

src/Infrastructure/BotSharp.Abstraction/Loggers/Models/StateChangeOutputModel.cs

@@ -0,0 +1,7 @@
+namespace BotSharp.Abstraction.Loggers.Models;
+
+public class StateChangeOutputModel : StateChangeModel
+{
+    [JsonPropertyName("created_at")]
+    public DateTime CreateTime { get; set; } = DateTime.UtcNow;
+}

src/Infrastructure/BotSharp.Abstraction/Messaging/JsonConverters/RichContentJsonConverter .cs

@@ -10,15 +10,7 @@ public class RichContentJsonConverter : JsonConverter<IRichMessage>
         using var jsonDoc = JsonDocument.ParseValue(ref reader);
         var root = jsonDoc.RootElement;
         var jsonText = root.GetRawText();
-        IRichMessage? res = null;
-
-        var parser = new MessageParser();
-        if (root.TryGetProperty("rich_type", out JsonElement element))
-        {
-            var richType = element.GetString();
-            res = parser.ParseRichMessage(richType, jsonText, root, options);
-        }
-
+        var res = MessageParser.ParseRichMessage(root, options);
         return res;
     }
 

src/Infrastructure/BotSharp.Abstraction/Messaging/JsonConverters/TemplateMessageJsonConverter.cs

@@ -10,15 +10,7 @@ public class TemplateMessageJsonConverter : JsonConverter<ITemplateMessage>
         using var jsonDoc = JsonDocument.ParseValue(ref reader);
         var root = jsonDoc.RootElement;
         var jsonText = root.GetRawText();
-        ITemplateMessage? res = null;
-
-        var parser = new MessageParser();
-        if (root.TryGetProperty("template_type", out JsonElement element))
-        {
-            var templateType = element.GetString();
-            res = parser.ParseTemplateMessage(templateType, jsonText, root, options);
-        }
-
+        var res = MessageParser.ParseTemplateMessage(root, options);
         return res;
     }
 

src/Infrastructure/BotSharp.Abstraction/Messaging/MessageParser.cs

@@ -6,79 +6,96 @@
 
 namespace BotSharp.Core.Messaging;
 
-public class MessageParser
+public static class MessageParser
 {
-    public MessageParser()
-    {
-    }
 
-    public IRichMessage? ParseRichMessage(string richType, string jsonText, JsonElement root, JsonSerializerOptions options)
+    public static IRichMessage? ParseRichMessage(JsonElement root, JsonSerializerOptions options)
     {
         IRichMessage? res = null;
+        JsonElement element;
+        var jsonText = root.GetRawText();
 
-        if (richType == RichTypeEnum.ButtonTemplate)
-        {
-            res = JsonSerializer.Deserialize<ButtonTemplateMessage>(jsonText, options);
-        }
-        else if (richType == RichTypeEnum.MultiSelectTemplate)
-        {
-            res = JsonSerializer.Deserialize<MultiSelectTemplateMessage>(jsonText, options);
-        }
-        else if (richType == RichTypeEnum.QuickReply)
-        {
-            res = JsonSerializer.Deserialize<QuickReplyMessage>(jsonText, options);
-        }
-        else if (richType == RichTypeEnum.CouponTemplate)
-        {
-            res = JsonSerializer.Deserialize<CouponTemplateMessage>(jsonText, options);
-        }
-        else if (richType == RichTypeEnum.Text)
+        if (root.TryGetProperty("rich_type", out element))
         {
-            res = JsonSerializer.Deserialize<TextMessage>(jsonText, options);
-        }
-        else if (richType == RichTypeEnum.GenericTemplate)
-        {
-            if (root.TryGetProperty("element_type", out var element))
+            var richType = element.GetString();
+            if (richType == RichTypeEnum.ButtonTemplate)
+            {
+                res = JsonSerializer.Deserialize<ButtonTemplateMessage>(jsonText, options);
+            }
+            else if (richType == RichTypeEnum.MultiSelectTemplate)
+            {
+                res = JsonSerializer.Deserialize<MultiSelectTemplateMessage>(jsonText, options);
+            }
+            else if (richType == RichTypeEnum.QuickReply)
+            {
+                res = JsonSerializer.Deserialize<QuickReplyMessage>(jsonText, options);
+            }
+            else if (richType == RichTypeEnum.CouponTemplate)
+            {
+                res = JsonSerializer.Deserialize<CouponTemplateMessage>(jsonText, options);
+            }
+            else if (richType == RichTypeEnum.Text)
+            {
+                res = JsonSerializer.Deserialize<TextMessage>(jsonText, options);
+            }
+            else if (richType == RichTypeEnum.GenericTemplate)
             {
-                var elementType = element.GetString();
-                if (elementType == typeof(GenericElement).Name)
+                if (root.TryGetProperty("element_type", out element))
                 {
-                    res = JsonSerializer.Deserialize<GenericTemplateMessage<GenericElement>>(jsonText, options);
+                    var elementType = element.GetString();
+                    if (elementType == typeof(GenericElement).Name)
+                    {
+                        res = JsonSerializer.Deserialize<GenericTemplateMessage<GenericElement>>(jsonText, options);
+                    }
+                    else if (elementType == typeof(ButtonElement).Name)
+                    {
+                        res = JsonSerializer.Deserialize<GenericTemplateMessage<ButtonElement>>(jsonText, options);
+                    }
                 }
             }
         }
 
         return res;
     }
 
-    public ITemplateMessage? ParseTemplateMessage(string templateType, string jsonText, JsonElement root, JsonSerializerOptions options)
+    public static ITemplateMessage? ParseTemplateMessage(JsonElement root, JsonSerializerOptions options)
     {
         ITemplateMessage? res = null;
+        JsonElement element;
+        var jsonText = root.GetRawText();
 
-        if (templateType == TemplateTypeEnum.Button)
-        {
-            res = JsonSerializer.Deserialize<ButtonTemplateMessage>(jsonText, options);
-        }
-        else if (templateType == TemplateTypeEnum.MultiSelect)
+        if (root.TryGetProperty("template_type", out element))
         {
-            res = JsonSerializer.Deserialize<MultiSelectTemplateMessage>(jsonText, options);
-        }
-        else if (templateType == TemplateTypeEnum.Coupon)
-        {
-            res = JsonSerializer.Deserialize<CouponTemplateMessage>(jsonText, options);
-        }
-        else if (templateType == TemplateTypeEnum.Product)
-        {
-            res = JsonSerializer.Deserialize<ProductTemplateMessage>(jsonText, options);
-        }
-        else if (templateType == TemplateTypeEnum.Generic)
-        {
-            if (root.TryGetProperty("element_type", out var element))
+            var templateType = element.GetString();
+            if (templateType == TemplateTypeEnum.Button)
+            {
+                res = JsonSerializer.Deserialize<ButtonTemplateMessage>(jsonText, options);
+            }
+            else if (templateType == TemplateTypeEnum.MultiSelect)
+            {
+                res = JsonSerializer.Deserialize<MultiSelectTemplateMessage>(jsonText, options);
+            }
+            else if (templateType == TemplateTypeEnum.Coupon)
+            {
+                res = JsonSerializer.Deserialize<CouponTemplateMessage>(jsonText, options);
+            }
+            else if (templateType == TemplateTypeEnum.Product)
+            {
+                res = JsonSerializer.Deserialize<ProductTemplateMessage>(jsonText, options);
+            }
+            else if (templateType == TemplateTypeEnum.Generic)
             {
-                var elementType = element.GetString();
-                if (elementType == typeof(GenericElement).Name)
+                if (root.TryGetProperty("element_type", out element))
                 {
-                    res = JsonSerializer.Deserialize<GenericTemplateMessage<GenericElement>>(jsonText, options);
+                    var elementType = element.GetString();
+                    if (elementType == typeof(GenericElement).Name)
+                    {
+                        res = JsonSerializer.Deserialize<GenericTemplateMessage<GenericElement>>(jsonText, options);
+                    }
+                    else if (elementType == typeof(ButtonElement).Name)
+                    {
+                        res = JsonSerializer.Deserialize<GenericTemplateMessage<ButtonElement>>(jsonText, options);
+                    }
                 }
             }
         }

src/Infrastructure/BotSharp.Abstraction/Options/BotSharpOptions.cs

@@ -1,4 +1,3 @@
-using BotSharp.Abstraction.Messaging.JsonConverters;
 using System.Text.Json;
 
 namespace BotSharp.Abstraction.Options;

src/Infrastructure/BotSharp.Abstraction/Routing/Models/RoutingRule.cs

@@ -18,6 +18,7 @@ public class RoutingRule
     /// <summary>
     /// Field type: string, number, object
     /// </summary>
+    [JsonPropertyName("field_type")]
     public string FieldType { get; set; } = "string";
 
     public bool Required { get; set; }

src/Infrastructure/BotSharp.Abstraction/Using.cs

@@ -9,4 +9,8 @@
 global using BotSharp.Abstraction.Utilities;
 global using BotSharp.Abstraction.Conversations.Models;
 global using BotSharp.Abstraction.Agents.Enums;
-global using BotSharp.Abstraction.Models;
+global using BotSharp.Abstraction.Infrastructures.Enums;
+global using BotSharp.Abstraction.Models;
+global using BotSharp.Abstraction.Routing.Models;
+global using BotSharp.Abstraction.Routing.Planning;
+global using BotSharp.Abstraction.Templating;