graduate filters, add exception during addition and some cleanup

python/pyproject.toml

@@ -146,6 +146,7 @@ environments = [
 ]
 
 [tool.pytest.ini_options]
+testpaths = 'tests'
 addopts = "-ra -q -r fEX"
 asyncio_default_fixture_loop_scope = "function"
 filterwarnings = [

python/samples/concepts/filtering/auto_function_invoke_filters.py

@@ -4,19 +4,12 @@
 import os
 
 from semantic_kernel import Kernel
-from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
+from semantic_kernel.connectors.ai import FunctionChoiceBehavior
 from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion, OpenAIChatPromptExecutionSettings
-from semantic_kernel.contents 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 import ChatHistory, ChatMessageContent, FunctionCallContent, FunctionResultContent
 from semantic_kernel.core_plugins import MathPlugin, TimePlugin
-from semantic_kernel.filters.auto_function_invocation.auto_function_invocation_context import (
-    AutoFunctionInvocationContext,
-)
-from semantic_kernel.filters.filter_types import FilterTypes
-from semantic_kernel.functions import KernelArguments
-from semantic_kernel.functions.function_result import FunctionResult
+from semantic_kernel.filters import AutoFunctionInvocationContext, FilterTypes
+from semantic_kernel.functions import FunctionResult, KernelArguments
 
 system_message = """
 You are a chat bot. Your name is Mosscap and

python/samples/concepts/filtering/function_invocation_filters.py

@@ -6,12 +6,11 @@
 from collections.abc import Callable, Coroutine
 from typing import Any
 
-from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion
-from semantic_kernel.contents.chat_history import ChatHistory
-from semantic_kernel.exceptions.kernel_exceptions import OperationCancelledException
-from semantic_kernel.filters.filter_types import FilterTypes
-from semantic_kernel.filters.functions.function_invocation_context import FunctionInvocationContext
-from semantic_kernel.kernel import Kernel
+from semantic_kernel import Kernel
+from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
+from semantic_kernel.contents import ChatHistory
+from semantic_kernel.exceptions import OperationCancelledException
+from semantic_kernel.filters import FilterTypes, FunctionInvocationContext
 
 logger = logging.getLogger(__name__)
 

python/samples/concepts/filtering/function_invocation_filters_stream.py

@@ -3,15 +3,15 @@
 import asyncio
 import logging
 import os
+from collections.abc import Callable, Coroutine
 from functools import reduce
+from typing import Any
 
-from semantic_kernel.connectors.ai.open_ai.services.open_ai_chat_completion import OpenAIChatCompletion
-from semantic_kernel.contents import AuthorRole
-from semantic_kernel.contents.chat_history import ChatHistory
-from semantic_kernel.contents.streaming_chat_message_content import StreamingChatMessageContent
-from semantic_kernel.filters.filter_types import FilterTypes
-from semantic_kernel.functions.function_result import FunctionResult
-from semantic_kernel.kernel import Kernel
+from semantic_kernel import Kernel
+from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
+from semantic_kernel.contents import AuthorRole, ChatHistory, StreamingChatMessageContent
+from semantic_kernel.filters import FilterTypes, FunctionInvocationContext
+from semantic_kernel.functions import FunctionResult
 
 logger = logging.getLogger(__name__)
 
@@ -32,15 +32,20 @@
 # in the specific case of a filter for streaming functions, you need to override the generator
 # that is present in the function_result.value as seen below.
 @kernel.filter(FilterTypes.FUNCTION_INVOCATION)
-async def streaming_exception_handling(context, next):
+async def streaming_exception_handling(
+    context: FunctionInvocationContext,
+    next: Callable[[FunctionInvocationContext], Coroutine[Any, Any, None]],
+):
     await next(context)
 
     async def override_stream(stream):
         try:
             async for partial in stream:
                 yield partial
         except Exception as e:
-            yield [StreamingChatMessageContent(role=AuthorRole.ASSISTANT, content=f"Exception caught: {e}")]
+            yield [
+                StreamingChatMessageContent(role=AuthorRole.ASSISTANT, content=f"Exception caught: {e}", choice_index=0)
+            ]
 
     stream = context.result.value
     context.result = FunctionResult(function=context.result.function, value=override_stream(stream))

python/semantic_kernel/connectors/ai/__init__.py

@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft. All rights reserved.
 
+from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
 from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
 
-__all__ = ["PromptExecutionSettings"]
+__all__ = ["FunctionChoiceBehavior", "PromptExecutionSettings"]

python/semantic_kernel/contents/chat_message_content.py

@@ -84,7 +84,7 @@ class ChatMessageContent(KernelContent):
     tag: ClassVar[str] = CHAT_MESSAGE_CONTENT_TAG
     role: AuthorRole
     name: str | None = None
-    items: list[Annotated[ITEM_TYPES, Field(..., discriminator=DISCRIMINATOR_FIELD)]] = Field(default_factory=list)
+    items: list[Annotated[ITEM_TYPES, Field(discriminator=DISCRIMINATOR_FIELD)]] = Field(default_factory=list)
     encoding: str | None = None
     finish_reason: FinishReason | None = None
 

python/semantic_kernel/exceptions/__init__.py

@@ -2,6 +2,7 @@
 
 from semantic_kernel.exceptions.agent_exceptions import *  # noqa: F403
 from semantic_kernel.exceptions.content_exceptions import *  # noqa: F403
+from semantic_kernel.exceptions.filter_exceptions import *  # noqa: F403
 from semantic_kernel.exceptions.function_exceptions import *  # noqa: F403
 from semantic_kernel.exceptions.kernel_exceptions import *  # noqa: F403
 from semantic_kernel.exceptions.memory_connector_exceptions import *  # noqa: F403

python/semantic_kernel/exceptions/filter_exceptions.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft. All rights reserved.
+from semantic_kernel.exceptions.kernel_exceptions import KernelException
+
+
+class FilterException(KernelException):
+    """Base class for all filter exceptions."""
+
+    pass
+
+
+class FilterManagementException(FilterException):
+    """An error occurred while adding or removing the filter to/from the kernel."""
+
+    pass
+
+
+__all__ = [
+    "FilterException",
+    "FilterManagementException",
+]

python/semantic_kernel/filters/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.filters.auto_function_invocation.auto_function_invocation_context import (
+    AutoFunctionInvocationContext,
+)
+from semantic_kernel.filters.filter_types import FilterTypes
+from semantic_kernel.filters.functions.function_invocation_context import FunctionInvocationContext
+from semantic_kernel.filters.prompts.prompt_render_context import PromptRenderContext
+
+__all__ = [
+    "AutoFunctionInvocationContext",
+    "FilterTypes",
+    "FunctionInvocationContext",
+    "PromptRenderContext",
+]

python/semantic_kernel/filters/auto_function_invocation/auto_function_invocation_context.py

@@ -10,7 +10,27 @@
 
 
 class AutoFunctionInvocationContext(FilterContextBase):
-    """Class for auto function invocation context."""
+    """Class for auto function invocation context.
+
+    This is the context supplied to the auto function invocation filters.
+
+    Common use case are to alter the function_result, for instance filling it with a pre-computed
+    value, in order to skip a step, for instance when doing caching.
+
+    Another option is to terminate, this can be done by setting terminate to True.
+
+    Attributes:
+        function: The function invoked.
+        kernel: The kernel used.
+        arguments: The arguments used to call the function.
+        chat_history: The chat history or None.
+        function_result: The function result or None.
+        request_sequence_index: The request sequence index.
+        function_sequence_index: The function sequence index.
+        function_count: The function count.
+        terminate: The flag to terminate.
+
+    """
 
     chat_history: "ChatHistory | None" = None
     function_result: "FunctionResult | None" = None

python/semantic_kernel/filters/filter_context_base.py

@@ -3,15 +3,13 @@
 from typing import TYPE_CHECKING
 
 from semantic_kernel.kernel_pydantic import KernelBaseModel
-from semantic_kernel.utils.experimental_decorator import experimental_class
 
 if TYPE_CHECKING:
     from semantic_kernel.functions.kernel_arguments import KernelArguments
     from semantic_kernel.functions.kernel_function import KernelFunction
     from semantic_kernel.kernel import Kernel
 
 
-@experimental_class
 class FilterContextBase(KernelBaseModel):
     """Base class for Kernel Filter Contexts."""
 

python/semantic_kernel/filters/filter_types.py

@@ -2,10 +2,7 @@
 
 from enum import Enum
 
-from semantic_kernel.utils.experimental_decorator import experimental_class
 
-
-@experimental_class
 class FilterTypes(str, Enum):
     """Enum for the filter types."""
 

python/semantic_kernel/filters/functions/function_invocation_context.py

@@ -9,6 +9,18 @@
 
 
 class FunctionInvocationContext(FilterContextBase):
-    """Class for function invocation context."""
+    """Class for function invocation context.
+
+    This filter can be used to monitor which functions are called.
+    To log what function was called with which parameters and what output.
+    Finally it can be used for caching by setting the result value.
+
+    Attributes:
+        function: The function invoked.
+        kernel: The kernel used.
+        arguments: The arguments used to call the function.
+        result: The result of the function, or None.
+
+    """
 
     result: "FunctionResult | None" = None

python/semantic_kernel/filters/kernel_filters_extension.py

@@ -7,10 +7,10 @@
 
 from pydantic import Field
 
+from semantic_kernel.exceptions.filter_exceptions import FilterManagementException
 from semantic_kernel.filters.filter_context_base import FilterContextBase
 from semantic_kernel.filters.filter_types import FilterTypes
 from semantic_kernel.kernel_pydantic import KernelBaseModel
-from semantic_kernel.utils.experimental_decorator import experimental_function
 
 FILTER_CONTEXT_TYPE = TypeVar("FILTER_CONTEXT_TYPE", bound=FilterContextBase)
 CALLABLE_FILTER_TYPE = Callable[[FILTER_CONTEXT_TYPE, Callable[[FILTER_CONTEXT_TYPE], None]], None]
@@ -32,7 +32,6 @@ class KernelFilterExtension(KernelBaseModel, ABC):
     prompt_rendering_filters: list[tuple[int, CALLABLE_FILTER_TYPE]] = Field(default_factory=list)
     auto_function_invocation_filters: list[tuple[int, CALLABLE_FILTER_TYPE]] = Field(default_factory=list)
 
-    @experimental_function
     def add_filter(self, filter_type: ALLOWED_FILTERS_LITERAL | FilterTypes, filter: CALLABLE_FILTER_TYPE) -> None:
         """Add a filter to the Kernel.
 
@@ -45,12 +44,17 @@ def add_filter(self, filter_type: ALLOWED_FILTERS_LITERAL | FilterTypes, filter:
             filter_type (str): The type of the filter to add (function_invocation, prompt_rendering)
             filter (object): The filter to add
 
+        Raises:
+            FilterDefinitionException: If an error occurs while adding the filter to the kernel
+
         """
-        if not isinstance(filter_type, FilterTypes):
-            filter_type = FilterTypes(filter_type)
-        getattr(self, FILTER_MAPPING[filter_type.value]).insert(0, (id(filter), filter))
+        try:
+            if not isinstance(filter_type, FilterTypes):
+                filter_type = FilterTypes(filter_type)
+            getattr(self, FILTER_MAPPING[filter_type.value]).insert(0, (id(filter), filter))
+        except Exception as ecx:
+            raise FilterManagementException(f"Error adding filter {filter} to {filter_type}") from ecx
 
-    @experimental_function
     def filter(
         self, filter_type: ALLOWED_FILTERS_LITERAL | FilterTypes
     ) -> Callable[[CALLABLE_FILTER_TYPE], CALLABLE_FILTER_TYPE]:
@@ -64,7 +68,6 @@ def decorator(
 
         return decorator
 
-    @experimental_function
     def remove_filter(
         self,
         filter_type: ALLOWED_FILTERS_LITERAL | FilterTypes | None = None,
@@ -83,10 +86,10 @@ def remove_filter(
         if filter_type and not isinstance(filter_type, FilterTypes):
             filter_type = FilterTypes(filter_type)
         if filter_id is None and position is None:
-            raise ValueError("Either hook_id or position should be provided.")
+            raise FilterManagementException("Either hook_id or position should be provided.")
         if position is not None:
             if filter_type is None:
-                raise ValueError("Please specify the type of filter when using position.")
+                raise FilterManagementException("Please specify the type of filter when using position.")
             getattr(self, FILTER_MAPPING[filter_type]).pop(position)
             return
         if filter_type:

python/semantic_kernel/filters/prompts/prompt_render_context.py

@@ -9,7 +9,19 @@
 
 
 class PromptRenderContext(FilterContextBase):
-    """Context for prompt rendering filters."""
+    """Context for prompt rendering filters.
+
+    When prompt rendering is expensive (for instance when there are expensive functions being called.)
+    This filter can be used to set the rendered_prompt directly and returning.
+
+    Attributes:
+        function: The function invoked.
+        kernel: The kernel used.
+        arguments: The arguments used to call the function.
+        rendered_prompt: The result of the prompt rendering.
+        function_result: The result of the function that used the prompt.
+
+    """
 
     rendered_prompt: str | None = None
     function_result: "FunctionResult | None" = None

python/tests/integration/audio_to_text/audio_to_text_test_base.py

@@ -11,7 +11,7 @@
 # There is only the whisper model available on Azure OpenAI for audio to text. And that model is
 # only available in the North Switzerland region. Therefore, the endpoint is different than the one
 # we use for other services.
-is_service_setup_for_testing(["AZURE_OPENAI_AUDIO_TO_TEXT_ENDPOINT"])
+azure_setup = is_service_setup_for_testing(["AZURE_OPENAI_AUDIO_TO_TEXT_ENDPOINT"], raise_if_not_set=False)
 
 
 class AudioToTextTestBase:
@@ -22,5 +22,7 @@ def services(self) -> dict[str, AudioToTextClientBase]:
         """Return audio-to-text services."""
         return {
             "openai": OpenAIAudioToText(),
-            "azure_openai": AzureAudioToText(endpoint=os.environ["AZURE_OPENAI_AUDIO_TO_TEXT_ENDPOINT"]),
+            "azure_openai": AzureAudioToText(endpoint=os.environ["AZURE_OPENAI_AUDIO_TO_TEXT_ENDPOINT"])
+            if azure_setup
+            else None,
         }

python/tests/integration/audio_to_text/test_audio_to_text.py

@@ -49,6 +49,8 @@ async def test_audio_to_text(
         """
 
         service = services[service_id]
+        if not service:
+            pytest.mark.xfail("Azure Audio to Text not setup.")
         result = await service.get_text_content(audio_content)
 
         for word in expected_text:

python/tests/integration/completions/chat_completion_test_base.py

@@ -56,17 +56,21 @@
 # There is no single model in Ollama that supports both image and tool call in chat completion
 # We are splitting the Ollama test into three services: chat, image, and tool call. The chat model
 # can be any model that supports chat completion. Also, Ollama is only available on Linux runners in our pipeline.
-ollama_setup: bool = is_service_setup_for_testing(["OLLAMA_CHAT_MODEL_ID"]) and is_test_running_on_supported_platforms([
-    "Linux"
-])
-ollama_image_setup: bool = is_service_setup_for_testing([
-    "OLLAMA_CHAT_MODEL_ID_IMAGE"
-]) and is_test_running_on_supported_platforms(["Linux"])
-ollama_tool_call_setup: bool = is_service_setup_for_testing([
-    "OLLAMA_CHAT_MODEL_ID_TOOL_CALL"
-]) and is_test_running_on_supported_platforms(["Linux"])
-google_ai_setup: bool = is_service_setup_for_testing(["GOOGLE_AI_API_KEY", "GOOGLE_AI_GEMINI_MODEL_ID"])
-vertex_ai_setup: bool = is_service_setup_for_testing(["VERTEX_AI_PROJECT_ID", "VERTEX_AI_GEMINI_MODEL_ID"])
+ollama_setup: bool = is_service_setup_for_testing(
+    ["OLLAMA_CHAT_MODEL_ID"], raise_if_not_set=False
+) and is_test_running_on_supported_platforms(["Linux"])
+ollama_image_setup: bool = is_service_setup_for_testing(
+    ["OLLAMA_CHAT_MODEL_ID_IMAGE"], raise_if_not_set=False
+) and is_test_running_on_supported_platforms(["Linux"])
+ollama_tool_call_setup: bool = is_service_setup_for_testing(
+    ["OLLAMA_CHAT_MODEL_ID_TOOL_CALL"], raise_if_not_set=False
+) and is_test_running_on_supported_platforms(["Linux"])
+google_ai_setup: bool = is_service_setup_for_testing(
+    ["GOOGLE_AI_API_KEY", "GOOGLE_AI_GEMINI_MODEL_ID"], raise_if_not_set=False
+)
+vertex_ai_setup: bool = is_service_setup_for_testing(
+    ["VERTEX_AI_PROJECT_ID", "VERTEX_AI_GEMINI_MODEL_ID"], raise_if_not_set=False
+)
 onnx_setup: bool = is_service_setup_for_testing(
     ["ONNX_GEN_AI_CHAT_MODEL_FOLDER"], raise_if_not_set=False
 )  # Tests are optional for ONNX