.Net: New result types - FunctionResult and KernelResult (microsoft#2864

)

### Motivation and Context

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->

This PR contains changes to replace `SKContext` as result type with new
types `FunctionResult` and `KernelResult`.

1. `FunctionResult` - new return type from single function invocation.
It contains `object? Value` which can be any primitive, complex type or
`IAsyncEnumerable<T>`. It also contains `SKContext`, but internally.
This is required to pass `SKContext` to the next function in pipeline
and keep the implementation simple at first iteration. Context could be
removed from `FunctionResult` if needed in the future. It's not publicly
available as part of `FunctionResult`.
2. `KernelResult` - new return type in `Kernel.RunAsync` method. It
doesn't contain `SKContext`, just `object? Value` to get execution
result.

`FunctionResult` also contains `Metadata` - property, that contains
additional data, including AI model response (e.g. token usage).
`KernelResult` contains collection of `FunctionResult` - all function
results from pipeline, so it's possible to check result of each function
in pipeline, observe result value, AI-related information, like amount
of tokens etc.

Syntax in examples and tests were changed from `result.Result` to
`result.GetValue<string>`, but now it should be possible to get any type
as a result and not only string.

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->
1. Updated `ISKFunction` interface to return `FunctionResult` instead of
`SKContext`.
2. Updated `IKernel` interface to return `KernelResult` instead of
`SKContext`.
3. Updated `NativeFunction` to support `IAsyncEnumerable<T>` return
type.
4. Added tests to `SKFunctionTests2` to verify the behavior for
different result types.
5. Removed test
`KernelTests.ItProvidesAccessToFunctionsViaSKContextAsync`. Reason:
Invalid scenario. Kernel should not provide public access to functions
via `SKContext`.
6. Updated tests and examples across the codebase to align with new
signature.

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [ ] I didn't break anyone 😄
- BREAKING CHANGE: This PR will modify syntax of getting result using
`ISKFunction.InvokeAsync` and `IKernel.RunAsync` methods. Syntax changed
from `SKContext.Result` to `FunctionResult/KernelResult.GetValue<T>()`.

docs/decisions/0009-function-and-kernel-result-types.md

