semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/azure_ai_inference/services/utils.py

@@ -0,0 +1,144 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import json
+import logging
+from collections.abc import Callable
+
+from azure.ai.inference.models import (
+    AssistantMessage,
+    ChatCompletionsFunctionToolCall,
+    ChatCompletionsToolCall,
+    ChatRequestMessage,
+    ContentItem,
+    FunctionCall,
+    ImageContentItem,
+    ImageDetailLevel,
+    ImageUrl,
+    SystemMessage,
+    TextContentItem,
+    ToolMessage,
+    UserMessage,
+)
+
+from semantic_kernel.contents.chat_message_content import ChatMessageContent
+from semantic_kernel.contents.function_call_content import FunctionCallContent
+from semantic_kernel.contents.function_result_content import FunctionResultContent
+from semantic_kernel.contents.image_content import ImageContent
+from semantic_kernel.contents.text_content import TextContent
+from semantic_kernel.contents.utils.author_role import AuthorRole
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+def _format_system_message(message: ChatMessageContent) -> SystemMessage:
+    """Format a system message to the expected object for the client.
+
+    Args:
+        message: The system message.
+
+    Returns:
+        The formatted system message.
+    """
+    return SystemMessage(content=message.content)
+
+
+def _format_user_message(message: ChatMessageContent) -> UserMessage:
+    """Format a user message to the expected object for the client.
+
+    If there are any image items in the message, we need to create a list of content items,
+    otherwise we need to just pass in the content as a string or it will error.
+
+    Args:
+        message: The user message.
+
+    Returns:
+        The formatted user message.
+    """
+    if not any(isinstance(item, (ImageContent)) for item in message.items):
+        return UserMessage(content=message.content)
+
+    content_items: list[ContentItem] = []
+    for item in message.items:
+        if isinstance(item, TextContent):
+            content_items.append(TextContentItem(text=item.text))
+        elif isinstance(item, ImageContent) and (item.data_uri or item.uri):
+            content_items.append(
+                ImageContentItem(
+                    image_url=ImageUrl(url=item.data_uri or str(item.uri), detail=ImageDetailLevel.Auto.value)
+                )
+            )
+        else:
+            logger.warning(
+                "Unsupported item type in User message while formatting chat history for Azure AI"
+                f" Inference: {type(item)}"
+            )
+
+    return UserMessage(content=content_items)
+
+
+def _format_assistant_message(message: ChatMessageContent) -> AssistantMessage:
+    """Format an assistant message to the expected object for the client.
+
+    Args:
+        message: The assistant message.
+
+    Returns:
+        The formatted assistant message.
+    """
+    tool_calls: list[ChatCompletionsToolCall] = []
+
+    for item in message.items:
+        if isinstance(item, TextContent):
+            # Assuming the assistant message will have only one text content item
+            # and we assign the content directly to the message content, which is a string.
+            continue
+        if isinstance(item, FunctionCallContent):
+            tool_calls.append(
+                ChatCompletionsFunctionToolCall(
+                    id=item.id or "",
+                    function=FunctionCall(
+                        name=item.name or "",
+                        arguments=json.dumps(item.arguments)
+                        if isinstance(item.arguments, dict)
+                        else item.arguments or "",
+                    ),
+                )
+            )
+        else:
+            logger.warning(
+                "Unsupported item type in Assistant message while formatting chat history for Azure AI"
+                f" Inference: {type(item)}"
+            )
+
+    # tollCalls cannot be an empty list, so we need to set it to None if it is empty
+    return AssistantMessage(content=message.content, tool_calls=tool_calls if tool_calls else None)
+
+
+def _format_tool_message(message: ChatMessageContent) -> ToolMessage:
+    """Format a tool message to the expected object for the client.
+
+    Args:
+        message: The tool message.
+
+    Returns:
+        The formatted tool message.
+    """
+    if len(message.items) != 1:
+        logger.warning(
+            "Unsupported number of items in Tool message while formatting chat history for Azure AI"
+            f" Inference: {len(message.items)}"
+        )
+
+    if not isinstance(message.items[0], FunctionResultContent):
+        raise ValueError("No FunctionResultContent found in the message items")
+
+    # The API expects the result to be a string, so we need to convert it to a string
+    return ToolMessage(content=str(message.items[0].result), tool_call_id=message.items[0].id)
+
+
+MESSAGE_CONVERTERS: dict[AuthorRole, Callable[[ChatMessageContent], ChatRequestMessage]] = {
+    AuthorRole.SYSTEM: _format_system_message,
+    AuthorRole.USER: _format_user_message,
+    AuthorRole.ASSISTANT: _format_assistant_message,
+    AuthorRole.TOOL: _format_tool_message,
+}

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/chat_completion_client_base.py

