KernelPlugin Class

Represents a Kernel Plugin with functions.

This class behaves mostly like a dictionary, with functions as values and their names as keys. When you add a function, through .set or setitem, the function is copied, the metadata is deep-copied and the name of the plugin is set in the metadata and added to the dict of functions. This is done in the same way as a normal dict, so a existing key will be overwritten.

Class methods: from_object(plugin_name: str, plugin_instance: Any | dict[str, Any], description: str | None = None): Create a plugin from a existing object, like a custom class with annotated functions.

from_directory(plugin_name: str, parent_directory: str, description: str | None = None): Create a plugin from a directory, parsing: .py files, .yaml files and directories with skprompt.txt and config.json files.

from_openapi( plugin_name: str, openapi_document_path: str, execution_settings: OpenAPIFunctionExecutionParameters | None = None, description: str | None = None):

  Create a plugin from an OpenAPI document.

Create a KernelPlugin.

Constructor

KernelPlugin(name: str, description: str | None = None, functions: KernelFunction | Callable[[...], Any] | KernelPlugin | Sequence[KernelFunction | Callable[[...], Any] | KernelPlugin] | None | dict[str, KernelFunction | Callable[[...], Any]] = None)

Parameters

Name	Description
name Required	The name of the plugin. The name can be upper/lower case letters and underscores.
description	The description of the plugin. Default value: None
functions	The functions in the plugin, will be rewritten to a dictionary of functions. Default value: None

Methods

add	Add functions to the plugin.
add_dict	Add a dictionary of functions to the plugin.
add_list	Add a list of functions to the plugin.
from_directory	Create a plugin from a specified directory. This method does not recurse into subdirectories beyond one level deep from the specified plugin directory. For YAML files, function names are extracted from the content of the YAML files themselves (the name property). For directories, the function name is assumed to be the name of the directory. Each KernelFunction object is initialized with data parsed from the associated files and added to a list of functions that are then assigned to the created KernelPlugin object. A .py file is parsed and a plugin created, the functions within as then combined with any other functions found. The python file needs to contain a class with one or more kernel_function decorated methods. If this class has a init method, it will be called with the arguments provided in the class_init_arguments dictionary, the key needs to be the same as the name of the class, with the value being a dictionary of arguments to pass to the class (using kwargs). MyPlugins/ |<<— pluginA.yaml |<<— pluginB.yaml |<<— native_function.py |<<— Directory1/ >>|<<— skprompt.txt >>|<<— config.json |<<— Directory2/ >>|<<— skprompt.txt >>|<<— config.json Calling KernelPlugin.from_directory("MyPlugins", "/path/to") will create a KernelPlugin object named "MyPlugins", containing KernelFunction objects for pluginA.yaml, pluginB.yaml, Directory1, and Directory2, each initialized with their respective configurations. And functions for anything within native_function.py.
from_object	Creates a plugin that wraps the specified target object and imports it into the kernel's plugin collection.
from_openapi	Create a plugin from an OpenAPI document.
from_python_file	Create a plugin from a Python file.
from_text_search_with_get_search_results	Creates a plugin that wraps the text search "get_search_results" function.
from_text_search_with_get_text_search_results	Creates a plugin that wraps the text search "get_text_search_results" function.
from_text_search_with_search	Creates a plugin that wraps the text search "search" function.
get	Get a function from the plugin.
get_functions_metadata	Get the metadata for the functions in the plugin.
set	Set a function in the plugin.
setdefault	Set a default value for a key.
update	Update the plugin with the functions from another.

add

Add functions to the plugin.

add(functions: Any) -> None

add_dict

Add a dictionary of functions to the plugin.

add_dict(functions: dict[str, KernelFunction | Callable[[...], Any]]) -> None

Parameters

Name	Description
functions Required

add_list

Add a list of functions to the plugin.

add_list(functions: list[KernelFunction | Callable[[...], Any] | KernelPlugin]) -> None

Parameters

Name	Description
functions Required

from_directory

Create a plugin from a specified directory.

This method does not recurse into subdirectories beyond one level deep from the specified plugin directory. For YAML files, function names are extracted from the content of the YAML files themselves (the name property). For directories, the function name is assumed to be the name of the directory. Each KernelFunction object is initialized with data parsed from the associated files and added to a list of functions that are then assigned to the created KernelPlugin object. A .py file is parsed and a plugin created, the functions within as then combined with any other functions found. The python file needs to contain a class with one or more kernel_function decorated methods. If this class has a init method, it will be called with the arguments provided in the class_init_arguments dictionary, the key needs to be the same as the name of the class, with the value being a dictionary of arguments to pass to the class (using kwargs).

MyPlugins/

|<<— pluginA.yaml |<<— pluginB.yaml |<<— native_function.py |<<— Directory1/

  >>|<<— skprompt.txt
  >>|<<— config.json

|<<— Directory2/ >>|<<— skprompt.txt >>|<<— config.json

Calling KernelPlugin.from_directory("MyPlugins", "/path/to") will create a KernelPlugin object named "MyPlugins", containing KernelFunction objects for pluginA.yaml, pluginB.yaml, Directory1, and Directory2, each initialized with their respective configurations. And functions for anything within native_function.py.

