.Net: New result types - FunctionResult and KernelResult

[dmytrostruk]

Motivation and Context

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

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

• The code builds clean without any errors or warnings
• The PR follows the SK Contribution Guidelines and the pre-submission formatting script raises no violations
• 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>().

[markwallace-microsoft]

@dmytrostruk can you create an ADR for this change. This will be helpful for the community and the Java team.

[stephentoub]

Was just updating to use the new SK beta that has this. Did we consider overriding ToString to make experimentation / prototyping with this a bit easier? e.g.

public override string ToString() => Value?.ToString() ?? base.ToString();

or something like that?

Related, what do we expect a consumer to do if they don't know the T that the function might return? The only API available to get back any information about it is GetValue<T>.

[dmytrostruk]

Did we consider overriding ToString to make experimentation / prototyping with this a bit easier?

@stephentoub I thought about that, but this is something that can be provided separately as extension method to FunctionResult (e.g. ReadAsString()) or implemented on users' side, if user mainly works with strings. I decided to avoid ToString override, because type of Value property will be forced to have meaningful ToString override as well. Otherwise, if it's custom type for example, we will return typeof(T).FullName, which won't provide additional benefits. In my opinion, FunctionResult should remain type-agnostic.

what do we expect a consumer to do if they don't know the T that the function might return?

It depends on return type of last function in pipeline.

• If it's Semantic Function - return type will be always string.
• If it's Native Function - return type will be always the same as return type of invoked function.

Also, it's possible to get plain .GetValue<object> and then try to cast it to any potential return types and see if it's successful.
Another way would be to try to search for potential TypeConverter, and convert object to another known type, as we did in in StepwisePlanner, since in planning functionality we don't know about last function return type in generated plan:

semantic-kernel/dotnet/src/Planners/Planners.Core/Stepwise/StepwisePlanner.cs

Lines 534 to 542 in 7b46188

	var kernelResult = await this._kernel.RunAsync(targetFunction, vars, cancellationToken).ConfigureAwait(false);
	var resultObject = kernelResult.GetValue<object>();
	var converter = TypeDescriptor.GetConverter(resultObject);
	if (converter.CanConvertTo(typeof(string)))
	{
	result = converter.ConvertToString(resultObject);
	}

If function pipeline is static (i.e., last function in pipeline will be always the same), and user doesn't know its return type, when user will try to cast it to invalid type, the exception will mention type of Value property which should be used for casting.

[stephentoub]

because type of Value property will be forced to have meaningful ToString override as well.

It won't be forced to. If it doesn't, you'll get its type name, which is no worse than getting the type name of "FunctionResult". And without either a ToString or a DebuggerDisplay attribute, it's harder to use in a debugger, eg you need to expand it in a watch to see anything useful.

Everywhere I previously just output the result of a function invocation, I now need to know about and use .GetValue<object>(). It's less condusive to quick tests and experimentation and prototyping.

As a point of reference, there are multiple container types in .NET that serve to just wrap some T with additional functionality, like Lazy, Nullable, and ThreadLocal, and that override ToString to delegate to the wrapped T's ToString. It's not intended to be something someone parses and consumes programmatically, but an aid for logging, debugging, etc.

[dmytrostruk]

Everywhere I previously just output the result of a function invocation, I now need to know about and use .GetValue<object>(). It's less condusive to quick tests and experimentation and prototyping.

I agree, but taking into account that we are on the way to v1.0 and usage of SK in production environments, is it something that we want to deliver out of the box? We can add DebuggerDisplay attribute to simplify debugging process, but ToString override, as you said, it's something that is useful for tests and prototyping, but should not be used in production environments.

If you have some business scenario in production, you should know about the result type you expect to be returned from Kernel, so you can take it and handle it as needed.

[stephentoub]

Are Lazy<T>, Nullable<T>, ThreadLocal<T>, every arity of Tuple<...> and ValueTuple<...>, etc. not meant for production environments?

[dmytrostruk]

Are Lazy<T>, Nullable<T>, ThreadLocal<T>, every arity of Tuple<...> and ValueTuple<...>, etc. not meant for production environments?

Sorry, I missed that part about these types and their ToString overrides. If this is common implementation, then I will add ToString override as well as DebuggerDisplay attribute and we will deliver it as part of next release. Thanks for the information!