semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/memory/volatile_memory_store.py

@@ -0,0 +1,319 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from copy import deepcopy
+
+from numpy import array, linalg, ndarray
+
+from semantic_kernel.exceptions import ServiceResourceNotFoundError
+from semantic_kernel.memory.memory_record import MemoryRecord
+from semantic_kernel.memory.memory_store_base import MemoryStoreBase
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+@experimental_class
+class VolatileMemoryStore(MemoryStoreBase):
+    """A volatile memory store that stores data in memory."""
+
+    _store: dict[str, dict[str, MemoryRecord]]
+
+    def __init__(self) -> None:
+        """Initializes a new instance of the VolatileMemoryStore class."""
+        self._store = {}
+
+    async def create_collection(self, collection_name: str) -> None:
+        """Creates a new collection if it does not exist.
+
+        Args:
+            collection_name (str): The name of the collection to create.
+
+        Returns:
+            None
+        """
+        if collection_name in self._store:
+            pass
+        else:
+            self._store[collection_name] = {}
+
+    async def get_collections(
+        self,
+    ) -> list[str]:
+        """Gets the list of collections.
+
+        Returns:
+            List[str]: The list of collections.
+        """
+        return list(self._store.keys())
+
+    async def delete_collection(self, collection_name: str) -> None:
+        """Deletes a collection.
+
+        Args:
+            collection_name (str): The name of the collection to delete.
+
+        Returns:
+            None
+        """
+        if collection_name in self._store:
+            del self._store[collection_name]
+
+    async def does_collection_exist(self, collection_name: str) -> bool:
+        """Checks if a collection exists.
+
+        Args:
+            collection_name (str): The name of the collection to check.
+
+        Returns:
+            bool: True if the collection exists; otherwise, False.
+        """
+        return collection_name in self._store
+
+    async def upsert(self, collection_name: str, record: MemoryRecord) -> str:
+        """Upserts a record.
+
+        Args:
+            collection_name (str): The name of the collection to upsert the record into.
+            record (MemoryRecord): The record to upsert.
+
+        Returns:
+            str: The unique database key of the record.
+        """
+        if collection_name not in self._store:
+            raise ServiceResourceNotFoundError(f"Collection '{collection_name}' does not exist")
+
+        record._key = record._id
+        self._store[collection_name][record._key] = record
+        return record._key
+
+    async def upsert_batch(self, collection_name: str, records: list[MemoryRecord]) -> list[str]:
+        """Upserts a batch of records.
+
+        Args:
+            collection_name (str): The name of the collection to upsert the records into.
+            records (List[MemoryRecord]): The records to upsert.
+
+        Returns:
+            List[str]: The unique database keys of the records.
+        """
+        if collection_name not in self._store:
+            raise ServiceResourceNotFoundError(f"Collection '{collection_name}' does not exist")
+
+        for record in records:
+            record._key = record._id
+            self._store[collection_name][record._key] = record
+        return [record._key for record in records]
+
+    async def get(self, collection_name: str, key: str, with_embedding: bool = False) -> MemoryRecord:
+        """Gets a record.
+
+        Args:
+            collection_name (str): The name of the collection to get the record from.
+            key (str): The unique database key of the record.
+            with_embedding (bool): Whether to include the embedding in the result. (default: {False})
+
+        Returns:
+            MemoryRecord: The record.
+        """
+        if collection_name not in self._store:
+            raise ServiceResourceNotFoundError(f"Collection '{collection_name}' does not exist")
+
+        if key not in self._store[collection_name]:
+            raise ServiceResourceNotFoundError(f"Key '{key}' not found in collection '{collection_name}'")
+
+        result = self._store[collection_name][key]
+
+        if not with_embedding:
+            # create copy of results without embeddings
+            result = deepcopy(result)
+            result._embedding = None
+        return result
+
+    async def get_batch(
+        self, collection_name: str, keys: list[str], with_embeddings: bool = False
+    ) -> list[MemoryRecord]:
+        """Gets a batch of records.
+
+        Args:
+            collection_name (str): The name of the collection to get the records from.
+            keys (List[str]): The unique database keys of the records.
+            with_embeddings (bool): Whether to include the embeddings in the results. (default: {False})
+
+        Returns:
+            List[MemoryRecord]: The records.
+        """
+        if collection_name not in self._store:
+            raise ServiceResourceNotFoundError(f"Collection '{collection_name}' does not exist")
+
+        results = [self._store[collection_name][key] for key in keys if key in self._store[collection_name]]
+
+        if not with_embeddings:
+            # create copy of results without embeddings
+            for result in results:
+                result = deepcopy(result)
+                result._embedding = None
+        return results
+
+    async def remove(self, collection_name: str, key: str) -> None:
+        """Removes a record.
+
+        Args:
+            collection_name (str): The name of the collection to remove the record from.
+            key (str): The unique database key of the record to remove.
+
+        Returns:
+            None
+        """
+        if collection_name not in self._store:
+            raise ServiceResourceNotFoundError(f"Collection '{collection_name}' does not exist")
+
+        if key not in self._store[collection_name]:
+            raise ServiceResourceNotFoundError(f"Key '{key}' not found in collection '{collection_name}'")
+
+        del self._store[collection_name][key]
+
+    async def remove_batch(self, collection_name: str, keys: list[str]) -> None:
+        """Removes a batch of records.
+
+        Args:
+            collection_name (str): The name of the collection to remove the records from.
+            keys (List[str]): The unique database keys of the records to remove.
+
+        Returns:
+            None
+        """
+        if collection_name not in self._store:
+            raise ServiceResourceNotFoundError(f"Collection '{collection_name}' does not exist")
+
+        for key in keys:
+            if key in self._store[collection_name]:
+                del self._store[collection_name][key]
+
+    async def get_nearest_match(
+        self,
+        collection_name: str,
+        embedding: ndarray,
+        min_relevance_score: float = 0.0,
+        with_embedding: bool = False,
+    ) -> tuple[MemoryRecord, float]:
+        """Gets the nearest match to an embedding using cosine similarity.
+
+        Args:
+            collection_name (str): The name of the collection to get the nearest match from.
+            embedding (ndarray): The embedding to find the nearest match to.
+            min_relevance_score (float): The minimum relevance score of the match. (default: {0.0})
+            with_embedding (bool): Whether to include the embedding in the result. (default: {False})
+
+        Returns:
+            Tuple[MemoryRecord, float]: The record and the relevance score.
+        """
+        return self.get_nearest_matches(
+            collection_name=collection_name,
+            embedding=embedding,
+            limit=1,
+            min_relevance_score=min_relevance_score,
+            with_embeddings=with_embedding,
+        )
+
+    async def get_nearest_matches(
+        self,
+        collection_name: str,
+        embedding: ndarray,
+        limit: int,
+        min_relevance_score: float = 0.0,
+        with_embeddings: bool = False,
+    ) -> list[tuple[MemoryRecord, float]]:
+        """Gets the nearest matches to an embedding using cosine similarity.
+
+        Args:
+            collection_name (str): The name of the collection to get the nearest matches from.
+            embedding (ndarray): The embedding to find the nearest matches to.
+            limit (int): The maximum number of matches to return.
+            min_relevance_score (float): The minimum relevance score of the matches. (default: {0.0})
+            with_embeddings (bool): Whether to include the embeddings in the results. (default: {False})
+
+        Returns:
+            List[Tuple[MemoryRecord, float]]: The records and their relevance scores.
+        """
+        if collection_name not in self._store:
+            logger.warning(
+                f"Collection '{collection_name}' does not exist in collections: "
+                f"{', '.join([collection for collection in await self.get_collections()])}"
+            )
+            return []
+
+        # Get all the records in the collection
+        memory_records = list(self._store[collection_name].values())
+
+        # Convert the collection of embeddings into a numpy array (stacked)
+        embeddings = array([x._embedding for x in memory_records], dtype=float)
+        embeddings = embeddings.reshape(embeddings.shape[0], -1)
+
+        # If the query embedding has shape (1, embedding_size),
+        # reshape it to (embedding_size,)
+        if len(embedding.shape) == 2:
+            embedding = embedding.reshape(
+                embedding.shape[1],
+            )
+
+        # Use numpy to get the cosine similarity between the query
+        # embedding and all the embeddings in the collection
+        similarity_scores = self.compute_similarity_scores(embedding, embeddings)
+
+        # Then, sort the results by the similarity score
+        sorted_results = sorted(
+            zip(memory_records, similarity_scores),
+            key=lambda x: x[1],
+            reverse=True,
+        )
+
+        # Then, filter out the results that are below the minimum relevance score
+        filtered_results = [x for x in sorted_results if x[1] >= min_relevance_score]
+
+        # Then, take the top N results
+        top_results = filtered_results[:limit]
+
+        if not with_embeddings:
+            # create copy of results without embeddings
+            for result in top_results:
+                result = deepcopy(result)
+                result[0]._embedding = None
+        return top_results
+
+    def compute_similarity_scores(self, embedding: ndarray, embedding_array: ndarray) -> ndarray:
+        """Computes the cosine similarity scores between a query embedding and a group of embeddings.
+
+        Args:
+            embedding (ndarray): The query embedding.
+            embedding_array (ndarray): The group of embeddings.
+
+        Returns:
+            ndarray: The cosine similarity scores.
+        """
+        query_norm = linalg.norm(embedding)
+        collection_norm = linalg.norm(embedding_array, axis=1)
+
+        # Compute indices for which the similarity scores can be computed
+        valid_indices = (query_norm != 0) & (collection_norm != 0)
+
+        # Initialize the similarity scores with -1 to distinguish the cases
+        # between zero similarity from orthogonal vectors and invalid similarity
+        similarity_scores = array([-1.0] * embedding_array.shape[0])
+
+        if valid_indices.any():
+            similarity_scores[valid_indices] = embedding.dot(embedding_array[valid_indices].T) / (
+                query_norm * collection_norm[valid_indices]
+            )
+            if not valid_indices.all():
+                logger.warning(
+                    "Some vectors in the embedding collection are zero vectors."
+                    "Ignoring cosine similarity score computation for those vectors."
+                )
+        else:
+            raise ValueError(
+                f"Invalid vectors, cannot compute cosine similarity scores"
+                f"for zero vectors"
+                f"{embedding_array} or {embedding}"
+            )
+        return similarity_scores

