semantic-kernel 0.3.0.dev0__py3-none-any.whl → 0.3.2.dev0__py3-none-any.whl

semantic_kernel/connectors/memory/pinecone/pinecone_memory_store.py

@@ -0,0 +1,401 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from logging import Logger
+from typing import List, Optional, Tuple
+
+from numpy import ndarray
+
+import pinecone
+from pinecone import FetchResponse, IndexDescription
+from semantic_kernel.connectors.memory.pinecone.utils import (
+    build_payload,
+    parse_payload,
+)
+from semantic_kernel.memory.memory_record import MemoryRecord
+from semantic_kernel.memory.memory_store_base import MemoryStoreBase
+from semantic_kernel.utils.null_logger import NullLogger
+
+# Limitations set by Pinecone at https://docs.pinecone.io/docs/limits
+MAX_DIMENSIONALITY = 20000
+MAX_UPSERT_BATCH_SIZE = 100
+MAX_QUERY_WITHOUT_METADATA_BATCH_SIZE = 10000
+MAX_QUERY_WITH_METADATA_BATCH_SIZE = 1000
+MAX_FETCH_BATCH_SIZE = 1000
+MAX_DELETE_BATCH_SIZE = 1000
+
+
+class PineconeMemoryStore(MemoryStoreBase):
+    _logger: Logger
+    _pinecone_api_key: str
+    _pinecone_environment: str
+    _default_dimensionality: int
+
+    def __init__(
+        self,
+        api_key: str,
+        environment: str,
+        default_dimensionality: int,
+        logger: Optional[Logger] = None,
+    ) -> None:
+        """Initializes a new instance of the PineconeMemoryStore class.
+
+        Arguments:
+            pinecone_api_key {str} -- The Pinecone API key.
+            pinecone_environment {str} -- The Pinecone environment.
+            logger {Optional[Logger]} -- The logger to use. (default: {None})
+            default_dimensionality {int} -- The default dimensionality to use for new collections.
+        """
+        if default_dimensionality > MAX_DIMENSIONALITY:
+            raise ValueError(
+                f"Dimensionality of {default_dimensionality} exceeds "
+                + f"the maximum allowed value of {MAX_DIMENSIONALITY}."
+            )
+        self._pinecone_api_key = api_key
+        self._pinecone_environment = environment
+        self._default_dimensionality = default_dimensionality
+        self._logger = logger or NullLogger()
+
+        pinecone.init(
+            api_key=self._pinecone_api_key, environment=self._pinecone_environment
+        )
+
+    def get_collections(self) -> List[str]:
+        return pinecone.list_indexes()
+
+    async def create_collection_async(
+        self,
+        collection_name: str,
+        dimension_num: Optional[int] = None,
+        distance_type: Optional[str] = "cosine",
+        num_of_pods: Optional[int] = 1,
+        replica_num: Optional[int] = 0,
+        type_of_pod: Optional[str] = "p1.x1",
+        metadata_config: Optional[dict] = None,
+    ) -> None:
+        """Creates a new collection in Pinecone if it does not exist.
+            This function creates an index, by default the following index
+            settings are used: metric = cosine, pods = 1, replicas = 0,
+            pod_type = p1.x1, metadata_config = None.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to create.
+            In Pinecone, a collection is represented as an index. The concept
+            of "collection" in Pinecone is just a static copy of an index.
+
+        Returns:
+            None
+        """
+        if dimension_num is None:
+            dimension_num = self._default_dimensionality
+        if dimension_num > MAX_DIMENSIONALITY:
+            raise ValueError(
+                f"Dimensionality of {dimension_num} exceeds "
+                + f"the maximum allowed value of {MAX_DIMENSIONALITY}."
+            )
+
+        if collection_name not in pinecone.list_indexes():
+            pinecone.create_index(
+                name=collection_name,
+                dimension=dimension_num,
+                metric=distance_type,
+                pods=num_of_pods,
+                replicas=replica_num,
+                pod_type=type_of_pod,
+                metadata_config=metadata_config,
+            )
+
+    async def describe_collection_async(
+        self, collection_name: str
+    ) -> Optional[IndexDescription]:
+        """Gets the description of the index.
+        Arguments:
+            collection_name {str} -- The name of the index to get.
+        Returns:
+            Optional[dict] -- The index.
+        """
+        if collection_name in pinecone.list_indexes():
+            return pinecone.describe_index(collection_name)
+        return None
+
+    async def get_collections_async(
+        self,
+    ) -> List[str]:
+        """Gets the list of collections.
+
+        Returns:
+            List[str] -- The list of collections.
+        """
+        return list(pinecone.list_indexes())
+
+    async def delete_collection_async(self, collection_name: str) -> None:
+        """Deletes a collection.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to delete.
+
+        Returns:
+            None
+        """
+        if collection_name in pinecone.list_indexes():
+            pinecone.delete_index(collection_name)
+
+    async def does_collection_exist_async(self, collection_name: str) -> bool:
+        """Checks if a collection exists.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to check.
+
+        Returns:
+            bool -- True if the collection exists; otherwise, False.
+        """
+        return collection_name in pinecone.list_indexes()
+
+    async def upsert_async(self, collection_name: str, record: MemoryRecord) -> str:
+        """Upserts a record.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to upsert the record into.
+            record {MemoryRecord} -- The record to upsert.
+
+        Returns:
+            str -- The unique database key of the record. In Pinecone, this is the record ID.
+        """
+        if collection_name not in pinecone.list_indexes():
+            raise Exception(f"Collection '{collection_name}' does not exist")
+
+        collection = pinecone.Index(collection_name)
+
+        upsert_response = collection.upsert(
+            vectors=[(record._id, record.embedding.tolist(), build_payload(record))],
+            namespace="",
+        )
+
+        if upsert_response.upserted_count is None:
+            raise Exception(f"Error upserting record: {upsert_response.message}")
+
+        return record._id
+
+    async def upsert_batch_async(
+        self, collection_name: str, records: List[MemoryRecord]
+    ) -> List[str]:
+        """Upserts a batch of records.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to upsert the records into.
+            records {List[MemoryRecord]} -- The records to upsert.
+
+        Returns:
+            List[str] -- The unique database keys of the records.
+        """
+        if collection_name not in pinecone.list_indexes():
+            raise Exception(f"Collection '{collection_name}' does not exist")
+
+        collection = pinecone.Index(collection_name)
+
+        vectors = [
+            (
+                record._id,
+                record.embedding.tolist(),
+                build_payload(record),
+            )
+            for record in records
+        ]
+
+        upsert_response = collection.upsert(
+            vectors, namespace="", batch_size=MAX_UPSERT_BATCH_SIZE
+        )
+
+        if upsert_response.upserted_count is None:
+            raise Exception(f"Error upserting record: {upsert_response.message}")
+        else:
+            return [record._id for record in records]
+
+    async def get_async(
+        self, collection_name: str, key: str, with_embedding: bool = False
+    ) -> MemoryRecord:
+        """Gets a record.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to get the record from.
+            key {str} -- The unique database key of the record.
+            with_embedding {bool} -- Whether to include the embedding in the result. (default: {False})
+
+        Returns:
+            MemoryRecord -- The record.
+        """
+        if collection_name not in pinecone.list_indexes():
+            raise Exception(f"Collection '{collection_name}' does not exist")
+
+        collection = pinecone.Index(collection_name)
+        fetch_response = collection.fetch([key])
+
+        if len(fetch_response.vectors) == 0:
+            raise KeyError(f"Record with key '{key}' does not exist")
+
+        return parse_payload(fetch_response.vectors[key], with_embedding)
+
+    async def get_batch_async(
+        self, collection_name: str, keys: List[str], with_embeddings: bool = False
+    ) -> List[MemoryRecord]:
+        """Gets a batch of records.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to get the records from.
+            keys {List[str]} -- The unique database keys of the records.
+            with_embeddings {bool} -- Whether to include the embeddings in the results. (default: {False})
+
+        Returns:
+            List[MemoryRecord] -- The records.
+        """
+        if collection_name not in pinecone.list_indexes():
+            raise Exception(f"Collection '{collection_name}' does not exist")
+
+        fetch_response = await self.__get_batch_async(
+            collection_name, keys, with_embeddings
+        )
+        return [
+            parse_payload(fetch_response.vectors[key], with_embeddings)
+            for key in fetch_response.vectors.keys()
+        ]
+
+    async def remove_async(self, collection_name: str, key: str) -> None:
+        """Removes a record.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to remove the record from.
+            key {str} -- The unique database key of the record to remove.
+
+        Returns:
+            None
+        """
+        if collection_name not in pinecone.list_indexes():
+            raise Exception(f"Collection '{collection_name}' does not exist")
+
+        collection = pinecone.Index(collection_name)
+        collection.delete([key])
+
+    async def remove_batch_async(self, collection_name: str, keys: List[str]) -> None:
+        """Removes a batch of records.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to remove the records from.
+            keys {List[str]} -- The unique database keys of the records to remove.
+
+        Returns:
+            None
+        """
+        if collection_name not in pinecone.list_indexes():
+            raise Exception(f"Collection '{collection_name}' does not exist")
+
+        collection = pinecone.Index(collection_name)
+        for i in range(0, len(keys), MAX_DELETE_BATCH_SIZE):
+            collection.delete(keys[i : i + MAX_DELETE_BATCH_SIZE])
+        collection.delete(keys)
+
+    async def get_nearest_match_async(
+        self,
+        collection_name: str,
+        embedding: ndarray,
+        min_relevance_score: float = 0.0,
+        with_embedding: bool = False,
+    ) -> Tuple[MemoryRecord, float]:
+        """Gets the nearest match to an embedding using cosine similarity.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to get the nearest match from.
+            embedding {ndarray} -- The embedding to find the nearest match to.
+            min_relevance_score {float} -- The minimum relevance score of the match. (default: {0.0})
+            with_embedding {bool} -- Whether to include the embedding in the result. (default: {False})
+
+        Returns:
+            Tuple[MemoryRecord, float] -- The record and the relevance score.
+        """
+        matches = await self.get_nearest_matches_async(
+            collection_name=collection_name,
+            embedding=embedding,
+            limit=1,
+            min_relevance_score=min_relevance_score,
+            with_embeddings=with_embedding,
+        )
+        return matches[0]
+
+    async def get_nearest_matches_async(
+        self,
+        collection_name: str,
+        embedding: ndarray,
+        limit: int,
+        min_relevance_score: float = 0.0,
+        with_embeddings: bool = False,
+    ) -> List[Tuple[MemoryRecord, float]]:
+        """Gets the nearest matches to an embedding using cosine similarity.
+
+        Arguments:
+            collection_name {str} -- The name of the collection to get the nearest matches from.
+            embedding {ndarray} -- The embedding to find the nearest matches to.
+            limit {int} -- The maximum number of matches to return.
+            min_relevance_score {float} -- The minimum relevance score of the matches. (default: {0.0})
+            with_embeddings {bool} -- Whether to include the embeddings in the results. (default: {False})
+
+        Returns:
+            List[Tuple[MemoryRecord, float]] -- The records and their relevance scores.
+        """
+        if collection_name not in pinecone.list_indexes():
+            raise Exception(f"Collection '{collection_name}' does not exist")
+
+        collection = pinecone.Index(collection_name)
+
+        if limit > MAX_QUERY_WITHOUT_METADATA_BATCH_SIZE:
+            raise Exception(
+                "Limit must be less than or equal to "
+                + f"{MAX_QUERY_WITHOUT_METADATA_BATCH_SIZE}"
+            )
+        elif limit > MAX_QUERY_WITH_METADATA_BATCH_SIZE:
+            query_response = collection.query(
+                vector=embedding.tolist(),
+                top_k=limit,
+                include_values=False,
+                include_metadata=False,
+            )
+            keys = [match.id for match in query_response.matches]
+            fetch_response = await self.__get_batch_async(
+                collection_name, keys, with_embeddings
+            )
+            vectors = fetch_response.vectors
+            for match in query_response.matches:
+                vectors[match.id].update(match)
+            matches = [vectors[key] for key in vectors.keys()]
+        else:
+            query_response = collection.query(
+                vector=embedding.tolist(),
+                top_k=limit,
+                include_values=with_embeddings,
+                include_metadata=True,
+            )
+            matches = query_response.matches
+        if min_relevance_score is not None:
+            matches = [match for match in matches if match.score >= min_relevance_score]
+        return (
+            [
+                (
+                    parse_payload(match, with_embeddings),
+                    match["score"],
+                )
+                for match in matches
+            ]
+            if len(matches) > 0
+            else []
+        )
+
+    async def __get_batch_async(
+        self, collection_name: str, keys: List[str], with_embeddings: bool = False
+    ) -> "FetchResponse":
+        index = pinecone.Index(collection_name)
+        if len(keys) > MAX_FETCH_BATCH_SIZE:
+            fetch_response = index.fetch(keys[0:MAX_FETCH_BATCH_SIZE])
+            for i in range(MAX_FETCH_BATCH_SIZE, len(keys), MAX_FETCH_BATCH_SIZE):
+                fetch_response.vectors.update(
+                    index.fetch(keys[i : i + MAX_FETCH_BATCH_SIZE]).vectors
+                )
+        else:
+            fetch_response = index.fetch(keys)
+        return fetch_response

