semantic-kernel 1.8.3__zip

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

@@ -0,0 +1,44 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import model_validator
+
+from semantic_kernel.connectors.ai.open_ai.prompt_execution_settings.open_ai_prompt_execution_settings import (
+    OpenAIPromptExecutionSettings,
+)
+from semantic_kernel.planners.planner_options import PlannerOptions
+
+
+class FunctionCallingStepwisePlannerOptions(PlannerOptions):
+    """The Function Calling Stepwise Planner Options."""
+
+    max_tokens: int | None = None
+    max_tokens_ratio: float | None = 0.1
+    max_completion_tokens: int | None = None
+    max_prompt_tokens: int | None = None
+    get_initial_plan: Callable[[], str] | None = None
+    get_step_prompt: Callable[[], str] | None = None
+    max_iterations: int | None = 15
+    min_iteration_time_ms: int | None = 100
+    execution_settings: OpenAIPromptExecutionSettings | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def calculate_token_limits(cls, data: Any) -> Any:
+        """Calculate the token limits based on the max_tokens and max_tokens_ratio."""
+        if isinstance(data, dict):
+            max_tokens = data.get("max_tokens")
+            # Ensure max_tokens_ratio has a default value if not provided
+            max_tokens_ratio = data.get("max_tokens_ratio", 0.1)
+
+            if max_tokens is not None:
+                data["max_completion_tokens"] = int(max_tokens * max_tokens_ratio)
+                data["max_prompt_tokens"] = int(max_tokens * (1 - max_tokens_ratio))
+            else:
+                # Explicitly setting them to None if max_tokens is None, for clarity
+                data["max_completion_tokens"] = None
+                data["max_prompt_tokens"] = None
+
+        return data

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

@@ -0,0 +1,24 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import Annotated
+
+from semantic_kernel.contents.chat_history import ChatHistory
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class FunctionCallingStepwisePlannerResult(KernelBaseModel):
+    """The result of the function calling stepwise planner."""
+
+    final_answer: str = ""
+    chat_history: ChatHistory | None = None
+    iterations: int = 0
+
+
+class UserInteraction:
+    """The Kernel Function used to interact with the user."""
+
+    @kernel_function(description="The final answer to return to the user", name="SendFinalAnswer")
+    def send_final_answer(self, answer: Annotated[str, "The final answer"]) -> str:
+        """Send the final answer to the user."""
+        return "Thanks"

semantic_kernel-1.8.3/semantic_kernel/planners/function_calling_stepwise_planner/generate_plan.yaml

@@ -0,0 +1,32 @@
+template_format: semantic-kernel
+template: |
+    <message role="system">
+    You are an expert at generating plans from a given GOAL. Think step by step and determine a plan to satisfy the specified GOAL using only the FUNCTIONS provided to you. You can also make use of your own knowledge while forming an answer but you must not use functions that are not provided. Once you have come to a final answer, use the UserInteraction{{$name_delimiter}}SendFinalAnswer function to communicate this back to the user.
+
+    [FUNCTIONS]
+
+    {{$available_functions}}
+
+    [END FUNCTIONS]
+
+    To create the plan, follow these steps:
+    0. Each step should be something that is capable of being done by the list of available functions.
+    1. Steps can use output from one or more previous steps as input, if appropriate.
+    2. The plan should be as short as possible.
+    </message>
+    <message role="user">{{$goal}}</message>
+description: Generate a step-by-step plan to satisfy a given goal
+name: GeneratePlan
+input_variables:
+    - name: available_functions
+      description: A list of functions that can be used to generate the plan
+    - name: goal
+      description: The goal to satisfy
+execution_settings:
+    default:
+        temperature: 0.0
+        top_p: 0.0
+        presence_penalty: 0.0
+        frequency_penalty: 0.0
+        max_tokens: 256
+        stop_sequences: []

semantic_kernel-1.8.3/semantic_kernel/planners/function_calling_stepwise_planner/step_prompt.txt

@@ -0,0 +1,6 @@
+Original request: {{$goal}}
+
+You are in the process of helping the user fulfill this request using the following plan:
+{{$initial_plan}}
+
+The user will ask you for help with each step.

semantic_kernel-1.8.3/semantic_kernel/planners/plan.py

