semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/core_plugins/http_plugin.py

@@ -0,0 +1,106 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import json
+from typing import Annotated, Any
+
+import aiohttp
+
+from semantic_kernel.exceptions import FunctionExecutionException
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class HttpPlugin(KernelBaseModel):
+    """A plugin that provides HTTP functionality.
+
+    Usage:
+        kernel.add_plugin(HttpPlugin(), "http")
+
+    Examples:
+        {{http.getAsync $url}}
+        {{http.postAsync $url}}
+        {{http.putAsync $url}}
+        {{http.deleteAsync $url}}
+    """
+
+    @kernel_function(description="Makes a GET request to a url", name="getAsync")
+    async def get(self, url: Annotated[str, "The URL to send the request to."]) -> str:
+        """Sends an HTTP GET request to the specified URI and returns the response body as a string.
+
+        Args:
+            url: The URL to send the request to.
+
+        Returns:
+            The response body as a string.
+        """
+        if not url:
+            raise FunctionExecutionException("url cannot be `None` or empty")
+
+        async with aiohttp.ClientSession() as session, session.get(url, raise_for_status=True) as response:
+            return await response.text()
+
+    @kernel_function(description="Makes a POST request to a uri", name="postAsync")
+    async def post(
+        self,
+        url: Annotated[str, "The URI to send the request to."],
+        body: Annotated[dict[str, Any] | None, "The body of the request"] = {},
+    ) -> str:
+        """Sends an HTTP POST request to the specified URI and returns the response body as a string.
+
+        Args:
+            url: The URI to send the request to.
+            body: Contains the body of the request
+        returns:
+            The response body as a string.
+        """
+        if not url:
+            raise FunctionExecutionException("url cannot be `None` or empty")
+
+        headers = {"Content-Type": "application/json"}
+        data = json.dumps(body)
+        async with (
+            aiohttp.ClientSession() as session,
+            session.post(url, headers=headers, data=data, raise_for_status=True) as response,
+        ):
+            return await response.text()
+
+    @kernel_function(description="Makes a PUT request to a uri", name="putAsync")
+    async def put(
+        self,
+        url: Annotated[str, "The URI to send the request to."],
+        body: Annotated[dict[str, Any] | None, "The body of the request"] = {},
+    ) -> str:
+        """Sends an HTTP PUT request to the specified URI and returns the response body as a string.
+
+        Args:
+            url: The URI to send the request to.
+            body: Contains the body of the request
+
+        Returns:
+            The response body as a string.
+        """
+        if not url:
+            raise FunctionExecutionException("url cannot be `None` or empty")
+
+        headers = {"Content-Type": "application/json"}
+        data = json.dumps(body)
+        async with (
+            aiohttp.ClientSession() as session,
+            session.put(url, headers=headers, data=data, raise_for_status=True) as response,
+        ):
+            return await response.text()
+
+    @kernel_function(description="Makes a DELETE request to a uri", name="deleteAsync")
+    async def delete(self, url: Annotated[str, "The URI to send the request to."]) -> str:
+        """Sends an HTTP DELETE request to the specified URI and returns the response body as a string.
+
+        Args:
+            url: The URI to send the request to.
+
+        Returns:
+            The response body as a string.
+        """
+        if not url:
+            raise FunctionExecutionException("url cannot be `None` or empty")
+        async with aiohttp.ClientSession() as session, session.delete(url, raise_for_status=True) as response:
+            return await response.text()

semantic_kernel-1.8.3/semantic_kernel/core_plugins/math_plugin.py