semantic_kernel/connectors/memory/pinecone/utils.py

@@ -0,0 +1,37 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import numpy
+
+from pinecone import Vector
+from semantic_kernel.memory.memory_record import MemoryRecord
+
+
+def build_payload(record: MemoryRecord) -> dict:
+    """
+    Builds a metadata payload to be sent to Pinecone from a MemoryRecord.
+    """
+    payload: dict = {}
+    if record._text:
+        payload["text"] = record._text
+    if record._description:
+        payload["description"] = record._description
+    if record._additional_metadata:
+        payload["additional_metadata"] = record._additional_metadata
+    return payload
+
+
+def parse_payload(record: Vector, with_embeddings: bool) -> MemoryRecord:
+    """
+    Parses a record from Pinecone into a MemoryRecord.
+    """
+    payload = record.metadata
+    description = payload.get("description", None)
+    text = payload.get("text", None)
+    additional_metadata = payload.get("additional_metadata", None)
+    return MemoryRecord.local_record(
+        id=record.id,
+        description=description,
+        text=text,
+        additional_metadata=additional_metadata,
+        embedding=record.values if with_embeddings else numpy.array([]),
+    )

semantic_kernel/connectors/memory/{weaviate_memory_store.py → weaviate/weaviate_memory_store.py}

@@ -52,6 +52,11 @@ SCHEMA = {
             "description": "The text of the record.",
             "dataType": ["text"],
         },
