Python Kernel Updates: A Closer Look at Our Redesigned Plugin and Function Integration

Evan Mattson

Eduard van Valkenburg

As we approach a stable v1.0 version of the Python Semantic Kernel SDK, we analysed the methods used to add plugins and functions to the kernel. We realised that the variety of available methods might confuse developers. For instance, when should one use import_plugin_from_object() versus import_native_plugin_from_directory()? Or create_function_from_prompt() versus register_function_from_method()? Our goal has always been to keep the SDK as Pythonic and simple as possible, and the complexity of these interactions was not aligning with that principle. This realisation prompted a major simplification in how we handle plugins and functions.

As of our beta package version 0.9.6b1, you can now simply use one of the following: kernel.add_plugin(), kernel.add_plugins(), kernel.add_function(), or kernel.add_functions() and for the really special cases kernel.add_function_from_openai and kernel.add_function_from_openapi.

Adding Plugins to the Kernel

There are four ways to add a plugin:

• Directly as a KernelPlugin instance—other parameters will be ignored.
• As a custom class with methods decorated by kernel_function.
• As a dictionary where one or more methods are decorated with kernel_function.
• From a directory, with parent_directory and plugin_name.

The add_plugin method always returns the plugin in case you want to store that or use it.

To demonstrate, here’s how you can add a plugin to the kernel. First, let’s create a sample plugin:

class LightPlugin(KernelBaseModel):
    is_on: bool = False
    @kernel_function(
        name="get_state",
        description="Gets the state of the light.",
    )
    def get_state(
        self,
    ) -> Annotated[str, "the output is a string"]:
        """Returns the state result of the light."""
        return "On" if self.is_on else "Off"
    @kernel_function(
        name="change_state",
        description="Changes the state of the light.",
    )
    def change_state(
        self,
        new_state: Annotated[bool, "the new state of the light"],
    ) -> Annotated[str, "the output is a string"]:
        """Changes the state of the light."""
        self.is_on = new_state
        state = self.get_state()
        print(f"The light is now: {state}")
        return state

light_plugin = kernel.add_plugin(
        plugin=LightPlugin(),
        plugin_name="LightPlugin",
    )

From Directory

Add Functions to the Kernel

Adding functions follows a similar streamlined process. When you add a function, it associates with the specified plugin. If the plugin doesn’t exist, the kernel creates it and adds the functions. Be default Kernel.add_function returns the newly created function, but there is an optional flag (return_plugin: bool) to return the plugin instead. Kernel.add_functions('plugin_name', functions=[func1, func2]) always returns the created or updated plugin.

Here’s how you might add a function:

chat_function = kernel.add_function(
    prompt=system_message + """{{$chat_history}}{{$user_input}}""",
    function_name="chat",
    plugin_name="chat",
    prompt_execution_settings=req_settings,
)

@kernel_function(name="func1")
def func1(arg1: str) -> str:
    return "test"

@kernel_function(name="func2")
def func2(arg1: str) -> str:
    return "test"

plugin = kernel.add_functions(plugin_name="test", functions=[func1, func2])

A key change that was made now is that whenever a function is added to a plugin (regardless of how) that function is copied and the metadata of that function is updated to reflect the name of the plugin, this means that this is valid, notice that the function that is returned no longer equals the function that was given.

@kernel_function(name="func1") def func1(arg1: str) -> str:
    return "test"

func2 = kernel.add_function(plugin_name='test_plugin', function=func1)
func1 != func2

One important note, when you add two functions with the same name, the function is overridden, the KernelPlugin works like a dict in that regard.

Under the covers

To make this work and cleanup the code, we made some changes under the covers that are good to know.

We removed the KernelPluginCollection class, as it was just a dict of plugin names and plugins and we could just as easily use a dict instead, the benefit of that is less code for us to maintain and a fully dict like experience (thinks like kernel.plugins['name'] just work).

One of the big changes we made under the covers for this is to move all the logic of loading and parsing to either the KernelPlugin or KernelFunction class, for instance when add_plugin is called with the directory info (and no plugin), it calls KernelPlugin.from_directory and then adds the returned plugin to the plugins dict inside of the Kernel, this reduced the amount of code in the Kernel tremendously.

All the initialisation methods for plugins are:

• KernelPlugin(name, description, functions)
• KernelPlugin.from_object(plugin_name, object, description)
• KernelPlugin.from_directory(plugin_name, parent_directory, description, class_init_arguments)
• KernelPlugin.from_openapi(plugin_name, openapi_document_path, execution_settings, description)
• KernelPlugin.from_openai(plugin_name, plugin_url, plugin_str, execution_parameters, description)
• KernelPlugin.from_python_file(plugin_name, py_file (path to), description, class_init_arguments)

and for functions:

• KernelFunctionFromPrompt(function_name, plugin_name, description, prompt, template_format, prompt_template, prompt_template_config, prompt_execution_settings)
  • Alias: KernelFunction.from_prompt
• KernelFunctionFromPrompt.from_yaml(yaml_str, plugin_name (optional))
• KernelFunctionFromPrompt.from_directory(path, plugin_name (optional))
• KernelFunctionFromMethod(method, plugin_name, stream_method) (where the method has name, description, etc. defined through the decorator)
  • Alias: KernelFunction.from_method

Summary

Evan Mattson

Follow

Eduard van Valkenburg

Follow