semantic-kernel 1.8.3__zip

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

@@ -0,0 +1,260 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from collections.abc import Callable
+from enum import Enum
+from typing import TYPE_CHECKING, Literal, TypeVar
+
+from typing_extensions import deprecated
+
+from semantic_kernel.connectors.ai.function_calling_utils import _combine_filter_dicts
+from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.ai.function_call_behavior import FunctionCallBehavior
+    from semantic_kernel.connectors.ai.function_call_choice_configuration import FunctionCallChoiceConfiguration
+    from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+    from semantic_kernel.kernel import Kernel
+
+
+DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS = 5
+
+logger = logging.getLogger(__name__)
+
+
+_T = TypeVar("_T", bound="FunctionChoiceBehavior")
+
+
+@experimental_class
+class FunctionChoiceType(Enum):
+    """The type of function choice behavior."""
+
+    AUTO = "auto"
+    NONE = "none"
+    REQUIRED = "required"
+
+
+@experimental_class
+class FunctionChoiceBehavior(KernelBaseModel):
+    """Class that controls function choice behavior.
+
+    Attributes:
+        enable_kernel_functions: Enable kernel functions.
+        max_auto_invoke_attempts: The maximum number of auto invoke attempts.
+        filters: Filters for the function choice behavior. Available options are: excluded_plugins,
+            included_plugins, excluded_functions, or included_functions.
+        type_: The type of function choice behavior.
+
+    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:
+        Auto: Returns FunctionChoiceBehavior class with auto_invoke enabled, and the desired functions
+            based on either the specified filters or the full qualified names. The model will decide which function
+            to use, if any.
+        NoneInvoke: Returns FunctionChoiceBehavior class with auto_invoke disabled, and the desired functions
+            based on either the specified filters or the full qualified names. The model does not invoke any functions,
+            but can rather describe how it would invoke a function to complete a given task/query.
+        Required: Returns FunctionChoiceBehavior class with auto_invoke enabled, and the desired functions
+            based on either the specified filters or the full qualified names. The model is required to use one of the
+            provided functions to complete a given task/query.
+    """
+
+    enable_kernel_functions: bool = True
+    maximum_auto_invoke_attempts: int = DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS
+    filters: (
+        dict[Literal["excluded_plugins", "included_plugins", "excluded_functions", "included_functions"], list[str]]
+        | None
+    ) = None
+    type_: FunctionChoiceType | None = None
+
+    @classmethod
+    @deprecated("The `FunctionCallBehavior` class is deprecated; use `FunctionChoiceBehavior` instead.")
+    def from_function_call_behavior(cls: type[_T], behavior: "FunctionCallBehavior") -> _T:
+        """Create a FunctionChoiceBehavior from a FunctionCallBehavior."""
+        from semantic_kernel.connectors.ai.function_call_behavior import (
+            EnabledFunctions,
+            KernelFunctions,
+            RequiredFunction,
+        )
+
+        if isinstance(behavior, (EnabledFunctions, KernelFunctions)):
+            return cls.Auto(
+                auto_invoke=behavior.auto_invoke_kernel_functions,
+                filters=behavior.filters if hasattr(behavior, "filters") else None,
+            )
+        if isinstance(behavior, (RequiredFunction)):
+            return cls.Required(
+                auto_invoke=behavior.auto_invoke_kernel_functions,
+                filters={"included_functions": [behavior.function_fully_qualified_name]},
+            )
+        return cls(
+            enable_kernel_functions=behavior.enable_kernel_functions,
+            maximum_auto_invoke_attempts=behavior.max_auto_invoke_attempts,
+        )
+
+    @property
+    def auto_invoke_kernel_functions(self):
+        """Return True if auto_invoke_kernel_functions is enabled."""
+        return self.maximum_auto_invoke_attempts > 0
+
+    @auto_invoke_kernel_functions.setter
+    def auto_invoke_kernel_functions(self, value: bool):
+        """Set the auto_invoke_kernel_functions property."""
+        self.maximum_auto_invoke_attempts = DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS if value else 0
+
+    def _check_and_get_config(
+        self,
+        kernel: "Kernel",
+        filters: dict[
+            Literal["excluded_plugins", "included_plugins", "excluded_functions", "included_functions"], list[str]
+        ]
+        | None = {},
+    ) -> "FunctionCallChoiceConfiguration":
+        """Check for missing functions and get the function call choice configuration."""
+        from semantic_kernel.connectors.ai.function_call_choice_configuration import FunctionCallChoiceConfiguration
+
+        if filters:
+            return FunctionCallChoiceConfiguration(available_functions=kernel.get_list_of_function_metadata(filters))
+        return FunctionCallChoiceConfiguration(available_functions=kernel.get_full_list_of_function_metadata())
+
+    def configure(
+        self,
+        kernel: "Kernel",
+        update_settings_callback: Callable[..., None],
+        settings: "PromptExecutionSettings",
+    ) -> None:
+        """Configure the function choice behavior."""
+        if not self.enable_kernel_functions:
+            return
+
+        config = self.get_config(kernel)
+
+        if config:
+            update_settings_callback(config, settings, self.type_)
+
+    def get_config(self, kernel: "Kernel") -> "FunctionCallChoiceConfiguration":
+        """Get the function call choice configuration based on the type."""
+        return self._check_and_get_config(kernel, self.filters)
+
+    @classmethod
+    def Auto(
+        cls: type[_T],
+        auto_invoke: bool = True,
+        *,
+        filters: dict[
+            Literal["excluded_plugins", "included_plugins", "excluded_functions", "included_functions"], list[str]
+        ]
+        | None = None,
+        **kwargs,
+    ) -> _T:
+        """Creates a FunctionChoiceBehavior with type AUTO.
+
+        Returns FunctionChoiceBehavior class with auto_invoke enabled, and the desired functions
+        based on either the specified filters or the full qualified names. The model will decide which function
+        to use, if any.
+        """
+        kwargs.setdefault("maximum_auto_invoke_attempts", DEFAULT_MAX_AUTO_INVOKE_ATTEMPTS if auto_invoke else 0)
+        return cls(
+            type_=FunctionChoiceType.AUTO,
+            filters=filters,
+            **kwargs,
+        )
+
+    @classmethod
+    def NoneInvoke(
+        cls: type[_T],
+        *,
+        filters: dict[
+            Literal["excluded_plugins", "included_plugins", "excluded_functions", "included_functions"], list[str]
+        ]
+        | None = None,
+        **kwargs,
+    ) -> _T:
+        """Creates a FunctionChoiceBehavior with type NONE.
+
+        Returns FunctionChoiceBehavior class with auto_invoke disabled, and the desired functions
+        based on either the specified filters or the full qualified names. The model does not invoke any functions,
+        but can rather describe how it would invoke a function to complete a given task/query.
+        """
+        kwargs.setdefault("maximum_auto_invoke_attempts", 0)
+        return cls(
+            type_=FunctionChoiceType.NONE,
+            filters=filters,
+            **kwargs,
+        )
+
+    @classmethod
+    def Required(
+        cls: type[_T],
+        auto_invoke: bool = True,
+        *,
+        filters: dict[
+            Literal["excluded_plugins", "included_plugins", "excluded_functions", "included_functions"], list[str]
+        ]
+        | None = None,
+        **kwargs,
+    ) -> _T:
+        """Creates a FunctionChoiceBehavior with type REQUIRED.
+
+        Returns FunctionChoiceBehavior class with auto_invoke enabled, and the desired functions
+        based on either the specified filters or the full qualified names. The model is required to use one of the
+        provided functions to complete a given task/query.
+        """
+        kwargs.setdefault("maximum_auto_invoke_attempts", 1 if auto_invoke else 0)
+        return cls(
+            type_=FunctionChoiceType.REQUIRED,
+            filters=filters,
+            **kwargs,
+        )
+
+    @classmethod
+    def from_dict(cls: type[_T], data: dict) -> _T:
+        """Create a FunctionChoiceBehavior from a dictionary."""
+        type_map = {
+            "auto": cls.Auto,
+            "none": cls.NoneInvoke,
+            "required": cls.Required,
+        }
+        behavior_type = data.pop("type", "auto")
+        auto_invoke = data.pop("auto_invoke", False)
+        functions = data.pop("functions", None)
+        filters = data.pop("filters", None)
+
+        if functions:
+            valid_fqns = [name.replace(".", "-") for name in functions]
+            if filters:
+                filters = _combine_filter_dicts(filters, {"included_functions": valid_fqns})
+            else:
+                filters = {"included_functions": valid_fqns}
+
+        return type_map[behavior_type](  # type: ignore
+            auto_invoke=auto_invoke,
+            filters=filters,
+            **data,
+        )
+
+    @classmethod
+    def from_string(cls: type[_T], data: str) -> _T:
+        """Create a FunctionChoiceBehavior from a string.
+
+        This method converts the provided string to a FunctionChoiceBehavior object
+        for the specified type.
+        """
+        type_value = data.lower()
+        if type_value == "auto":
+            return cls.Auto()
+        if type_value == "none":
+            return cls.NoneInvoke()
+        if type_value == "required":
+            return cls.Required()
+        raise ServiceInitializationError(
+            f"The specified type `{type_value}` is not supported. Allowed types are: `auto`, `none`, `required`."
+        )

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/google/README.md

