semantic-kernel 1.8.3__zip

semantic_kernel-1.8.3/semantic_kernel/core_plugins/text_memory_plugin.py

@@ -0,0 +1,96 @@
+# Copyright (c) Microsoft. All rights reserved.
+import json
+import logging
+from typing import Annotated, Any, Final
+
+from pydantic import Field
+
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.memory.semantic_text_memory_base import SemanticTextMemoryBase
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+DEFAULT_COLLECTION: Final[str] = "generic"
+COLLECTION_PARAM: Final[str] = "collection"
+DEFAULT_RELEVANCE: Final[float] = 0.75
+RELEVANCE_PARAM: Final[str] = "relevance"
+DEFAULT_LIMIT: Final[int] = 1
+
+
+class TextMemoryPlugin(KernelBaseModel):
+    """A plugin to interact with a Semantic Text Memory."""
+
+    memory: SemanticTextMemoryBase
+    embeddings_kwargs: dict[str, Any] = Field(default_factory=dict)
+
+    def __init__(self, memory: SemanticTextMemoryBase, embeddings_kwargs: dict[str, Any] = {}) -> None:
+        """Initialize a new instance of the TextMemoryPlugin.
+
+        Args:
+            memory (SemanticTextMemoryBase): the underlying Semantic Text Memory to use
+            embeddings_kwargs (Optional[Dict[str, Any]]): the keyword arguments to pass to the embedding generator
+        """
+        super().__init__(memory=memory, embeddings_kwargs=embeddings_kwargs)
+
+    @kernel_function(
+        description="Recall a fact from the long term memory",
+        name="recall",
+    )
+    async def recall(
+        self,
+        ask: Annotated[str, "The information to retrieve"],
+        collection: Annotated[str, "The collection to search for information."] = DEFAULT_COLLECTION,
+        relevance: Annotated[
+            float, "The relevance score, from 0.0 to 1.0; 1.0 means perfect match"
+        ] = DEFAULT_RELEVANCE,
+        limit: Annotated[int, "The maximum number of relevant memories to recall."] = DEFAULT_LIMIT,
+    ) -> str:
+        """Recall a fact from the long term memory.
+
+        Example:
+            {{memory.recall $ask}} => "Paris"
+
+        Args:
+            ask: The question to ask the memory
+            collection: The collection to search for information
+            relevance: The relevance score, from 0.0 to 1.0; 1.0 means perfect match
+            limit: The maximum number of relevant memories to recall
+
+        Returns:
+            The nearest item from the memory store as a string or empty string if not found.
+        """
+        results = await self.memory.search(
+            collection=collection,
+            query=ask,
+            limit=limit,
+            min_relevance_score=relevance,
+        )
+        if results is None or len(results) == 0:
+            logger.warning(f"Memory not found in collection: {collection}")
+            return ""
+
+        return results[0].text if limit == 1 else json.dumps([r.text for r in results])  # type: ignore
+
+    @kernel_function(
+        description="Save information to semantic memory",
+        name="save",
+    )
+    async def save(
+        self,
+        text: Annotated[str, "The information to save."],
+        key: Annotated[str, "The unique key to associate with the information."],
+        collection: Annotated[str, "The collection to save the information."] = DEFAULT_COLLECTION,
+    ) -> None:
+        """Save a fact to the long term memory.
+
+        Args:
+            text: The text to save to the memory
+            kernel: The kernel instance, that has a memory store
+            collection: The collection to save the information
+            key: The unique key to associate with the information
+
+        """
+        await self.memory.save_information(
+            collection=collection, text=text, id=key, embeddings_kwargs=self.embeddings_kwargs
+        )

semantic_kernel-1.8.3/semantic_kernel/core_plugins/text_plugin.py