from_directory(plugin_name: str, parent_directory: str, description: str | None = None, class_init_arguments: dict[str, dict[str, Any]] | None = None) -> _T

Parameters

Name	Description
plugin_name Required	str The name of the plugin, this is the name of the directory within the parent directory
parent_directory Required	str The parent directory path where the plugin directory resides
description Required	<xref:<xref:semantic_kernel.functions.kernel_plugin.str | None>> The description of the plugin Default value: None
class_init_arguments Required	dict[str,dict[str,<xref: Any>]]<xref: | None> The class initialization arguments Default value: None

Returns

Type	Description
KernelPlugin	The created plugin of type KernelPlugin.

Exceptions

Type	Description
PluginInitializationError	If the plugin directory does not exist.
PluginInvalidNameError	If the plugin name is invalid.

Examples

Assuming a plugin directory structure as follows:

from_object

Creates a plugin that wraps the specified target object and imports it into the kernel's plugin collection.

from_object(plugin_name: str, plugin_instance: Any | dict[str, Any], description: str | None = None) -> _T

Parameters

Name	Description
plugin_name Required	str The name of the plugin. Allows chars: upper, lower ASCII and underscores.
plugin_instance Required	<xref:Any | dict>[str,<xref: Any>] The plugin instance. This can be a custom class or a dictionary of classes that contains methods with the kernel_function decorator for one or several methods. See TextMemoryPlugin as an example.
description Required	<xref:<xref:semantic_kernel.functions.kernel_plugin.str | None>> The description of the plugin. Default value: None

Returns

Type	Description
KernelPlugin	The imported plugin of type KernelPlugin.

from_openapi

Create a plugin from an OpenAPI document.

from_openapi(plugin_name: str, openapi_document_path: str | None = None, openapi_parsed_spec: dict[str, Any] | None = None, execution_settings: OpenAPIFunctionExecutionParameters | None = None, description: str | None = None) -> _T

Parameters

Name	Description
plugin_name Required	The name of the plugin
openapi_document_path Required	The path to the OpenAPI document (optional) Default value: None
openapi_parsed_spec Required	The parsed OpenAPI spec (optional) Default value: None
execution_settings Required	The execution parameters Default value: None
description Required	The description of the plugin Default value: None

Returns

Type	Description
KernelPlugin	The created plugin

Exceptions

Type	Description
PluginInitializationError	if the plugin URL or plugin JSON/YAML is not provided

from_python_file

Create a plugin from a Python file.

from_python_file(plugin_name: str, py_file: str, description: str | None = None, class_init_arguments: dict[str, dict[str, Any]] | None = None) -> _T

Parameters

Name	Description
plugin_name Required
py_file Required
description Required	Default value: None
class_init_arguments Required	Default value: None

from_text_search_with_get_search_results

Creates a plugin that wraps the text search "get_search_results" function.

from_text_search_with_get_search_results(text_search: TextSearch, plugin_name: str, plugin_description: str | None = None, **kwargs: Any) -> _T

Parameters

Name	Description
text_search Required	The text search to use.
plugin_name Required	The name of the plugin.
plugin_description Required	The description of the search plugin. Default value: None
**kwargs Required	The keyword arguments to use to create the search function.

Returns

Type	Description
	a KernelPlugin.

from_text_search_with_get_text_search_results

Creates a plugin that wraps the text search "get_text_search_results" function.

from_text_search_with_get_text_search_results(text_search: TextSearch, plugin_name: str, plugin_description: str | None = None, **kwargs: Any) -> _T

Parameters

Name	Description
text_search Required	The text search to use.
plugin_name Required	The name of the plugin.
plugin_description Required	The description of the search plugin. Default value: None
**kwargs Required	The keyword arguments to use to create the search function.

Returns

Type	Description
	a KernelPlugin.

from_text_search_with_search

Creates a plugin that wraps the text search "search" function.

from_text_search_with_search(text_search: TextSearch, plugin_name: str, plugin_description: str | None = None, **kwargs: Any) -> _T

Parameters

Name	Description
text_search Required	The text search to use.
plugin_name Required	The name of the plugin.
plugin_description Required	The description of the search plugin. Default value: None
**kwargs Required	The keyword arguments to use to create the search function.

Returns

Type	Description
	a KernelPlugin.

get

Get a function from the plugin.

get()

Parameters

Name	Description
key Required
default Required	Default value: None

get_functions_metadata

Get the metadata for the functions in the plugin.

get_functions_metadata()

set

Set a function in the plugin.

set()

Parameters

Name	Description
key Required
value Required

setdefault

Set a default value for a key.

setdefault()

Parameters

Name	Description
key Required
value Required	Default value: None

update

Update the plugin with the functions from another.

update()

Attributes

name

The name of the plugin. The name can be upper/lower case letters and underscores.

name: StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=^[0-9A-Za-z_]+$)]

description

The description of the plugin.

description: str | None

functions

The functions in the plugin, indexed by their name.

functions: dict[str, KernelFunction]