@@ -0,0 +1,135 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING, Any
+
+from semantic_kernel.contents.annotation_content import AnnotationContent
+from semantic_kernel.contents.file_reference_content import FileReferenceContent
+from semantic_kernel.services.ai_service_client_base import AIServiceClientBase
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+    from semantic_kernel.contents.chat_history import ChatHistory
+    from semantic_kernel.contents.chat_message_content import ChatMessageContent
+    from semantic_kernel.contents.streaming_chat_message_content import StreamingChatMessageContent
+
+
+class ChatCompletionClientBase(AIServiceClientBase, ABC):
+    """Base class for chat completion AI services."""
+
+    @abstractmethod
+    async def get_chat_message_contents(
+        self,
+        chat_history: "ChatHistory",
+        settings: "PromptExecutionSettings",
+        **kwargs: Any,
+    ) -> list["ChatMessageContent"]:
+        """Create chat message contents, in the number specified by the settings.
+
+        Args:
+            chat_history (ChatHistory): A list of chats in a chat_history object, that can be
+                rendered into messages from system, user, assistant and tools.
+            settings (PromptExecutionSettings): Settings for the request.
+            **kwargs (Any): The optional arguments.
+
+        Returns:
+            A list of chat message contents representing the response(s) from the LLM.
+        """
+        pass
+
+    async def get_chat_message_content(
+        self, chat_history: "ChatHistory", settings: "PromptExecutionSettings", **kwargs: Any
+    ) -> "ChatMessageContent | None":
+        """This is the method that is called from the kernel to get a response from a chat-optimized LLM.
+
+        Args:
+            chat_history (ChatHistory): A list of chat chat_history, that can be rendered into a
+                set of chat_history, from system, user, assistant and function.
+            settings (PromptExecutionSettings): Settings for the request.
+            kwargs (Dict[str, Any]): The optional arguments.
+
+        Returns:
+            A string representing the response from the LLM.
+        """
+        results = await self.get_chat_message_contents(chat_history=chat_history, settings=settings, **kwargs)
+        if results:
+            return results[0]
+        # this should not happen, should error out before returning an empty list
+        return None  # pragma: no cover
+
+    @abstractmethod
+    def get_streaming_chat_message_contents(
+        self,
+        chat_history: "ChatHistory",
+        settings: "PromptExecutionSettings",
+        **kwargs: Any,
+    ) -> AsyncGenerator[list["StreamingChatMessageContent"], Any]:
+        """Create streaming chat message contents, in the number specified by the settings.
+
+        Args:
+            chat_history (ChatHistory): A list of chat chat_history, that can be rendered into a
+                set of chat_history, from system, user, assistant and function.
+            settings (PromptExecutionSettings): Settings for the request.
+            kwargs (Dict[str, Any]): The optional arguments.
+
+        Yields:
+            A stream representing the response(s) from the LLM.
+        """
+        ...
+
+    async def get_streaming_chat_message_content(
+        self,
+        chat_history: "ChatHistory",
+        settings: "PromptExecutionSettings",
+        **kwargs: Any,
+    ) -> AsyncGenerator["StreamingChatMessageContent | None", Any]:
+        """This is the method that is called from the kernel to get a stream response from a chat-optimized LLM.
+
+        Args:
+            chat_history (ChatHistory): A list of chat chat_history, that can be rendered into a
+                set of chat_history, from system, user, assistant and function.
+            settings (PromptExecutionSettings): Settings for the request.
+            kwargs (Dict[str, Any]): The optional arguments.
+
+        Yields:
+            A stream representing the response(s) from the LLM.
+        """
+        async for streaming_chat_message_contents in self.get_streaming_chat_message_contents(
+            chat_history, settings, **kwargs
+        ):
+            if streaming_chat_message_contents:
+                yield streaming_chat_message_contents[0]
+            else:
+                # this should not happen, should error out before returning an empty list
+                yield None  # pragma: no cover
+
+    def _prepare_chat_history_for_request(
+        self,
+        chat_history: "ChatHistory",
+        role_key: str = "role",
+        content_key: str = "content",
+    ) -> Any:
+        """Prepare the chat history for a request.
+
+        Allowing customization of the key names for role/author, and optionally overriding the role.
+
+        ChatRole.TOOL messages need to be formatted different than system/user/assistant messages:
+            They require a "tool_call_id" and (function) "name" key, and the "metadata" key should
+            be removed. The "encoding" key should also be removed.
+
+        Override this method to customize the formatting of the chat history for a request.
+
+        Args:
+            chat_history (ChatHistory): The chat history to prepare.
+            role_key (str): The key name for the role/author.
+            content_key (str): The key name for the content/message.
+
+        Returns:
+            prepared_chat_history (Any): The prepared chat history for a request.
+        """
+        return [
+            message.to_dict(role_key=role_key, content_key=content_key)
+            for message in chat_history.messages
+            if not isinstance(message, (AnnotationContent, FileReferenceContent))
+        ]

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/embeddings/embedding_generator_base.py