@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class TextPlugin(KernelBaseModel):
+    """TextPlugin provides a set of functions to manipulate strings.
+
+    Usage:
+        kernel.add_plugin(TextPlugin(), plugin_name="text")
+
+    Examples:
+        KernelArguments["input"] = "  hello world  "
+        {{text.trim $input}} => "hello world"
+
+        KernelArguments["input"] = "  hello world  "
+        {{text.trimStart $input}} => "hello world  "
+
+        KernelArguments["input"] = "  hello world  "
+        {{text.trimEnd $input}} => "  hello world"
+
+        KernelArguments["input"] = "hello world"
+        {{text.uppercase $input}} => "HELLO WORLD"
+
+        KernelArguments["input"] = "HELLO WORLD"
+        {{text.lowercase $input}} => "hello world"
+    """
+
+    @kernel_function(description="Trim whitespace from the start and end of a string.")
+    def trim(self, input: str) -> str:
+        """Trim whitespace from the start and end of a string.
+
+        Example:
+            KernelArguments["input"] = "  hello world  "
+            {{text.trim $input}} => "hello world"
+        """
+        return input.strip()
+
+    @kernel_function(description="Trim whitespace from the start of a string.")
+    def trim_start(self, input: str) -> str:
+        """Trim whitespace from the start of a string.
+
+        Example:
+             KernelArguments["input"] = "  hello world  "
+             {{input.trim $input}} => "hello world  "
+        """
+        return input.lstrip()
+
+    @kernel_function(description="Trim whitespace from the end of a string.")
+    def trim_end(self, input: str) -> str:
+        """Trim whitespace from the end of a string.
+
+        Example:
+             KernelArguments["input"] = "  hello world  "
+             {{input.trim $input}} => "  hello world"
+        """
+        return input.rstrip()
+
+    @kernel_function(description="Convert a string to uppercase.")
+    def uppercase(self, input: str) -> str:
+        """Convert a string to uppercase.
+
+        Example:
+            KernelArguments["input"] = "hello world"
+             {{input.uppercase $input}} => "HELLO WORLD"
+        """
+        return input.upper()
+
+    @kernel_function(description="Convert a string to lowercase.")
+    def lowercase(self, input: str) -> str:
+        """Convert a string to lowercase.
+
+        Example:
+             KernelArguments["input"] = "HELLO WORLD"
+             {{input.lowercase $input}} => "hello world"
+        """
+        return input.lower()

semantic_kernel-1.8.3/semantic_kernel/core_plugins/time_plugin.py