@@ -0,0 +1,48 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import Annotated
+
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+
+
+class MathPlugin:
+    """Description: MathPlugin provides a set of functions to make Math calculations.
+
+    Usage:
+        kernel.add_plugin(MathPlugin(), plugin_name="math")
+
+    Examples:
+        {{math.Add}} => Returns the sum of input and amount (provided in the KernelArguments)
+        {{math.Subtract}} => Returns the difference of input and amount (provided in the KernelArguments)
+    """
+
+    @kernel_function(name="Add")
+    def add(
+        self,
+        input: Annotated[int, "the first number to add"],
+        amount: Annotated[int, "the second number to add"],
+    ) -> Annotated[int, "the output is a number"]:
+        """Returns the Addition result of the values provided."""
+        if isinstance(input, str):
+            input = int(input)
+        if isinstance(amount, str):
+            amount = int(amount)
+        return MathPlugin.add_or_subtract(input, amount, add=True)
+
+    @kernel_function(name="Subtract")
+    def subtract(
+        self,
+        input: Annotated[int, "the first number"],
+        amount: Annotated[int, "the number to subtract"],
+    ) -> int:
+        """Returns the difference of numbers provided."""
+        if isinstance(input, str):
+            input = int(input)
+        if isinstance(amount, str):
+            amount = int(amount)
+        return MathPlugin.add_or_subtract(input, amount, add=False)
+
+    @staticmethod
+    def add_or_subtract(input: int, amount: int, add: bool) -> int:
+        """Helper function to perform addition or subtraction based on the add flag."""
+        return input + amount if add else input - amount

semantic_kernel-1.8.3/semantic_kernel/core_plugins/sessions_python_tool/README.md