@@ -0,0 +1,84 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2023-09-21
+deciders: shawncal, dmytrostruk
+consulted: 
+informed: 
+---
+# Replace SKContext as Function/Kernel result type with FunctionResult and KernelResult models
+
+## Context and Problem Statement
+
+Methods `function.InvokeAsync` and `kernel.RunAsync` return `SKContext` as result type. This has several problems:
+
+1. `SKContext` contains property `Result`, which is `string`. Based on that, it's not possible to return complex type or implement streaming capability in Kernel.
+2. `SKContext` contains property `ModelResults`, which is coupled to LLM-specific logic, so it's only applicable to semantic functions in specific cases.
+3. `SKContext` as a mechanism of passing information between functions in pipeline should be internal implementation. Caller of Kernel should provide input/request and receive some result, but not `SKContext`.
+4. `SKContext` contains information related to the last executed function without a way to access information about specific function in pipeline.
+
+## Decision Drivers
+
+1. Kernel should be able to return complex type as well as support streaming capability.
+2. Kernel should be able to return data related to function execution (e.g. amount of tokens used) in a way, when it's not coupled to AI logic.
+3. `SKContext` should work as internal mechanism of passing information between functions.
+4. There should be a way how to differentiate function result from kernel result, since these entities are different by nature and may contain different set of properties in the future.
+5. The possibility to access specific function result in the middle of pipeline will provide more insights to the users how their functions performed.
+
+## Considered Options
+
+1. Use `dynamic` as return type - this option provides some flexibility, but on the other hand removes strong typing, which is preferred option in .NET world. Also, there will be no way how to differentiate function result from Kernel result.
+2. Define new types - `FunctionResult` and `KernelResult` - chosen approach.
+
+## Decision Outcome
+
+New `FunctionResult` and `KernelResult` return types should cover scenarios like returning complex types from functions, supporting streaming and possibility to access result of each function separately.
+
+### Complex Types and Streaming
+
+For complex types and streaming, property `object Value` will be defined in `FunctionResult` to store single function result, and in `KernelResult` to store result from last function in execution pipeline. For better usability, generic method `GetValue<T>` will allow to cast `object Value` to specific type.
+
+Examples:
+
+```csharp
+// string
+var text = (await kernel.RunAsync(function)).GetValue<string>();
+
+// complex type
+var myComplexType = (await kernel.RunAsync(function)).GetValue<MyComplexType>();
+
+// streaming
+var results = (await kernel.RunAsync(function)).GetValue<IAsyncEnumerable<int>>();
+
+await foreach (var result in results)
+{
+    Console.WriteLine(result);
+}
+```
+
+When `FunctionResult`/`KernelResult` will store `TypeA` and caller will try to cast it to `TypeB` - in this case `InvalidCastException` will be thrown with details about types. This will provide some information to the caller which type should be used for casting.
+
+### Metadata
+
+To return additional information related to function execution - property `Dictionary<string, object> Metadata` will be added to `FunctionResult`. This will allow to pass any kind of information to the caller, which should provide some insights how function performed (e.g. amount of tokens used, AI model response etc.)
+
+Examples:
+
+```csharp
+var functionResult = await function.InvokeAsync(context);
+Console.WriteLine(functionResult.Metadata["MyInfo"]);
+```
+
+### Multiple function results
+
+`KernelResult` will contain collection of function results - `IReadOnlyCollection<FunctionResult> FunctionResults`. This will allow to get specific function result from `KernelResult`. Properties `FunctionName` and `PluginName` in `FunctionResult` will help to get specific function from collection.
+
+Example:
+
+```csharp
+var kernelResult = await kernel.RunAsync(function1, function2, function3);
+
+var functionResult2 = kernelResult.FunctionResults.First(l => l.FunctionName == "Function2" && l.PluginName == "MyPlugin");
+
+Assert.Equal("Result2", functionResult2.GetValue<string>());
+```

dotnet/samples/ApplicationInsightsExample/Program.cs

@@ -70,7 +70,7 @@ public static async Task Main()
             var result = await kernel.RunAsync(plan);
 
             Console.WriteLine("Result:");
-            Console.WriteLine(result.Result);
+            Console.WriteLine(result.GetValue<string>());
         }
         finally
         {

dotnet/samples/KernelSyntaxExamples/Example02_Pipeline.cs

@@ -22,11 +22,11 @@ public static async Task RunAsync()
         // Load native plugin
         var text = kernel.ImportPlugin(new TextPlugin());
 
-        SKContext result = await kernel.RunAsync("    i n f i n i t e     s p a c e     ",
+        KernelResult result = await kernel.RunAsync("    i n f i n i t e     s p a c e     ",
             text["TrimStart"],
             text["TrimEnd"],
             text["Uppercase"]);
 
-        Console.WriteLine(result);
+        Console.WriteLine(result.GetValue<string>());
     }
 }

dotnet/samples/KernelSyntaxExamples/Example03_Variables.cs

@@ -24,10 +24,10 @@ public static async Task RunAsync()
         var variables = new ContextVariables("Today is: ");
         variables.Set("day", DateTimeOffset.Now.ToString("dddd", CultureInfo.CurrentCulture));
 
-        SKContext result = await kernel.RunAsync(variables,
+        KernelResult result = await kernel.RunAsync(variables,
             text["AppendDay"],
             text["Uppercase"]);
 
-        Console.WriteLine(result);
+        Console.WriteLine(result.GetValue<string>());
     }
 }

dotnet/samples/KernelSyntaxExamples/Example07_BingAndGooglePlugins.cs

@@ -144,13 +144,15 @@ private static async Task Example2Async(IKernel kernel)
             ["externalInformation"] = string.Empty
         });
 
+        var result = answer.GetValue<string>()!;
+
         // If the answer contains commands, execute them using the prompt renderer.
