Python: Implement Function calling for Chat (#2356)

### Motivation and Context

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->
I built support for function calling into SK!

Related to/fixes: 
- #2315 
- #2175 
- #1450 

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->
This implementation builds on top of all the existing pieces, but did
require some major work, so feel free to comment on where that is or is
not appropriate.

- Added a `ChatMessage` class to capture the relevant pieces of function
calling (name and content)
- Added a `complete_chat_with_functions_async` into
OpenAIChatCompletions class
- Added a `function_call` field to ChatRequestSettings class
- Added several helper functions and smaller changes
- Added a sample with updated core_skill that uses function calling to
demonstrate
- Added a second sample that shows how to use function_calling with
non-sk functions.

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone 😄

---------

Co-authored-by: Abby Harrison <abby.harrison@microsoft.com>

python/.vscode/settings.json

@@ -18,4 +18,9 @@
         "OPENAI",
         "skfunction"
     ],
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
 }

python/samples/kernel-syntax-examples/chat_gpt_api_function_calling.py

@@ -0,0 +1,121 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from typing import Tuple
+
+import semantic_kernel as sk
+import semantic_kernel.connectors.ai.open_ai as sk_oai
+from semantic_kernel.connectors.ai.open_ai.semantic_functions.open_ai_chat_prompt_template import (
+    OpenAIChatPromptTemplate,
+)
+from semantic_kernel.connectors.ai.open_ai.utils import (
+    chat_completion_with_function_call,
+    get_function_calling_object,
+)
+from semantic_kernel.core_skills import MathSkill
+
+system_message = """
+You are a chat bot. Your name is Mosscap and
+you have one goal: figure out what people need.
+Your full name, should you need to know it, is
+Splendid Speckled Mosscap. You communicate
+effectively, but you tend to answer with long
+flowery prose. You are also a math wizard, 
+especially for adding and subtracting.
+You also excel at joke telling, where your tone is often sarcastic.
+Once you have the answer I am looking for, 
+you will return a full answer to me as soon as possible.
+"""
+
+kernel = sk.Kernel()
+
+deployment_name, api_key, endpoint = sk.azure_openai_settings_from_dot_env()
+api_version = "2023-07-01-preview"
+kernel.add_chat_service(
+    "chat-gpt",
+    sk_oai.AzureChatCompletion(
+        deployment_name,
+        endpoint,
+        api_key,
+        api_version=api_version,
+    ),
+)
+
+skills_directory = os.path.join(__file__, "../../../../samples/skills")
+# adding skills to the kernel
+# the joke skill in the FunSkills is a semantic skill and has the function calling disabled.
+kernel.import_semantic_skill_from_directory(skills_directory, "FunSkill")
+# the math skill is a core skill and has the function calling enabled.
+kernel.import_skill(MathSkill(), skill_name="math")
+
+# enabling or disabling function calling is done by setting the function_call parameter for the completion.
+# when the function_call parameter is set to "auto" the model will decide which function to use, if any.
+# if you only want to use a specific function, set the name of that function in this parameter,
+# the format for that is 'SkillName-FunctionName', (i.e. 'math-Add').
+# if the model or api version do not support this you will get an error.
+prompt_config = sk.PromptTemplateConfig.from_completion_parameters(
+    max_tokens=2000,
+    temperature=0.7,
+    top_p=0.8,
+    function_call="auto",
+    chat_system_prompt=system_message,
+)
+prompt_template = OpenAIChatPromptTemplate(
+    "{{$user_input}}", kernel.prompt_template_engine, prompt_config
+)
+prompt_template.add_user_message("Hi there, who are you?")
+prompt_template.add_assistant_message(
+    "I am Mosscap, a chat bot. I'm trying to figure out what people need."
+)
+
+function_config = sk.SemanticFunctionConfig(prompt_config, prompt_template)
+chat_function = kernel.register_semantic_function("ChatBot", "Chat", function_config)
+
+# calling the chat, you could add a overloaded version of the settings here,
+# to enable or disable function calling or set the function calling to a specific skill.
+# see the openai_function_calling example for how to use this with a unrelated function definition
+filter = {"exclude_skill": ["ChatBot"]}
+functions = get_function_calling_object(kernel, filter)
+
+
+async def chat(context: sk.SKContext) -> Tuple[bool, sk.SKContext]:
+    try:
+        user_input = input("User:> ")
+        context.variables["user_input"] = user_input
+    except KeyboardInterrupt:
+        print("\n\nExiting chat...")
+        return False, None
+    except EOFError:
+        print("\n\nExiting chat...")
+        return False, None
+
+    if user_input == "exit":
+        print("\n\nExiting chat...")
+        return False, None
+
+    context = await chat_completion_with_function_call(
+        kernel,
+        chat_skill_name="ChatBot",
+        chat_function_name="Chat",
+        context=context,
+        functions=functions,
+    )
+    print(f"Mosscap:> {context.result}")
+    return True, context
+
+
+async def main() -> None:
+    chatting = True
+    context = kernel.create_new_context()
+    print(
+        "Welcome to the chat bot!\
+\n  Type 'exit' to exit.\
+\n  Try a math question to see the function calling in action (i.e. what is 3+3?)."
+    )
+    while chatting:
+        chatting, context = await chat(context)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/kernel-syntax-examples/openai_function_calling.py

