chore: import upstream snapshot with attribution

python/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"]

python/semantic_kernel/services/ai_service_client_base.py

@@ -0,0 +1,64 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC
+from typing import TYPE_CHECKING, Annotated, Any
+
+from pydantic.types import 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 = ""
+
+    def model_post_init(self, __context: Any):
+        """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)
+
+    def service_url(self) -> str | None:
+        """Get the URL of the service.
+
+        Override this in the subclass to return the proper URL.
+        If the service does not have a URL, return None.
+        """
+        return None

python/semantic_kernel/services/ai_service_selector.py

@@ -0,0 +1,69 @@
+# 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 | None" = None,
+        arguments: "KernelArguments | None" = None,
+        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.
+
+        Args:
+            kernel: The kernel used.
+            function: The function used. (optional)
+            arguments: The arguments used. (optional)
+            type_: The type of service to select. (optional)
+        """
+        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
+            from semantic_kernel.connectors.ai.text_to_audio_client_base import TextToAudioClientBase
+            from semantic_kernel.connectors.ai.text_to_image_client_base import TextToImageClientBase
+
+            type_ = (TextCompletionClientBase, ChatCompletionClientBase, TextToAudioClientBase, TextToImageClientBase)  # type: ignore
+
+        execution_settings_dict = arguments.execution_settings if arguments and arguments.execution_settings else {}
+        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.")

python/semantic_kernel/services/kernel_services_extension.py

