Partager via

KernelPlugin Class

  • Reference

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.

from_openai( plugin_name: str, plugin_url: str | None = None, plugin_str: str | None = None, execution_parameters: OpenAIFunctionExecutionParameters | None = None, description: str | None = None):

  Create a plugin from the Open AI manifest.

Create a KernelPlugin.

Inheritance
KernelBaseModel
KernelPlugin

Constructor

KernelPlugin(name: str, description: str | None = None, functions: KernelFunction | Callable[[...], Any] | KernelPlugin | list[KernelFunction | Callable[[...], Any] | KernelPlugin] | dict[str, KernelFunction | Callable[[...], Any]] | None = 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_openai

Create a plugin from the Open AI manifest.
from_openapi

Create a plugin from an OpenAPI document.
from_python_file

Create a plugin from a Python file.
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) -> KernelPlugin

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
<xref:<xref:semantic_kernel.functions.str | None>>

The description of the plugin

Default value: None
class_init_arguments
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) -> KernelPlugin

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
<xref:<xref:semantic_kernel.functions.str | None>>

The description of the plugin.

Default value: None

Returns

Type Description
KernelPlugin

The imported plugin of type KernelPlugin.

from_openai

Create a plugin from the Open AI manifest.

async classmethod from_openai(plugin_name: str, plugin_url: str | None = None, plugin_str: str | None = None, execution_parameters: OpenAIFunctionExecutionParameters | None = None, description: str | None = None) -> KernelPlugin

Parameters

Name Description
plugin_name
Required
str

The name of the plugin
plugin_url
<xref:<xref:semantic_kernel.functions.str | None>>

The URL of the plugin

Default value: None
plugin_str
<xref:<xref:semantic_kernel.functions.str | None>>

The JSON string of the plugin

Default value: None
execution_parameters
<xref:<xref:semantic_kernel.functions.OpenAIFunctionExecutionParameters | None>>

The execution parameters

Default value: None
description
<xref:<xref:semantic_kernel.functions.str | None>>

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_openapi

Create a plugin from an OpenAPI document.

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

Parameters

Name Description
plugin_name
Required
str

The name of the plugin
openapi_document_path
Required
str

The path to the OpenAPI document
execution_settings
<xref:<xref:semantic_kernel.functions.OpenAPIFunctionExecutionParameters | None>>

The execution parameters

Default value: None
description
<xref:<xref:semantic_kernel.functions.str | None>>

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) -> KernelPlugin

Parameters

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

get

Get a function from the plugin.

get()

Parameters

Name Description
key
Required
default
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
Default value: None

update

Update the plugin with the functions from another.

update()

Attributes

model_computed_fields

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'populate_by_name': True, 'validate_assignment': True}

model_fields

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.fields from Pydantic V1.

model_fields: ClassVar[Dict[str, FieldInfo]] = {'description': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'functions': FieldInfo(annotation=dict[str, KernelFunction], required=False, default_factory=dict), 'name': FieldInfo(annotation=str, required=True, metadata=[StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern='^[0-9A-Za-z_]+$')])}

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]