@@ -0,0 +1,109 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+import semantic_kernel as sk
+import semantic_kernel.connectors.ai.open_ai as sk_oai
+from semantic_kernel.core_skills import MathSkill
+
+system_message = """
+You are a chat bot. Your name is Mosscap and
+you have one goal: figure out what people need.
+Your full name, should you need to know it, is
+Splendid Speckled Mosscap. You communicate
+effectively, but you tend to answer with long
+flowery prose. You are also a math wizard, 
+especially for adding and subtracting.
+You also excel at joke telling, where your tone is often sarcastic.
+Once you have the answer I am looking for, 
+you will return a full answer to me as soon as possible.
+"""
+
+kernel = sk.Kernel()
+
+deployment_name, api_key, endpoint = sk.azure_openai_settings_from_dot_env()
+api_version = "2023-07-01-preview"
+kernel.add_chat_service(
+    "chat-gpt",
+    sk_oai.AzureChatCompletion(
+        deployment_name,
+        endpoint,
+        api_key,
+        api_version=api_version,
+    ),
+)
+
+skills_directory = os.path.join(__file__, "../../../../samples/skills")
+# adding skills to the kernel
+# the joke skill in the FunSkills is a semantic skill and has the function calling disabled.
+kernel.import_semantic_skill_from_directory(skills_directory, "FunSkill")
+# the math skill is a core skill and has the function calling enabled.
+kernel.import_skill(MathSkill(), skill_name="math")
+
+# enabling or disabling function calling is done by setting the function_call parameter for the completion.
+# when the function_call parameter is set to "auto" the model will decide which function to use, if any.
+# if you only want to use a specific function, set the name of that function in this parameter,
+# the format for that is 'SkillName-FunctionName', (i.e. 'math-Add').
+# if the model or api version do not support this you will get an error.
+prompt_config = sk.PromptTemplateConfig.from_completion_parameters(
+    max_tokens=2000,
+    temperature=0.7,
+    top_p=0.8,
+    function_call="auto",
+    chat_system_prompt=system_message,
+)
+prompt_template = sk.ChatPromptTemplate(
+    "{{$user_input}}", kernel.prompt_template_engine, prompt_config
+)
+prompt_template.add_user_message("Hi there, who are you?")
+prompt_template.add_assistant_message(
+    "I am Mosscap, a chat bot. I'm trying to figure out what people need."
+)
+
+function_config = sk.SemanticFunctionConfig(prompt_config, prompt_template)
+chat_function = kernel.register_semantic_function("ChatBot", "Chat", function_config)
+# define the functions available
+functions = [
+    {
+        "name": "search_hotels",
+        "description": "Retrieves hotels from the search index based on the parameters provided",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "description": "The location of the hotel (i.e. Seattle, WA)",
+                },
+                "max_price": {
+                    "type": "number",
+                    "description": "The maximum price for the hotel",
+                },
+                "features": {
+                    "type": "string",
+                    "description": "A comma separated list of features (i.e. beachfront, free wifi, etc.)",
+                },
+            },
+            "required": ["location"],
+        },
+    }
+]
+
+
+async def main() -> None:
+    context = kernel.create_new_context()
+    context.variables[
+        "user_input"
+    ] = "I want to find a hotel in Seattle with free wifi and a pool."
+
+    context = await chat_function.invoke_async(context=context, functions=functions)
+    if function_call := context.pop_function_call():
+        print(f"Function to be called: {function_call.name}")
+        print(f"Function parameters: \n{function_call.arguments}")
+        return
+    print("No function was called")
+    print(f"Output was: {str(context)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/semantic_kernel/connectors/ai/chat_completion_client_base.py

@@ -2,26 +2,27 @@
 
 from abc import ABC, abstractmethod
 from logging import Logger
-from typing import TYPE_CHECKING, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, List, Optional, Union
 
 if TYPE_CHECKING:
     from semantic_kernel.connectors.ai.chat_request_settings import ChatRequestSettings
+    from semantic_kernel.models.chat.chat_message import ChatMessage
 
 
 class ChatCompletionClientBase(ABC):
     @abstractmethod
     async def complete_chat_async(
         self,
-        messages: List[Tuple[str, str]],
+        messages: List["ChatMessage"],
         settings: "ChatRequestSettings",
         logger: Optional[Logger] = None,
     ) -> Union[str, List[str]]:
         """
         This is the method that is called from the kernel to get a response from a chat-optimized LLM.
 
         Arguments:
-            messages {List[Tuple[str, str]]} -- A list of tuples, where each tuple is
-                comprised of a speaker ID and a message.
+            messages {List[ChatMessage]} -- A list of chat messages, that can be rendered into a
+                set of messages, from system, user, assistant and function.
             settings {ChatRequestSettings} -- Settings for the request.
             logger {Logger} -- A logger to use for logging.
 
@@ -33,16 +34,16 @@ async def complete_chat_async(
     @abstractmethod
     async def complete_chat_stream_async(
         self,
-        messages: List[Tuple[str, str]],
+        messages: List["ChatMessage"],
         settings: "ChatRequestSettings",
         logger: Optional[Logger] = None,
     ):
         """
         This is the method that is called from the kernel to get a stream response from a chat-optimized LLM.
 
         Arguments:
-            messages {List[Tuple[str, str]]} -- A list of tuples, where each tuple is
-                comprised of a speaker ID and a message.
+            messages {List[ChatMessage]} -- A list of chat messages, that can be rendered into a
+                set of messages, from system, user, assistant and function.
             settings {ChatRequestSettings} -- Settings for the request.
             logger {Logger} -- A logger to use for logging.
 

python/semantic_kernel/connectors/ai/chat_request_settings.py

@@ -1,7 +1,7 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Dict, List
+from typing import TYPE_CHECKING, Dict, List, Optional
 
 if TYPE_CHECKING:
     from semantic_kernel.semantic_functions.prompt_template_config import (
@@ -19,6 +19,7 @@ class ChatRequestSettings:
     max_tokens: int = 256
     token_selection_biases: Dict[int, int] = field(default_factory=dict)
     stop_sequences: List[str] = field(default_factory=list)
+    function_call: Optional[str] = None
 
     def update_from_completion_config(
         self, completion_config: "PromptTemplateConfig.CompletionConfig"
@@ -31,6 +32,11 @@ def update_from_completion_config(
         self.presence_penalty = completion_config.presence_penalty
         self.frequency_penalty = completion_config.frequency_penalty
         self.token_selection_biases = completion_config.token_selection_biases
+        self.function_call = (
+            completion_config.function_call
+            if hasattr(completion_config, "function_call")
+            else None
+        )
 
     @staticmethod
     def from_completion_config(

python/semantic_kernel/connectors/ai/open_ai/models/chat/function_call.py

@@ -0,0 +1,36 @@
+"""Class to hold chat messages."""
+import json
+from typing import Dict, Tuple
+
+from semantic_kernel.orchestration.context_variables import ContextVariables
+from semantic_kernel.sk_pydantic import SKBaseModel
+
+
+class FunctionCall(SKBaseModel):
+    """Class to hold a function call response."""
+
+    name: str
+    arguments: str
+
+    def parse_arguments(self) -> Dict[str, str]:
+        """Parse the arguments into a dictionary."""
+        try:
+            return json.loads(self.arguments)
+        except json.JSONDecodeError:
+            return None
+
+    def to_context_variables(self) -> ContextVariables:
+        """Return the arguments as a ContextVariables instance."""
+        args = self.parse_arguments()
+        return ContextVariables(variables={k.lower(): v for k, v in args.items()})
+
+    def split_name(self) -> Tuple[str, str]:
+        """Split the name into a skill and function name."""
+        if "-" not in self.name:
+            return None, self.name
+        return self.name.split("-")
+
+    def split_name_dict(self) -> dict:
+        """Split the name into a skill and function name."""
+        parts = self.split_name()
+        return {"skill_name": parts[0], "function_name": parts[1]}

python/semantic_kernel/connectors/ai/open_ai/models/chat/open_ai_chat_message.py

@@ -0,0 +1,14 @@
+"""Class to hold chat messages."""
+from typing import Optional
+
+from semantic_kernel.connectors.ai.open_ai.models.chat.function_call import (
+    FunctionCall,
+)
+from semantic_kernel.models.chat.chat_message import ChatMessage
+
+
+class OpenAIChatMessage(ChatMessage):
+    """Class to hold openai chat messages, which might include name and function_call fields."""
+
+    name: Optional[str] = None
+    function_call: Optional[FunctionCall] = None