semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/filters/auto_function_invocation/auto_function_invocation_context.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import TYPE_CHECKING
+
+from semantic_kernel.filters.filter_context_base import FilterContextBase
+
+if TYPE_CHECKING:
+    from semantic_kernel.contents.chat_history import ChatHistory
+    from semantic_kernel.functions.function_result import FunctionResult
+
+
+class AutoFunctionInvocationContext(FilterContextBase):
+    """Class for auto function invocation context."""
+
+    chat_history: "ChatHistory | None" = None
+    function_result: "FunctionResult | None" = None
+    request_sequence_index: int = 0
+    function_sequence_index: int = 0
+    function_count: int = 0
+    terminate: bool = False

semantic_kernel-1.8.3/semantic_kernel/filters/filter_context_base.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import TYPE_CHECKING
+
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+if TYPE_CHECKING:
+    from semantic_kernel.functions.kernel_arguments import KernelArguments
+    from semantic_kernel.functions.kernel_function import KernelFunction
+    from semantic_kernel.kernel import Kernel
+
+
+@experimental_class
+class FilterContextBase(KernelBaseModel):
+    """Base class for Kernel Filter Contexts."""
+
+    function: "KernelFunction"
+    kernel: "Kernel"
+    arguments: "KernelArguments"

semantic_kernel-1.8.3/semantic_kernel/filters/filter_types.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from enum import Enum
+
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+
+@experimental_class
+class FilterTypes(str, Enum):
+    """Enum for the filter types."""
+
+    FUNCTION_INVOCATION = "function_invocation"
+    PROMPT_RENDERING = "prompt_rendering"
+    AUTO_FUNCTION_INVOCATION = "auto_function_invocation"

semantic_kernel-1.8.3/semantic_kernel/filters/functions/function_invocation_context.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import TYPE_CHECKING
+
+from semantic_kernel.filters.filter_context_base import FilterContextBase
+
+if TYPE_CHECKING:
+    from semantic_kernel.functions.function_result import FunctionResult
+
+
+class FunctionInvocationContext(FilterContextBase):
+    """Class for function invocation context."""
+
+    result: "FunctionResult | None" = None

semantic_kernel-1.8.3/semantic_kernel/filters/kernel_filters_extension.py

