Python: Add Google PaLM connector with text completion and example file (microsoft#2076)

### 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.
-->
Implementation of Google PaLM connector with text completion and an
example file to demonstrate its functionality.
Closes microsoft#1979

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

1. Implemented Google Palm connector with text completion 
2. Added example file to ```python/samples/kernel-syntax-examples```
3. Added integration tests with different inputs to kernel.run_async
4. Added unit tests to ensure successful initialization of the class and
successful API calls
5. 3 optional arguments (top_k, safety_settings, client) for
google.generativeai.generate_text were not included. See more
information about the function and its arguments:
https://developers.generativeai.google/api/python/google/generativeai/generate_text

I also opened a PR for text embedding and chat completion microsoft#2258

### 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#dev-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone 😄

Currently no warnings, there was 1 warning when first installing genai
with `poetry add google.generativeai==v0.1.0rc2` from within poetry
shell: "The locked version 0.1.0rc2 for google-generativeai is a yanked
version. Reason for being yanked: Release is marked as supporting Py3.8,
but in practice it requires 3.9". We would need to require later
versions of python to fix it.

---------

Co-authored-by: Abby Harrison <[email protected]>
Co-authored-by: Abby Harrison <[email protected]>

Author: 2 people

python/.env.example

@@ -8,5 +8,5 @@ AZURE_COGNITIVE_SEARCH_ADMIN_KEY=""
 PINECONE_API_KEY=""
 PINECONE_ENVIRONMENT=""
 POSTGRES_CONNECTION_STRING=""
-GOOGLE_API_KEY=""
+GOOGLE_PALM_API_KEY=""
 GOOGLE_SEARCH_ENGINE_ID=""

python/poetry.lock

@@ -25,6 +25,10 @@ pytest = "7.4.0"
 ruff = "0.0.283"
 pytest-asyncio = "0.21.1"
 
+[tool.poetry.group.google_palm.dependencies]
+google-generativeai = { version = "^0.1.0", markers = "python_version >= '3.9'" }
+grpcio-status = { version = "^1.53.0", markers = "python_version >= '3.9'" }
+
 [tool.poetry.group.hugging_face.dependencies]
 transformers = "^4.28.1"
 sentence-transformers = "^2.2.2"

python/pyproject.toml

@@ -0,0 +1,54 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+import semantic_kernel as sk
+import semantic_kernel.connectors.ai.google_palm as sk_gp
+from semantic_kernel.connectors.ai.complete_request_settings import (
+    CompleteRequestSettings,
+)
+
+
+async def text_completion_example_complete_async(kernel, api_key, user_mssg, settings):
+    """
+    Complete a text prompt using the Google PaLM model and print the results.
+    """
+    palm_text_completion = sk_gp.GooglePalmTextCompletion(
+        "models/text-bison-001", api_key
+    )
+    kernel.add_text_completion_service("models/text-bison-001", palm_text_completion)
+    answer = await palm_text_completion.complete_async(user_mssg, settings)
+    return answer
+
+
+async def main() -> None:
+    kernel = sk.Kernel()
+    apikey = sk.google_palm_settings_from_dot_env()
+    settings = CompleteRequestSettings()
+
+    user_mssg1 = (
+        "Sam has three boxes, each containing a certain number of coins. "
+        "The first box has twice as many coins as the second box, and the second "
+        "box has three times as many coins as the third box. Together, the three "
+        "boxes have 98 coins in total. How many coins are there in each box? "
+        "Think about it step by step, and show your work."
+    )
+    response = await text_completion_example_complete_async(
+        kernel, apikey, user_mssg1, settings
+    )
+    print(f"User:> {user_mssg1}\n\nChatBot:> {response}\n")
+    # Use temperature to influence the variance of the responses
+    settings.number_of_responses = 3
+    settings.temperature = 1
+    user_mssg2 = (
+        "I need a concise answer. A common method for traversing a binary tree is"
+    )
+    response = await text_completion_example_complete_async(
+        kernel, apikey, user_mssg2, settings
+    )
+    print(f"User:> {user_mssg2}\n\nChatBot:> {response}")
+    return
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -16,6 +16,7 @@
 from semantic_kernel.utils.null_logger import NullLogger
 from semantic_kernel.utils.settings import (
     azure_openai_settings_from_dot_env,
+    google_palm_settings_from_dot_env,
     openai_settings_from_dot_env,
     pinecone_settings_from_dot_env,
     postgres_settings_from_dot_env,
@@ -28,6 +29,7 @@
     "azure_openai_settings_from_dot_env",
     "postgres_settings_from_dot_env",
     "pinecone_settings_from_dot_env",
+    "google_palm_settings_from_dot_env",
     "PromptTemplateConfig",
     "PromptTemplate",
     "ChatPromptTemplate",

python/semantic_kernel/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.connectors.ai.google_palm.services.gp_text_completion import (
+    GooglePalmTextCompletion,
+)
+
+__all__ = ["GooglePalmTextCompletion"]

python/semantic_kernel/connectors/ai/google_palm/__init__.py

@@ -0,0 +1,105 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import List, Union
+
+import google.generativeai as palm
+
+from semantic_kernel.connectors.ai.ai_exception import AIException
+from semantic_kernel.connectors.ai.complete_request_settings import (
+    CompleteRequestSettings,
+)
+from semantic_kernel.connectors.ai.text_completion_client_base import (
+    TextCompletionClientBase,
+)
+
+
+class GooglePalmTextCompletion(TextCompletionClientBase):
+    _model_id: str
+    _api_key: str
+
+    def __init__(self, model_id: str, api_key: str) -> None:
+        """
+        Initializes a new instance of the GooglePalmTextCompletion class.
+
+        Arguments:
+            model_id {str} -- GooglePalm model name, see
+            https://developers.generativeai.google/models/language
+            api_key {str} -- GooglePalm API key, see
+            https://developers.generativeai.google/products/palm
+        """
+        if not api_key:
+            raise ValueError("The Google PaLM API key cannot be `None` or empty`")
+
+        self._model_id = model_id
+        self._api_key = api_key
+
+    async def complete_async(
+        self, prompt: str, request_settings: CompleteRequestSettings
+    ) -> Union[str, List[str]]:
+        response = await self._send_completion_request(prompt, request_settings)
+
+        if request_settings.number_of_responses > 1:
+            return [candidate["output"] for candidate in response.candidates]
+        else:
+            return response.result
+
+    async def complete_stream_async(
+        self, prompt: str, request_settings: CompleteRequestSettings
+    ):
+        raise NotImplementedError(
+            "Google Palm API does not currently support streaming"
+        )
+
+    async def _send_completion_request(
+        self, prompt: str, request_settings: CompleteRequestSettings
+    ):
+        """
+        Completes the given prompt. Returns a single string completion.
+        Cannot return multiple completions. Cannot return logprobs.
+
+        Arguments:
+            prompt {str} -- The prompt to complete.
+            request_settings {CompleteRequestSettings} -- The request settings.
+
+        Returns:
+            str -- The completed text.
+        """
+        if not prompt:
+            raise ValueError("Prompt cannot be `None` or empty")
+        if request_settings is None:
+            raise ValueError("Request settings cannot be `None`")
+        if request_settings.max_tokens < 1:
+            raise AIException(
+                AIException.ErrorCodes.InvalidRequest,
+                "The max tokens must be greater than 0, "
+                f"but was {request_settings.max_tokens}",
+            )
+        try:
+            palm.configure(api_key=self._api_key)
+        except Exception as ex:
+            raise PermissionError(
+                "Google PaLM service failed to configure. Invalid API key provided.",
+                ex,
+            )
+        try:
+            response = palm.generate_text(
+                model=self._model_id,
+                prompt=prompt,
+                temperature=request_settings.temperature,
+                max_output_tokens=request_settings.max_tokens,
+                stop_sequences=(
+                    request_settings.stop_sequences
+                    if request_settings.stop_sequences is not None
+                    and len(request_settings.stop_sequences) > 0
+                    else None
+                ),
+                candidate_count=request_settings.number_of_responses,
+                top_p=request_settings.top_p,
+            )
+        except Exception as ex:
+            raise AIException(
+                AIException.ErrorCodes.ServiceError,
+                "Google PaLM service failed to complete the prompt",
+                ex,
+            )
+        return response

python/semantic_kernel/connectors/ai/google_palm/services/gp_text_completion.py

@@ -79,3 +79,19 @@ def pinecone_settings_from_dot_env() -> Tuple[str, str]:
     assert environment, "Pinecone environment not found in .env file"
 
     return api_key, environment
+
+
+def google_palm_settings_from_dot_env() -> str:
+    """
+    Reads the Google PaLM API key from the .env file.
+
+    Returns:
+        str: The Google PaLM API key
+    """
+
+    config = dotenv_values(".env")
+    api_key = config.get("GOOGLE_PALM_API_KEY", None)
+
+    assert api_key is not None, "Google PaLM API key not found in .env file"
+
+    return api_key

python/semantic_kernel/utils/settings.py

@@ -37,3 +37,14 @@ def get_oai_config():
         api_key, org_id = sk.openai_settings_from_dot_env()
 
     return api_key, org_id
+
+
+@pytest.fixture(scope="session")
+def get_gp_config():
+    if "Python_Integration_Tests" in os.environ:
+        api_key = os.environ["GOOGLE_PALM_API_KEY"]
+    else:
+        # Load credentials from .env file
+        api_key = sk.google_palm_settings_from_dot_env()
+
+    return api_key

python/tests/conftest.py

@@ -2,6 +2,7 @@
 
 import pytest
 
+import semantic_kernel.connectors.ai.google_palm as sk_gp
 import semantic_kernel.connectors.ai.hugging_face as sk_hf
 
 
@@ -149,3 +150,27 @@ def setup_summarize_conversation_using_skill(create_kernel):
         John: Yeah, that's a good idea."""
 
     yield kernel, ChatTranscript
+
+
+@pytest.fixture(scope="module")
+def setup_gp_text_completion_function(create_kernel, get_gp_config):
+    kernel = create_kernel
+    api_key = get_gp_config
+    # Configure LLM service
+    palm_text_completion = sk_gp.GooglePalmTextCompletion(
+        "models/text-bison-001", api_key
+    )
+    kernel.add_text_completion_service("models/text-bison-001", palm_text_completion)
+
+    # Define semantic function using SK prompt template language
+    sk_prompt = "Hello, I like {{$input}}{{$input2}}"
+
+    # Create the semantic function
+    text2text_function = kernel.create_semantic_function(
+        sk_prompt, max_tokens=25, temperature=0.7, top_p=0.5
+    )
+
+    # User input
+    simple_input = "sleeping and "
+
+    yield kernel, text2text_function, simple_input

python/tests/integration/completions/conftest.py

@@ -0,0 +1,117 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+import sys
+
+import pytest
+
+import semantic_kernel as sk
+
+pytestmark = pytest.mark.skipif(
+    sys.version_info < (3, 9), reason="Google Palm requires Python 3.9 or greater"
+)
+
+pytestmark = pytest.mark.skipif(
+    "Python_Integration_Tests" in os.environ,
+    reason="Google Palm integration tests are only set up to run locally",
+)
+
+
+@pytest.mark.asyncio
+async def test_text2text_generation_input_str(setup_gp_text_completion_function):
+    kernel, text2text_function, simple_input = setup_gp_text_completion_function
+
+    # Complete input string and print
+    summary = await kernel.run_async(text2text_function, input_str=simple_input)
+
+    output = str(summary).strip()
+    print(f"Completion using input string: '{output}'")
+    assert len(output) > 0
+
+
+@pytest.mark.asyncio
+async def test_text2text_generation_input_vars(setup_gp_text_completion_function):
+    kernel, text2text_function, simple_input = setup_gp_text_completion_function
+
+    # Complete input as context variable and print
+    context_vars = sk.ContextVariables(simple_input)
+    summary = await kernel.run_async(text2text_function, input_vars=context_vars)
+
+    output = str(summary).strip()
+    print(f"Completion using context variables: '{output}'")
+    assert len(output) > 0
+
+
+@pytest.mark.asyncio
+async def test_text2text_generation_input_context(setup_gp_text_completion_function):
+    kernel, text2text_function, simple_input = setup_gp_text_completion_function
+
+    # Complete input context and print
+    context = kernel.create_new_context()
+    context["input"] = simple_input
+    summary = await kernel.run_async(text2text_function, input_context=context)
+
+    output = str(summary).strip()
+    print(f"Completion using input context: '{output}'")
+    assert len(output) > 0
+
+
+@pytest.mark.asyncio
+async def test_text2text_generation_input_context_with_vars(
+    setup_gp_text_completion_function,
+):
+    kernel, text2text_function, simple_input = setup_gp_text_completion_function
+
+    # Complete input context with additional variables and print
+    context = kernel.create_new_context()
+    context["input"] = simple_input
+    context_vars = sk.ContextVariables("running and")
+    summary = await kernel.run_async(
+        text2text_function, input_context=context, input_vars=context_vars
+    )
+
+    output = str(summary).strip()
+    print(f"Completion using context and additional variables: '{output}'")
+    assert len(output) > 0
+
+
+@pytest.mark.asyncio
+async def test_text2text_generation_input_context_with_str(
+    setup_gp_text_completion_function,
+):
+    kernel, text2text_function, simple_input = setup_gp_text_completion_function
+
+    # Complete input context with additional input string and print
+    context = kernel.create_new_context()
+    context["input"] = simple_input
+    summary = await kernel.run_async(
+        text2text_function, input_context=context, input_str="running and"
+    )
+
+    output = str(summary).strip()
+    print(f"Completion using context and additional string: '{output}'")
+    assert len(output) > 0
+
+
+@pytest.mark.asyncio
+async def test_text2text_generation_input_context_with_vars_and_str(
+    setup_gp_text_completion_function,
+):
+    kernel, text2text_function, simple_input = setup_gp_text_completion_function
+
+    # Complete input context with additional variables and string and print
+    context = kernel.create_new_context()
+    context["input"] = simple_input
+    context_vars = sk.ContextVariables(variables={"input2": "running and"})
+    summary = await kernel.run_async(
+        text2text_function,
+        input_context=context,
+        input_vars=context_vars,
+        input_str="new text",
+    )
+
+    output = str(summary).strip()
+    print(
+        f"Completion using context, additional variables, and additional string: '{output}'"
+    )
+    assert len(output) > 0