semantic_kernel-1.8.3/semantic_kernel/planners/__init__.py

@@ -0,0 +1,24 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+
+from semantic_kernel.planners.function_calling_stepwise_planner.function_calling_stepwise_planner import (
+    FunctionCallingStepwisePlanner,
+)
+from semantic_kernel.planners.function_calling_stepwise_planner.function_calling_stepwise_planner_options import (
+    FunctionCallingStepwisePlannerOptions,
+)
+from semantic_kernel.planners.function_calling_stepwise_planner.function_calling_stepwise_planner_result import (
+    FunctionCallingStepwisePlannerResult,
+)
+from semantic_kernel.planners.plan import Plan
+from semantic_kernel.planners.planner_options import PlannerOptions
+from semantic_kernel.planners.sequential_planner import SequentialPlanner
+
+__all__ = [
+    "FunctionCallingStepwisePlanner",
+    "FunctionCallingStepwisePlannerOptions",
+    "FunctionCallingStepwisePlannerResult",
+    "Plan",
+    "PlannerOptions",
+    "SequentialPlanner",
+]

semantic_kernel-1.8.3/semantic_kernel/planners/function_calling_stepwise_planner/__init__.py

@@ -0,0 +1,17 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.planners.function_calling_stepwise_planner.function_calling_stepwise_planner import (
+    FunctionCallingStepwisePlanner,
+)
+from semantic_kernel.planners.function_calling_stepwise_planner.function_calling_stepwise_planner_options import (
+    FunctionCallingStepwisePlannerOptions,
+)
+from semantic_kernel.planners.function_calling_stepwise_planner.function_calling_stepwise_planner_result import (
+    FunctionCallingStepwisePlannerResult,
+)
+
+__all__ = [
+    "FunctionCallingStepwisePlanner",
+    "FunctionCallingStepwisePlannerOptions",
+    "FunctionCallingStepwisePlannerResult",
+]