+        {
+            "name": "additionalMetadata",
+            "description": "Optional custom metadata of the record.",
+            "dataType": ["string"],
+        },
     ],
 }
 
@@ -81,6 +86,7 @@ class WeaviateMemoryStore(MemoryStoreBase):
             "_id": "skId",
             "_description": "description",
             "_text": "text",
+            "_additional_metadata": "additionalMetadata",
             "_embedding": "vector",
         }
 
@@ -133,14 +139,20 @@ class WeaviateMemoryStore(MemoryStoreBase):
     async def create_collection_async(self, collection_name: str) -> None:
         schema = SCHEMA.copy()
         schema["class"] = collection_name
-        await asyncio.to_thread(self.client.schema.create_class, schema)
+        await asyncio.get_running_loop().run_in_executor(
+            None, self.client.schema.create_class, schema
+        )
 
     async def get_collections_async(self) -> List[str]:
-        schemas = await asyncio.to_thread(self.client.schema.get)
+        schemas = await asyncio.get_running_loop().run_in_executor(
+            None, self.client.schema.get
+        )
         return [schema["class"] for schema in schemas["classes"]]
 
     async def delete_collection_async(self, collection_name: str) -> bool:
-        await asyncio.to_thread(self.client.schema.delete_class, collection_name)
+        await asyncio.get_running_loop().run_in_executor(
+            None, self.client.schema.delete_class, collection_name
+        )
 
     async def does_collection_exist_async(self, collection_name: str) -> bool:
         collections = await self.get_collections_async()
