semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/prompt_template/utils/jinja2_system_helpers.py

@@ -0,0 +1,94 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+import re
+from collections.abc import Callable
+from enum import Enum
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+def _messages(chat_history):
+    from semantic_kernel.contents.chat_history import ChatHistory
+
+    if not isinstance(chat_history, ChatHistory):
+        return ""
+    return chat_history.to_prompt()
+
+
+def _message_to_prompt(context):
+    from semantic_kernel.contents.chat_message_content import ChatMessageContent
+
+    if isinstance(context, ChatMessageContent):
+        return str(context.to_prompt())
+    return str(context)
+
+
+def _message(item):
+    from semantic_kernel.contents.const import CHAT_MESSAGE_CONTENT_TAG
+
+    start = f"<{CHAT_MESSAGE_CONTENT_TAG}"
+    role = item.role
+    content = item.content
+    if isinstance(role, Enum):
+        role = role.value
+    start += f' role="{role}"'
+    start += ">"
+    end = f"</{CHAT_MESSAGE_CONTENT_TAG}>"
+    return f"{start}{content}{end}"
+
+
+# Wrap the _get function to safely handle calls without arguments
+def _safe_get_wrapper(context=None, name=None, default=""):
+    if context is None or name is None:
+        return default
+    return _get(context, name, default)
+
+
+def _get(context, name, default=""):
+    """Retrieves a value from the context, with a default if not found."""
+    return context.get(name, default)
+
+
+def _double_open():
+    """Returns the string representing double open braces."""
+    return "{{"
+
+
+def _double_close():
+    """Returns the string representing double close braces."""
+    return "}}"
+
+
+def _array(*args, **kwargs):
+    return list(args)
+
+
+def _camel_case(*args, **kwargs):
+    return "".join([word.capitalize() for word in args[0].split("_")])
+
+
+def _snake_case(*args, **kwargs):
+    arg = args[0]
+    arg = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", arg)
+    arg = re.sub(r"([a-z\d])([A-Z])", r"\1_\2", arg)
+    arg = arg.replace("-", "_")
+    return arg.lower()
+
+
+JINJA2_SYSTEM_HELPERS: dict[str, Callable] = {
+    "get": _safe_get_wrapper,
+    "double_open": _double_open,
+    "doubleOpen": _double_open,
+    "double_close": _double_close,
+    "doubleClose": _double_close,
+    "message": _message,
+    "message_to_prompt": _message_to_prompt,
+    "messages": _messages,
+    "messageToPrompt": _message_to_prompt,
+    "array": _array,
+    "camel_case": _camel_case,
+    "camelCase": _camel_case,
+    "snake_case": _snake_case,
+    "snakeCase": _snake_case,
+}

semantic_kernel-1.8.3/semantic_kernel/prompt_template/utils/template_function_helpers.py

