semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/connectors/search_engine/connector.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC, abstractmethod
+
+
+class ConnectorBase(ABC):
+    """Base class for search engine connectors."""
+
+    @abstractmethod
+    async def search(self, query: str, num_results: int = 1, offset: int = 0) -> list[str]:
+        """Returns the search results of the query provided by pinging the search engine API."""
+        pass

semantic_kernel-1.8.3/semantic_kernel/connectors/search_engine/google_connector.py

@@ -0,0 +1,106 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+import urllib
+
+from httpx import AsyncClient, HTTPStatusError, RequestError
+from pydantic import ValidationError
+
+from semantic_kernel.connectors.search_engine.connector import ConnectorBase
+from semantic_kernel.connectors.search_engine.google_search_settings import GoogleSearchSettings
+from semantic_kernel.exceptions import ServiceInitializationError, ServiceInvalidRequestError
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class GoogleConnector(ConnectorBase):
+    """A search engine connector that uses the Google Custom Search API to perform a web search."""
+
+    _settings: GoogleSearchSettings
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        search_engine_id: str | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initializes a new instance of the GoogleConnector class.
+
+        Args:
+            api_key (str | None): The Google Custom Search API key. If provided, will override
+                the value in the env vars or .env file.
+            search_engine_id (str | None): The Google search engine ID. If provided, will override
+                the value in the env vars or .env file.
+            env_file_path (str | None): The optional path to the .env file. If provided,
+                the settings are read from this file path location.
+            env_file_encoding (str | None): The optional encoding of the .env file.
+        """
+        try:
+            self._settings = GoogleSearchSettings.create(
+                api_key=api_key,
+                search_engine_id=search_engine_id,
+                env_file_path=env_file_path,
+                env_file_encoding=env_file_encoding,
+            )
+        except ValidationError as ex:
+            raise ServiceInitializationError("Failed to create Google Search settings.") from ex
+
+        if not self._settings.search_engine_id:
+            raise ServiceInitializationError("Google search engine ID cannot be null.")
+
+    async def search(self, query: str, num_results: int = 1, offset: int = 0) -> list[str]:
+        """Returns the search results of the query provided by pinging the Google Custom search API.
+
+        Args:
+            query (str): The search query.
+            num_results (int): The number of search results to return. Default is 1.
+            offset (int): The offset of the search results. Default is 0.
+
+        Returns:
+            list[str]: A list of search results snippets.
+        """
+        if not query:
+            raise ServiceInvalidRequestError("query cannot be 'None' or empty.")
+
+        if num_results <= 0:
+            raise ServiceInvalidRequestError("num_results value must be greater than 0.")
+        if num_results > 10:
+            raise ServiceInvalidRequestError("num_results value must be less than or equal to 10.")
+
+        if offset < 0:
+            raise ServiceInvalidRequestError("offset must be greater than 0.")
+
+        logger.info(
+            f"Received request for google search with \
+                params:\nquery: {query}\nnum_results: {num_results}\noffset: {offset}"
+        )
+
+        base_url = "https://www.googleapis.com/customsearch/v1"
+        request_url = (
+            f"{base_url}?q={urllib.parse.quote_plus(query)}"
+            f"&key={self._settings.search_api_key.get_secret_value()}&cx={self._settings.search_engine_id}"
+            f"&num={num_results}&start={offset}"
+        )
+
+        logger.info("Sending GET request to Google Search API.")
+
+        logger.info("Sending GET request to Google Search API.")
+
+        try:
+            async with AsyncClient() as client:
+                response = await client.get(request_url)
+                response.raise_for_status()
+                data = response.json()
+                logger.info("Request successful.")
+                logger.info(f"API Response: {data}")
+                return [x["snippet"] for x in data.get("items", [])]
+        except HTTPStatusError as ex:
+            logger.error(f"Failed to get search results: {ex}")
+            raise ServiceInvalidRequestError("Failed to get search results.") from ex
+        except RequestError as ex:
+            logger.error(f"Client error occurred: {ex}")
+            raise ServiceInvalidRequestError("A client error occurred while getting search results.") from ex
+        except Exception as ex:
+            logger.error(f"An unexpected error occurred: {ex}")
+            raise ServiceInvalidRequestError("An unexpected error occurred while getting search results.") from ex

semantic_kernel-1.8.3/semantic_kernel/connectors/search_engine/google_search_settings.py

@@ -0,0 +1,30 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import ClassVar
+
+from pydantic import SecretStr
+
+from semantic_kernel.kernel_pydantic import KernelBaseSettings
+
+
+class GoogleSearchSettings(KernelBaseSettings):
+    """Google Search Connector settings.
+
+    The settings are first loaded from environment variables with the prefix 'GOOGLE_'. If the
+    environment variables are not found, the settings can be loaded from a .env file with the
+    encoding 'utf-8'. If the settings are not found in the .env file, the settings are ignored;
+    however, validation will fail alerting that the settings are missing.
+
+    Required settings for prefix 'GOOGLE_' are:
+    - search_api_key: SecretStr - The Google Search API key (Env var GOOGLE_API_KEY)
+
+    Optional settings for prefix 'GOOGLE_' are:
+    - search_engine_id: str - The Google search engine ID (Env var GOOGLE_SEARCH_ENGINE_ID)
+    - env_file_path: str | None - if provided, the .env settings are read from this file path location
+    - env_file_encoding: str - if provided, the .env file encoding used. Defaults to "utf-8".
+    """
+
+    env_prefix: ClassVar[str] = "GOOGLE_"
+
+    search_api_key: SecretStr
+    search_engine_id: str | None = None

semantic_kernel-1.8.3/semantic_kernel/connectors/utils/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.connectors.utils.document_loader import DocumentLoader
+
+__all__ = ["DocumentLoader"]

semantic_kernel-1.8.3/semantic_kernel/connectors/utils/document_loader.py

@@ -0,0 +1,50 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from collections.abc import Awaitable, Callable
+from inspect import isawaitable
+
+from httpx import AsyncClient, HTTPStatusError, RequestError
+
+from semantic_kernel.exceptions import ServiceInvalidRequestError
+from semantic_kernel.utils.telemetry.user_agent import HTTP_USER_AGENT
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class DocumentLoader:
+    """Utility class to load a document from a URL."""
+
+    @staticmethod
+    async def from_uri(
+        url: str,
+        http_client: AsyncClient,
+        auth_callback: Callable[..., None | Awaitable[dict[str, str]]] | None,
+        user_agent: str | None = HTTP_USER_AGENT,
+    ):
+        """Load the manifest from the given URL."""
+        if user_agent is None:
+            user_agent = HTTP_USER_AGENT
+
+        headers = {"User-Agent": user_agent}
+        try:
+            async with http_client as client:
+                if auth_callback:
+                    callback = auth_callback(client, url)
+                    if isawaitable(callback):
+                        await callback
+
+                logger.info(f"Importing document from {url}")
+
+                response = await client.get(url, headers=headers)
+                response.raise_for_status()
+                return response.text
+        except HTTPStatusError as ex:
+            logger.error(f"Failed to get document: {ex}")
+            raise ServiceInvalidRequestError("Failed to get document.") from ex
+        except RequestError as ex:
+            logger.error(f"Client error occurred: {ex}")
+            raise ServiceInvalidRequestError("A client error occurred while getting the document.") from ex
+        except Exception as ex:
+            logger.error(f"An unexpected error occurred: {ex}")
+            raise ServiceInvalidRequestError("An unexpected error occurred while getting the document.") from ex

semantic_kernel-1.8.3/semantic_kernel/const.py

@@ -0,0 +1,8 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import Final
+
+METADATA_EXCEPTION_KEY: Final[str] = "exception"
+DEFAULT_SERVICE_NAME: Final[str] = "default"
+USER_AGENT: Final[str] = "User-Agent"
+PARSED_ANNOTATION_UNION_DELIMITER: Final[str] = ","

semantic_kernel-1.8.3/semantic_kernel/contents/__init__.py

@@ -0,0 +1,27 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.contents.annotation_content import AnnotationContent
+from semantic_kernel.contents.chat_history import ChatHistory
+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_chat_message_content import StreamingChatMessageContent
+from semantic_kernel.contents.streaming_text_content import StreamingTextContent
+from semantic_kernel.contents.text_content import TextContent
+from semantic_kernel.contents.utils.author_role import AuthorRole
+from semantic_kernel.contents.utils.finish_reason import FinishReason
+
+__all__ = [
+    "AnnotationContent",
+    "AuthorRole",
+    "ChatHistory",
+    "ChatMessageContent",
+    "FinishReason",
+    "FunctionCallContent",
+    "FunctionResultContent",
+    "ImageContent",
+    "StreamingChatMessageContent",
+    "StreamingTextContent",
+    "TextContent",
+]

semantic_kernel-1.8.3/semantic_kernel/contents/annotation_content.py

@@ -0,0 +1,61 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from typing import Any, ClassVar, Literal, TypeVar
+from xml.etree.ElementTree import Element  # nosec
+
+from pydantic import Field
+
+from semantic_kernel.contents.const import ANNOTATION_CONTENT_TAG, ContentTypes
+from semantic_kernel.contents.kernel_content import KernelContent
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+logger = logging.getLogger(__name__)
+
+_T = TypeVar("_T", bound="AnnotationContent")
+
+
+@experimental_class
+class AnnotationContent(KernelContent):
+    """Annotation content."""
+
+    content_type: Literal[ContentTypes.ANNOTATION_CONTENT] = Field(ANNOTATION_CONTENT_TAG, init=False)  # type: ignore
+    tag: ClassVar[str] = ANNOTATION_CONTENT_TAG
+    file_id: str | None = None
+    quote: str | None = None
+    start_index: int | None = None
+    end_index: int | None = None
+
+    def __str__(self) -> str:
+        """Return the string representation of the annotation content."""
+        return f"AnnotationContent(file_id={self.file_id}, quote={self.quote}, start_index={self.start_index}, end_index={self.end_index})"  # noqa: E501
+
+    def to_element(self) -> Element:
+        """Convert the annotation content to an Element."""
+        element = Element(self.tag)
+        if self.file_id:
+            element.set("file_id", self.file_id)
+        if self.quote:
+            element.set("quote", self.quote)
+        if self.start_index is not None:
+            element.set("start_index", str(self.start_index))
+        if self.end_index is not None:
+            element.set("end_index", str(self.end_index))
+        return element
+
+    @classmethod
+    def from_element(cls: type[_T], element: Element) -> _T:
+        """Create an instance from an Element."""
+        return cls(
+            file_id=element.get("file_id"),
+            quote=element.get("quote"),
+            start_index=int(element.get("start_index")) if element.get("start_index") else None,  # type: ignore
+            end_index=int(element.get("end_index")) if element.get("end_index") else None,  # type: ignore
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the instance to a dictionary."""
+        return {
+            "type": "text",
+            "text": f"{self.file_id} {self.quote} (Start Index={self.start_index}->End Index={self.end_index})",
+        }

