.Net: Add support for descriptions in nested parameters

[markwallace-microsoft]

When using complex types as Kernel Function parameters, nested properties do not include their metadata (i.e. Descriptions) when being sent to OpenAI.

A completely made up example:

class LightPlugin
{
    [KernelFunction("ChangeState")]
    [Description("Changes the state of the light.'")]
    public string ChangeState(LightState state)
    {
    }
}


class LightState {
    [Description("Whether the light is on or off")]
    public bool BinaryState { get; set; }


    [Description("The brightness level of the light (0 - 100)")]
    public int Brightness { get; set; }

    [Description("The color of the light")]
    public int Color { get; set; }
}

The descriptions of the properties in LightState, will not be sent in the request to OpenAI.

Additionally, what would be the way to indicate if some of the nested properties are required as well.

[markwallace-microsoft]

I have confirmed that this works

I've tested the above plugin (with enhancements) and the parameters schema sent to the LLM looks like this:

{
    "type": "object",
    "required": [
        "state"
    ],
    "properties": {
        "state": {
            "type": "object",
            "properties": {
                "BinaryState": {
                    "description": "Whether the light is on or off",
                    "type": "boolean"
                },
                "Brightness": {
                    "description": "The brightness level of the light (0 - 100)",
                    "type": "integer"
                },
                "Color": {
                    "description": "The color of the light as an RGB value",
                    "type": "integer"
                }
            }
        }
    }
}

For this ask
Change the light so that it is on and is a very bright red.

I get this response:
The light have been changed to be on and are now a very bright red.

And the state of the light is:
The light is now True and is 100% bright and is the color 16711680.

// Copyright (c) Microsoft. All rights reserved.
using System.ComponentModel;
using System.Threading.Tasks;
using Examples;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using Xunit;
using Xunit.Abstractions;
namespace GettingStarted;
/// <summary>
/// This example shows how to load a <see cref="KernelPlugin"/> instances.
/// </summary>
public sealed class FunctionCalling : BaseTest
{
    /// <summary>
    /// Shows different ways to load a <see cref="KernelPlugin"/> instances.
    /// </summary>
    [Fact]
    public async Task RunAsync()
    {
        var lightPlugin = new LightPlugin();
        // Create a kernel with OpenAI chat completion
        IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
        kernelBuilder.AddOpenAIChatCompletion(
                modelId: TestConfiguration.OpenAI.ChatModelId,
                apiKey: TestConfiguration.OpenAI.ApiKey);
        kernelBuilder.Plugins.AddFromObject(lightPlugin);
        Kernel kernel = kernelBuilder.Build();
        OpenAIPromptExecutionSettings settings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };
        WriteLine(await kernel.InvokePromptAsync("Change the light so that it is on and is a very bright red.", new(settings)));
        WriteLine($"The light is now {lightPlugin.State.BinaryState} and is {lightPlugin.State.Brightness}% bright and is the color {lightPlugin.State.Color}.");
    }
    /// <summary>
    /// A plugin that returns the current time.
    /// </summary>
    public class LightPlugin
    {
        public LightState State { get; set; }
        [KernelFunction("ChangeState")]
        [Description("Changes the state of the light.'")]
        public void ChangeState(LightState state)
        {
            this.State = state;
        }
    }
    public class LightState
    {
        [Description("Whether the light is on or off")]
        public bool BinaryState { get; set; }
        [Description("The brightness level of the light (0 - 100)")]
        public int Brightness { get; set; }
        [Description("The color of the light as an RGB value")]
        public int Color { get; set; }
    }
    public FunctionCalling(ITestOutputHelper output) : base(output)
    {
    }
}

[elagunas]

Hello Mark,

I am trying to put in the description of the parameters if them are optional o than only has required in a based condition.

But I think is not working.

An other question, it is possible to have a description with a enum type?

How can I see the parameters schema sent to the LLM ?

Thanks a lot.

Eduardo