semantic-kernel 1.8.3__zip

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

@@ -0,0 +1,120 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from typing import Any, TypeVar
+
+from pydantic import Field, model_validator
+
+from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+logger = logging.getLogger(__name__)
+
+_T = TypeVar("_T", bound="PromptExecutionSettings")
+
+
+class PromptExecutionSettings(KernelBaseModel):
+    """Base class for prompt execution settings.
+
+    Can be used by itself or as a base class for other prompt execution settings. The methods are used to create
+    specific prompt execution settings objects based on the keys in the extension_data field, this way you can
+    create a generic PromptExecutionSettings object in your application, which gets mapped into the keys of the
+    prompt execution settings that each services returns by using the service.get_prompt_execution_settings() method.
+
+    Attributes:
+        service_id (str | None): The service ID to use for the request.
+        extension_data (Dict[str, Any]): Any additional data to send with the request.
+        function_choice_behavior (FunctionChoiceBehavior | None): The function choice behavior settings.
+
+    Methods:
+        prepare_settings_dict: Prepares the settings as a dictionary for sending to the AI service.
+        update_from_prompt_execution_settings: Update the keys from another prompt execution settings object.
+        from_prompt_execution_settings: Create a prompt execution settings from another prompt execution settings.
+    """
+
+    service_id: str | None = Field(None, min_length=1)
+    extension_data: dict[str, Any] = Field(default_factory=dict)
+    function_choice_behavior: FunctionChoiceBehavior | None = Field(None, exclude=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def parse_function_choice_behavior(cls: type[_T], data: dict[str, Any]) -> dict[str, Any]:
+        """Parse the function choice behavior data."""
+        function_choice_behavior_data = data.get("function_choice_behavior")
+        if function_choice_behavior_data:
+            if isinstance(function_choice_behavior_data, str):
+                data["function_choice_behavior"] = FunctionChoiceBehavior.from_string(function_choice_behavior_data)
+            elif isinstance(function_choice_behavior_data, dict):
+                data["function_choice_behavior"] = FunctionChoiceBehavior.from_dict(function_choice_behavior_data)
+        return data
+
+    def __init__(self, service_id: str | None = None, **kwargs: Any):
+        """Initialize the prompt execution settings.
+
+        Args:
+            service_id (str): The service ID to use for the request.
+            kwargs (Any): Additional keyword arguments,
+                these are attempted to parse into the keys of the specific prompt execution settings.
+        """
+        extension_data = kwargs.pop("extension_data", {})
+        function_choice_behavior = kwargs.pop("function_choice_behavior", None)
+        extension_data.update(kwargs)
+        super().__init__(
+            service_id=service_id, extension_data=extension_data, function_choice_behavior=function_choice_behavior
+        )
+        self.unpack_extension_data()
+
+    @property
+    def keys(self):
+        """Get the keys of the prompt execution settings."""
+        return self.model_fields.keys()
+
+    def prepare_settings_dict(self, **kwargs) -> dict[str, Any]:
+        """Prepare the settings as a dictionary for sending to the AI service.
+
+        By default, this method excludes the service_id and extension_data fields.
+        As well as any fields that are None.
+        """
+        return self.model_dump(
+            exclude={
+                "service_id",
+                "extension_data",
+            },
+            exclude_none=True,
+            by_alias=True,
+        )
+
+    def update_from_prompt_execution_settings(self, config: _T) -> None:
+        """Update the prompt execution settings from a completion config."""
+        if config.service_id is not None:
+            self.service_id = config.service_id
+        config.pack_extension_data()
+        self.extension_data.update(config.extension_data)
+        self.unpack_extension_data()
+
+    @classmethod
+    def from_prompt_execution_settings(cls: type[_T], config: _T) -> _T:
+        """Create a prompt execution settings from a completion config."""
+        config.pack_extension_data()
+        return cls(
+            service_id=config.service_id,
+            extension_data=config.extension_data,
+            function_choice_behavior=config.function_choice_behavior,
+        )
+
+    def unpack_extension_data(self) -> None:
+        """Update the prompt execution settings from extension data.
+
+        Does not overwrite existing values with None.
+        """
+        for key, value in self.extension_data.items():
+            if value is None:
+                continue
+            if key in self.keys:
+                setattr(self, key, value)
+
+    def pack_extension_data(self) -> None:
+        """Update the extension data from the prompt execution settings."""
+        for key in self.model_fields_set:
+            if key not in ["service_id", "extension_data"] and getattr(self, key) is not None:
+                self.extension_data[key] = getattr(self, key)

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

@@ -0,0 +1,83 @@
+# 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.services.ai_service_client_base import AIServiceClientBase
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+    from semantic_kernel.contents import StreamingTextContent, TextContent
+
+
+class TextCompletionClientBase(AIServiceClientBase, ABC):
+    """Base class for text completion AI services."""
+
+    @abstractmethod
+    async def get_text_contents(
+        self,
+        prompt: str,
+        settings: "PromptExecutionSettings",
+    ) -> list["TextContent"]:
+        """Create text contents, in the number specified by the settings.
+
+        Args:
+            prompt (str): The prompt to send to the LLM.
+            settings (PromptExecutionSettings): Settings for the request.
+
+        Returns:
+            list[TextContent]: A string or list of strings representing the response(s) from the LLM.
+        """
+
+    async def get_text_content(self, prompt: str, settings: "PromptExecutionSettings") -> "TextContent | None":
+        """This is the method that is called from the kernel to get a response from a text-optimized LLM.
+
+        Args:
+            prompt (str): The prompt to send to the LLM.
+            settings (PromptExecutionSettings): Settings for the request.
+
+        Returns:
+            TextContent: A string or list of strings representing the response(s) from the LLM.
+        """
+        result = await self.get_text_contents(prompt=prompt, settings=settings)
+        if result:
+            return result[0]
+        # this should not happen, should error out before returning an empty list
+        return None  # pragma: no cover
+
+    @abstractmethod
+    def get_streaming_text_contents(
+        self,
+        prompt: str,
+        settings: "PromptExecutionSettings",
+    ) -> AsyncGenerator[list["StreamingTextContent"], Any]:
+        """Create streaming text contents, in the number specified by the settings.
+
+        Args:
+            prompt (str): The prompt to send to the LLM.
+            settings (PromptExecutionSettings): Settings for the request.
+
+        Yields:
+            list[StreamingTextContent]: A stream representing the response(s) from the LLM.
+        """
+        ...
+
+    async def get_streaming_text_content(
+        self, prompt: str, settings: "PromptExecutionSettings"
+    ) -> AsyncGenerator["StreamingTextContent | None", Any]:
+        """This is the method that is called from the kernel to get a stream response from a text-optimized LLM.
+
+        Args:
+            prompt (str): The prompt to send to the LLM.
+            settings (PromptExecutionSettings): Settings for the request.
+
+        Returns:
+            StreamingTextContent: A stream representing the response(s) from the LLM.
+        """
+        async for contents in self.get_streaming_text_contents(prompt, settings):
+            if contents:
+                yield contents[0]
+            else:
+                # this should not happen, should error out before returning an empty list
+                yield None  # pragma: no cover

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

@@ -0,0 +1,25 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from semantic_kernel.services.ai_service_client_base import AIServiceClientBase
+
+
+class TextToImageClientBase(AIServiceClientBase, ABC):
+    """Base class for text to image client."""
+
+    @abstractmethod
+    async def generate_image(self, description: str, width: int, height: int, **kwargs: Any) -> bytes | str:
+        """Generate image from text.
+
+        Args:
+            description: Description of the image.
+            width: Width of the image.
+            height: Height of the image.
+            kwargs: Additional arguments.
+
+        Returns:
+            bytes | str: Image bytes or image URL.
+        """
+        raise NotImplementedError

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

@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.

semantic_kernel-1.8.3/semantic_kernel/connectors/memory/astradb/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.connectors.memory.astradb.astradb_memory_store import (
+    AstraDBMemoryStore,
+)
+from semantic_kernel.connectors.memory.astradb.astradb_settings import AstraDBSettings
+
+__all__ = ["AstraDBMemoryStore", "AstraDBSettings"]

semantic_kernel-1.8.3/semantic_kernel/connectors/memory/astradb/astra_client.py

@@ -0,0 +1,182 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import json
+
+import aiohttp
+
+from semantic_kernel.connectors.memory.astradb.utils import AsyncSession
+from semantic_kernel.exceptions import ServiceResponseException
+from semantic_kernel.utils.experimental_decorator import experimental_class
+from semantic_kernel.utils.telemetry.user_agent import APP_INFO
+
+ASTRA_CALLER_IDENTITY: str
+SEMANTIC_KERNEL_VERSION = APP_INFO.get("Semantic-Kernel-Version")
+ASTRA_CALLER_IDENTITY = f"semantic-kernel/{SEMANTIC_KERNEL_VERSION}" if SEMANTIC_KERNEL_VERSION else "semantic-kernel"
+
+
+@experimental_class
+class AstraClient:
+    """AstraClient."""
+
+    def __init__(
+        self,
+        astra_id: str,
+        astra_region: str,
+        astra_application_token: str,
+        keyspace_name: str,
+        embedding_dim: int,
+        similarity_function: str,
+        session: aiohttp.ClientSession | None = None,
+    ):
+        """Initializes a new instance of the AstraClient class."""
+        self.astra_id = astra_id
+        self.astra_application_token = astra_application_token
+        self.astra_region = astra_region
+        self.keyspace_name = keyspace_name
+        self.embedding_dim = embedding_dim
+        self.similarity_function = similarity_function
+
+        self.request_base_url = (
+            f"https://{self.astra_id}-{self.astra_region}.apps.astra.datastax.com/api/json/v1/{self.keyspace_name}"
+        )
+        self.request_header = {
+            "x-cassandra-token": self.astra_application_token,
+            "Content-Type": "application/json",
+            "User-Agent": ASTRA_CALLER_IDENTITY,
+        }
+        self._session = session
+
+    async def _run_query(self, request_url: str, query: dict):
+        async with (
+            AsyncSession(self._session) as session,
+            session.post(request_url, data=json.dumps(query), headers=self.request_header) as response,
+        ):
+            if response.status == 200:
+                response_dict = await response.json()
+                if "errors" in response_dict:
+                    raise ServiceResponseException(f"Astra DB request error - {response_dict['errors']}")
+                return response_dict
+            raise ServiceResponseException(f"Astra DB not available. Status : {response}")
+
+    async def find_collections(self, include_detail: bool = True):
+        """Finds all collections in the keyspace."""
+        query = {"findCollections": {"options": {"explain": include_detail}}}
+        result = await self._run_query(self.request_base_url, query)
+        return result["status"]["collections"]
+
+    async def find_collection(self, collection_name: str):
+        """Finds a collection in the keyspace."""
+        collections = await self.find_collections(False)
+        found = False
+        for collection in collections:
+            if collection == collection_name:
+                found = True
+                break
+        return found
+
+    async def create_collection(
+        self,
+        collection_name: str,
+        embedding_dim: int | None = None,
+        similarity_function: str | None = None,
+    ):
+        """Creates a new collection in the keyspace."""
+        query = {
+            "createCollection": {
+                "name": collection_name,
+                "options": {
+                    "vector": {
+                        "dimension": embedding_dim if embedding_dim is not None else self.embedding_dim,
+                        "metric": similarity_function if similarity_function is not None else self.similarity_function,
+                    }
+                },
+            }
+        }
+        result = await self._run_query(self.request_base_url, query)
+        return result["status"]["ok"] == 1
+
+    async def delete_collection(self, collection_name: str):
+        """Deletes a collection from the keyspace."""
+        query = {"deleteCollection": {"name": collection_name}}
+        result = await self._run_query(self.request_base_url, query)
+        return result["status"]["ok"] == 1
+
+    def _build_request_collection_url(self, collection_name: str):
+        return f"{self.request_base_url}/{collection_name}"
+
+    async def find_documents(
+        self,
+        collection_name: str,
+        filter: dict | None = None,
+        vector: list[float] | None = None,
+        limit: int | None = None,
+        include_vector: bool | None = None,
+        include_similarity: bool | None = None,
+    ) -> list[dict]:
+        """Finds all documents in the collection."""
+        find_query = {}
+
+        if filter is not None:
+            find_query["filter"] = filter
+
+        if vector is not None:
+            find_query["sort"] = {"$vector": vector}
+
+        if include_vector is not None and include_vector is False:
+            find_query["projection"] = {"$vector": 0}
+        else:
+            find_query["projection"] = {"*": 1}
+
+        if limit is not None:
+            find_query["options"] = {"limit": limit}
+
+        if include_similarity is not None:
+            if "options" in find_query:
+                find_query["options"]["includeSimilarity"] = int(include_similarity)
+            else:
+                find_query["options"] = {"includeSimilarity": int(include_similarity)}
+
+        query = {"find": find_query}
+        result = await self._run_query(self._build_request_collection_url(collection_name), query)
+        return result["data"]["documents"]
+
+    async def insert_document(self, collection_name: str, document: dict) -> str:
+        """Inserts a document into the collection."""
+        query = {"insertOne": {"document": document}}
+        result = await self._run_query(self._build_request_collection_url(collection_name), query)
+        return result["status"]["insertedIds"][0]
+
+    async def insert_documents(self, collection_name: str, documents: list[dict]) -> list[str]:
+        """Inserts multiple documents into the collection."""
+        query = {"insertMany": {"documents": documents}}
+        result = await self._run_query(self._build_request_collection_url(collection_name), query)
+        return result["status"]["insertedIds"]
+
+    async def update_document(self, collection_name: str, filter: dict, update: dict, upsert: bool = True) -> dict:
+        """Updates a document in the collection."""
+        query = {
+            "findOneAndUpdate": {
+                "filter": filter,
+                "update": update,
+                "options": {"returnDocument": "after", "upsert": upsert},
+            }
+        }
+        result = await self._run_query(self._build_request_collection_url(collection_name), query)
+        return result["status"]
+
+    async def update_documents(self, collection_name: str, filter: dict, update: dict):
+        """Updates multiple documents in the collection."""
+        query = {
+            "updateMany": {
+                "filter": filter,
+                "update": update,
+            }
+        }
+        result = await self._run_query(self._build_request_collection_url(collection_name), query)
+        return result["status"]
+
+    async def delete_documents(self, collection_name: str, filter: dict) -> int:
+        """Deletes documents from the collection."""
+        query = {"deleteMany": {"filter": filter}}
+        result = await self._run_query(self._build_request_collection_url(collection_name), query)
+        return result["status"]["deletedCount"]