@@ -0,0 +1,50 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from semantic_kernel.services.ai_service_client_base import AIServiceClientBase
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+if TYPE_CHECKING:
+    from numpy import ndarray
+
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+
+
+@experimental_class
+class EmbeddingGeneratorBase(AIServiceClientBase, ABC):
+    """Base class for embedding generators."""
+
+    @abstractmethod
+    async def generate_embeddings(
+        self,
+        texts: list[str],
+        settings: "PromptExecutionSettings | None" = None,
+        **kwargs: Any,
+    ) -> "ndarray":
+        """Returns embeddings for the given texts as ndarray.
+
+        Args:
+            texts (List[str]): The texts to generate embeddings for.
+            settings (PromptExecutionSettings): The settings to use for the request, optional.
+            kwargs (Any): Additional arguments to pass to the request.
+        """
+        pass
+
+    async def generate_raw_embeddings(
+        self,
+        texts: list[str],
+        settings: "PromptExecutionSettings | None" = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Returns embeddings for the given texts in the unedited format.
+
+        This is not implemented for all embedding services, falling back to the generate_embeddings method.
+
+        Args:
+            texts (List[str]): The texts to generate embeddings for.
+            settings (PromptExecutionSettings): The settings to use for the request, optional.
+            kwargs (Any): Additional arguments to pass to the request.
+        """
+        return await self.generate_embeddings(texts, settings, **kwargs)

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/function_call_behavior.py

@@ -0,0 +1,209 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Literal
+
+from pydantic.dataclasses import dataclass
+from typing_extensions import deprecated
+
+from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+    from semantic_kernel.kernel import Kernel
+
+DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS = 5
+
+
+@dataclass
+class FunctionCallConfiguration:
+    """Class that holds the configured functions for function calling."""
+
+    available_functions: list["KernelFunctionMetadata"] | None = None
+    required_functions: list["KernelFunctionMetadata"] | None = None
+
+
+@deprecated("The `FunctionCallBehavior` class is deprecated; use `FunctionChoiceBehavior` instead.", category=None)
+class FunctionCallBehavior(KernelBaseModel):
+    """Class that controls function calling behavior.
+
+    DEPRECATED: This class has been replaced by FunctionChoiceBehavior.
+
+    Args:
+        enable_kernel_functions (bool): Enable kernel functions.
+        max_auto_invoke_attempts (int): The maximum number of auto invoke attempts.
+
+    Attributes:
+        enable_kernel_functions (bool): Enable kernel functions.
+        max_auto_invoke_attempts (int): The maximum number of auto invoke attempts.
+
+    Properties:
+        auto_invoke_kernel_functions: Check if the kernel functions should be auto-invoked.
+            Determined as max_auto_invoke_attempts > 0.
+
+    Methods:
+        configure: Configures the settings for the function call behavior,
+            the default version in this class, does nothing, use subclasses for different behaviors.
+
+    Class methods:
+        AutoInvokeKernelFunctions: Returns KernelFunctions class with auto_invoke enabled, all functions.
+        EnableKernelFunctions: Returns KernelFunctions class with auto_invoke disabled, all functions.
+        EnableFunctions: Set the enable kernel functions flag, filtered functions, auto_invoke optional.
+        RequiredFunction: Set the required function flag, auto_invoke optional.
+
+    """
+
+    enable_kernel_functions: bool = True
+    max_auto_invoke_attempts: int = DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS
+
+    @property
+    def auto_invoke_kernel_functions(self):
+        """Check if the kernel functions should be auto-invoked."""
+        return self.max_auto_invoke_attempts > 0
+
+    @auto_invoke_kernel_functions.setter
+    def auto_invoke_kernel_functions(self, value: bool):
+        """Set the auto_invoke_kernel_functions flag."""
+        if not value:
+            self.max_auto_invoke_attempts = 0
+        else:
+            if self.max_auto_invoke_attempts == 0:
+                self.max_auto_invoke_attempts = DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS
+
+    def configure(
+        self,
+        kernel: "Kernel",
+        update_settings_callback: Callable[..., None],
+        settings: "PromptExecutionSettings",
+    ) -> None:
+        """Configures the settings for the function call behavior.
+
+        Using the base ToolCallBehavior means that you manually have to set tool_choice and tools.
+
+        For different behaviors, use the subclasses of ToolCallBehavior:
+            KernelFunctions (all functions in the Kernel)
+            EnabledFunctions (filtered set of functions from the Kernel)
+            RequiredFunction (a single function)
+
+        By default, the update_settings_callback is called with FunctionCallConfiguration,
+        which contains a list of available functions or a list of required functions, it also
+        takes the PromptExecutionSettings object.
+
+        It should update the prompt execution settings with the available functions or required functions.
+
+        Alternatively you can override this class and add your own logic in the configure method.
+        """
+        return
+
+    @classmethod
+    @deprecated("Use the `FunctionChoiceBehavior` `Auto` class instead.")
+    def AutoInvokeKernelFunctions(cls) -> "KernelFunctions":
+        """Returns KernelFunctions class with auto_invoke enabled."""
+        return KernelFunctions(max_auto_invoke_attempts=DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS)
+
+    @classmethod
+    @deprecated("Use the `FunctionChoiceBehavior` `Auto` class method instead.")
+    def EnableKernelFunctions(cls) -> "KernelFunctions":
+        """Returns KernelFunctions class with auto_invoke disabled.
+
+        Function calls are enabled in this case, just not invoked.
+        """
+        return KernelFunctions(max_auto_invoke_attempts=0)
+
+    @classmethod
+    @deprecated("Use the `FunctionChoiceBehavior` `Auto` class method instead.")
+    def EnableFunctions(
+        cls,
+        auto_invoke: bool = False,
+        *,
+        filters: dict[
+            Literal["excluded_plugins", "included_plugins", "excluded_functions", "included_functions"], list[str]
+        ]
+        | None = {},
+    ) -> "EnabledFunctions":
+        """Set the enable kernel functions flag."""
+        return EnabledFunctions(
+            filters=filters, max_auto_invoke_attempts=DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS if auto_invoke else 0
+        )
+
+    @classmethod
+    @deprecated("Use the `FunctionChoiceBehavior` `Required` class method instead.")
+    def RequiredFunction(
+        cls,
+        auto_invoke: bool = False,
+        *,
+        function_fully_qualified_name: str,
+    ) -> "RequiredFunction":
+        """Set the required function flag."""
+        return RequiredFunction(
+            function_fully_qualified_name=function_fully_qualified_name,
+            max_auto_invoke_attempts=1 if auto_invoke else 0,
+        )
+
+
+@deprecated("Use the `FunctionChoiceBehavior` `Auto` class instead.")
+class KernelFunctions(FunctionCallBehavior):
+    """Function call behavior for making all kernel functions available for tool calls."""
+
+    def configure(
+        self,
+        kernel: "Kernel",
+        update_settings_callback: Callable[..., None],
+        settings: "PromptExecutionSettings",
+    ) -> None:
+        """Set the options for the tool call behavior in the settings."""
+        if self.enable_kernel_functions:
+            update_settings_callback(
+                FunctionCallConfiguration(available_functions=kernel.get_full_list_of_function_metadata()), settings
+            )
+
+
+@deprecated("Use the `FunctionChoiceBehavior` `Auto` class instead.")
+class EnabledFunctions(FunctionCallBehavior):
+    """Function call behavior for making a filtered set of functions available for tool calls."""
+
+    filters: dict[
+        Literal["excluded_plugins", "included_plugins", "excluded_functions", "included_functions"], list[str]
+    ]
+
+    def configure(
+        self,
+        kernel: "Kernel",
+        update_settings_callback: Callable[..., None],
+        settings: "PromptExecutionSettings",
+    ) -> None:
+        """Set the options for the tool call behavior in the settings."""
+        if self.enable_kernel_functions:
+            update_settings_callback(
+                FunctionCallConfiguration(available_functions=kernel.get_list_of_function_metadata(self.filters)),
+                settings,
+            )
+
+
+@deprecated("Use the `FunctionChoiceBehavior` `Required` class instead.")
+class RequiredFunction(FunctionCallBehavior):
+    """Function call behavior for making a single function available for tool calls."""
+
+    function_fully_qualified_name: str
+
+    def configure(
+        self,
+        kernel: "Kernel",
+        update_settings_callback: Callable[..., None],
+        settings: "PromptExecutionSettings",
+    ) -> None:
+        """Set the options for the tool call behavior in the settings."""
+        if not self.enable_kernel_functions:
+            return
+        # since using this always calls this single function, we do not want to allow repeated calls
+        if self.max_auto_invoke_attempts > 1:
+            self.max_auto_invoke_attempts = 1
+        update_settings_callback(
+            FunctionCallConfiguration(
+                required_functions=kernel.get_list_of_function_metadata(
+                    {"included_functions": [self.function_fully_qualified_name]}
+                )
+            ),
+            settings,
+        )

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/function_call_choice_configuration.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+
+from pydantic.dataclasses import dataclass
+
+from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+
+@experimental_class
+@dataclass
+class FunctionCallChoiceConfiguration:
+    """Configuration for function call choice."""
+
+    available_functions: list[KernelFunctionMetadata] | None = None

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/function_calling_utils.py

@@ -0,0 +1,92 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Any
+
+from semantic_kernel.contents.chat_message_content import ChatMessageContent
+from semantic_kernel.contents.function_result_content import FunctionResultContent
+from semantic_kernel.contents.utils.author_role import AuthorRole
+from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.ai.function_choice_behavior import FunctionCallChoiceConfiguration
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+    from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+
+
+def update_settings_from_function_call_configuration(
+    function_choice_configuration: "FunctionCallChoiceConfiguration",
+    settings: "PromptExecutionSettings",
+    type: str,
+) -> None:
+    """Update the settings from a FunctionChoiceConfiguration."""
+    if (
+        function_choice_configuration.available_functions
+        and hasattr(settings, "tool_choice")
+        and hasattr(settings, "tools")
+    ):
+        settings.tool_choice = type
+        settings.tools = [
+            kernel_function_metadata_to_function_call_format(f)
+            for f in function_choice_configuration.available_functions
+        ]
+
+
+def kernel_function_metadata_to_function_call_format(
+    metadata: "KernelFunctionMetadata",
+) -> dict[str, Any]:
+    """Convert the kernel function metadata to function calling format."""
+    return {
+        "type": "function",
+        "function": {
+            "name": metadata.fully_qualified_name,
+            "description": metadata.description or "",
+            "parameters": {
+                "type": "object",
+                "properties": {param.name: param.schema_data for param in metadata.parameters},
+                "required": [p.name for p in metadata.parameters if p.is_required],
+            },
+        },
+    }
+
+
+def _combine_filter_dicts(*dicts: dict[str, list[str]]) -> dict:
+    """Combine multiple filter dictionaries with list values into one dictionary.
+
+    This method is ensuring unique values while preserving order.
+    """
+    combined_filters = {}
+
+    keys = set().union(*(d.keys() for d in dicts))
+
+    for key in keys:
+        combined_functions: OrderedDict[str, None] = OrderedDict()
+        for d in dicts:
+            if key in d:
+                if isinstance(d[key], list):
+                    for item in d[key]:
+                        combined_functions[item] = None
+                else:
+                    raise ServiceInitializationError(f"Values for filter key '{key}' are not lists.")
+        combined_filters[key] = list(combined_functions.keys())
+
+    return combined_filters
+
+
+def merge_function_results(
+    messages: list[ChatMessageContent],
+) -> list[ChatMessageContent]:
+    """Combine multiple function result content types to one chat message content type.
+
+    This method combines the FunctionResultContent items from separate ChatMessageContent messages,
+    and is used in the event that the `context.terminate = True` condition is met.
+    """
+    items: list[Any] = []
+    for message in messages:
+        items.extend([item for item in message.items if isinstance(item, FunctionResultContent)])
+    return [
+        ChatMessageContent(
+            role=AuthorRole.TOOL,
+            items=items,
+        )
+    ]