@@ -0,0 +1,142 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+from collections.abc import Callable
+from html import escape
+from typing import TYPE_CHECKING, Any
+
+import nest_asyncio
+
+from semantic_kernel.functions.kernel_arguments import KernelArguments
+from semantic_kernel.prompt_template.const import (
+    HANDLEBARS_TEMPLATE_FORMAT_NAME,
+    JINJA2_TEMPLATE_FORMAT_NAME,
+    TEMPLATE_FORMAT_TYPES,
+)
+
+if TYPE_CHECKING:
+    from semantic_kernel.functions.kernel_function import KernelFunction
+    from semantic_kernel.kernel import Kernel
+
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+def create_template_helper_from_function(
+    function: "KernelFunction",
+    kernel: "Kernel",
+    base_arguments: "KernelArguments",
+    template_format: TEMPLATE_FORMAT_TYPES,
+    allow_dangerously_set_content: bool = False,
+    enable_async: bool = False,
+) -> Callable[..., Any]:
+    """Create a helper function for both the Handlebars and Jinja2 templating engines from a kernel function.
+
+    Args:
+        function (KernelFunction): The kernel function to create a helper for.
+        kernel (Kernel): The kernel to use for invoking the function.
+        base_arguments (KernelArguments): The base arguments to use when invoking the function.
+        template_format (TEMPLATE_FORMAT_TYPES): The template format to create the helper for.
+        allow_dangerously_set_content (bool, optional): Return the content of the function result
+            without encoding it or not.
+        enable_async (bool, optional): Enable async helper function. Defaults to False.
+            Currently only works for Jinja2 templates.
+
+    Returns:
+        The function with args that are callable by the different templates.
+
+    Raises:
+        ValueError: If the template format is not supported.
+
+    """
+    if enable_async:
+        return _create_async_template_helper_from_function(
+            function=function,
+            kernel=kernel,
+            base_arguments=base_arguments,
+            template_format=template_format,
+            allow_dangerously_set_content=allow_dangerously_set_content,
+        )
+    return _create_sync_template_helper_from_function(
+        function=function,
+        kernel=kernel,
+        base_arguments=base_arguments,
+        template_format=template_format,
+        allow_dangerously_set_content=allow_dangerously_set_content,
+    )
+
+
+def _create_sync_template_helper_from_function(
+    function: "KernelFunction",
+    kernel: "Kernel",
+    base_arguments: "KernelArguments",
+    template_format: TEMPLATE_FORMAT_TYPES,
+    allow_dangerously_set_content: bool = False,
+) -> Callable[..., Any]:
+    """Create a helper function for both the Handlebars and Jinja2 templating engines from a kernel function."""
+    if template_format not in [JINJA2_TEMPLATE_FORMAT_NAME, HANDLEBARS_TEMPLATE_FORMAT_NAME]:
+        raise ValueError(f"Invalid template format: {template_format}")
+
+    if not getattr(asyncio, "_nest_patched", False):
+        nest_asyncio.apply()
+
+    def func(*args, **kwargs):
+        arguments = KernelArguments()
+        if base_arguments and base_arguments.execution_settings:
+            arguments.execution_settings = base_arguments.execution_settings  # pragma: no cover
+        arguments.update(base_arguments)
+        arguments.update(kwargs)
+
+        if len(args) > 0 and template_format == HANDLEBARS_TEMPLATE_FORMAT_NAME:
+            this = args[0]
+            actual_args = args[1:]
+        else:
+            this = None
+            actual_args = args
+
+        if this is not None:
+            logger.debug(f"Handlebars context with `this`: {this}")
+        else:
+            logger.debug("Jinja2 context or Handlebars context without `this`")
+
+        logger.debug(
+            f"Invoking function {function.metadata.fully_qualified_name} "
+            f"with args: {actual_args} and kwargs: {kwargs} and this: {this}."
+        )
+
+        result = asyncio.run(function.invoke(kernel=kernel, arguments=arguments))
+        if allow_dangerously_set_content:
+            return result
+        return escape(str(result))
+
+    return func
+
+
+def _create_async_template_helper_from_function(
+    function: "KernelFunction",
+    kernel: "Kernel",
+    base_arguments: "KernelArguments",
+    template_format: TEMPLATE_FORMAT_TYPES,
+    allow_dangerously_set_content: bool = False,
+) -> Callable[..., Any]:
+    """Create a async helper function for Jinja2 templating engines from a kernel function."""
+    if template_format not in [JINJA2_TEMPLATE_FORMAT_NAME]:
+        raise ValueError(f"Invalid template format: {template_format}")
+
+    async def func(*args, **kwargs):
+        arguments = KernelArguments()
+        if base_arguments and base_arguments.execution_settings:
+            arguments.execution_settings = base_arguments.execution_settings  # pragma: no cover
+        arguments.update(base_arguments)
+        arguments.update(kwargs)
+        logger.debug(
+            f"Invoking function {function.metadata.fully_qualified_name} "
+            f"with args: {arguments} and kwargs: {kwargs}."
+        )
+        result = await function.invoke(kernel=kernel, arguments=arguments)
+        if allow_dangerously_set_content:
+            return result
+        return escape(str(result))
+
+    return func

semantic_kernel-1.8.3/semantic_kernel/reliability/kernel_reliability_extension.py

@@ -0,0 +1,18 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from abc import ABC
+
+from pydantic import Field
+
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.reliability.pass_through_without_retry import PassThroughWithoutRetry
+from semantic_kernel.reliability.retry_mechanism_base import RetryMechanismBase
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class KernelReliabilityExtension(KernelBaseModel, ABC):
+    """Kernel reliability extension."""
+
+    retry_mechanism: RetryMechanismBase = Field(default_factory=PassThroughWithoutRetry)

semantic_kernel-1.8.3/semantic_kernel/reliability/pass_through_without_retry.py

@@ -0,0 +1,31 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.reliability.retry_mechanism_base import RetryMechanismBase
+
+T = TypeVar("T")
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class PassThroughWithoutRetry(RetryMechanismBase, KernelBaseModel):
+    """A retry mechanism that does not retry."""
+
+    async def execute_with_retry(self, action: Callable[[], Awaitable[T]]) -> Awaitable[T]:
+        """Executes the given action with retry logic.
+
+        Args:
+            action (Callable[[], Awaitable[T]]): The action to retry on exception.
+
+        Returns:
+            Awaitable[T]: An awaitable that will return the result of the action.
+        """
+        try:
+            return action()
+        except Exception as e:
+            logger.warning(e, "Error executing action, not retrying")
+            raise e

