What's the best way to use a semantic function within a native function?

[Swimburger]

I have a native function that needs to call a sematic function.
I got this to work by passing the kernel into the ctor of the native function class, then add an inline function which I'm storing in a field.
From the native function I call the inline function. This works, but since I have to register the inline function, I have to provide the plugin name and function name, which I'd like the consumer of the plugin do.

public class MyPlugin
{
    private readonly IKernel _kernel;
    private readonly ISKFunction _getCommonFolderPathFunction;

    public MyPlugin(IKernel kernel)
    {
        _kernel = kernel;
        _getCommonFolderPathFunction = GetCommonFolderPathFunction();
    }

    private ISKFunction GetCommonFolderPathFunction()
    {
        var prompt = "What is the path for the common folder  {{$commonFolderName}} " +
                     $"on operating platform {Environment.OSVersion.Platform.ToString()} " +
                     $"with user profile path {Environment.GetFolderPath(Environment.SpecialFolder.UserProfile)}?";
        var promptConfig = new PromptTemplateConfig
        {
            Schema = 1,
            Type = "completion",
            Description = "Gets the path for the given common folder.",
            Completion =
            {
                MaxTokens = 500,
                Temperature = 0.0,
                TopP = 0.0,
                PresencePenalty = 0.0,
                FrequencyPenalty = 0.0
            },
            Input =
            {
                Parameters = new List<PromptTemplateConfig.InputParameter>
                {
                    new()
                    {
                        Name = "commonFolderName",
                        Description = "Name of the common folder"
                    }
                }
            }
        };

        var promptTemplate = new PromptTemplate(prompt, promptConfig, _kernel);
        var functionConfig = new SemanticFunctionConfig(promptConfig, promptTemplate);
        return _kernel.RegisterSemanticFunction("MyPluginInternal", "GetCommonFolderPath", functionConfig);
    }

    private async Task<string?> GetCommonFolderPath(string commonFolderName)
    {
        var variables = new ContextVariables
        {
            ["commonFolderName"] = commonFolderName
        };
        var context = await _getCommonFolderPathFunction.InvokeAsync(variables);
        var match = Regex.Match(context.Result, @"([a-zA-Z]?\:?[\/\\].*[\/\\][\S-[""'\.]]*)", RegexOptions.IgnoreCase);
        return match.Success ? match.Captures[0].Value : null;
    }

    [SKFunction, Description("Foobar")]
    public async Task<string> LocateFile(SKContext context)
    {
        var foo = await GetCommonFolderPath(commonFolderName);
        ...
    }
}

Is there a way to have the inline function be more in line with the native function?
Provide attributes or have a function that returns the config, and it gets registered along with the other functions in the plugin?

[noeltupas]

The only way I've gotten this to work is to manually pass in the running kernel instance:

// note they removed IKernel
public MyPlugin(Kernel kernel)
{
    _kernel = kernel;
    _getCommonFolderPathFunction = GetCommonFolderPathFunction();
}

But this also means I cannot register this Native class at the same time I'm building out my Kernel instance. Which means whatever your firing mechanism is, it will need to register your Native class at runtime:

var plugin = kernel.CreatePluginFromObject(new MyPlugin(kernel), "MyPlugin");

This is what we currently do for Plugins that serve and orchestrations of other Semantic Functions, where an individual code path (for us, a REST endpoint) triggers the above per request.

Note Singleton Kernels are not recommended (per documentation). Transient ones are wasteful, and I haven't been able to get Scoped ones working (though I may need to wrap it in an abstraction first, I don't know...I'll have to try it).

My preference would be that every Kernel built through the builder registers an instance to itself in its own service collection. Then the above would work more intuitively. However, note that what we're asking for is the Kernel to inject itself into a Native Function that itself is trying to call. We don't ask a Controller to inject an instance of itself to execute a Controller method...that's some weird circular dependency blackhole.

Perhaps it is cleaner/better to pass the dependency in to the function call while keeping the Native class's state free of a Kernel instance?

[stephentoub]