@@ -0,0 +1,146 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC
+from collections.abc import Callable, Coroutine
+from functools import partial
+from typing import Any, Literal, TypeVar
+
+from pydantic import Field
+
+from semantic_kernel.filters.filter_context_base import FilterContextBase
+from semantic_kernel.filters.filter_types import FilterTypes
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.utils.experimental_decorator import experimental_function
+
+FILTER_CONTEXT_TYPE = TypeVar("FILTER_CONTEXT_TYPE", bound=FilterContextBase)
+CALLABLE_FILTER_TYPE = Callable[[FILTER_CONTEXT_TYPE, Callable[[FILTER_CONTEXT_TYPE], None]], None]
+
+ALLOWED_FILTERS_LITERAL = Literal[
+    FilterTypes.AUTO_FUNCTION_INVOCATION, FilterTypes.FUNCTION_INVOCATION, FilterTypes.PROMPT_RENDERING
+]
+FILTER_MAPPING = {
+    FilterTypes.FUNCTION_INVOCATION: "function_invocation_filters",
+    FilterTypes.PROMPT_RENDERING: "prompt_rendering_filters",
+    FilterTypes.AUTO_FUNCTION_INVOCATION: "auto_function_invocation_filters",
+}
+
+
+class KernelFilterExtension(KernelBaseModel, ABC):
+    """KernelFilterExtension."""
+
+    function_invocation_filters: list[tuple[int, CALLABLE_FILTER_TYPE]] = Field(default_factory=list)
+    prompt_rendering_filters: list[tuple[int, CALLABLE_FILTER_TYPE]] = Field(default_factory=list)
+    auto_function_invocation_filters: list[tuple[int, CALLABLE_FILTER_TYPE]] = Field(default_factory=list)
+
+    @experimental_function
+    def add_filter(self, filter_type: ALLOWED_FILTERS_LITERAL | FilterTypes, filter: CALLABLE_FILTER_TYPE) -> None:
+        """Add a filter to the Kernel.
+
+        Each filter is added to the beginning of the list of filters,
+        this is because the filters are executed in the order they are added,
+        so the first filter added, will be the first to be executed,
+        but it will also be the last executed for the part after `await next(context)`.
+
+        Args:
+            filter_type (str): The type of the filter to add (function_invocation, prompt_rendering)
+            filter (object): The filter to add
+
+        """
+        if not isinstance(filter_type, FilterTypes):
+            filter_type = FilterTypes(filter_type)
+        getattr(self, FILTER_MAPPING[filter_type.value]).insert(0, (id(filter), filter))
+
+    @experimental_function
+    def filter(
+        self, filter_type: ALLOWED_FILTERS_LITERAL | FilterTypes
+    ) -> Callable[[CALLABLE_FILTER_TYPE], CALLABLE_FILTER_TYPE]:
+        """Decorator to add a filter to the Kernel."""
+
+        def decorator(
+            func: CALLABLE_FILTER_TYPE,
+        ) -> CALLABLE_FILTER_TYPE:
+            self.add_filter(filter_type, func)
+            return func
+
+        return decorator
+
+    @experimental_function
+    def remove_filter(
+        self,
+        filter_type: ALLOWED_FILTERS_LITERAL | FilterTypes | None = None,
+        filter_id: int | None = None,
+        position: int | None = None,
+    ) -> None:
+        """Remove a filter from the Kernel.
+
+        Args:
+            filter_type (str | FilterTypes | None):
+                The type of the filter to remove.
+            filter_id (int): The id of the hook to remove
+            position (int): The position of the filter in the list
+
+        """
+        if filter_type and not isinstance(filter_type, FilterTypes):
+            filter_type = FilterTypes(filter_type)
+        if filter_id is None and position is None:
+            raise ValueError("Either hook_id or position should be provided.")
+        if position is not None:
+            if filter_type is None:
+                raise ValueError("Please specify the type of filter when using position.")
+            getattr(self, FILTER_MAPPING[filter_type]).pop(position)
+            return
+        if filter_type:
+            for f_id, _ in getattr(self, FILTER_MAPPING[filter_type]):
+                if f_id == filter_id:
+                    getattr(self, FILTER_MAPPING[filter_type]).remove((f_id, _))
+                    return
+        for filter_list in FILTER_MAPPING.values():
+            for f_id, _ in getattr(self, filter_list):
+                if f_id == filter_id:
+                    getattr(self, filter_list).remove((f_id, _))
+                    return
+
+    def construct_call_stack(
+        self,
+        filter_type: FilterTypes,
+        inner_function: Callable[[FILTER_CONTEXT_TYPE], Coroutine[Any, Any, None]],
+    ) -> Callable[[FILTER_CONTEXT_TYPE], Coroutine[Any, Any, None]]:
+        """Construct the call stack for the given filter type."""
+        stack: list[Any] = [inner_function]
+        for _, filter in getattr(self, FILTER_MAPPING[filter_type]):
+            filter_with_next = partial(filter, next=stack[0])
+            stack.insert(0, filter_with_next)
+        return stack[0]
+
+
+def _rebuild_auto_function_invocation_context() -> None:
+    from semantic_kernel.contents.chat_history import ChatHistory  # noqa: F401
+    from semantic_kernel.filters.auto_function_invocation.auto_function_invocation_context import (
+        AutoFunctionInvocationContext,
+    )
+    from semantic_kernel.functions.function_result import FunctionResult  # noqa: F401
+    from semantic_kernel.functions.kernel_arguments import KernelArguments  # noqa: F401
+    from semantic_kernel.functions.kernel_function import KernelFunction  # noqa: F401
+    from semantic_kernel.kernel import Kernel  # noqa: F401
+
+    AutoFunctionInvocationContext.model_rebuild()
+
+
+def _rebuild_function_invocation_context() -> None:
+    from semantic_kernel.filters.functions.function_invocation_context import FunctionInvocationContext
+    from semantic_kernel.functions.function_result import FunctionResult  # noqa: F401
+    from semantic_kernel.functions.kernel_arguments import KernelArguments  # noqa: F401
+    from semantic_kernel.functions.kernel_function import KernelFunction  # noqa: F401
+    from semantic_kernel.kernel import Kernel  # noqa: F401
+
+    FunctionInvocationContext.model_rebuild()
+
+
+def _rebuild_prompt_render_context() -> None:
+    from semantic_kernel.filters.prompts.prompt_render_context import PromptRenderContext
+    from semantic_kernel.functions.function_result import FunctionResult  # noqa: F401
+    from semantic_kernel.functions.kernel_arguments import KernelArguments  # noqa: F401
+    from semantic_kernel.functions.kernel_function import KernelFunction  # noqa: F401
+    from semantic_kernel.kernel import Kernel  # noqa: F401
+
+    PromptRenderContext.model_rebuild()

semantic_kernel-1.8.3/semantic_kernel/filters/prompts/prompt_render_context.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import TYPE_CHECKING
+
+from semantic_kernel.filters.filter_context_base import FilterContextBase
+
+if TYPE_CHECKING:
+    from semantic_kernel.functions.function_result import FunctionResult
+
+
+class PromptRenderContext(FilterContextBase):
+    """Context for prompt rendering filters."""
+
+    rendered_prompt: str | None = None
+    function_result: "FunctionResult | None" = None

semantic_kernel-1.8.3/semantic_kernel/functions/__init__.py