semantic_kernel-1.8.3/semantic_kernel/reliability/retry_mechanism_base.py

@@ -0,0 +1,26 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class RetryMechanismBase(ABC):
+    """Base class for retry mechanisms."""
+
+    @abstractmethod
+    async def execute_with_retry(self, action: Callable[[], Awaitable[T]]) -> Awaitable[T]:
+        """Executes the given action with retry logic.
+
+        Args:
+            action (Callable[[], Awaitable[T]]): The action to retry on exception.
+
+        Returns:
+            Awaitable[T]: An awaitable that will return the result of the action.
+        """
+        pass

semantic_kernel-1.8.3/semantic_kernel/schema/kernel_json_schema_builder.py

@@ -0,0 +1,215 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import types
+from enum import Enum
+from typing import Any, Union, get_args, get_origin, get_type_hints
+
+from semantic_kernel.const import PARSED_ANNOTATION_UNION_DELIMITER
+from semantic_kernel.exceptions.function_exceptions import FunctionInvalidParameterConfiguration
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+TYPE_MAPPING = {
+    int: "integer",
+    str: "string",
+    bool: "boolean",
+    float: "number",
+    list: "array",
+    dict: "object",
+    set: "array",
+    tuple: "array",
+    "int": "integer",
+    "str": "string",
+    "bool": "boolean",
+    "float": "number",
+    "list": "array",
+    "dict": "object",
+    "set": "array",
+    "tuple": "array",
+    "object": "object",
+    "array": "array",
+}
+
+
+class KernelJsonSchemaBuilder:
+    """Kernel JSON schema builder."""
+
+    @classmethod
+    def build(cls, parameter_type: type | str, description: str | None = None) -> dict[str, Any]:
+        """Builds the JSON schema for a given parameter type and description.
+
+        Args:
+            parameter_type (type | str): The parameter type.
+            description (str, optional): The description of the parameter. Defaults to None.
+
+        Returns:
+            dict[str, Any]: The JSON schema for the parameter type.
+        """
+        if isinstance(parameter_type, str):
+            return cls.build_from_type_name(parameter_type, description)
+        if isinstance(parameter_type, KernelBaseModel):
+            return cls.build_model_schema(parameter_type, description)
+        if isinstance(parameter_type, type) and issubclass(parameter_type, Enum):
+            return cls.build_enum_schema(parameter_type, description)
+        if hasattr(parameter_type, "__annotations__"):
+            return cls.build_model_schema(parameter_type, description)
+        if hasattr(parameter_type, "__args__"):
+            return cls.handle_complex_type(parameter_type, description)
+        schema = cls.get_json_schema(parameter_type)
+        if description:
+            schema["description"] = description
+        return schema
+
+    @classmethod
+    def build_model_schema(cls, model: type, description: str | None = None) -> dict[str, Any]:
+        """Builds the JSON schema for a given model and description.
+
+        Args:
+            model (type): The model type.
+            description (str, optional): The description of the model. Defaults to None.
+
+        Returns:
+            dict[str, Any]: The JSON schema for the model.
+        """
+        # TODO (moonbox3): add support for handling forward references, which is not currently tested
+        # https://github.com/microsoft/semantic-kernel/issues/6464
+        properties = {}
+        required = []
+        hints = get_type_hints(model, globals(), locals())
+
+        for field_name, field_type in hints.items():
+            field_description = None
+            if hasattr(model, "model_fields") and field_name in model.model_fields:
+                field_info = model.model_fields[field_name]
+                if isinstance(field_info.metadata, dict):
+                    field_description = field_info.metadata.get("description")
+                elif isinstance(field_info.metadata, list) and field_info.metadata:
+                    field_description = field_info.metadata[0]
+                elif hasattr(field_info, "description"):
+                    field_description = field_info.description
+            if not cls._is_optional(field_type):
+                required.append(field_name)
+            properties[field_name] = cls.build(field_type, field_description)
+
+        schema = {"type": "object", "properties": properties}
+        if required:
+            schema["required"] = required
+        if description:
+            schema["description"] = description
+
+        return schema
+
+    @classmethod
+    def _is_optional(cls, field_type: Any) -> bool:
+        return get_origin(field_type) in {types.UnionType, Union} and type(None) in get_args(field_type)
+
+    @classmethod
+    def build_from_type_name(cls, parameter_type: str, description: str | None = None) -> dict[str, Any]:
+        """Builds the JSON schema for a given parameter type name and description.
+
+        Args:
+            parameter_type (str): The parameter type name.
+            description (str, optional): The description of the parameter. Defaults to None.
+
+        Returns:
+            dict[str, Any]: The JSON schema for the parameter type.
+        """
+        schema: dict[str, Any] = {}
+        if PARSED_ANNOTATION_UNION_DELIMITER in parameter_type:
+            # this means it is a Union or | so need to build with "anyOf"
+            types = parameter_type.split(PARSED_ANNOTATION_UNION_DELIMITER)
+            schemas = [cls.build_from_type_name(t.strip(), description) for t in types]
+            schema["anyOf"] = schemas
+        else:
+            type_name = TYPE_MAPPING.get(parameter_type, "object")
+            schema["type"] = type_name
+            if description:
+                schema["description"] = description
+        return schema
+
+    @classmethod
+    def get_json_schema(cls, parameter_type: type) -> dict[str, Any]:
+        """Gets JSON schema for a given parameter type.
+
+        Args:
+            parameter_type (type): The parameter type.
+
+        Returns:
+            dict[str, Any]: The JSON schema for the parameter type.
+        """
+        type_name = TYPE_MAPPING.get(parameter_type, "object")
+        return {"type": type_name}
+
+    @classmethod
+    def handle_complex_type(cls, parameter_type: type, description: str | None = None) -> dict[str, Any]:
+        """Handles building the JSON schema for complex types.
+
+        Args:
+            parameter_type (type): The parameter type.
+            description (str, optional): The description of the parameter. Defaults to None.
+
+        Returns:
+            dict[str, Any]: The JSON schema for the parameter type.
+        """
+        origin = get_origin(parameter_type)
+        args = get_args(parameter_type)
+
+        schema: dict[str, Any] = {}
+        if origin is list or origin is set:
+            item_type = args[0]
+            schema = {"type": "array", "items": cls.build(item_type)}
+            if description:
+                schema["description"] = description
+            return schema
+        if origin is dict:
+            _, value_type = args
+            additional_properties = cls.build(value_type)
+            if additional_properties == {"type": "object"}:
+                additional_properties["properties"] = {}  # Account for differences in Python 3.10 dict
+            schema = {"type": "object", "additionalProperties": additional_properties}
+            if description:
+                schema["description"] = description
+            return schema
+        if origin is tuple:
+            items = [cls.build(arg) for arg in args]
+            schema = {"type": "array", "items": items}
+            if description:
+                schema["description"] = description
+            return schema
+        if origin in {Union, types.UnionType}:
+            # Handle Optional[T] (Union[T, None]) by making schema nullable
+            if len(args) == 2 and type(None) in args:
+                non_none_type = args[0] if args[1] is type(None) else args[1]
+                schema = cls.build(non_none_type)
+                schema["type"] = [schema["type"], "null"]
+                if description:
+                    schema["description"] = description
+                return schema
+            schemas = [cls.build(arg, description) for arg in args]
+            return {"anyOf": schemas}
+        schema = cls.get_json_schema(parameter_type)
+        if description:
+            schema["description"] = description
+        return schema
+
+    @classmethod
+    def build_enum_schema(cls, enum_type: type, description: str | None = None) -> dict[str, Any]:
+        """Builds the JSON schema for an enum type.
+
+        Args:
+            enum_type (type): The enum type.
+            description (str, optional): The description of the enum. Defaults to None.
+
+        Returns:
+            dict[str, Any]: The JSON schema for the enum type.
+        """
+        if not issubclass(enum_type, Enum):
+            raise FunctionInvalidParameterConfiguration(f"{enum_type} is not a valid Enum type")
+
+        try:
+            enum_values = [item.value for item in enum_type]
+        except TypeError as ex:
+            raise FunctionInvalidParameterConfiguration(f"Failed to get enum values for {enum_type}") from ex
+        schema = {"type": TYPE_MAPPING.get(type(enum_values[0]), "string"), "enum": enum_values}
+        if description:
+            schema["description"] = description
+        return schema