@@ -0,0 +1,397 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+import re
+import threading
+from collections.abc import Callable
+from copy import copy
+from typing import Any, ClassVar, Optional
+
+from pydantic import PrivateAttr
+
+from semantic_kernel import Kernel
+from semantic_kernel.connectors.ai import PromptExecutionSettings
+from semantic_kernel.exceptions import KernelFunctionNotFoundError, KernelInvokeException, KernelPluginNotFoundError
+from semantic_kernel.functions.function_result import FunctionResult
+from semantic_kernel.functions.kernel_arguments import KernelArguments
+from semantic_kernel.functions.kernel_function import KernelFunction
+from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+from semantic_kernel.utils.naming import generate_random_ascii_name
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class Plan:
+    """A plan for the kernel."""
+
+    _state: KernelArguments = PrivateAttr()
+    _steps: list["Plan"] = PrivateAttr()
+    _function: KernelFunction = PrivateAttr()
+    _parameters: KernelArguments = PrivateAttr()
+    _outputs: list[str] = PrivateAttr()
+    _has_next_step: bool = PrivateAttr()
+    _next_step_index: int = PrivateAttr()
+    _name: str = PrivateAttr()
+    _plugin_name: str = PrivateAttr()
+    _description: str = PrivateAttr()
+    _is_prompt: bool = PrivateAttr()
+    _prompt_execution_settings: PromptExecutionSettings = PrivateAttr()
+    DEFAULT_RESULT_KEY: ClassVar[str] = "PLAN.RESULT"
+
+    @property
+    def name(self) -> str:
+        """Get the name for the plan."""
+        return self._name
+
+    @property
+    def state(self) -> KernelArguments:
+        """Get the state for the plan."""
+        return self._state
+
+    @property
+    def steps(self) -> list["Plan"]:
+        """Get the steps for the plan."""
+        return self._steps
+
+    @property
+    def plugin_name(self) -> str:
+        """Get the plugin name for the plan."""
+        return self._plugin_name
+
+    @property
+    def description(self) -> str:
+        """Get the description for the plan."""
+        return self._description
+
+    @property
+    def function(self) -> Callable[..., Any]:
+        """Get the function for the plan."""
+        return self._function
+
+    @property
+    def parameters(self) -> KernelArguments:
+        """Get the parameters for the plan."""
+        return self._parameters
+
+    @property
+    def is_prompt(self) -> bool:
+        """Check if the plan is a prompt."""
+        return self._is_prompt
+
+    @property
+    def is_native(self) -> bool:
+        """Check if the plan is native code."""
+        if self._is_prompt is None:
+            return None
+        return not self._is_prompt
+
+    @property
+    def prompt_execution_settings(self) -> PromptExecutionSettings:
+        """Get the AI configuration for the plan."""
+        return self._prompt_execution_settings
+
+    @property
+    def has_next_step(self) -> bool:
+        """Check if the plan has a next step."""
+        return self._next_step_index < len(self._steps)
+
+    @property
+    def next_step_index(self) -> int:
+        """Get the next step index."""
+        return self._next_step_index
+
+    def __init__(
+        self,
+        name: str | None = None,
+        plugin_name: str | None = None,
+        description: str | None = None,
+        next_step_index: int | None = None,
+        state: KernelArguments | None = None,
+        parameters: KernelArguments | None = None,
+        outputs: list[str] | None = None,
+        steps: list["Plan"] | None = None,
+        function: KernelFunction | None = None,
+    ) -> None:
+        """Initializes a new instance of the Plan class."""
+        self._name = f"plan_{generate_random_ascii_name()}" if name is None else name
+        self._plugin_name = f"p_{generate_random_ascii_name()}" if plugin_name is None else plugin_name
+        self._description = "" if description is None else description
+        self._next_step_index = 0 if next_step_index is None else next_step_index
+        self._state = KernelArguments() if state is None else state
+        self._parameters = KernelArguments() if parameters is None else parameters
+        self._outputs = [] if outputs is None else outputs
+        self._steps = [] if steps is None else steps
+        self._has_next_step = len(self._steps) > 0
+        self._is_prompt = None
+        self._function = function or None
+        self._prompt_execution_settings = None
+
+        if function is not None:
+            self.set_function(function)
+
+    @classmethod
+    def from_goal(cls, goal: str) -> "Plan":
+        """Create a plan from a goal."""
+        return cls(description=goal, plugin_name=cls.__name__)
+
+    @classmethod
+    def from_function(cls, function: KernelFunction) -> "Plan":
+        """Create a plan from a function."""
+        plan = cls()
+        plan.set_function(function)
+        return plan
+
+    async def invoke(
+        self,
+        kernel: Kernel,
+        arguments: KernelArguments | None = None,
+    ) -> FunctionResult:
+        """Invoke the plan asynchronously.
+
+        Args:
+            kernel (Kernel): The kernel to use for invocation.
+            arguments (KernelArguments, optional): The context to use. Defaults to None.
+
+        Returns:
+            FunctionResult: The result of the function.
+        """
+        if not arguments:
+            arguments = copy(self._state)
+        if self._function is not None:
+            try:
+                result = await self._function.invoke(kernel=kernel, arguments=arguments)
+            except Exception as exc:
+                logger.error(f"Something went wrong in plan step {self._plugin_name}.{self._name}:'{exc}'")
+                raise KernelInvokeException(
+                    "Error occurred while running plan step: " + str(exc),
+                    exc,
+                ) from exc
+            return result
+        # loop through steps until completion
+        partial_results = []
+        while self.has_next_step:
+            function_arguments = copy(arguments)
+            self.add_variables_to_state(self._state, function_arguments)
+            logger.info(
+                "Invoking next step: "
+                + str(self._steps[self._next_step_index].name)
+                + " with arguments: "
+                + str(function_arguments)
+            )
+            result = await self.invoke_next_step(kernel, function_arguments)
+            if result:
+                partial_results.append(result)
+                self._state[Plan.DEFAULT_RESULT_KEY] = str(result)
+                arguments = self.update_arguments_with_outputs(arguments)
+                logger.info(f"updated arguments: {arguments}")
+
+        result_string = str(partial_results[-1]) if len(partial_results) > 0 else ""
+
+        return FunctionResult(function=self.metadata, value=result_string, metadata={"results": partial_results})
+
+    def set_ai_configuration(
+        self,
+        settings: PromptExecutionSettings,
+    ) -> None:
+        """Set the AI configuration for the plan."""
+        self._prompt_execution_settings = settings
+
+    @property
+    def metadata(self) -> KernelFunctionMetadata:
+        """Get the metadata for the plan."""
+        if self._function is not None:
+            return self._function.metadata
+        return KernelFunctionMetadata(
+            name=self._name or "Plan",
+            plugin_name=self._plugin_name,
+            parameters=[],
+            description=self._description,
+            is_prompt=self._is_prompt or False,
+        )
+
+    def set_available_functions(self, plan: "Plan", kernel: "Kernel", arguments: "KernelArguments") -> "Plan":
+        """Set the available functions for the plan."""
+        if len(plan.steps) == 0:
+            try:
+                plugin_function = kernel.get_function(plan.plugin_name, plan.name)
+                plan.set_function(plugin_function)
+            except (KernelFunctionNotFoundError, KernelPluginNotFoundError) as exc:
+                logger.error(
+                    f"Something went wrong when setting available functions in {self._plugin_name}.{self._name}:'{exc}'"
+                )
+                pass
+        else:
+            for step in plan.steps:
+                step = self.set_available_functions(step, kernel, arguments)
+
+        return plan
+
+    def add_steps(self, steps: list["Plan"] | list[KernelFunction]) -> None:
+        """Add steps to the plan."""
+        for step in steps:
+            if type(step) is Plan:
+                self._steps.append(step)
+            else:
+                new_step = Plan(
+                    name=step.name,
+                    plugin_name=step.plugin_name,
+                    description=step.description,
+                    next_step_index=0,
+                    state=KernelArguments(),
+                    parameters=KernelArguments(),
+                    outputs=[],
+                    steps=[],
+                )
+                new_step.set_function(step)
+                self._steps.append(new_step)
+
+    def set_function(self, function: KernelFunction) -> None:
+        """Set the function for the plan."""
+        self._function = function
+        self._name = function.name
+        self._plugin_name = function.plugin_name
+        self._description = function.description
+        self._is_prompt = function.is_prompt
+        if hasattr(function, "prompt_execution_settings"):
+            self._prompt_execution_settings = function.prompt_execution_settings
+
+    async def run_next_step(
+        self,
+        kernel: Kernel,
+        arguments: KernelArguments,
+    ) -> Optional["FunctionResult"]:
+        """Run the next step in the plan."""
+        return await self.invoke_next_step(kernel, arguments)
+
+    async def invoke_next_step(self, kernel: Kernel, arguments: KernelArguments) -> Optional["FunctionResult"]:
+        """Invoke the next step in the plan."""
+        if not self.has_next_step:
+            return None
+        step = self._steps[self._next_step_index]
+
+        # merge the state with the current context variables for step execution
+        arguments = self.get_next_step_arguments(arguments, step)
+
+        try:
+            result = await step.invoke(kernel, arguments)
+        except Exception as exc:
+            raise KernelInvokeException(
+                "Error occurred while running plan step: " + str(exc),
+                exc,
+            ) from exc
+
+        # Update state with result
+        self._state["input"] = str(result)
+
+        # Update plan result in state with matching outputs (if any)
+        if set(self._outputs).intersection(set(step._outputs)):
+            current_plan_result = ""
+            if Plan.DEFAULT_RESULT_KEY in self._state:
+                current_plan_result = self._state[Plan.DEFAULT_RESULT_KEY]
+            self._state[Plan.DEFAULT_RESULT_KEY] = current_plan_result.strip() + str(result)
+
+        # Increment the step
+        self._next_step_index += 1
+        return result
+
+    def add_variables_to_state(self, state: KernelArguments, variables: KernelArguments) -> None:
+        """Add variables to the state."""
+        for key in variables:
+            if key not in state:
+                state[key] = variables[key]
+
+    def update_arguments_with_outputs(self, arguments: KernelArguments) -> KernelArguments:
+        """Update the arguments with the outputs from the current step."""
+        if Plan.DEFAULT_RESULT_KEY in self._state:
+            result_string = self._state[Plan.DEFAULT_RESULT_KEY]
+        else:
+            result_string = str(self._state)
+
+        arguments["input"] = result_string
+
+        for item in self._steps[self._next_step_index - 1]._outputs:
+            arguments[item] = self._state.get(item, result_string)
+        return arguments
+
+    def get_next_step_arguments(self, arguments: KernelArguments, step: "Plan") -> KernelArguments:
+        """Get the arguments for the next step."""
+        # Priority for Input
+        # - Parameters (expand from variables if needed)
+        # - KernelArguments
+        # - Plan.State
+        # - Empty if sending to another plan
+        # - Plan.Description
+        input_ = None
+        step_input_value = step._parameters.get("input")
+        variables_input_value = arguments.get("input")
+        state_input_value = self._state.get("input")
+        if step_input_value and step_input_value != "":
+            input_ = step_input_value
+        elif variables_input_value and variables_input_value != "":
+            input_ = variables_input_value
+        elif state_input_value and state_input_value != "":
+            input_ = state_input_value
+        elif len(step._steps) > 0:
+            input_ = ""
+        elif self._description is not None and self._description != "":
+            input_ = self._description
+
+        step_arguments = KernelArguments(input=input_)
+        logger.debug(f"Step input: {step_arguments}")
+
+        # Priority for remaining stepVariables is:
+        # - Function Parameters (pull from variables or state by a key value)
+        # - Step Parameters (pull from variables or state by a key value)
+        # - All other variables. These are carried over in case the function wants access to the ambient content.
+        function_params = step.metadata
+        if function_params:
+            logger.debug(f"Function parameters: {function_params.parameters}")
+            for param in function_params.parameters:
+                if param.name in arguments:
+                    step_arguments[param.name] = arguments[param.name]
+                elif param.name in self._state and (
+                    self._state[param.name] is not None and self._state[param.name] != ""
+                ):
+                    step_arguments[param.name] = self._state[param.name]
+        logger.debug(f"Added other parameters: {step_arguments}")
+
+        for param_name, param_val in step.parameters.items():
+            if param_name in step_arguments:
+                continue
+
+            if param_name in arguments:
+                step_arguments[param_name] = param_val
+            elif param_name in self._state:
+                step_arguments[param_name] = self._state[param_name]
+            else:
+                expanded_value = self.expand_from_arguments(arguments, param_val)
+                step_arguments[param_name] = expanded_value
+
+        for item in arguments:
+            if item not in step_arguments:
+                step_arguments[item] = arguments[item]
+
+        logger.debug(f"Final step arguments: {step_arguments}")
+
+        return step_arguments
+
+    def expand_from_arguments(self, arguments: KernelArguments, input_from_step: Any) -> str:
+        """Expand variables in the input from the step using the arguments."""
+        result = input_from_step
+        variables_regex = r"\$(?P<var>\w+)"
+        matches = [m for m in re.finditer(variables_regex, str(input_from_step))]
+        ordered_matches = sorted(matches, key=lambda m: len(m.group("var")), reverse=True)
+
+        for match in ordered_matches:
+            var_name = match.group("var")
+            if var_name in arguments:
+                result = result.replace(f"${var_name}", arguments[var_name])
+
+        return result
+
+    def _runThread(self, code: Callable):
+        result = []
+        thread = threading.Thread(target=self._runCode, args=(code, result))
+        thread.start()
+        thread.join()
+        return result[0]