semantic_kernel-1.8.3/semantic_kernel/planners/function_calling_stepwise_planner/function_calling_stepwise_planner.py

@@ -0,0 +1,293 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+import os
+from copy import copy
+from typing import Any
+
+import yaml
+
+from semantic_kernel.connectors.ai.function_calling_utils import kernel_function_metadata_to_function_call_format
+from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
+from semantic_kernel.connectors.ai.open_ai.prompt_execution_settings.open_ai_prompt_execution_settings import (
+    OpenAIChatPromptExecutionSettings,
+)
+from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion
+from semantic_kernel.connectors.ai.open_ai.services.open_ai_chat_completion import OpenAIChatCompletion
+from semantic_kernel.const import DEFAULT_SERVICE_NAME
+from semantic_kernel.contents.chat_history import ChatHistory
+from semantic_kernel.contents.function_call_content import FunctionCallContent
+from semantic_kernel.contents.function_result_content import FunctionResultContent
+from semantic_kernel.contents.text_content import TextContent
+from semantic_kernel.exceptions.planner_exceptions import PlannerInvalidConfigurationError
+from semantic_kernel.functions.kernel_arguments import KernelArguments
+from semantic_kernel.functions.kernel_function import KernelFunction
+from semantic_kernel.kernel import Kernel
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.planners.function_calling_stepwise_planner.function_calling_stepwise_planner_options import (
+    FunctionCallingStepwisePlannerOptions,
+)
+from semantic_kernel.planners.function_calling_stepwise_planner.function_calling_stepwise_planner_result import (
+    FunctionCallingStepwisePlannerResult,
+    UserInteraction,
+)
+from semantic_kernel.prompt_template.kernel_prompt_template import KernelPromptTemplate
+from semantic_kernel.prompt_template.prompt_template_config import PromptTemplateConfig
+
+CUR_DIR = os.path.dirname(os.path.realpath(__file__))
+PLAN_YAML_FILE_PATH = os.path.join(CUR_DIR, "generate_plan.yaml")
+STEP_PROMPT_FILE_PATH = os.path.join(CUR_DIR, "step_prompt.txt")
+
+STEPWISE_PLANNER_PLUGIN_NAME = "StepwisePlanner_Excluded"
+
+STEPWISE_USER_MESSAGE = (
+    "Perform the next step of the plan if there is more work to do. "
+    "When you have reached a final answer, use the UserInteraction-SendFinalAnswer "
+    "function to communicate this back to the user."
+)
+
+USER_INTERACTION_SEND_FINAL_ANSWER = "UserInteraction-SendFinalAnswer"
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class FunctionCallingStepwisePlanner(KernelBaseModel):
+    """A Function Calling Stepwise Planner."""
+
+    service_id: str
+    options: FunctionCallingStepwisePlannerOptions
+    generate_plan_yaml: str
+    step_prompt: str
+
+    def __init__(self, service_id: str, options: FunctionCallingStepwisePlannerOptions | None = None):
+        """Initialize a new instance of the FunctionCallingStepwisePlanner.
+
+        The FunctionCallingStepwisePlanner is a planner based on top of an OpenAI Chat Completion service
+        (whether it be AzureOpenAI or OpenAI), so that we can use tools.
+
+        If the options are configured to use callbacks to get the initial plan and the step prompt,
+        the planner will use those provided callbacks to get that information. Otherwise, it will
+        read from the default yaml plan file and the step prompt file.
+
+        Args:
+            service_id (str): The service id
+            options (Optional[FunctionCallingStepwisePlannerOptions], optional): The options for
+                the function calling stepwise planner. Defaults to None.
+        """
+        options = options or FunctionCallingStepwisePlannerOptions()
+
+        if options.get_initial_plan:
+            generate_plan_yaml = options.get_initial_plan()
+        else:
+            with open(PLAN_YAML_FILE_PATH) as f:
+                generate_plan_yaml = f.read()
+
+        if options.get_step_prompt:
+            step_prompt = options.get_step_prompt()
+        else:
+            with open(STEP_PROMPT_FILE_PATH) as f:
+                step_prompt = f.read()
+
+        options.excluded_plugins.add(STEPWISE_PLANNER_PLUGIN_NAME)
+
+        super().__init__(
+            service_id=service_id,
+            options=options,
+            generate_plan_yaml=generate_plan_yaml,
+            step_prompt=step_prompt,
+        )
+
+    async def invoke(
+        self,
+        kernel: Kernel,
+        question: str,
+        arguments: KernelArguments | None = None,
+        **kwargs: Any,
+    ) -> FunctionCallingStepwisePlannerResult:
+        """Execute the function calling stepwise planner.
+
+        Args:
+            kernel: The kernel instance
+            question: The input question
+            arguments: (optional) The kernel arguments
+            kwargs: (optional) Additional keyword arguments
+
+        Returns:
+            FunctionCallingStepwisePlannerResult: The result of the function calling stepwise planner
+
+        Raises:
+            PlannerInvalidConfigurationError: If the input question is empty
+        """
+        if not question:
+            raise PlannerInvalidConfigurationError("Input question cannot be empty")
+
+        if not arguments:
+            arguments = KernelArguments(**kwargs)
+
+        try:
+            chat_completion: OpenAIChatCompletion | AzureChatCompletion = kernel.get_service(service_id=self.service_id)
+        except Exception as exc:
+            raise PlannerInvalidConfigurationError(
+                f"The OpenAI service `{self.service_id}` is not available. Please configure the AI service."
+            ) from exc
+
+        if not isinstance(chat_completion, (OpenAIChatCompletion, AzureChatCompletion)):
+            raise PlannerInvalidConfigurationError(
+                f"The service with id `{self.service_id}` is not an OpenAI based service."
+            )
+
+        prompt_execution_settings: OpenAIChatPromptExecutionSettings = (
+            self.options.execution_settings
+            or chat_completion.instantiate_prompt_execution_settings(service_id=self.service_id)
+        )
+        if self.options.max_completion_tokens:
+            prompt_execution_settings.max_tokens = self.options.max_completion_tokens
+
+        # Clone the kernel so that we can add planner-specific plugins without affecting the original kernel instance
+        cloned_kernel = copy(kernel)
+        cloned_kernel.add_plugin(UserInteraction(), "UserInteraction")
+
+        # Create and invoke a kernel function to generate the initial plan
+        initial_plan = await self._generate_plan(question=question, kernel=cloned_kernel, arguments=arguments)
+
+        chat_history_for_steps = await self._build_chat_history_for_step(
+            goal=question, initial_plan=initial_plan, kernel=cloned_kernel, arguments=arguments, service=chat_completion
+        )
+        prompt_execution_settings.function_choice_behavior = FunctionChoiceBehavior.Auto(
+            auto_invoke=False, filters={"excluded_plugins": list(self.options.excluded_plugins)}
+        )
+        for i in range(self.options.max_iterations):
+            # sleep for a bit to avoid rate limiting
+            if i > 0:
+                await asyncio.sleep(self.options.min_iteration_time_ms / 1000.0)  # convert ms to sec
+            # For each step, request another completion to select a function for that step
+            chat_history_for_steps.add_user_message(STEPWISE_USER_MESSAGE)
+            chat_result = await chat_completion.get_chat_message_contents(
+                chat_history=chat_history_for_steps,
+                settings=prompt_execution_settings,
+                kernel=cloned_kernel,
+            )
+            chat_result = chat_result[0]
+            chat_history_for_steps.add_message(chat_result)
+
+            if not any(isinstance(item, FunctionCallContent) for item in chat_result.items):
+                chat_history_for_steps.add_user_message("That function call is invalid. Try something else!")
+                continue
+
+            # Try to get the final answer out
+            function_call_content = next(
+                (
+                    item
+                    for item in chat_result.items
+                    if isinstance(item, FunctionCallContent) and item.name == USER_INTERACTION_SEND_FINAL_ANSWER
+                ),
+                None,
+            )
+
+            if function_call_content is not None:
+                args = function_call_content.parse_arguments()
+                return FunctionCallingStepwisePlannerResult(
+                    final_answer=args.get("answer", ""),
+                    chat_history=chat_history_for_steps,
+                    iterations=i + 1,
+                )
+
+            for item in chat_result.items:
+                if not isinstance(item, FunctionCallContent):
+                    continue
+                try:
+                    context = await chat_completion._process_function_call(
+                        function_call=item,
+                        kernel=cloned_kernel,
+                        chat_history=chat_history_for_steps,
+                        arguments=arguments,
+                        function_call_count=1,
+                        request_index=0,
+                        function_call_behavior=prompt_execution_settings.function_choice_behavior,
+                    )
+                    if context is not None:
+                        # Only add the function result content to the chat history if the context is present
+                        # which means it wasn't added in the _process_function_call method
+                        frc = FunctionResultContent.from_function_call_content_and_result(
+                            function_call_content=item, result=context.function_result
+                        )
+                        chat_history_for_steps.add_message(message=frc.to_chat_message_content())
+                except Exception as exc:
+                    frc = FunctionResultContent.from_function_call_content_and_result(
+                        function_call_content=item,
+                        result=TextContent(text=f"An error occurred during planner invocation: {exc}"),
+                    )
+                    chat_history_for_steps.add_message(message=frc.to_chat_message_content())
+                    continue
+
+        # We're done, but the model hasn't returned a final answer.
+        return FunctionCallingStepwisePlannerResult(
+            final_answer="",
+            chat_history=chat_history_for_steps,
+            iterations=i + 1,
+        )
+
+    async def _build_chat_history_for_step(
+        self,
+        goal: str,
+        initial_plan: str,
+        kernel: Kernel,
+        arguments: KernelArguments,
+        service: OpenAIChatCompletion | AzureChatCompletion,
+    ) -> ChatHistory:
+        """Build the chat history for the stepwise planner."""
+        ChatHistory()
+        additional_arguments = KernelArguments(
+            goal=goal,
+            initial_plan=initial_plan,
+        )
+        arguments.update(additional_arguments)
+        kernel_prompt_template = KernelPromptTemplate(
+            prompt_template_config=PromptTemplateConfig(
+                template=self.step_prompt,
+            )
+        )
+        prompt = await kernel_prompt_template.render(kernel, arguments)
+        return ChatHistory.from_rendered_prompt(prompt)
+
+    def _create_config_from_yaml(self, kernel: Kernel) -> "KernelFunction":
+        """A temporary method to create a function from the yaml file.
+
+        The yaml.safe_load will be replaced with the proper kernel
+        method later.
+        """
+        data = yaml.safe_load(self.generate_plan_yaml)
+        prompt_template_config = PromptTemplateConfig(**data)
+        if DEFAULT_SERVICE_NAME in prompt_template_config.execution_settings:
+            settings = prompt_template_config.execution_settings.pop(DEFAULT_SERVICE_NAME)
+            prompt_template_config.execution_settings[self.service_id] = settings
+        return kernel.add_function(
+            function_name="create_plan",
+            plugin_name="sequential_planner",
+            description="Create a plan for the given goal",
+            prompt_template_config=prompt_template_config,
+        )
+
+    async def _generate_plan(
+        self,
+        question: str,
+        kernel: Kernel,
+        arguments: KernelArguments,
+    ) -> str:
+        """Generate the plan for the given question using the kernel."""
+        generate_plan_function = self._create_config_from_yaml(kernel)
+        functions_manual = [
+            kernel_function_metadata_to_function_call_format(f)
+            for f in kernel.get_list_of_function_metadata({
+                "excluded_functions": [f"{self.service_id}", "sequential_planner-create_plan"]
+            })
+        ]
+        generated_plan_args = KernelArguments(
+            name_delimiter="-",
+            available_functions=functions_manual,
+            goal=question,
+        )
+        generated_plan_args.update(arguments)
+        generate_plan_result = await kernel.invoke(generate_plan_function, generated_plan_args)
+        return str(generate_plan_result)