@@ -0,0 +1,54 @@
+# Google - Gemini
+
+Gemini models are Google's large language models. Semantic Kernel provides two connectors to access these models from Google Cloud.
+
+## Google AI
+
+You can access the Gemini API from Google AI Studio. This mode of access is for quick prototyping as it relies on API keys.
+
+Follow [these instructions](https://cloud.google.com/docs/authentication/api-keys) to create an API key.
+
+Once you have an API key, you can start using Gemini models in SK using the `google_ai` connector. Example:
+
+```Python
+kernel = Kernel()
+kernel.add_service(
+    GoogleAIChatCompletion(
+        gemini_model_id="gemini-1.5-flash",
+        api_key="...",
+    )
+)
+...
+```
+
+> Alternatively, you can use an .env file to store the model id and api key.
+
+## Vertex AI
+
+Google also offers access to Gemini through its Vertex AI platform. Vertex AI provides a more complete solution to build your enterprise AI applications end-to-end. You can read more about it [here](https://cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai).
+
+This mode of access requires a Google Cloud service account. Follow these [instructions](https://cloud.google.com/vertex-ai/generative-ai/docs/migrate/migrate-google-ai) to create a Google Cloud project if you don't have one already. Remember the `project id` as it is required to access the models.
+
+Follow the steps below to set up your environment to use the Vertex AI API:
+
+- [Install the gcloud CLI](https://cloud.google.com/sdk/docs/install)
+- [Initialize the gcloud CLI](https://cloud.google.com/sdk/docs/initializing)
+
+Once you have your project and your environment is set up, you can start using Gemini models in SK using the `vertex_ai` connector. Example:
+
+```Python
+kernel = Kernel()
+kernel.add_service(
+    VertexAIChatCompletion(
+        project_id="...",
+        gemini_model_id="gemini-1.5-flash",
+    )
+)
+...
+```
+
+> Alternatively, you can use an .env file to store the model id and project id.
+
+## Why is there code that looks almost identical in the implementations on the two connectors
+
+The two connectors have very similar implementations, including the utils files. However, they are fundamentally different as they depend on different packages from Google. Although the namings of many types are identical, they are different types.

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/google/google_ai/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.connectors.ai.google.google_ai.google_ai_prompt_execution_settings import (
+    GoogleAIChatPromptExecutionSettings,
+    GoogleAIEmbeddingPromptExecutionSettings,
+    GoogleAIPromptExecutionSettings,
+)
+from semantic_kernel.connectors.ai.google.google_ai.services.google_ai_chat_completion import GoogleAIChatCompletion
+from semantic_kernel.connectors.ai.google.google_ai.services.google_ai_text_completion import GoogleAITextCompletion
+from semantic_kernel.connectors.ai.google.google_ai.services.google_ai_text_embedding import GoogleAITextEmbedding
+
+__all__ = [
+    "GoogleAIChatCompletion",
+    "GoogleAIChatPromptExecutionSettings",
+    "GoogleAIEmbeddingPromptExecutionSettings",
+    "GoogleAIPromptExecutionSettings",
+    "GoogleAITextCompletion",
+    "GoogleAITextEmbedding",
+]

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/google/google_ai/google_ai_prompt_execution_settings.py

@@ -0,0 +1,65 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import sys
+from typing import Any, Literal
+
+from pydantic import Field
+
+if sys.version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
+
+
+class GoogleAIPromptExecutionSettings(PromptExecutionSettings):
+    """Google AI Prompt Execution Settings."""
+
+    stop_sequences: list[str] | None = Field(None, max_length=5)
+    response_mime_type: Literal["text/plain", "application/json"] | None = None
+    response_schema: Any | None = None
+    candidate_count: int | None = Field(None, ge=1)
+    max_output_tokens: int | None = Field(None, ge=1)
+    temperature: float | None = Field(None, ge=0.0, le=2.0)
+    top_p: float | None = None
+    top_k: int | None = None
+
+
+class GoogleAITextPromptExecutionSettings(GoogleAIPromptExecutionSettings):
+    """Google AI Text Prompt Execution Settings."""
+
+    pass
+
+
+class GoogleAIChatPromptExecutionSettings(GoogleAIPromptExecutionSettings):
+    """Google AI Chat Prompt Execution Settings."""
+
+    tools: list[dict[str, Any]] | None = Field(
+        None,
+        max_length=64,
+        description="Do not set this manually. It is set by the service based on the function choice configuration.",
+    )
+    tool_config: dict[str, Any] | None = Field(
+        None,
+        description="Do not set this manually. It is set by the service based on the function choice configuration.",
+    )
+
+    @override
+    def prepare_settings_dict(self, **kwargs) -> dict[str, Any]:
+        """Prepare the settings as a dictionary for sending to the AI service.
+
+        This method removes the tools and tool_choice keys from the settings dictionary, as
+        the Google AI service mandates these two settings to be sent as separate parameters.
+        """
+        settings_dict = super().prepare_settings_dict(**kwargs)
+        settings_dict.pop("tools", None)
+        settings_dict.pop("tool_config", None)
+
+        return settings_dict
+
+
+class GoogleAIEmbeddingPromptExecutionSettings(PromptExecutionSettings):
+    """Google AI Embedding Prompt Execution Settings."""
+
+    output_dimensionality: int | None = None

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/google/google_ai/google_ai_settings.py

@@ -0,0 +1,37 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import ClassVar
+
+from pydantic import SecretStr
+
+from semantic_kernel.kernel_pydantic import KernelBaseSettings
+
+
+class GoogleAISettings(KernelBaseSettings):
+    """Google AI settings.
+
+    The settings are first loaded from environment variables with
+    the prefix 'GOOGLE_AI_'.
+    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_AI_' are:
+    - gemini_model_id: str - The Gemini model ID for the Google AI service, i.e. gemini-1.5-pro
+                This value can be found in the Google AI service deployment.
+                (Env var GOOGLE_AI_GEMINI_MODEL_ID)
+    - embedding_model_id: str - The embedding model ID for the Google AI service, i.e. text-embedding-004
+                This value can be found in the Google AI service deployment.
+                (Env var GOOGLE_AI_EMBEDDING_MODEL_ID)
+    - api_key: SecretStr - The API key for the Google AI service deployment.
+                This value can be found in the Google AI service deployment.
+                (Env var GOOGLE_AI_API_KEY)
+    """
+
+    env_prefix: ClassVar[str] = "GOOGLE_AI_"
+
+    gemini_model_id: str | None = None
+    embedding_model_id: str | None = None
+    api_key: SecretStr

semantic_kernel-1.8.3/semantic_kernel/connectors/ai/google/google_ai/services/google_ai_base.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from abc import ABC
+from typing import ClassVar
+
+from semantic_kernel.connectors.ai.google.google_ai.google_ai_settings import GoogleAISettings
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class GoogleAIBase(KernelBaseModel, ABC):
+    """Google AI Service."""
+
+    MODEL_PROVIDER_NAME: ClassVar[str] = "googleai"
+
+    service_settings: GoogleAISettings