semantic_kernel-1.8.3/semantic_kernel/planners/planner_extensions.py

@@ -0,0 +1,74 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+
+from semantic_kernel.functions.kernel_arguments import KernelArguments
+from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+from semantic_kernel.kernel import Kernel
+from semantic_kernel.planners.planner_options import PlannerOptions
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+# NOTE these extensions will be used going forward by the FunctionCallingStepWisePlanner and others.
+# The other sequential planner extensions will be left in right now for as long as we support that planner
+# and will be removed once we deprecate it.
+
+
+class PlannerFunctionExtension:
+    """Function extension for the planner."""
+
+    @staticmethod
+    def to_manual_string(function: KernelFunctionMetadata):
+        """Convert the function to a string that can be used in the manual."""
+        inputs = [
+            f"  - {parameter.name}: {parameter.description}"
+            + (f" (default value: {parameter.default_value})" if parameter.default_value else "")
+            for parameter in function.parameters
+        ]
+        inputs = "\n".join(inputs)
+        return f"{function.fully_qualified_name}:\n  description: {function.description}\n  inputs:\n  {inputs}"
+
+    @staticmethod
+    def to_embedding_string(function: KernelFunctionMetadata):
+        """Convert the function to a string that can be used as an embedding."""
+        inputs = "\n".join([f"    - {parameter.name}: {parameter.description}" for parameter in function.parameters])
+        return f"{function.name}:\n  description: {function.description}\n  inputs:\n{inputs}"
+
+
+class PlannerKernelExtension:
+    """Kernel extension for the planner."""
+
+    PLANNER_MEMORY_COLLECTION_NAME = " Planning.KernelFunctionManual"
+    PLAN_KERNEL_FUNCTIONS_ARE_REMEMBERED = "Planning.KernelFunctionsAreRemembered"
+
+    @staticmethod
+    async def get_functions_manual(
+        kernel: "Kernel",
+        arguments: KernelArguments,
+        options: PlannerOptions = None,
+    ) -> str:
+        """Get the string of the function."""
+        options = options or PlannerOptions()
+
+        if options.get_available_functions is None:
+            functions = await PlannerKernelExtension.get_available_functions(kernel, arguments, options)
+        else:
+            functions = await options.get_available_functions(options)
+
+        return "\n\n".join([PlannerFunctionExtension.to_manual_string(func) for func in functions])
+
+    @staticmethod
+    async def get_available_functions(
+        kernel: Kernel,
+        arguments: KernelArguments,
+        options: PlannerOptions,
+    ):
+        """Get the available functions for the kernel."""
+        excluded_plugins = options.excluded_plugins or []
+        excluded_functions = options.excluded_functions or []
+
+        return [
+            func
+            for func in kernel.get_list_of_function_metadata()
+            if (func.plugin_name not in excluded_plugins and func.name not in excluded_functions)
+        ]