Why do you need to pass the Kernel to the plugin's constructor? If you have a method like:

[KernelFunction]
public void MyAmazingMethod(Kernel kernel) { ... }

the Kernel being used when that method is invoked will be automatically passed in as that Kernel argument.

[noeltupas]

OMG I didn't know this! Thank you!

[noeltupas]

Just tried. Worked well. Thanks again!

[stephentoub]

Glad you got it working.

[stephentoub]

Seems like better docs are needed here. There are various things you can have as arguments that the system will automatically fill in, with Kernel being one but not the only one. For reference, and so you can see what else is handled, here's where it happens:

semantic-kernel/dotnet/src/SemanticKernel.Core/Functions/KernelFunctionFromMethod.cs

Lines 305 to 372 in 88bdb11

	if (type == typeof(KernelFunction))
	{
	return (static (KernelFunction func, Kernel _, KernelArguments _, CancellationToken _) => func, null);
	}
	if (type == typeof(Kernel))
	{
	return (static (KernelFunction _, Kernel kernel, KernelArguments _, CancellationToken _) => kernel, null);
	}
	if (type == typeof(KernelArguments))
	{
	return (static (KernelFunction _, Kernel _, KernelArguments arguments, CancellationToken _) => arguments, null);
	}
	if (type == typeof(ILoggerFactory))
	{
	return ((KernelFunction _, Kernel kernel, KernelArguments _, CancellationToken _) => kernel.LoggerFactory, null);
	}
	if (type == typeof(ILogger))
	{
	return ((KernelFunction _, Kernel kernel, KernelArguments _, CancellationToken _) => kernel.LoggerFactory.CreateLogger(method?.DeclaringType ?? typeof(KernelFunctionFromPrompt)) ?? NullLogger.Instance, null);
	}
	if (type == typeof(IAIServiceSelector))
	{
	return ((KernelFunction _, Kernel kernel, KernelArguments _, CancellationToken _) => kernel.ServiceSelector, null);
	}
	if (type == typeof(CultureInfo) || type == typeof(IFormatProvider))
	{
	return (static (KernelFunction _, Kernel kernel, KernelArguments _, CancellationToken _) => kernel.Culture, null);
	}
	if (type == typeof(CancellationToken))
	{
	return (static (KernelFunction _, Kernel _, KernelArguments _, CancellationToken cancellationToken) => cancellationToken, null);
	}
	// Handle the special FromKernelServicesAttribute, which indicates that the parameter should be sourced from the kernel's services.
	// As with the above, these are not reported as part of KernelParameterMetadata because they're not satisfied from arguments.
	if (parameter.GetCustomAttribute<FromKernelServicesAttribute>() is FromKernelServicesAttribute fromKernelAttr)
	{
	return ((KernelFunction _, Kernel kernel, KernelArguments _, CancellationToken _) =>
	{
	// Try to resolve the service from kernel.Services, using the attribute's key if one was provided.
	object? service = kernel.Services is IKeyedServiceProvider keyedServiceProvider ?
	keyedServiceProvider.GetKeyedService(type, fromKernelAttr.ServiceKey) :
	kernel.Services.GetService(type);
	if (service is not null)
	{
	return service;
	}
	// The service wasn't available. If the parameter has a default value (typically null), use that.
	if (parameter.HasDefaultValue)
	{
	return parameter.DefaultValue;
	}
	// Otherwise, fail.
	throw new KernelException($"Missing service for function parameter '{parameter.Name}'",
	new ArgumentException("Missing service for function parameter", parameter.Name));
	}, null);
	}
	// Handle parameters to be satisfied from KernelArguments.

[noeltupas]

Seems like better docs are needed here.

Yes. Going through SK documentation it's never explicitly state whether or not a Native Function is intended to run Kernel functions internally (clearly it can but DI was awkward). Since the abstraction (IKernel) was removed, I figured you guys decided against the concept of Native functions serving as workflow orchestrations (of other Semantic and/or Native functions).

The above knowledge you've provided I think would be super valuable to readers who are looking at docs and may not necessarily be looking through SK code 😜👍