semantic_kernel-1.8.3/semantic_kernel/services/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.services.ai_service_selector import AIServiceSelector
+
+__all__ = ["AIServiceSelector"]

semantic_kernel-1.8.3/semantic_kernel/services/ai_service_client_base.py

@@ -0,0 +1,56 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC
+from typing import TYPE_CHECKING, Annotated
+
+from pydantic import Field, StringConstraints
+
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+
+
+class AIServiceClientBase(KernelBaseModel, ABC):
+    """Base class for all AI Services.
+
+    Has an ai_model_id and service_id, any other fields have to be defined by the subclasses.
+
+    The ai_model_id can refer to a specific model, like 'gpt-35-turbo' for OpenAI,
+    or can just be a string that is used to identify the model in the service.
+
+    The service_id is used in Semantic Kernel to identify the service, if empty the ai_model_id is used.
+    """
+
+    ai_model_id: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+    service_id: str = Field("")
+
+    def model_post_init(self, __context: object | None = None):
+        """Update the service_id if it is not set."""
+        if not self.service_id:
+            self.service_id = self.ai_model_id
+
+    # Override this in subclass to return the proper prompt execution type the
+    # service is expecting.
+    def get_prompt_execution_settings_class(self) -> type["PromptExecutionSettings"]:
+        """Get the request settings class."""
+        from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+
+        return PromptExecutionSettings
+
+    def instantiate_prompt_execution_settings(self, **kwargs) -> "PromptExecutionSettings":
+        """Create a request settings object.
+
+        All arguments are passed to the constructor of the request settings object.
+        """
+        return self.get_prompt_execution_settings_class()(**kwargs)
+
+    def get_prompt_execution_settings_from_settings(
+        self, settings: "PromptExecutionSettings"
+    ) -> "PromptExecutionSettings":
+        """Get the request settings from a settings object."""
+        prompt_execution_settings_type = self.get_prompt_execution_settings_class()
+        if isinstance(settings, prompt_execution_settings_type):
+            return settings
+
+        return prompt_execution_settings_type.from_prompt_execution_settings(settings)