semantic_kernel-1.8.3/semantic_kernel/contents/binary_content.py

@@ -0,0 +1,162 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from typing import Annotated, Any, ClassVar, Literal, TypeVar
+from xml.etree.ElementTree import Element  # nosec
+
+from pydantic import Field, UrlConstraints, computed_field
+from pydantic_core import Url
+
+from semantic_kernel.contents.const import BINARY_CONTENT_TAG, ContentTypes
+from semantic_kernel.contents.kernel_content import KernelContent
+from semantic_kernel.contents.utils.data_uri import DataUri
+from semantic_kernel.exceptions.content_exceptions import ContentInitializationError
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+logger = logging.getLogger(__name__)
+
+_T = TypeVar("_T", bound="BinaryContent")
+
+DataUrl = Annotated[Url, UrlConstraints(allowed_schemes=["data"])]
+
+
+@experimental_class
+class BinaryContent(KernelContent):
+    """This is a base class for different types of binary content.
+
+    This can be created either the bytes data or a data uri, additionally it can have a uri.
+    The uri is a reference to the source, and might or might not point to the same thing as the data.
+
+    Ideally only subclasses of this class are used, like ImageContent.
+
+    Methods:
+        __str__: Returns the string representation of the content.
+
+    Raises:
+        ValidationError: If any arguments are malformed.
+
+    """
+
+    content_type: Literal[ContentTypes.BINARY_CONTENT] = Field(BINARY_CONTENT_TAG, init=False)  # type: ignore
+    uri: Url | None = None
+    default_mime_type: ClassVar[str] = "text/plain"
+    tag: ClassVar[str] = BINARY_CONTENT_TAG
+    _data_uri: DataUri | None = None
+
+    def __init__(
+        self,
+        uri: Url | str | None = None,
+        data_uri: DataUrl | str | None = None,
+        data: str | bytes | None = None,
+        data_format: str | None = None,
+        mime_type: str | None = None,
+        **kwargs: Any,
+    ):
+        """Create a Binary Content object, either from a data_uri or data.
+
+        Args:
+            uri (Url | None): The reference uri of the content.
+            data_uri (DataUrl | None): The data uri of the content.
+            data (str | bytes | None): The data of the content.
+            data_format (str | None): The format of the data (e.g. base64).
+            mime_type (str | None): The mime type of the image, only used with data.
+            kwargs (Any): Any additional arguments:
+                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.
+        """
+        _data_uri = None
+        if data_uri:
+            _data_uri = DataUri.from_data_uri(data_uri, self.default_mime_type)
+            if "metadata" in kwargs:
+                kwargs["metadata"].update(_data_uri.parameters)
+            else:
+                kwargs["metadata"] = _data_uri.parameters
+        elif data:
+            if isinstance(data, str):
+                _data_uri = DataUri(
+                    data_str=data, data_format=data_format, mime_type=mime_type or self.default_mime_type
+                )
+            else:
+                _data_uri = DataUri(
+                    data_bytes=data, data_format=data_format, mime_type=mime_type or self.default_mime_type
+                )
+        super().__init__(uri=uri, **kwargs)
+        self._data_uri = _data_uri
+
+    @computed_field  # type: ignore
+    @property
+    def data_uri(self) -> str:
+        """Get the data uri."""
+        if self._data_uri:
+            return self._data_uri.to_string(self.metadata)
+        return ""
+
+    @data_uri.setter
+    def data_uri(self, value: str):
+        """Set the data uri."""
+        self._data_uri = DataUri.from_data_uri(value)
+        self.metadata.update(self._data_uri.parameters)
+
+    @property
+    def data(self) -> bytes:
+        """Get the data."""
+        if self._data_uri and self._data_uri.data_bytes:
+            return self._data_uri.data_bytes
+        if self._data_uri and self._data_uri.data_str:
+            return self._data_uri.data_str.encode("utf-8")
+        return b""
+
+    @data.setter
+    def data(self, value: str | bytes):
+        """Set the data."""
+        if self._data_uri:
+            self._data_uri.update_data(value)
+        else:
+            if isinstance(value, str):
+                self._data_uri = DataUri(data_str=value, mime_type=self.mime_type)
+            else:
+                self._data_uri = DataUri(data_bytes=value, mime_type=self.mime_type)
+
+    @property
+    def mime_type(self) -> str:
+        """Get the mime type."""
+        if self._data_uri and self._data_uri.mime_type:
+            return self._data_uri.mime_type
+        return self.default_mime_type
+
+    @mime_type.setter
+    def mime_type(self, value: str):
+        """Set the mime type."""
+        if self._data_uri:
+            self._data_uri.mime_type = value
+
+    def __str__(self) -> str:
+        """Return the string representation of the content."""
+        return self.data_uri if self._data_uri else str(self.uri)
+
+    def to_element(self) -> Element:
+        """Convert the instance to an Element."""
+        element = Element(self.tag)
+        if self._data_uri:
+            element.text = self.data_uri
+        if self.uri:
+            element.set("uri", str(self.uri))
+        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
+
+        if element.text:
+            return cls(data_uri=element.text, uri=element.get("uri", None))
+
+        return cls(uri=element.get("uri", None))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the instance to a dictionary."""
+        return {"type": "binary", "binary": {"uri": str(self)}}