@@ -0,0 +1,70 @@
+# Getting Started with the Sessions Python Plugin
+
+## Setup
+
+Please follow the [Azure Container Apps Documentation](https://learn.microsoft.com/en-us/azure/container-apps/sessions-code-interpreter) to get started.
+
+## Configuring the Python Plugin
+
+To successfully use the Python Plugin in Semantic Kernel, you must install the `azure` extras by running `uv sync --extra azure` or `pip install semantic-kernel[azure]`.
+
+Next, as an environment variable or in the .env file, add the `poolManagementEndpoint` value from above to the variable `ACA_POOL_MANAGEMENT_ENDPOINT`. The `poolManagementEndpoint` should look something like:
+
+```html
+https://eastus.acasessions.io/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/sessionPools/{{sessionPool}}/python/execute
+```
+
+It is possible to add the code interpreter plugin as follows:
+
+```python
+kernel = Kernel()
+
+service_id = "azure_oai"
+chat_service = AzureChatCompletion(
+    service_id=service_id, **azure_openai_settings_from_dot_env_as_dict(include_api_version=True)
+)
+kernel.add_service(chat_service)
+
+python_code_interpreter = SessionsPythonTool(
+    auth_callback=auth_callback
+)
+
+sessions_tool = kernel.add_plugin(python_code_interpreter, "PythonCodeInterpreter")
+
+code = "import json\n\ndef add_numbers(a, b):\n    return a + b\n\nargs = '{\"a\": 1, \"b\": 1}'\nargs_dict = json.loads(args)\nprint(add_numbers(args_dict['a'], args_dict['b']))"
+result = await kernel.invoke(sessions_tool["execute_code"], code=code)
+
+print(result)
+```
+
+Instead of hard-coding a well-formatted Python code string, you may use automatic function calling inside of SK and allow the model to form the Python and call the plugin.
+
+The authentication callback must return a valid token for the session pool. One possible way of doing this with a `DefaultAzureCredential` is as follows:
+
+```python
+async def auth_callback() -> str:
+    """Auth callback for the SessionsPythonTool.
+    This is a sample auth callback that shows how to use Azure's DefaultAzureCredential
+    to get an access token.
+    """
+    global auth_token
+    current_utc_timestamp = int(datetime.datetime.now(datetime.timezone.utc).timestamp())
+
+    if not auth_token or auth_token.expires_on < current_utc_timestamp:
+        credential = DefaultAzureCredential()
+
+        try:
+            auth_token = credential.get_token(ACA_TOKEN_ENDPOINT)
+        except ClientAuthenticationError as cae:
+            err_messages = getattr(cae, "messages", [])
+            raise FunctionExecutionException(
+                f"Failed to retrieve the client auth token with messages: {' '.join(err_messages)}"
+            ) from cae
+
+    return auth_token.token
+```
+
+Currently, there are two concept examples that show this plugin in more detail:
+
+- [Plugin example](../../../samples/concepts/plugins/azure_python_code_interpreter.py): shows the basic usage of calling the code execute function on the plugin.
+- [Function Calling example](../../../samples/concepts/auto_function_calling/azure_python_code_interpreter_function_calling.py): shows a simple chat application that leverages the Python code interpreter plugin for function calling.

semantic_kernel-1.8.3/semantic_kernel/core_plugins/sessions_python_tool/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.core_plugins.sessions_python_tool.sessions_python_plugin import (
+    SessionsPythonTool,
+)
+from semantic_kernel.core_plugins.sessions_python_tool.sessions_python_settings import (
+    SessionsPythonSettings,
+)
+
+__all__ = ["SessionsPythonSettings", "SessionsPythonTool"]

semantic_kernel-1.8.3/semantic_kernel/core_plugins/sessions_python_tool/sessions_python_plugin.py

@@ -0,0 +1,322 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+import os
+import re
+from collections.abc import Awaitable, Callable
+from io import BytesIO
+from typing import Annotated, Any
+
+from httpx import AsyncClient, HTTPStatusError
+from pydantic import ValidationError
+
+from semantic_kernel.const import USER_AGENT
+from semantic_kernel.core_plugins.sessions_python_tool.sessions_python_settings import (
+    ACASessionsSettings,
+    SessionsPythonSettings,
+)
+from semantic_kernel.core_plugins.sessions_python_tool.sessions_remote_file_metadata import SessionsRemoteFileMetadata
+from semantic_kernel.exceptions.function_exceptions import FunctionExecutionException, FunctionInitializationError
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.kernel_pydantic import HttpsUrl, KernelBaseModel
+from semantic_kernel.utils.telemetry.user_agent import HTTP_USER_AGENT, version_info
+
+logger = logging.getLogger(__name__)
+
+
+SESSIONS_USER_AGENT = f"{HTTP_USER_AGENT}/{version_info} (Language=Python)"
+
+SESSIONS_API_VERSION = "2024-02-02-preview"
+
+
+class SessionsPythonTool(KernelBaseModel):
+    """A plugin for running Python code in an Azure Container Apps dynamic sessions code interpreter."""
+
+    pool_management_endpoint: HttpsUrl
+    settings: SessionsPythonSettings
+    auth_callback: Callable[..., Awaitable[Any]]
+    http_client: AsyncClient
+
+    def __init__(
+        self,
+        auth_callback: Callable[..., Awaitable[Any]],
+        pool_management_endpoint: str | None = None,
+        settings: SessionsPythonSettings | None = None,
+        http_client: AsyncClient | None = None,
+        env_file_path: str | None = None,
+        **kwargs,
+    ):
+        """Initializes a new instance of the SessionsPythonTool class."""
+        try:
+            aca_settings = ACASessionsSettings.create(
+                env_file_path=env_file_path, pool_management_endpoint=pool_management_endpoint
+            )
+        except ValidationError as e:
+            logger.error(f"Failed to load the ACASessionsSettings with message: {e!s}")
+            raise FunctionInitializationError(f"Failed to load the ACASessionsSettings with message: {e!s}") from e
+
+        if not settings:
+            settings = SessionsPythonSettings()
+
+        if not http_client:
+            http_client = AsyncClient()
+
+        super().__init__(
+            pool_management_endpoint=aca_settings.pool_management_endpoint,
+            settings=settings,
+            auth_callback=auth_callback,
+            http_client=http_client,
+            **kwargs,
+        )
+
+    # region Helper Methods
+    async def _ensure_auth_token(self) -> str:
+        """Ensure the auth token is valid."""
+        try:
+            auth_token = await self.auth_callback()
+        except Exception as e:
+            logger.error(f"Failed to retrieve the client auth token with message: {e!s}")
+            raise FunctionExecutionException(f"Failed to retrieve the client auth token with messages: {e!s}") from e
+
+        return auth_token
+
+    def _sanitize_input(self, code: str) -> str:
+        """Sanitize input to the python REPL.
+
+        Remove whitespace, backtick & python (if llm mistakes python console as terminal).
+
+        Args:
+            code (str): The query to sanitize
+        Returns:
+            str: The sanitized query
+        """
+        # Removes `, whitespace & python from start
+        code = re.sub(r"^(\s|`)*(?i:python)?\s*", "", code)
+        # Removes whitespace & ` from end
+        return re.sub(r"(\s|`)*$", "", code)
+
+    def _construct_remote_file_path(self, remote_file_path: str) -> str:
+        """Construct the remote file path.
+
+        Args:
+            remote_file_path (str): The remote file path.
+
+        Returns:
+            str: The remote file path.
+        """
+        if not remote_file_path.startswith("/mnt/data/"):
+            remote_file_path = f"/mnt/data/{remote_file_path}"
+        return remote_file_path
+
+    def _build_url_with_version(self, base_url, endpoint, params):
+        """Builds a URL with the provided base URL, endpoint, and query parameters."""
+        params["api-version"] = SESSIONS_API_VERSION
+        query_string = "&".join([f"{key}={value}" for key, value in params.items()])
+        if not base_url.endswith("/"):
+            base_url += "/"
+        if endpoint.endswith("/"):
+            endpoint = endpoint[:-1]
+        return f"{base_url}{endpoint}?{query_string}"
+
+    # endregion
+
+    # region Kernel Functions
+    @kernel_function(
+        description="""Executes the provided Python code.
+                     Start and end the code snippet with double quotes to define it as a string.
+                     Insert \\n within the string wherever a new line should appear.
+                     Add spaces directly after \\n sequences to replicate indentation.
+                     Use \" to include double quotes within the code without ending the string.
+                     Keep everything in a single line; the \\n sequences will represent line breaks
+                     when the string is processed or displayed.
+                     """,
+        name="execute_code",
+    )
+    async def execute_code(self, code: Annotated[str, "The valid Python code to execute"]) -> str:
+        """Executes the provided Python code.
+
+        Args:
+            code (str): The valid Python code to execute
+        Returns:
+            str: The result of the Python code execution in the form of Result, Stdout, and Stderr
+        Raises:
+            FunctionExecutionException: If the provided code is empty.
+        """
+        if not code:
+            raise FunctionExecutionException("The provided code is empty")
+
+        if self.settings.sanitize_input:
+            code = self._sanitize_input(code)
+
+        auth_token = await self._ensure_auth_token()
+
+        logger.info(f"Executing Python code: {code}")
+
+        self.http_client.headers.update(
+            {
+                "Authorization": f"Bearer {auth_token}",
+                "Content-Type": "application/json",
+                USER_AGENT: SESSIONS_USER_AGENT,
+            }
+        )
+
+        self.settings.python_code = code
+
+        request_body = {
+            "properties": self.settings.model_dump(exclude_none=True, exclude={"sanitize_input"}, by_alias=True),
+        }
+
+        url = self._build_url_with_version(
+            base_url=str(self.pool_management_endpoint),
+            endpoint="code/execute/",
+            params={"identifier": self.settings.session_id},
+        )
+
+        try:
+            response = await self.http_client.post(
+                url=url,
+                json=request_body,
+            )
+            response.raise_for_status()
+            result = response.json()["properties"]
+            return f"Result:\n{result['result']}Stdout:\n{result['stdout']}Stderr:\n{result['stderr']}"
+        except HTTPStatusError as e:
+            error_message = e.response.text if e.response.text else e.response.reason_phrase
+            raise FunctionExecutionException(
+                f"Code execution failed with status code {e.response.status_code} and error: {error_message}"
+            ) from e
+
+    @kernel_function(name="upload_file", description="Uploads a file for the current Session ID")
+    async def upload_file(
+        self,
+        *,
+        local_file_path: Annotated[str, "The path to the local file on the machine"],
+        remote_file_path: Annotated[
+            str | None, "The remote path to the file in the session. Defaults to /mnt/data"
+        ] = None,
+    ) -> Annotated[SessionsRemoteFileMetadata, "The metadata of the uploaded file"]:
+        """Upload a file to the session pool.
+
+        Args:
+            remote_file_path (str): The path to the file in the session.
+            local_file_path (str): The path to the file on the local machine.
+
+        Returns:
+            RemoteFileMetadata: The metadata of the uploaded file.
+
+        Raises:
+            FunctionExecutionException: If local_file_path is not provided.
+        """
+        if not local_file_path:
+            raise FunctionExecutionException("Please provide a local file path to upload.")
+
+        remote_file_path = self._construct_remote_file_path(remote_file_path or os.path.basename(local_file_path))
+
+        auth_token = await self._ensure_auth_token()
+        self.http_client.headers.update(
+            {
+                "Authorization": f"Bearer {auth_token}",
+                USER_AGENT: SESSIONS_USER_AGENT,
+            }
+        )
+
+        url = self._build_url_with_version(
+            base_url=str(self.pool_management_endpoint),
+            endpoint="files/upload",
+            params={"identifier": self.settings.session_id},
+        )
+
+        try:
+            with open(local_file_path, "rb") as data:
+                files = {"file": (remote_file_path, data, "application/octet-stream")}
+                response = await self.http_client.post(url=url, files=files)
+                response.raise_for_status()
+                response_json = response.json()
+                return SessionsRemoteFileMetadata.from_dict(response_json["value"][0]["properties"])
+        except HTTPStatusError as e:
+            error_message = e.response.text if e.response.text else e.response.reason_phrase
+            raise FunctionExecutionException(
+                f"Upload failed with status code {e.response.status_code} and error: {error_message}"
+            ) from e
+
+    @kernel_function(name="list_files", description="Lists all files in the provided Session ID")
+    async def list_files(self) -> list[SessionsRemoteFileMetadata]:
+        """List the files in the session pool.
+
+        Returns:
+            list[SessionsRemoteFileMetadata]: The metadata for the files in the session pool
+        """
+        auth_token = await self._ensure_auth_token()
+        self.http_client.headers.update(
+            {
+                "Authorization": f"Bearer {auth_token}",
+                USER_AGENT: SESSIONS_USER_AGENT,
+            }
+        )
+
+        url = self._build_url_with_version(
+            base_url=str(self.pool_management_endpoint),
+            endpoint="files",
+            params={"identifier": self.settings.session_id},
+        )
+
+        try:
+            response = await self.http_client.get(
+                url=url,
+            )
+            response.raise_for_status()
+            response_json = response.json()
+            return [SessionsRemoteFileMetadata.from_dict(entry["properties"]) for entry in response_json["value"]]
+        except HTTPStatusError as e:
+            error_message = e.response.text if e.response.text else e.response.reason_phrase
+            raise FunctionExecutionException(
+                f"List files failed with status code {e.response.status_code} and error: {error_message}"
+            ) from e
+
+    async def download_file(
+        self,
+        *,
+        remote_file_name: Annotated[str, "The name of the file to download, relative to /mnt/data"],
+        local_file_path: Annotated[str | None, "The local file path to save the file to, optional"] = None,
+    ) -> Annotated[BytesIO | None, "The data of the downloaded file"]:
+        """Download a file from the session pool.
+
+        Args:
+            remote_file_name: The name of the file to download, relative to `/mnt/data`.
+            local_file_path: The path to save the downloaded file to. Should include the extension.
+                If not provided, the file is returned as a BufferedReader.
+
+        Returns:
+            BufferedReader: The data of the downloaded file.
+        """
+        auth_token = await self._ensure_auth_token()
+        self.http_client.headers.update(
+            {
+                "Authorization": f"Bearer {auth_token}",
+                USER_AGENT: SESSIONS_USER_AGENT,
+            }
+        )
+
+        url = self._build_url_with_version(
+            base_url=str(self.pool_management_endpoint),
+            endpoint=f"files/content/{remote_file_name}",
+            params={"identifier": self.settings.session_id},
+        )
+
+        try:
+            response = await self.http_client.get(
+                url=url,
+            )
+            response.raise_for_status()
+            if local_file_path:
+                with open(local_file_path, "wb") as f:
+                    f.write(response.content)
+                return None
+
+            return BytesIO(response.content)
+        except HTTPStatusError as e:
+            error_message = e.response.text if e.response.text else e.response.reason_phrase
+            raise FunctionExecutionException(
+                f"Download failed with status code {e.response.status_code} and error: {error_message}"
+            ) from e
+        # endregion

semantic_kernel-1.8.3/semantic_kernel/core_plugins/sessions_python_tool/sessions_python_settings.py

@@ -0,0 +1,62 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import re
+import uuid
+from enum import Enum
+from typing import ClassVar
+from urllib.parse import urlsplit, urlunsplit
+
+from pydantic import Field, field_validator
+
+from semantic_kernel.kernel_pydantic import HttpsUrl, KernelBaseModel, KernelBaseSettings
+
+
+class CodeInputType(str, Enum):
+    """Code input type."""
+
+    Inline = "inline"
+
+
+class CodeExecutionType(str, Enum):
+    """Code execution type."""
+
+    Synchronous = "synchronous"
+    # Asynchronous = "asynchronous" TODO: Enable when available
+
+
+class SessionsPythonSettings(KernelBaseModel):
+    """The Sessions Python code interpreter settings."""
+
+    session_id: str | None = Field(default_factory=lambda: str(uuid.uuid4()), alias="identifier", exclude=True)
+    code_input_type: CodeInputType | None = Field(default=CodeInputType.Inline, alias="codeInputType")
+    execution_type: CodeExecutionType | None = Field(default=CodeExecutionType.Synchronous, alias="executionType")
+    python_code: str | None = Field(alias="code", default=None)
+    timeout_in_sec: int | None = Field(default=100, alias="timeoutInSeconds")
+    sanitize_input: bool | None = Field(default=True, alias="sanitizeInput")
+
+
+class ACASessionsSettings(KernelBaseSettings):
+    """Azure Container Apps sessions settings.
+
+    Required:
+    - pool_management_endpoint: HttpsUrl - The URL of the Azure Container Apps pool management endpoint.
+        (Env var ACA_POOL_MANAGEMENT_ENDPOINT)
+    """
+
+    env_prefix: ClassVar[str] = "ACA_"
+
+    pool_management_endpoint: HttpsUrl
+
+    @field_validator("pool_management_endpoint", mode="before")
+    @classmethod
+    def _validate_endpoint(cls, endpoint: str) -> str:
+        """Validates the pool management endpoint."""
+        if "python/execute" in endpoint:
+            endpoint_parsed = urlsplit(endpoint.replace("python/execute", ""))._asdict()
+        else:
+            endpoint_parsed = urlsplit(endpoint)._asdict()
+        if endpoint_parsed["path"]:
+            endpoint_parsed["path"] = re.sub("/{2,}", "/", endpoint_parsed["path"])
+        else:
+            endpoint_parsed["path"] = "/"
+        return str(urlunsplit(endpoint_parsed.values()))

semantic_kernel-1.8.3/semantic_kernel/core_plugins/sessions_python_tool/sessions_remote_file_metadata.py

@@ -0,0 +1,35 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import Any
+
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class SessionsRemoteFileMetadata(KernelBaseModel):
+    """Metadata for a file in the session."""
+
+    """The filename relative to `/mnt/data/`."""
+    filename: str
+
+    """The size of the file in bytes."""
+    size_in_bytes: int
+
+    @property
+    def full_path(self) -> str:
+        """Get the full path of the file."""
+        if not self.filename.startswith("/mnt/data/"):
+            return f"/mnt/data/{self.filename}"
+        return self.filename
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> "SessionsRemoteFileMetadata":
+        """Create a SessionsRemoteFileMetadata object from a dictionary of file data values.
+        
+        Args:
+            data (dict[str, Any]): The file data values.
+
+        Returns:
+            SessionsRemoteFileMetadata: The metadata for the file.
+        """
+        return SessionsRemoteFileMetadata(filename=data["filename"], size_in_bytes=data["size"])
+