@@ -152,12 +164,13 @@ class WeaviateMemoryStore(MemoryStoreBase):
         vector = weaviate_record.pop("vector", None)
         weaviate_id = weaviate.util.generate_uuid5(weaviate_record, collection_name)
 
-        return await asyncio.to_thread(
+        return await asyncio.get_running_loop().run_in_executor(
+            None,
             self.client.data_object.create,
-            data_object=weaviate_record,
-            uuid=weaviate_id,
-            vector=vector,
-            class_name=collection_name,
+            weaviate_record,
+            collection_name,
+            weaviate_id,
+            vector,
         )
 
     async def upsert_batch_async(
@@ -182,7 +195,9 @@ class WeaviateMemoryStore(MemoryStoreBase):
 
             return results
 
-        return await asyncio.to_thread(_upsert_batch_inner)
+        return await asyncio.get_running_loop().run_in_executor(
+            None, _upsert_batch_inner
+        )
 
     async def get_async(
         self, collection_name: str, key: str, with_embedding: bool
@@ -196,7 +211,9 @@ class WeaviateMemoryStore(MemoryStoreBase):
     ) -> List[MemoryRecord]:
         queries = self._build_multi_get_query(collection_name, keys, with_embedding)
 
-        results = await asyncio.to_thread(self.client.query.multi_get(queries).do)
+        results = await asyncio.get_running_loop().run_in_executor(
+            None, self.client.query.multi_get(queries).do
+        )
 
         get_dict = results.get("data", {}).get("Get", {})
 
@@ -254,10 +271,8 @@ class WeaviateMemoryStore(MemoryStoreBase):
                 "valueString": key,
             }
 
-            await asyncio.to_thread(
-                self.client.batch.delete_objects,
-                class_name=collection_name,
-                where=where,
+            await asyncio.get_running_loop().run_in_executor(
+                None, self.client.batch.delete_objects, collection_name, where
             )
 
     async def get_nearest_matches_async(
@@ -284,7 +299,7 @@ class WeaviateMemoryStore(MemoryStoreBase):
             .with_limit(limit)
         )
 
-        results = await asyncio.to_thread(query.do)
+        results = await asyncio.get_running_loop().run_in_executor(None, query.do)
 
         get_dict = results.get("data", {}).get("Get", {})
 

semantic_kernel/core_skills/file_io_skill.py

@@ -11,7 +11,7 @@ class FileIOSkill:
     Description: Read and write from a file.
 
     Usage:
-        kernel.import_skill("file", FileIOSkill());
+        kernel.import_skill(FileIOSkill(), skill_name="file")
 
     Examples:
 

semantic_kernel/core_skills/math_skill.py

@@ -9,7 +9,7 @@ class MathSkill:
     Description: MathSkill provides a set of functions to make Math calculations.
 
     Usage:
-        kernel.import_skill("math", new MathSkill())
+        kernel.import_skill(MathSkill(), skill_name="math")
 
     Examples:
         {{math.Add}}         => Returns the sum of initial_value_text and Amount (provided in the SKContext)

semantic_kernel/core_skills/text_skill.py

@@ -6,7 +6,7 @@ class TextSkill:
     TextSkill provides a set of functions to manipulate strings.
 
     Usage:
-        kernel.import_skill("text", TextSkill());
+        kernel.import_skill(TextSkill(), skill_name="text")
 
     Examples:
         SKContext["input"] = "  hello world  "

semantic_kernel/core_skills/time_skill.py

@@ -9,11 +9,12 @@ class TimeSkill:
                  to get the current time and date.
 
     Usage:
-        kernel.import_skill("time", TimeSkill())
+        kernel.import_skill(TimeSkill(), skill_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
@@ -55,6 +56,17 @@ class TimeSkill:
         """
         return self.date()
 
+    @sk_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()
+
     @sk_function(description="Get the current date and time in the local time zone")
     def now(self) -> str:
         """
@@ -196,8 +208,8 @@ class TimeSkill:
         return d.strftime("%A, %d %B, %Y")
 
     @sk_function(
-        description="""Get the date of the last day matching the supplied week day name in English. 
-        Example: Che giorno era 'Martedi' scorso -> dateMatchingLastDayName 'Tuesday' => Tuesday, 
+        description="""Get the date of the last day matching the supplied week day name in English.
+        Example: Che giorno era 'Martedi' scorso -> dateMatchingLastDayName 'Tuesday' => Tuesday,
         16 May, 2023"""
     )
     def date_matching_last_day_name(self, day_name: str) -> str:

semantic_kernel/core_skills/wait_skill.py

@@ -0,0 +1,23 @@
+import asyncio
+
+from semantic_kernel.skill_definition import sk_function
+
+
+class WaitSkill:
+    """
+    WaitSkill provides a set of functions to wait for a certain amount of time.
+
+    Usage:
+        kernel.import_skill(WaitSkill(), skill_name="wait")
+
+    Examples:
+        {{wait.seconds 5}} => Wait for 5 seconds
+    """
+
+    @sk_function(description="Wait for a certain number of seconds.")
+    async def wait(self, seconds_text: str):
+        try:
+            seconds = max(float(seconds_text), 0)
+        except ValueError:
+            raise ValueError("seconds text must be a number")
+        await asyncio.sleep(seconds)

semantic_kernel/kernel.py

@@ -693,6 +693,7 @@ class Kernel:
         top_p: float = 1.0,
         presence_penalty: float = 0.0,
         frequency_penalty: float = 0.0,
+        number_of_responses: int = 1,
         stop_sequences: Optional[List[str]] = None,
     ) -> "SKFunctionBase":
         function_name = (
@@ -714,6 +715,7 @@ class Kernel:
                 presence_penalty,
                 frequency_penalty,
                 max_tokens,
+                number_of_responses,
                 stop_sequences if stop_sequences is not None else [],
             ),
         )

semantic_kernel/memory/memory_query_result.py

@@ -13,6 +13,7 @@ class MemoryQueryResult:
     id: str
     description: Optional[str]
     text: Optional[str]
+    additional_metadata: Optional[str]
     relevance: float
     embedding: Optional[ndarray]
 
@@ -23,6 +24,7 @@ class MemoryQueryResult:
         id: str,
         description: Optional[str],
         text: Optional[str],
+        additional_metadata: Optional[str],
         embedding: Optional[ndarray],
         relevance: float,
     ) -> None:
@@ -45,6 +47,7 @@ class MemoryQueryResult:
         self.id = id
         self.description = description
         self.text = text
+        self.additional_metadata = additional_metadata
         self.relevance = relevance
         self.embedding = embedding
 
@@ -68,6 +71,7 @@ class MemoryQueryResult:
             id=record._id,
             description=record._description,
             text=record._text,
+            additional_metadata=record._additional_metadata,
             embedding=record._embedding,
             relevance=relevance,
         )