semantic_kernel-1.8.3/semantic_kernel/planners/planner_options.py

@@ -0,0 +1,16 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from collections.abc import Callable
+
+from pydantic import Field
+
+from semantic_kernel.functions.kernel_function_metadata import KernelFunctionMetadata
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class PlannerOptions(KernelBaseModel):
+    """The default planner options that planners inherit from."""
+
+    excluded_plugins: set[str] = Field(default_factory=set)
+    excluded_functions: set[str] = Field(default_factory=set)
+    get_available_functions: Callable[["PlannerOptions", str | None], list[KernelFunctionMetadata]] | None = None

semantic_kernel-1.8.3/semantic_kernel/planners/sequential_planner/Plugins/SequentialPlanning/config.json

@@ -0,0 +1,27 @@
+{
+  "schema": 1,
+  "description": "Given a request or command or goal generate a step by step plan to fulfill the request using functions. This ability is also known as decision making and function flow",
+  "type": "completion",
+  "execution_settings": {
+    "default": {
+    "max_tokens": 1024,
+    "temperature": 0,
+    "top_p": 0,
+    "presence_penalty": 0,
+    "frequency_penalty": 0,
+    "stop_sequences": ["<!-- END -->"]
+    }
+  },
+  "input_variables": [
+    {
+      "name": "input",
+      "description": "The question to answer",
+      "defaultValue": ""
+    },
+    {
+      "name": "available_functions",
+      "description": "The list of the agent's available_functions",
+      "defaultValue": ""
+    }
+  ]
+}