-        if (answer.Result.Contains("bing.search", StringComparison.OrdinalIgnoreCase))
+        if (result.Contains("bing.search", StringComparison.OrdinalIgnoreCase))
         {
             var promptRenderer = new PromptTemplateEngine();
 
             Console.WriteLine("---- Fetching information from Bing...");
-            var information = await promptRenderer.RenderAsync(answer.Result, kernel.CreateNewContext());
+            var information = await promptRenderer.RenderAsync(result, kernel.CreateNewContext());
 
             Console.WriteLine("Information found:");
             Console.WriteLine(information);
@@ -168,7 +170,7 @@ private static async Task Example2Async(IKernel kernel)
         }
 
         Console.WriteLine("---- ANSWER:");
-        Console.WriteLine(answer);
+        Console.WriteLine(answer.GetValue<string>());
 
         /* OUTPUT:
 

dotnet/samples/KernelSyntaxExamples/Example12_SequentialPlanner.cs

@@ -99,7 +99,7 @@ private static async Task PoetrySamplesAsync()
         var result = await kernel.RunAsync(plan);
 
         Console.WriteLine("Result:");
-        Console.WriteLine(result.Result);
+        Console.WriteLine(result.GetValue<string>());
     }
 
     private static async Task EmailSamplesWithRecallAsync()
@@ -187,7 +187,7 @@ await foreach (MemoryQueryResult memory in memories)
             var result = await kernel.RunAsync(restoredPlan, new(newInput));
 
             Console.WriteLine("Result:");
-            Console.WriteLine(result.Result);
+            Console.WriteLine(result.GetValue<string>());
         }
     }
 

dotnet/samples/KernelSyntaxExamples/Example13_ConversationSummaryPlugin.cs

@@ -135,12 +135,12 @@ private static async Task ConversationSummaryPluginAsync()
         IDictionary<string, ISKFunction> conversationSummaryPlugin =
              kernel.ImportPlugin(new ConversationSummaryPlugin(kernel));
 
-        SKContext summary = await kernel.RunAsync(
+        KernelResult summary = await kernel.RunAsync(
             ChatTranscript,
             conversationSummaryPlugin["SummarizeConversation"]);
 
         Console.WriteLine("Generated Summary:");
-        Console.WriteLine(summary.Result);
+        Console.WriteLine(summary.GetValue<string>());
     }
 
     private static async Task GetConversationActionItemsAsync()
@@ -151,12 +151,12 @@ private static async Task GetConversationActionItemsAsync()
         IDictionary<string, ISKFunction> conversationSummaryPlugin =
              kernel.ImportPlugin(new ConversationSummaryPlugin(kernel));
 
-        SKContext summary = await kernel.RunAsync(
+        KernelResult summary = await kernel.RunAsync(
             ChatTranscript,
             conversationSummaryPlugin["GetConversationActionItems"]);
 
         Console.WriteLine("Generated Action Items:");
-        Console.WriteLine(summary.Result);
+        Console.WriteLine(summary.GetValue<string>());
     }
 
     private static async Task GetConversationTopicsAsync()
@@ -167,12 +167,12 @@ private static async Task GetConversationTopicsAsync()
         IDictionary<string, ISKFunction> conversationSummaryPlugin =
              kernel.ImportPlugin(new ConversationSummaryPlugin(kernel));
 
-        SKContext summary = await kernel.RunAsync(
+        KernelResult summary = await kernel.RunAsync(
             ChatTranscript,
             conversationSummaryPlugin["GetConversationTopics"]);
 
         Console.WriteLine("Generated Topics:");
-        Console.WriteLine(summary.Result);
+        Console.WriteLine(summary.GetValue<string>());
     }
 
     private static IKernel InitializeKernel()

dotnet/samples/KernelSyntaxExamples/Example16_CustomLLM.cs

@@ -117,7 +117,7 @@ private static async Task CustomTextCompletionWithSKFunctionAsync()
 
         // Details of the my custom model response
         Console.WriteLine(JsonSerializer.Serialize(
-            result.ModelResults,
+            result.GetModelResults(),
             new JsonSerializerOptions() { WriteIndented = true }
         ));
     }

dotnet/samples/KernelSyntaxExamples/Example23_OpenApiPlugin_Github.cs

@@ -47,7 +47,7 @@ public static async Task<string> ListPullRequestsFromGitHubAsync(BearerAuthentic
         var result = await kernel.RunAsync(contextVariables, plugin["PullsList"]);
 
         Console.WriteLine("Successful GitHub List Pull Requests plugin response.");
-        var resultJson = JsonConvert.DeserializeObject<Dictionary<string, object>>(result.Result);
+        var resultJson = JsonConvert.DeserializeObject<Dictionary<string, object>>(result.GetValue<string>()!);
         var pullRequests = JArray.Parse((string)resultJson!["content"]);
 
         if (pullRequests != null && pullRequests.First != null)

dotnet/samples/KernelSyntaxExamples/Example24_OpenApiPlugin_Jira.cs

@@ -60,7 +60,7 @@ public static async Task RunAsync()
             var result = await kernel.RunAsync(contextVariables, jiraSkills["GetIssue"]);
 
             Console.WriteLine("\n\n\n");
-            var formattedContent = JsonConvert.SerializeObject(JsonConvert.DeserializeObject(result.Result), Formatting.Indented);
+            var formattedContent = JsonConvert.SerializeObject(JsonConvert.DeserializeObject(result.GetValue<string>()!), Formatting.Indented);
             Console.WriteLine("GetIssue jiraSkills response: \n{0}", formattedContent);
         }
 
@@ -74,7 +74,7 @@ public static async Task RunAsync()
             var result = await kernel.RunAsync(contextVariables, jiraSkills["AddComment"]);
 
             Console.WriteLine("\n\n\n");
-            var formattedContent = JsonConvert.SerializeObject(JsonConvert.DeserializeObject(result.Result), Formatting.Indented);
+            var formattedContent = JsonConvert.SerializeObject(JsonConvert.DeserializeObject(result.GetValue<string>()!), Formatting.Indented);
             Console.WriteLine("AddComment jiraSkills response: \n{0}", formattedContent);
         }
     }

dotnet/samples/KernelSyntaxExamples/Example28_ActionPlanner.cs

@@ -3,7 +3,6 @@
 using System;
 using System.Threading.Tasks;
 using Microsoft.SemanticKernel;
-using Microsoft.SemanticKernel.Orchestration;
 using Microsoft.SemanticKernel.Planning;
 using Microsoft.SemanticKernel.Planning.Action;
 using RepoUtils;
@@ -43,10 +42,10 @@ public static async Task RunAsync()
         var plan = await planner.CreatePlanAsync(goal);
 
         // Execute the full plan (which is a single function)
-        SKContext result = await plan.InvokeAsync(kernel);
+        var result = await plan.InvokeAsync(kernel);
 
         // Show the result, which should match the given goal
-        Console.WriteLine(result);
+        Console.WriteLine(result.GetValue<string>());
 
         /* Output:
          *

dotnet/samples/KernelSyntaxExamples/Example31_CustomPlanner.cs

@@ -48,7 +48,7 @@ public static async Task RunAsync()
         var result = await plan.InvokeAsync(context);
 
         Console.WriteLine("Result:");
-        Console.WriteLine(result.Result);
+        Console.WriteLine(result.GetValue<string>());
         Console.WriteLine();
     }
     /* Example Output
@@ -154,7 +154,7 @@ public async Task<string> RunMarkupAsync(string docString, SKContext context, IK
         Console.WriteLine();
 
         var result = await plan.InvokeAsync(kernel);
-        return result.Result;
+        return result.GetValue<string>()!;
     }
 }
 

dotnet/samples/KernelSyntaxExamples/Example43_GetModelResult.cs

@@ -5,10 +5,12 @@
 using System.Linq;
 using System.Threading.Tasks;
 using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.AI;
 using Microsoft.SemanticKernel.AI.TextCompletion;
 using Microsoft.SemanticKernel.Connectors.AI.OpenAI;
 using Microsoft.SemanticKernel.Connectors.AI.OpenAI.ChatCompletion;
 using Microsoft.SemanticKernel.Diagnostics;
+using Microsoft.SemanticKernel.Orchestration;
 using RepoUtils;
 
 #pragma warning disable RCS1192 // (Unnecessary usage of verbatim string literal)
@@ -32,17 +34,20 @@ public static async Task RunAsync()
         var myFunction = kernel.CreateSemanticFunction(FunctionDefinition);
 
         // Using InvokeAsync with 3 results (Currently invoke only supports 1 result, but you can get the other results from the ModelResults)
-        var textResult = await myFunction.InvokeAsync("Sci-fi",
+        var functionResult = await myFunction.InvokeAsync("Sci-fi",
             kernel,
             requestSettings: new OpenAIRequestSettings { ResultsPerPrompt = 3, MaxTokens = 500, Temperature = 1, TopP = 0.5 });
-        Console.WriteLine(textResult);
-        Console.WriteLine(textResult.ModelResults.Select(result => result.GetOpenAIChatResult()).AsJson());
+
+        Console.WriteLine(functionResult.GetValue<string>());
+        Console.WriteLine(functionResult.GetModelResults()?.Select(result => result.GetOpenAIChatResult()).AsJson());
         Console.WriteLine();
 
         // Using the Kernel RunAsync
-        textResult = await kernel.RunAsync("sorry I forgot your birthday", myFunction);
-        Console.WriteLine(textResult);
-        Console.WriteLine(textResult.ModelResults.LastOrDefault()?.GetOpenAIChatResult()?.Usage.AsJson());
+        var kernelResult = await kernel.RunAsync("sorry I forgot your birthday", myFunction);
+        var modelResults = kernelResult.FunctionResults.SelectMany(l => l.GetModelResults() ?? Enumerable.Empty<ModelResult>());
+
+        Console.WriteLine(kernelResult.GetValue<string>());
+        Console.WriteLine(modelResults.LastOrDefault()?.GetOpenAIChatResult()?.Usage.AsJson());
         Console.WriteLine();
 
         // Using Chat Completion directly

dotnet/samples/KernelSyntaxExamples/Example48_GroundednessChecks.cs

@@ -88,15 +88,15 @@ public static async Task GroundednessCheckingSkillAsync()
         context.Variables.Set("topic", "people and places");
         context.Variables.Set("example_entities", "John, Jane, mother, brother, Paris, Rome");
 
-        var extractionResult = (await kernel.RunAsync(context.Variables, entityExtraction)).Result;
+        var extractionResult = (await kernel.RunAsync(context.Variables, entityExtraction)).GetValue<string>();
 
         Console.WriteLine("======== Extract Entities ========");
         Console.WriteLine(extractionResult);
 
         context.Variables.Update(extractionResult);
         context.Variables.Set("reference_context", s_groundingText);
 
-        var groundingResult = (await kernel.RunAsync(context.Variables, reference_check)).Result;
+        var groundingResult = (await kernel.RunAsync(context.Variables, reference_check)).GetValue<string>();
 
         Console.WriteLine("======== Reference Check ========");
         Console.WriteLine(groundingResult);
@@ -106,7 +106,7 @@ public static async Task GroundednessCheckingSkillAsync()
         var excisionResult = await kernel.RunAsync(context.Variables, entity_excision);
 
         Console.WriteLine("======== Excise Entities ========");
-        Console.WriteLine(excisionResult.Result);
+        Console.WriteLine(excisionResult.GetValue<string>());
     }
 
     public static async Task PlanningWithGroundednessAsync()
@@ -142,7 +142,7 @@ public static async Task PlanningWithGroundednessAsync()
         Console.WriteLine(plan.ToPlanWithGoalString());
 
         var results = await kernel.RunAsync(s_groundingText, plan);
-        Console.WriteLine(results.Result);
+        Console.WriteLine(results.GetValue<string>());
     }
 }