@@ -0,0 +1,149 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from abc import ABC
+from collections.abc import Mapping, MutableMapping
+from typing import TYPE_CHECKING, TypeVar
+
+from pydantic import Field, field_validator
+
+from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+from semantic_kernel.const import DEFAULT_SERVICE_NAME
+from semantic_kernel.exceptions import KernelFunctionAlreadyExistsError, KernelServiceNotFoundError
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.services.ai_service_client_base import AIServiceClientBase
+from semantic_kernel.services.ai_service_selector import AIServiceSelector
+
+if TYPE_CHECKING:
+    from semantic_kernel.functions.kernel_arguments import KernelArguments
+    from semantic_kernel.functions.kernel_function import KernelFunction
+
+AI_SERVICE_CLIENT_TYPE = TypeVar("AI_SERVICE_CLIENT_TYPE", bound=AIServiceClientBase)
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class KernelServicesExtension(KernelBaseModel, ABC):
+    """Kernel services extension.
+
+    Adds all services related entities to the Kernel.
+    """
+
+    services: MutableMapping[str, AIServiceClientBase] = Field(default_factory=dict)
+    ai_service_selector: AIServiceSelector = Field(default_factory=AIServiceSelector)
+
+    @field_validator("services", mode="before")
+    @classmethod
+    def rewrite_services(
+        cls,
+        services: (
+            AI_SERVICE_CLIENT_TYPE | list[AI_SERVICE_CLIENT_TYPE] | dict[str, AI_SERVICE_CLIENT_TYPE] | None
+        ) = None,
+    ) -> dict[str, AI_SERVICE_CLIENT_TYPE]:
+        """Rewrite services to a dictionary."""
+        if not services:
+            return {}
+        if isinstance(services, AIServiceClientBase):
+            return {services.service_id if services.service_id else DEFAULT_SERVICE_NAME: services}  # type: ignore
+        if isinstance(services, list):
+            return {s.service_id if s.service_id else DEFAULT_SERVICE_NAME: s for s in services}
+        return services
+
+    def select_ai_service(
+        self,
+        function: "KernelFunction | None" = None,
+        arguments: "KernelArguments | None" = None,
+        type: type[AI_SERVICE_CLIENT_TYPE] | tuple[type[AI_SERVICE_CLIENT_TYPE], ...] | None = None,
+    ) -> tuple[AIServiceClientBase, PromptExecutionSettings]:
+        """Uses the AI service selector to select a service for the function.
+
+        Args:
+            function (KernelFunction | None): The function used.
+            arguments (KernelArguments | None): The arguments used.
+            type (Type[AI_SERVICE_CLIENT_TYPE] | tuple[type[AI_SERVICE_CLIENT_TYPE], ...] | None): The type of
+                service to select. Defaults to None.
+        """
+        return self.ai_service_selector.select_ai_service(self, function=function, arguments=arguments, type_=type)
+
+    def get_service(
+        self,
+        service_id: str | None = None,
+        type: type[AI_SERVICE_CLIENT_TYPE] | tuple[type[AI_SERVICE_CLIENT_TYPE], ...] | None = None,
+    ) -> AI_SERVICE_CLIENT_TYPE:
+        """Get a service by service_id and type.
+
+        Type is optional and when not supplied, no checks are done.
+        Type should be
+            TextCompletionClientBase, ChatCompletionClientBase, EmbeddingGeneratorBase
+            or a subclass of one.
+            You can also check for multiple types in one go,
+            by using a tuple: (TextCompletionClientBase, ChatCompletionClientBase).
+
+        If type and service_id are both None, the first service is returned.
+
+        Args:
+            service_id (str | None): The service id,
+                if None, the default service is returned or the first service is returned.
+            type (Type[AI_SERVICE_CLIENT_TYPE] | tuple[type[AI_SERVICE_CLIENT_TYPE], ...] | None):
+                The type of the service, if None, no checks are done on service type.
+
+        Returns:
+            AIServiceClientBase: The service, should be a class derived from AIServiceClientBase.
+
+        Raises:
+            KernelServiceNotFoundError: If no service is found that matches the type or id.
+
+        """
+        services = self.get_services_by_type(type)
+        if not services:
+            raise KernelServiceNotFoundError(f"No services found of type {type}.")
+        if not service_id:
+            service_id = DEFAULT_SERVICE_NAME
+
+        if service_id not in services:
+            if service_id == DEFAULT_SERVICE_NAME:
+                return next(iter(services.values()))
+            raise KernelServiceNotFoundError(
+                f"Service with service_id '{service_id}' does not exist or has a different type."
+            )
+        return services[service_id]
+
+    def get_services_by_type(
+        self, type: type[AI_SERVICE_CLIENT_TYPE] | tuple[type[AI_SERVICE_CLIENT_TYPE], ...] | None
+    ) -> Mapping[str, AI_SERVICE_CLIENT_TYPE]:
+        """Get all services of a specific type."""
+        if type is None:
+            return self.services  # type: ignore
+        return {service.service_id: service for service in self.services.values() if isinstance(service, type)}  # type: ignore
+
+    def get_prompt_execution_settings_from_service_id(
+        self, service_id: str, type: type[AI_SERVICE_CLIENT_TYPE] | None = None
+    ) -> PromptExecutionSettings:
+        """Get the specific request settings from the service, instantiated with the service_id and ai_model_id."""
+        service = self.get_service(service_id, type=type)
+        return service.instantiate_prompt_execution_settings(
+            service_id=service_id,
+            extension_data={"ai_model_id": service.ai_model_id},
+        )
+
+    def add_service(self, service: AIServiceClientBase, overwrite: bool = False) -> None:
+        """Add a single service to the Kernel.
+
+        Args:
+            service (AIServiceClientBase): The service to add.
+            overwrite (bool, optional): Whether to overwrite the service if it already exists. Defaults to False.
+        """
+        if service.service_id not in self.services or overwrite:
+            self.services[service.service_id] = service
+            return
+        raise KernelFunctionAlreadyExistsError(f"Service with service_id '{service.service_id}' already exists")
+
+    def remove_service(self, service_id: str) -> None:
+        """Delete a single service from the Kernel."""
+        if service_id not in self.services:
+            raise KernelServiceNotFoundError(f"Service with service_id '{service_id}' does not exist")
+        del self.services[service_id]
+
+    def remove_all_services(self) -> None:
+        """Removes the services from the Kernel, does not delete them."""
+        self.services.clear()