semantic_kernel-1.8.3/semantic_kernel/services/ai_service_selector.py

@@ -0,0 +1,61 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import TYPE_CHECKING
+
+from semantic_kernel.const import DEFAULT_SERVICE_NAME
+from semantic_kernel.exceptions import KernelServiceNotFoundError
+from semantic_kernel.kernel_types import AI_SERVICE_CLIENT_TYPE
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+    from semantic_kernel.functions.kernel_arguments import KernelArguments
+    from semantic_kernel.functions.kernel_function import KernelFunction
+    from semantic_kernel.services.ai_service_client_base import AIServiceClientBase
+    from semantic_kernel.services.kernel_services_extension import KernelServicesExtension
+
+
+class AIServiceSelector:
+    """Default service selector, can be subclassed and overridden.
+
+    To use a custom service selector, subclass this class and override the select_ai_service method.
+    Make sure that the function signature stays the same.
+    """
+
+    def select_ai_service(
+        self,
+        kernel: "KernelServicesExtension",
+        function: "KernelFunction",
+        arguments: "KernelArguments",
+        type_: type[AI_SERVICE_CLIENT_TYPE] | tuple[type[AI_SERVICE_CLIENT_TYPE], ...] | None = None,
+    ) -> tuple["AIServiceClientBase", "PromptExecutionSettings"]:
+        """Select an AI Service on a first come, first served basis.
+
+        Starts with execution settings in the arguments,
+        followed by the execution settings from the function.
+        If the same service_id is in both, the one in the arguments will be used.
+        """
+        if type_ is None:
+            from semantic_kernel.connectors.ai.chat_completion_client_base import ChatCompletionClientBase
+            from semantic_kernel.connectors.ai.text_completion_client_base import TextCompletionClientBase
+
+            type_ = (TextCompletionClientBase, ChatCompletionClientBase)  # type: ignore
+
+        execution_settings_dict = arguments.execution_settings or {}
+        if func_exec_settings := getattr(function, "prompt_execution_settings", None):
+            for id, settings in func_exec_settings.items():
+                if id not in execution_settings_dict:
+                    execution_settings_dict[id] = settings
+        if not execution_settings_dict:
+            from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+
+            execution_settings_dict = {DEFAULT_SERVICE_NAME: PromptExecutionSettings()}
+        for service_id, settings in execution_settings_dict.items():
+            try:
+                if (service := kernel.get_service(service_id, type=type_)) is not None:
+                    settings_class = service.get_prompt_execution_settings_class()
+                    if isinstance(settings, settings_class):
+                        return service, settings
+                    return service, settings_class.from_prompt_execution_settings(settings)
+            except KernelServiceNotFoundError:
+                continue
+        raise KernelServiceNotFoundError("No service found.")