@@ -0,0 +1,23 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.functions.function_result import FunctionResult
+from semantic_kernel.functions.kernel_arguments import KernelArguments
+from semantic_kernel.functions.kernel_function import KernelFunction
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.functions.kernel_function_from_method import KernelFunctionFromMethod
+from semantic_kernel.functions.kernel_function_from_prompt import KernelFunctionFromPrompt
+from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+from semantic_kernel.functions.kernel_parameter_metadata import KernelParameterMetadata
+from semantic_kernel.functions.kernel_plugin import KernelPlugin
+
+__all__ = [
+    "FunctionResult",
+    "KernelArguments",
+    "KernelFunction",
+    "KernelFunctionFromMethod",
+    "KernelFunctionFromPrompt",
+    "KernelFunctionMetadata",
+    "KernelParameterMetadata",
+    "KernelPlugin",
+    "kernel_function",
+]

semantic_kernel-1.8.3/semantic_kernel/functions/function_result.py

@@ -0,0 +1,66 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from typing import Any
+
+from pydantic import Field
+
+from semantic_kernel.contents.kernel_content import KernelContent
+from semantic_kernel.exceptions import FunctionResultError
+from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+logger = logging.getLogger(__name__)
+
+
+class FunctionResult(KernelBaseModel):
+    """The result of a function.
+
+    Args:
+        function (KernelFunctionMetadata): The metadata of the function that was invoked.
+        value (Any): The value of the result.
+        metadata (Mapping[str, Any]): The metadata of the result.
+
+    Methods:
+        __str__: Get the string representation of the result, will call str() on the value,
+            or if the value is a list, will call str() on the first element of the list.
+        get_inner_content: Get the inner content of the function result
+            when that is a KernelContent or subclass of the first item of the value if it is a list.
+
+    """
+
+    function: KernelFunctionMetadata
+    value: Any
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def __str__(self) -> str:
+        """Get the string representation of the result."""
+        if self.value:
+            try:
+                if isinstance(self.value, list):
+                    return (
+                        str(self.value[0])
+                        if isinstance(self.value[0], KernelContent)
+                        else ",".join(map(str, self.value))
+                    )
+                if isinstance(self.value, dict):
+                    # TODO (eavanvalkenburg): remove this once function result doesn't include input args
+                    # This is so an integration test can pass.
+                    return str(list(self.value.values())[-1])
+                return str(self.value)
+            except Exception as e:
+                raise FunctionResultError(f"Failed to convert value to string: {e}") from e
+        else:
+            return ""
+
+    def get_inner_content(self, index: int = 0) -> Any | None:
+        """Get the inner content of the function result.
+
+        Args:
+            index (int): The index of the inner content if the inner content is a list, default 0.
+        """
+        if isinstance(self.value, list) and isinstance(self.value[index], KernelContent):
+            return self.value[index].inner_content
+        if isinstance(self.value, KernelContent):
+            return self.value.inner_content
+        return None

semantic_kernel-1.8.3/semantic_kernel/functions/kernel_arguments.py

@@ -0,0 +1,51 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import TYPE_CHECKING, Any
+
+from semantic_kernel.const import DEFAULT_SERVICE_NAME
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+
+
+class KernelArguments(dict):
+    """The arguments sent to the KernelFunction."""
+
+    def __init__(
+        self,
+        settings: (
+            "PromptExecutionSettings | list[PromptExecutionSettings] | dict[str, PromptExecutionSettings] | None"
+        ) = None,
+        **kwargs: Any,
+    ):
+        """Initializes a new instance of the KernelArguments class.
+
+        This is a dict-like class with the additional field for the execution_settings.
+
+        This class is derived from a dict, hence behaves the same way,
+        just adds the execution_settings as a dict, with service_id and the settings.
+
+        Args:
+            settings (PromptExecutionSettings | List[PromptExecutionSettings] | None):
+                The settings for the execution.
+                If a list is given, make sure all items in the list have a unique service_id
+                as that is used as the key for the dict.
+            **kwargs (dict[str, Any]): The arguments for the function invocation, works similar to a regular dict.
+        """
+        super().__init__(**kwargs)
+        settings_dict = None
+        if settings:
+            settings_dict = {}
+            if isinstance(settings, dict):
+                settings_dict = settings
+            elif isinstance(settings, list):
+                settings_dict = {s.service_id or DEFAULT_SERVICE_NAME: s for s in settings}
+            else:
+                settings_dict = {settings.service_id or DEFAULT_SERVICE_NAME: settings}
+        self.execution_settings: dict[str, "PromptExecutionSettings"] | None = settings_dict
+
+    def __bool__(self) -> bool:
+        """Returns True if the arguments have any values."""
+        has_arguments = self.__len__() > 0
+        has_execution_settings = self.execution_settings is not None and len(self.execution_settings) > 0
+        return has_arguments or has_execution_settings