semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/contents/streaming_chat_message_content.py

@@ -0,0 +1,219 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from enum import Enum
+from typing import Any, Union, overload
+from xml.etree.ElementTree import Element  # nosec
+
+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.streaming_content_mixin import StreamingContentMixin
+from semantic_kernel.contents.streaming_text_content import StreamingTextContent
+from semantic_kernel.contents.utils.author_role import AuthorRole
+from semantic_kernel.contents.utils.finish_reason import FinishReason
+from semantic_kernel.exceptions import ContentAdditionException
+
+ITEM_TYPES = Union[
+    ImageContent,
+    StreamingTextContent,
+    FunctionCallContent,
+    FunctionResultContent,
+]
+
+
+class StreamingChatMessageContent(ChatMessageContent, StreamingContentMixin):
+    """This is the class for streaming chat message response content.
+
+    All Chat Completion Services should return an instance of this class as streaming response,
+    where each part of the response as it is streamed is converted to an instance of this class,
+    the end-user will have to either do something directly or gather them and combine them into a
+    new instance. A service can implement their own subclass of this class and return instances of that.
+
+    Args:
+        choice_index: int - The index of the choice that generated this response.
+        inner_content: Optional[Any] - The inner content of the response,
+            this should hold all the information from the response so even
+            when not creating a subclass a developer can leverage the full thing.
+        ai_model_id: Optional[str] - The id of the AI model that generated this response.
+        metadata: Dict[str, Any] - Any metadata that should be attached to the response.
+        role: Optional[ChatRole] - The role of the chat message, defaults to ASSISTANT.
+        content: Optional[str] - The text of the response.
+        encoding: Optional[str] - The encoding of the text.
+
+    Methods:
+        __str__: Returns the content of the response.
+        __bytes__: Returns the content of the response encoded in the encoding.
+        __add__: Combines two StreamingChatMessageContent instances.
+    """
+
+    @overload
+    def __init__(
+        self,
+        role: AuthorRole,
+        items: list[ITEM_TYPES],
+        choice_index: int,
+        name: str | None = None,
+        inner_content: Any | None = None,
+        encoding: str | None = None,
+        finish_reason: FinishReason | None = None,
+        ai_model_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        role: AuthorRole,
+        content: str,
+        choice_index: int,
+        name: str | None = None,
+        inner_content: Any | None = None,
+        encoding: str | None = None,
+        finish_reason: FinishReason | None = None,
+        ai_model_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None: ...
+
+    def __init__(  # type: ignore
+        self,
+        role: AuthorRole,
+        choice_index: int,
+        items: list[ITEM_TYPES] | None = None,
+        content: str | None = None,
+        inner_content: Any | None = None,
+        name: str | None = None,
+        encoding: str | None = None,
+        finish_reason: FinishReason | None = None,
+        ai_model_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ):
+        """Create a new instance of StreamingChatMessageContent.
+
+        Args:
+            role: ChatRole - The role of the chat message.
+            choice_index: int - The index of the choice that generated this response.
+            items: list[TextContent, FunctionCallContent, FunctionResultContent, ImageContent] - The content.
+            content: str - The text of the response.
+            inner_content: Optional[Any] - The inner content of the response,
+                this should hold all the information from the response so even
+                when not creating a subclass a developer can leverage the full thing.
+            name: Optional[str] - The name of the response.
+            encoding: Optional[str] - The encoding of the text.
+            finish_reason: Optional[FinishReason] - The reason the response was finished.
+            metadata: Dict[str, Any] - Any metadata that should be attached to the response.
+            ai_model_id: Optional[str] - The id of the AI model that generated this response.
+        """
+        kwargs: dict[str, Any] = {
+            "role": role,
+            "choice_index": choice_index,
+        }
+        if encoding:
+            kwargs["encoding"] = encoding
+        if finish_reason:
+            kwargs["finish_reason"] = finish_reason
+        if name:
+            kwargs["name"] = name
+        if content:
+            item = StreamingTextContent(
+                choice_index=choice_index,
+                ai_model_id=ai_model_id,
+                inner_content=inner_content,
+                metadata=metadata or {},
+                text=content,
+                encoding=encoding,
+            )
+            if items:
+                items.append(item)
+            else:
+                items = [item]
+        if items:
+            kwargs["items"] = items
+        if inner_content:
+            kwargs["inner_content"] = inner_content
+        if metadata:
+            kwargs["metadata"] = metadata
+        if ai_model_id:
+            kwargs["ai_model_id"] = ai_model_id
+        super().__init__(
+            **kwargs,
+        )
+
+    def __bytes__(self) -> bytes:
+        """Return the content of the response encoded in the encoding."""
+        return self.content.encode(self.encoding if self.encoding else "utf-8") if self.content else b""
+
+    def __add__(self, other: "StreamingChatMessageContent") -> "StreamingChatMessageContent":
+        """When combining two StreamingChatMessageContent instances, the content fields are combined.
+
+        The inner_content of the first one is used, ai_model_id and encoding should be the same,
+        if role is set, they should be the same.
+        """
+        if not isinstance(other, StreamingChatMessageContent):
+            raise ContentAdditionException(
+                f"Cannot add other type to StreamingChatMessageContent, type supplied: {type(other)}"
+            )
+        if self.choice_index != other.choice_index:
+            raise ContentAdditionException("Cannot add StreamingChatMessageContent with different choice_index")
+        if self.ai_model_id != other.ai_model_id:
+            raise ContentAdditionException("Cannot add StreamingChatMessageContent from different ai_model_id")
+        if self.encoding != other.encoding:
+            raise ContentAdditionException("Cannot add StreamingChatMessageContent with different encoding")
+        if self.role and other.role and self.role != other.role:
+            raise ContentAdditionException("Cannot add StreamingChatMessageContent with different role")
+        if self.items or other.items:
+            for other_item in other.items:
+                added = False
+                for id, item in enumerate(list(self.items)):
+                    if type(item) is type(other_item) and hasattr(item, "__add__"):
+                        try:
+                            new_item = item + other_item  # type: ignore
+                            self.items[id] = new_item
+                            added = True
+                        except (ValueError, ContentAdditionException):
+                            continue
+                if not added:
+                    self.items.append(other_item)
+        if not isinstance(self.inner_content, list):
+            self.inner_content = [self.inner_content] if self.inner_content else []
+        other_content = (
+            other.inner_content
+            if isinstance(other.inner_content, list)
+            else [other.inner_content]
+            if other.inner_content
+            else []
+        )
+        self.inner_content.extend(other_content)
+        return StreamingChatMessageContent(
+            role=self.role,
+            items=self.items,  # type: ignore
+            choice_index=self.choice_index,
+            inner_content=self.inner_content,
+            ai_model_id=self.ai_model_id,
+            metadata=self.metadata,
+            encoding=self.encoding,
+            finish_reason=self.finish_reason or other.finish_reason,
+        )
+
+    def to_element(self) -> "Element":
+        """Convert the StreamingChatMessageContent to an XML Element.
+
+        Args:
+            root_key: str - The key to use for the root of the XML Element.
+
+        Returns:
+            Element - The XML Element representing the StreamingChatMessageContent.
+        """
+        root = Element(self.tag)
+        for field in self.model_fields_set:
+            if field not in ["role", "name", "encoding", "finish_reason", "ai_model_id", "choice_index"]:
+                continue
+            value = getattr(self, field)
+            if isinstance(value, Enum):
+                value = value.value
+            if isinstance(value, int):
+                value = str(value)
+            root.set(field, value)
+        for index, item in enumerate(self.items):
+            root.insert(index, item.to_element())
+        return root

semantic_kernel-1.8.3/semantic_kernel/contents/streaming_content_mixin.py

@@ -0,0 +1,28 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import sys
+from abc import ABC, abstractmethod
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    from typing import Self  # pragma: no cover
+else:
+    from typing_extensions import Self  # pragma: no cover
+
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class StreamingContentMixin(KernelBaseModel, ABC):
+    """Mixin class for all streaming kernel contents."""
+
+    choice_index: int
+
+    @abstractmethod
+    def __bytes__(self) -> bytes:
+        """Return the content of the response encoded in the encoding."""
+        pass
+
+    @abstractmethod
+    def __add__(self, other: Any) -> Self:
+        """Combine two streaming contents together."""
+        pass

semantic_kernel-1.8.3/semantic_kernel/contents/streaming_text_content.py

@@ -0,0 +1,49 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.contents.streaming_content_mixin import StreamingContentMixin
+from semantic_kernel.contents.text_content import TextContent
+from semantic_kernel.exceptions import ContentAdditionException
+
+
+class StreamingTextContent(StreamingContentMixin, TextContent):
+    """This represents streaming text response content.
+
+    Args:
+        choice_index: int - The index of the choice that generated this response.
+        inner_content: Optional[Any] - The inner content of the response,
+            this should hold all the information from the response so even
+            when not creating a subclass a developer can leverage the full thing.
+        ai_model_id: Optional[str] - The id of the AI model that generated this response.
+        metadata: Dict[str, Any] - Any metadata that should be attached to the response.
+        text: Optional[str] - The text of the response.
+        encoding: Optional[str] - The encoding of the text.
+
+    Methods:
+        __str__: Returns the text of the response.
+        __bytes__: Returns the content of the response encoded in the encoding.
+        __add__: Combines two StreamingTextContent instances.
+    """
+
+    def __bytes__(self) -> bytes:
+        """Return the content of the response encoded in the encoding."""
+        return self.text.encode(self.encoding if self.encoding else "utf-8") if self.text else b""
+
+    def __add__(self, other: TextContent) -> "StreamingTextContent":
+        """When combining two StreamingTextContent instances, the text fields are combined.
+
+        The inner_content of the first one is used, choice_index, ai_model_id and encoding should be the same.
+        """
+        if isinstance(other, StreamingTextContent) and self.choice_index != other.choice_index:
+            raise ContentAdditionException("Cannot add StreamingTextContent with different choice_index")
+        if self.ai_model_id != other.ai_model_id:
+            raise ContentAdditionException("Cannot add StreamingTextContent from different ai_model_id")
+        if self.encoding != other.encoding:
+            raise ContentAdditionException("Cannot add StreamingTextContent with different encoding")
+        return StreamingTextContent(
+            choice_index=self.choice_index,
+            inner_content=self.inner_content,
+            ai_model_id=self.ai_model_id,
+            metadata=self.metadata,
+            text=(self.text or "") + (other.text or ""),
+            encoding=self.encoding,
+        )

semantic_kernel-1.8.3/semantic_kernel/contents/text_content.py

@@ -0,0 +1,63 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from html import unescape
+from typing import ClassVar, Literal, TypeVar
+from xml.etree.ElementTree import Element  # nosec
+
+from pydantic import Field
+
+from semantic_kernel.contents.const import TEXT_CONTENT_TAG, ContentTypes
+from semantic_kernel.contents.kernel_content import KernelContent
+from semantic_kernel.exceptions.content_exceptions import ContentInitializationError
+
+_T = TypeVar("_T", bound="TextContent")
+
+
+class TextContent(KernelContent):
+    """This represents text response content.
+
+    Args:
+        inner_content: Any - The inner content of the response,
+            this should hold all the information from the response so even
+            when not creating a subclass a developer can leverage the full thing.
+        ai_model_id: str | None - The id of the AI model that generated this response.
+        metadata: dict[str, Any] - Any metadata that should be attached to the response.
+        text: str | None - The text of the response.
+        encoding: str | None - The encoding of the text.
+
+    Methods:
+        __str__: Returns the text of the response.
+    """
+
+    content_type: Literal[ContentTypes.TEXT_CONTENT] = Field(TEXT_CONTENT_TAG, init=False)  # type: ignore
+    tag: ClassVar[str] = TEXT_CONTENT_TAG
+    text: str
+    encoding: str | None = None
+
+    def __str__(self) -> str:
+        """Return the text of the response."""
+        return self.text
+
+    def to_element(self) -> Element:
+        """Convert the instance to an Element."""
+        element = Element(self.tag)
+        element.text = self.text
+        if self.encoding:
+            element.set("encoding", self.encoding)
+        return element
+
+    @classmethod
+    def from_element(cls: type[_T], element: Element) -> _T:
+        """Create an instance from an Element."""
+        if element.tag != cls.tag:
+            raise ContentInitializationError(f"Element tag is not {cls.tag}")  # pragma: no cover
+
+        return cls(text=unescape(element.text) if element.text else "", encoding=element.get("encoding", None))
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert the instance to a dictionary."""
+        return {"type": "text", "text": self.text}
+
+    def __hash__(self) -> int:
+        """Return the hash of the text content."""
+        return hash((self.tag, self.text, self.encoding))

semantic_kernel-1.8.3/semantic_kernel/contents/utils/author_role.py

@@ -0,0 +1,11 @@
+# Copyright (c) Microsoft. All rights reserved.
+from enum import Enum
+
+
+class AuthorRole(str, Enum):
+    """Author role enum."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"

semantic_kernel-1.8.3/semantic_kernel/contents/utils/data_uri.py

@@ -0,0 +1,125 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import base64
+import binascii
+import logging
+import re
+import sys
+from typing import Any, TypeVar
+
+if sys.version < "3.11":
+    from typing_extensions import Self  # pragma: no cover
+else:
+    from typing import Self  # type: ignore # pragma: no cover
+
+from pydantic import Field, ValidationError, field_validator, model_validator
+from pydantic_core import Url
+
+from semantic_kernel.exceptions import ContentInitializationError
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+logger = logging.getLogger(__name__)
+
+_T = TypeVar("_T", bound="DataUri")
+
+
+class DataUri(KernelBaseModel, validate_assignment=True):
+    """A class to represent a data uri."""
+
+    data_bytes: bytes | None = None
+    data_str: str | None = None
+    mime_type: str | None = None
+    parameters: dict[str, str] = Field(default_factory=dict)
+    data_format: str | None = None
+
+    def update_data(self, value: str | bytes):
+        """Update the data, using either a string or bytes."""
+        if isinstance(value, str):
+            self.data_str = value
+        else:
+            self.data_bytes = value
+
+    @model_validator(mode="before")
+    @classmethod
+    def _validate_data(cls, values: dict[str, Any]) -> dict[str, Any]:
+        """Validate the data."""
+        if not values.get("data_bytes") and not values.get("data_str"):
+            raise ContentInitializationError("Either data_bytes or data_str must be provided.")
+        return values
+
+    @model_validator(mode="after")
+    def _parse_data(self) -> Self:
+        """Parse the data bytes to str."""
+        if not self.data_str and self.data_bytes:
+            if self.data_format and self.data_format.lower() == "base64":
+                self.data_str = base64.b64encode(self.data_bytes).decode("utf-8")
+            else:
+                self.data_str = self.data_bytes.decode("utf-8")
+        if self.data_format and self.data_format.lower() == "base64" and self.data_str:
+            try:
+                if not self.data_bytes:
+                    self.data_bytes = base64.b64decode(self.data_str, validate=True)
+                else:
+                    base64.b64decode(self.data_str, validate=True)
+            except binascii.Error as exc:
+                raise ContentInitializationError("Invalid base64 data.") from exc
+        return self
+
+    @field_validator("parameters", mode="before")
+    def _validate_parameters(cls, value: list[str] | dict[str, str] | None = None) -> dict[str, str]:
+        if not value:
+            return {}
+        if isinstance(value, dict):
+            return value
+
+        new: dict[str, str] = {}
+        for item in value:
+            item = item.strip()
+            if not item:
+                continue
+            if "=" not in item:
+                raise ContentInitializationError("Invalid data uri format. The parameter is missing a value.")
+            name, val = item.split("=", maxsplit=1)
+            new[name] = val
+        return new
+
+    @classmethod
+    def from_data_uri(cls: type[_T], data_uri: str | Url, default_mime_type: str = "text/plain") -> _T:
+        """Create a DataUri object from a data URI string or pydantic URL."""
+        if isinstance(data_uri, str):
+            try:
+                data_uri = Url(data_uri)
+            except ValidationError as exc:
+                raise ContentInitializationError("Invalid data uri format.") from exc
+
+        data = data_uri.path
+        if not data or "," not in data:
+            raise ContentInitializationError("Invalid data uri format. The data is missing.")
+
+        pattern = "(((?P<mime_type>[a-zA-Z]+/[a-zA-Z-]+)(?P<parameters>(;[a-zA-Z0-9]+=+[a-zA-Z0-9]+)*))?(;+(?P<data_format>.*)))?(,(?P<data_str>.*))"  # noqa: E501
+        match = re.match(pattern, data)
+        if not match:
+            raise ContentInitializationError("Invalid data uri format.")
+        matches = match.groupdict()
+        if not matches.get("data_format"):
+            matches.pop("data_format")
+        if not matches.get("parameters"):
+            matches.pop("parameters")
+        else:
+            matches["parameters"] = matches["parameters"].strip(";").split(";")
+        if not matches.get("mime_type"):
+            matches["mime_type"] = default_mime_type
+        return cls(**matches)
+
+    def to_string(self, metadata: dict[str, str] = {}) -> str:
+        """Return the data uri as a string."""
+        parameters = ";".join([f"{key}={val}" for key, val in metadata.items()])
+        parameters = f";{parameters}" if parameters else ""
+        data_format = f"{self.data_format}" if self.data_format else ""
+        return f"data:{self.mime_type or ''}{parameters};{data_format},{self.data_str}"
+
+    def __eq__(self, value: object) -> bool:
+        """Check if the data uri is equal to another."""
+        if not isinstance(value, DataUri):
+            return False
+        return self.to_string() == value.to_string()

semantic_kernel-1.8.3/semantic_kernel/contents/utils/finish_reason.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft. All rights reserved.
+from enum import Enum
+
+
+class FinishReason(str, Enum):
+    """Finish Reason enum."""
+
+    STOP = "stop"
+    LENGTH = "length"
+    CONTENT_FILTER = "content_filter"
+    TOOL_CALLS = "tool_calls"
+    FUNCTION_CALL = "function_call"

semantic_kernel-1.8.3/semantic_kernel/core_plugins/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.core_plugins.conversation_summary_plugin import (
+    ConversationSummaryPlugin,
+)
+from semantic_kernel.core_plugins.http_plugin import HttpPlugin
+from semantic_kernel.core_plugins.math_plugin import MathPlugin
+from semantic_kernel.core_plugins.sessions_python_tool.sessions_python_plugin import (
+    SessionsPythonTool,
+)
+from semantic_kernel.core_plugins.text_memory_plugin import TextMemoryPlugin
+from semantic_kernel.core_plugins.text_plugin import TextPlugin
+from semantic_kernel.core_plugins.time_plugin import TimePlugin
+from semantic_kernel.core_plugins.web_search_engine_plugin import WebSearchEnginePlugin
+
+__all__ = [
+    "ConversationSummaryPlugin",
+    "HttpPlugin",
+    "MathPlugin",
+    "SessionsPythonTool",
+    "TextMemoryPlugin",
+    "TextPlugin",
+    "TimePlugin",
+    "WebSearchEnginePlugin",
+]

semantic_kernel-1.8.3/semantic_kernel/core_plugins/conversation_summary_plugin.py

@@ -0,0 +1,93 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from typing import TYPE_CHECKING, Annotated, Any
+
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.functions.kernel_function_from_prompt import KernelFunctionFromPrompt
+
+if TYPE_CHECKING:
+    from semantic_kernel.functions.kernel_arguments import KernelArguments
+    from semantic_kernel.kernel import Kernel
+    from semantic_kernel.prompt_template.prompt_template_config import PromptTemplateConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ConversationSummaryPlugin:
+    """Semantic plugin that enables conversations summarization."""
+
+    # The max tokens to process in a single semantic function call.
+    _max_tokens = 1024
+
+    _summarize_conversation_prompt_template = (
+        "BEGIN CONTENT TO SUMMARIZE:\n{{"
+        "$input"
+        "}}\nEND CONTENT TO SUMMARIZE.\nSummarize the conversation in 'CONTENT TO"
+        " SUMMARIZE',            identifying main points of discussion and any"
+        " conclusions that were reached.\nDo not incorporate other general"
+        " knowledge.\nSummary is in plain text, in complete sentences, with no markup"
+        " or tags.\n\nBEGIN SUMMARY:\n"
+    )
+
+    def __init__(
+        self, prompt_template_config: "PromptTemplateConfig", return_key: str = "summary", **kwargs: Any
+    ) -> None:
+        """Initializes a new instance of the ConversationSummaryPlugin.
+
+        The template for this plugin is built-in, and will overwrite any template passed in the prompt_template_config.
+
+        Args:
+            prompt_template_config (PromptTemplateConfig): The prompt template configuration.
+            return_key (str): The key to use for the return value.
+            **kwargs: Additional keyword arguments, not used only for compatibility.
+
+        """
+        if "kernel" in kwargs:
+            logger.warning(
+                "The kernel parameter is not used in the ConversationSummaryPlugin constructor anymore."
+                "Please make sure to remove and to add the created plugin to the kernel, by using:"
+                "kernel.add_plugin(conversation_plugin, 'summarizer')"
+            )
+
+        self.return_key = return_key
+        prompt_template_config.template = ConversationSummaryPlugin._summarize_conversation_prompt_template
+        prompt_template_config.template_format = "semantic-kernel"
+        self._summarizeConversationFunction = KernelFunctionFromPrompt(
+            plugin_name=ConversationSummaryPlugin.__name__,
+            function_name="SummarizeConversation",
+            prompt_template_config=prompt_template_config,
+        )
+
+    @kernel_function(
+        description="Given a long conversation transcript, summarize the conversation.",
+        name="SummarizeConversation",
+    )
+    async def summarize_conversation(
+        self,
+        input: Annotated[str, "A long conversation transcript."],
+        kernel: Annotated["Kernel", "The kernel instance."],
+        arguments: Annotated["KernelArguments", "Arguments used by the kernel."],
+    ) -> Annotated[
+        "KernelArguments", "KernelArguments with the summarized conversation result in key self.return_key."
+    ]:
+        """Given a long conversation transcript, summarize the conversation.
+
+        Args:
+            input (str): A long conversation transcript.
+            kernel (Kernel): The kernel for function execution.
+            arguments (KernelArguments): Arguments used by the kernel.
+
+        Returns:
+            KernelArguments with the summarized conversation result in key self.return_key.
+        """
+        from semantic_kernel.text import text_chunker
+        from semantic_kernel.text.function_extension import aggregate_chunked_results
+
+        lines = text_chunker._split_text_lines(input, ConversationSummaryPlugin._max_tokens, True)
+        paragraphs = text_chunker._split_text_paragraph(lines, ConversationSummaryPlugin._max_tokens)
+
+        arguments[self.return_key] = await aggregate_chunked_results(
+            self._summarizeConversationFunction, paragraphs, kernel, arguments
+        )
+        return arguments