@@ -0,0 +1,242 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import datetime
+
+from semantic_kernel.exceptions import FunctionExecutionException
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class TimePlugin(KernelBaseModel):
+    """TimePlugin provides a set of functions to get the current time and date.
+
+    Usage:
+        kernel.add_plugin(TimePlugin(), plugin_name="time")
+
+    Examples:
+        {{time.date}}            => Sunday, 12 January, 2031
+        {{time.today}}           => Sunday, 12 January, 2031
+        {{time.iso_date}}        => 2031-01-12
+        {{time.now}}             => Sunday, January 12, 2031 9:15 PM
+        {{time.utcNow}}          => Sunday, January 13, 2031 5:15 AM
+        {{time.time}}            => 09:15:07 PM
+        {{time.year}}            => 2031
+        {{time.month}}           => January
+        {{time.monthNumber}}     => 01
+        {{time.day}}             => 12
+        {{time.dayOfWeek}}       => Sunday
+        {{time.hour}}            => 9 PM
+        {{time.hourNumber}}      => 21
+        {{time.days_ago $days}} => Sunday, 7 May, 2023
+        {{time.last_matching_day $dayName}} => Sunday, 7 May, 2023
+        {{time.minute}}          => 15
+        {{time.minutes}}         => 15
+        {{time.second}}          => 7
+        {{time.seconds}}         => 7
+        {{time.timeZoneOffset}}  => -0800
+        {{time.timeZoneName}}    => PST
+    """
+
+    @kernel_function(description="Get the current date.")
+    def date(self) -> str:
+        """Get the current date.
+
+        Example:
+            {{time.date}} => Sunday, 12 January, 2031
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%A, %d %B, %Y")
+
+    @kernel_function(description="Get the current date.")
+    def today(self) -> str:
+        """Get the current date.
+
+        Example:
+            {{time.today}} => Sunday, 12 January, 2031
+        """
+        return self.date()
+
+    @kernel_function(description="Get the current date in iso format.")
+    def iso_date(self) -> str:
+        """Get the current date in iso format.
+
+        Example:
+            {{time.iso_date}} => 2031-01-12
+        """
+        today = datetime.date.today()
+        return today.isoformat()
+
+    @kernel_function(description="Get the current date and time in the local time zone")
+    def now(self) -> str:
+        """Get the current date and time in the local time zone.
+
+        Example:
+            {{time.now}} => Sunday, January 12, 2031 9:15 PM
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%A, %B %d, %Y %I:%M %p")
+
+    @kernel_function(description="Get the current date and time in UTC", name="utcNow")
+    def utc_now(self) -> str:
+        """Get the current date and time in UTC.
+
+        Example:
+            {{time.utcNow}} => Sunday, January 13, 2031 5:15 AM
+        """
+        now = datetime.datetime.utcnow()
+        return now.strftime("%A, %B %d, %Y %I:%M %p")
+
+    @kernel_function(description="Get the current time in the local time zone")
+    def time(self) -> str:
+        """Get the current time in the local time zone.
+
+        Example:
+            {{time.time}} => 09:15:07 PM
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%I:%M:%S %p")
+
+    @kernel_function(description="Get the current year")
+    def year(self) -> str:
+        """Get the current year.
+
+        Example:
+            {{time.year}} => 2031
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%Y")
+
+    @kernel_function(description="Get the current month")
+    def month(self) -> str:
+        """Get the current month.
+
+        Example:
+            {{time.month}} => January
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%B")
+
+    @kernel_function(description="Get the current month number")
+    def month_number(self) -> str:
+        """Get the current month number.
+
+        Example:
+            {{time.monthNumber}} => 01
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%m")
+
+    @kernel_function(description="Get the current day")
+    def day(self) -> str:
+        """Get the current day of the month.
+
+        Example:
+            {{time.day}} => 12
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%d")
+
+    @kernel_function(description="Get the current day of the week", name="dayOfWeek")
+    def day_of_week(self) -> str:
+        """Get the current day of the week.
+
+        Example:
+            {{time.dayOfWeek}} => Sunday
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%A")
+
+    @kernel_function(description="Get the current hour")
+    def hour(self) -> str:
+        """Get the current hour.
+
+        Example:
+            {{time.hour}} => 9 PM
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%I %p")
+
+    @kernel_function(description="Get the current hour number", name="hourNumber")
+    def hour_number(self) -> str:
+        """Get the current hour number.
+
+        Example:
+            {{time.hourNumber}} => 21
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%H")
+
+    @kernel_function(description="Get the current minute")
+    def minute(self) -> str:
+        """Get the current minute.
+
+        Example:
+            {{time.minute}} => 15
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%M")
+
+    @kernel_function(description="Get the date of offset from today by a provided number of days")
+    def days_ago(self, days: str) -> str:
+        """Get the date a provided number of days in the past.
+
+        Args:
+            days: The number of days to offset from today
+        Returns:
+            The date of the offset day.
+
+        Example:
+             {{time.days_ago $input}} => Sunday, 7 May, 2023
+        """
+        d = datetime.date.today() - datetime.timedelta(days=int(days))
+        return d.strftime("%A, %d %B, %Y")
+
+    @kernel_function(description="""Get the date of the last day matching the supplied week day name in English.""")
+    def date_matching_last_day_name(self, day_name: str) -> str:
+        """Get the date of the last day matching the supplied day name.
+
+        Args:
+            day_name: The day name to match with.
+
+        Returns:
+            The date of the matching day.
+
+        Example:
+             {{time.date_matching_last_day_name $input}} => Sunday, 7 May, 2023
+        """
+        d = datetime.date.today()
+        for i in range(1, 8):
+            d = d - datetime.timedelta(days=1)
+            if d.strftime("%A") == day_name:
+                return d.strftime("%A, %d %B, %Y")
+        raise FunctionExecutionException("day_name is not recognized")
+
+    @kernel_function(description="Get the seconds on the current minute")
+    def second(self) -> str:
+        """Get the seconds on the current minute.
+
+        Example:
+            {{time.second}} => 7
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%S")
+
+    @kernel_function(description="Get the current time zone offset", name="timeZoneOffset")
+    def time_zone_offset(self) -> str:
+        """Get the current time zone offset.
+
+        Example:
+            {{time.timeZoneOffset}} => -08:00
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%z")
+
+    @kernel_function(description="Get the current time zone name", name="timeZoneName")
+    def time_zone_name(self) -> str:
+        """Get the current time zone name.
+
+        Example:
+            {{time.timeZoneName}} => PST
+        """
+        now = datetime.datetime.now()
+        return now.strftime("%Z")

semantic_kernel-1.8.3/semantic_kernel/core_plugins/wait_plugin.py

@@ -0,0 +1,29 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from semantic_kernel.exceptions import FunctionExecutionException
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+
+
+class WaitPlugin(KernelBaseModel):
+    """WaitPlugin provides a set of functions to wait for a certain amount of time.
+
+    Usage:
+        kernel.add_plugin(WaitPlugin(), plugin_name="wait")
+
+    Examples:
+        {{wait.wait 5}} => Wait for 5 seconds
+    """
+
+    @kernel_function
+    async def wait(self, input: Annotated[float | str, "The number of seconds to wait, can be str or float."]) -> None:
+        """Wait for a certain number of seconds."""
+        if isinstance(input, str):
+            try:
+                input = float(input)
+            except ValueError as exc:
+                raise FunctionExecutionException("seconds text must be a number") from exc
+        await asyncio.sleep(abs(input))

semantic_kernel-1.8.3/semantic_kernel/core_plugins/web_search_engine_plugin.py

@@ -0,0 +1,38 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import TYPE_CHECKING, Annotated
+
+from semantic_kernel.functions.kernel_function_decorator import kernel_function
+
+if TYPE_CHECKING:
+    from semantic_kernel.connectors.search_engine.connector import ConnectorBase
+
+
+class WebSearchEnginePlugin:
+    """A plugin that provides web search engine functionality.
+
+    Usage:
+        connector = BingConnector(bing_search_api_key)
+        kernel.add_plugin(WebSearchEnginePlugin(connector), plugin_name="WebSearch")
+
+    Examples:
+        {{WebSearch.search "What is semantic kernel?"}}
+        =>  Returns the first `num_results` number of results for the given search query
+            and ignores the first `offset` number of results.
+    """
+
+    _connector: "ConnectorBase"
+
+    def __init__(self, connector: "ConnectorBase") -> None:
+        """Initializes a new instance of the WebSearchEnginePlugin class."""
+        self._connector = connector
+
+    @kernel_function(name="search", description="Performs a web search for a given query")
+    async def search(
+        self,
+        query: Annotated[str, "The search query"],
+        num_results: Annotated[int, "The number of search results to return"] = 1,
+        offset: Annotated[int, "The number of search results to skip"] = 0,
+    ) -> list[str]:
+        """Returns the search results of the query provided."""
+        return await self._connector.search(query, num_results, offset)

semantic_kernel-1.8.3/semantic_kernel/data/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from semantic_kernel.data.const import DistanceFunction, IndexKind
+from semantic_kernel.data.vector_store import VectorStore
+from semantic_kernel.data.vector_store_model_decorator import vectorstoremodel
+from semantic_kernel.data.vector_store_model_definition import (
+    VectorStoreRecordDefinition,
+)
+from semantic_kernel.data.vector_store_record_collection import VectorStoreRecordCollection
+from semantic_kernel.data.vector_store_record_fields import (
+    VectorStoreRecordDataField,
+    VectorStoreRecordKeyField,
+    VectorStoreRecordVectorField,
+)
+from semantic_kernel.data.vector_store_record_utils import VectorStoreRecordUtils
+
+__all__ = [
+    "DistanceFunction",
+    "IndexKind",
+    "VectorStore",
+    "VectorStoreRecordCollection",
+    "VectorStoreRecordDataField",
+    "VectorStoreRecordDefinition",
+    "VectorStoreRecordKeyField",
+    "VectorStoreRecordUtils",
+    "VectorStoreRecordVectorField",
+    "vectorstoremodel",
+]

semantic_kernel-1.8.3/semantic_kernel/data/const.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+
+from enum import Enum
+
+
+class IndexKind(str, Enum):
+    """Index kinds for similarity search."""
+
+    HNSW = "hnsw"
+    FLAT = "flat"
+
+
+class DistanceFunction(str, Enum):
+    """Distance functions for similarity search."""
+
+    COSINE = "cosine"
+    DOT_PROD = "dot_prod"
+    EUCLIDEAN = "euclidean"
+    MANHATTAN = "manhattan"

semantic_kernel-1.8.3/semantic_kernel/data/vector_store.py

@@ -0,0 +1,36 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+
+from abc import abstractmethod
+from collections.abc import Sequence
+from typing import Any
+
+from pydantic import Field
+
+from semantic_kernel.data.vector_store_model_definition import VectorStoreRecordDefinition
+from semantic_kernel.data.vector_store_record_collection import VectorStoreRecordCollection
+from semantic_kernel.kernel_pydantic import KernelBaseModel
+from semantic_kernel.utils.experimental_decorator import experimental_class
+
+
+@experimental_class
+class VectorStore(KernelBaseModel):
+    """Base class for vector stores."""
+
+    vector_record_collections: dict[str, VectorStoreRecordCollection] = Field(default_factory=dict)
+
+    @abstractmethod
+    def get_collection(
+        self,
+        collection_name: str,
+        data_model_type: type[object],
+        data_model_definition: VectorStoreRecordDefinition | None = None,
+        **kwargs: Any,
+    ) -> VectorStoreRecordCollection:
+        """Get a vector record store."""
+        ...  # pragma: no cover
+
+    @abstractmethod
+    async def list_collection_names(self, **kwargs) -> Sequence[str]:
+        """Get the names of all collections."""
+        ...  # pragma: no cover

semantic_kernel-1.8.3/semantic_kernel/data/vector_store_model_decorator.py

@@ -0,0 +1,117 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from inspect import _empty, signature
+from types import NoneType
+from typing import Any
+
+from semantic_kernel.data.vector_store_model_definition import VectorStoreRecordDefinition
+from semantic_kernel.data.vector_store_record_fields import VectorStoreRecordField, VectorStoreRecordVectorField
+from semantic_kernel.exceptions.memory_connector_exceptions import VectorStoreModelException
+
+logger = logging.getLogger(__name__)
+
+
+def vectorstoremodel(
+    cls: Any | None = None,
+):
+    """Returns the class as a vector store model.
+
+    This decorator makes a class a vector store model.
+    There are three things being checked:
+    - The class must have at least one field with a annotation,
+        of type VectorStoreRecordKeyField, VectorStoreRecordDataField or VectorStoreRecordVectorField.
+    - The class must have exactly one field with the VectorStoreRecordKeyField annotation.
+
+    Optionally, when there are VectorStoreRecordDataFields that specify a embedding property name,
+    there must be a corresponding VectorStoreRecordVectorField with the same name.
+
+    Args:
+        cls: The class to be decorated.
+
+    Raises:
+        DataModelException: If the class does not implement the serialize and deserialize methods.
+        DataModelException: If there are no fields with a VectorStoreRecordField annotation.
+        DataModelException: If there are fields with no name.
+        DataModelException: If there is no key field.
+        DataModelException: If there is a field with an embedding property name but no corresponding vector field.
+    """
+
+    def wrap(cls: Any):
+        # get fields and annotations
+        cls_sig = signature(cls)
+        setattr(cls, "__kernel_vectorstoremodel__", True)
+        setattr(cls, "__kernel_vectorstoremodel_definition__", _parse_signature_to_definition(cls_sig.parameters))
+
+        return cls
+
+    # See if we're being called as @vectorstoremodel or @vectorstoremodel().
+    if cls is None:
+        # We're called with parens.
+        return wrap
+
+    # We're called as @vectorstoremodel without parens.
+    return wrap(cls)
+
+
+def _parse_signature_to_definition(parameters) -> VectorStoreRecordDefinition:
+    if len(parameters) == 0:
+        raise VectorStoreModelException(
+            "There must be at least one field in the datamodel. If you are using this with a @dataclass, "
+            "you might have inverted the order of the decorators, the vectorstoremodel decorator should be the top one."
+        )
+    fields: dict[str, VectorStoreRecordField] = {}
+    for field in parameters.values():
+        annotation = field.annotation
+        # check first if there are any annotations
+        if not hasattr(annotation, "__metadata__"):
+            if field._default is _empty:
+                raise VectorStoreModelException(
+                    "Fields that do not have a VectorStoreRecord* annotation must have a default value."
+                )
+            logger.info(
+                f'Field "{field.name}" does not have a VectorStoreRecord* '
+                "annotation, will not be part of the record."
+            )
+            continue
+        property_type = annotation.__origin__
+        if (args := getattr(property_type, "__args__", None)) and NoneType in args and len(args) == 2:
+            property_type = args[0]
+        metadata = annotation.__metadata__
+        field_type = None
+        for item in metadata:
+            if isinstance(item, VectorStoreRecordField):
+                field_type = item
+                if not field_type.name or field_type.name != field.name:
+                    field_type.name = field.name
+                if not field_type.property_type:
+                    if hasattr(property_type, "__args__"):
+                        if isinstance(item, VectorStoreRecordVectorField):
+                            field_type.property_type = property_type.__args__[0].__name__
+                        elif property_type.__name__ == "list":
+                            field_type.property_type = f"{property_type.__name__}[{property_type.__args__[0].__name__}]"
+                        else:
+                            field_type.property_type = property_type.__name__
+
+                    else:
+                        field_type.property_type = property_type.__name__
+            elif isinstance(item, type(VectorStoreRecordField)):
+                if hasattr(property_type, "__args__") and property_type.__name__ == "list":
+                    property_type_name = f"{property_type.__name__}[{property_type.__args__[0].__name__}]"
+                else:
+                    property_type_name = property_type.__name__
+                field_type = item(name=field.name, property_type=property_type_name)
+        if not field_type:
+            if field._default is _empty:
+                raise VectorStoreModelException(
+                    "Fields that do not have a VectorStoreRecord* annotation must have a default value."
+                )
+            logger.debug(
+                f'Field "{field.name}" does not have a VectorStoreRecordField '
+                "annotation, will not be part of the record."
+            )
+            continue
+        # field name is set either when not None or by instantiating a new field
+        assert field_type.name is not None  # nosec
+        fields[field_type.name] = field_type
+    return VectorStoreRecordDefinition(fields=fields)