Python: documentation for /memory (#2176)

### Description

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

Added documentation for files in `python/semantic-kernel/memory` that
were missing them, worded mostly the exact as in .NET

Closes #2141 

### Contribution Checklist

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

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

---------

Co-authored-by: Abby Harrison <54643756+awharrison-28@users.noreply.github.com>

python/semantic_kernel/memory/memory_store_base.py

@@ -16,54 +16,145 @@ async def __aexit__(self, *args):
         await self.close_async()
 
     async def close_async(self):
+        """Async close connection, invoked by MemoryStoreBase.__aexit__()"""
         pass
 
     @abstractmethod
     async def create_collection_async(self, collection_name: str) -> None:
+        """Creates a new collection in the data store.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+
+        Returns:
+            None
+        """
         pass
 
     @abstractmethod
     async def get_collections_async(
         self,
     ) -> List[str]:
+        """Gets all collection names in the data store.
+
+        Returns:
+            List[str] -- A group of collection names.
+        """
         pass
 
     @abstractmethod
     async def delete_collection_async(self, collection_name: str) -> None:
+        """Deletes a collection from the data store.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+
+        Returns:
+            None
+        """
         pass
 
     @abstractmethod
     async def does_collection_exist_async(self, collection_name: str) -> bool:
+        """Determines if a collection exists in the data store.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+
+        Returns:
+            bool -- True if given collection exists, False if not.
+        """
+
         pass
 
     @abstractmethod
     async def upsert_async(self, collection_name: str, record: MemoryRecord) -> str:
+        """Upserts a memory record into the data store. Does not guarantee that the collection exists.
+            If the record already exists, it will be updated.
+            If the record does not exist, it will be created.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+            record {MemoryRecord} -- The memory record to upsert.
+
+        Returns:
+            str -- The unique identifier for the memory record.
+        """
         pass
 
     @abstractmethod
     async def upsert_batch_async(
         self, collection_name: str, records: List[MemoryRecord]
     ) -> List[str]:
+        """Upserts a group of memory records into the data store. Does not guarantee that the collection exists.
+            If the record already exists, it will be updated.
+            If the record does not exist, it will be created.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+            records {MemoryRecord} -- The memory records to upsert.
+
+        Returns:
+            List[str] -- The unique identifiers for the memory records.
+        """
         pass
 
     @abstractmethod
     async def get_async(
         self, collection_name: str, key: str, with_embedding: bool
     ) -> MemoryRecord:
+        """Gets a memory record from the data store. Does not guarantee that the collection exists.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+            key {str} -- The unique id associated with the memory record to get.
+            with_embedding {bool} -- If true, the embedding will be returned in the memory record.
+
+        Returns:
+            MemoryRecord -- The memory record if found
+        """
         pass
 
     @abstractmethod
     async def get_batch_async(
         self, collection_name: str, keys: List[str], with_embeddings: bool
     ) -> List[MemoryRecord]:
+        """Gets a batch of memory records from the data store. Does not guarantee that the collection exists.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+            keys {List[str]} -- The unique ids associated with the memory records to get.
+            with_embeddings {bool} -- If true, the embedding will be returned in the memory records.
+
+        Returns:
+            List[MemoryRecord] -- The memory records associated with the unique keys provided.
+        """
         pass
 
     @abstractmethod
     async def remove_async(self, collection_name: str, key: str) -> None:
+        """Removes a memory record from the data store. Does not guarantee that the collection exists.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+            key {str} -- The unique id associated with the memory record to remove.
+
+        Returns:
+            None
+        """
         pass
 
     @abstractmethod
     async def remove_batch_async(self, collection_name: str, keys: List[str]) -> None:
+        """Removes a batch of memory records from the data store. Does not guarantee that the collection exists.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+            keys {List[str]} -- The unique ids associated with the memory records to remove.
+
+        Returns:
+            None
+        """
         pass
 
     @abstractmethod
@@ -75,6 +166,19 @@ async def get_nearest_matches_async(
         min_relevance_score: float,
         with_embeddings: bool,
     ) -> List[Tuple[MemoryRecord, float]]:
+        """Gets the nearest matches to an embedding of type float. Does not guarantee that the collection exists.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+            embedding {ndarray} -- The embedding to compare the collection's embeddings with.
+            limit {int} -- The maximum number of similarity results to return.
+            min_relevance_score {float} -- The minimum relevance threshold for returned results.
+            with_embeddings {bool} -- If true, the embeddings will be returned in the memory records.
+
+        Returns:
+            List[Tuple[MemoryRecord, float]] -- A list of tuples where item1 is a MemoryRecord and item2
+                is its similarity score as a float.
+        """
         pass
 
     @abstractmethod
@@ -85,4 +189,15 @@ async def get_nearest_match_async(
         min_relevance_score: float,
         with_embedding: bool,
     ) -> Tuple[MemoryRecord, float]:
+        """Gets the nearest match to an embedding of type float. Does not guarantee that the collection exists.
+
+        Arguments:
+            collection_name {str} -- The name associated with a collection of embeddings.
+            embedding {ndarray} -- The embedding to compare the collection's embeddings with.
+            min_relevance_score {float} -- The minimum relevance threshold for returned result.
+            with_embedding {bool} -- If true, the embeddings will be returned in the memory record.
+
+        Returns:
+            Tuple[MemoryRecord, float] -- A tuple consisting of the MemoryRecord and the similarity score as a float.
+        """
         pass

python/semantic_kernel/memory/null_memory.py

@@ -15,6 +15,7 @@ async def save_information_async(
         description: Optional[str] = None,
         additional_metadata: Optional[str] = None,
     ) -> None:
+        """Nullifies behavior of SemanticTextMemoryBase.save_information_async()"""
         return None
 
     async def save_reference_async(
@@ -26,11 +27,13 @@ async def save_reference_async(
         description: Optional[str] = None,
         additional_metadata: Optional[str] = None,
     ) -> None:
+        """Nullifies behavior of SemanticTextMemoryBase.save_reference_async()"""
         return None
 
     async def get_async(
         self, collection: str, query: str
     ) -> Optional[MemoryQueryResult]:
+        """Nullifies behavior of SemanticTextMemoryBase.get_async()"""
         return None
 
     async def search_async(
@@ -40,9 +43,11 @@ async def search_async(
         limit: int = 1,
         min_relevance_score: float = 0.7,
     ) -> List[MemoryQueryResult]:
+        """Nullifies behavior of SemanticTextMemoryBase.search_async()"""
         return []
 
     async def get_collections_async(self) -> List[str]:
+        """Nullifies behavior of SemanticTextMemoryBase.get_collections_async()"""
         return []
 
 

python/semantic_kernel/memory/semantic_text_memory_base.py

@@ -17,6 +17,17 @@ async def save_information_async(
         additional_metadata: Optional[str] = None,
         # TODO: ctoken?
     ) -> None:
+        """Save information to the memory (calls the memory store's upsert method).
+
+        Arguments:
+            collection {str} -- The collection to save the information to.
+            text {str} -- The text to save.
+            id {str} -- The id of the information.
+            description {Optional[str]} -- The description of the information.
+
+        Returns:
+            None -- None.
+        """
         pass
 
     @abstractmethod
@@ -29,6 +40,18 @@ async def save_reference_async(
         description: Optional[str] = None,
         additional_metadata: Optional[str] = None,
     ) -> None:
+        """Save a reference to the memory (calls the memory store's upsert method).
+
+        Arguments:
+            collection {str} -- The collection to save the reference to.
+            text {str} -- The text to save.
+            external_id {str} -- The external id of the reference.
+            external_source_name {str} -- The external source name of the reference.
+            description {Optional[str]} -- The description of the reference.
+
+        Returns:
+            None -- None.
+        """
         pass
 
     @abstractmethod
@@ -37,6 +60,15 @@ async def get_async(
         collection: str,
         query: str,
     ) -> Optional[MemoryQueryResult]:
+        """Get information from the memory (calls the memory store's get method).
+
+        Arguments:
+            collection {str} -- The collection to get the information from.
+            key {str} -- The key of the information.
+
+        Returns:
+            Optional[MemoryQueryResult] -- The MemoryQueryResult if found, None otherwise.
+        """
         pass
 
     @abstractmethod
@@ -48,8 +80,25 @@ async def search_async(
         min_relevance_score: float = 0.7,
         # TODO: ctoken?
     ) -> List[MemoryQueryResult]:
+        """Search the memory (calls the memory store's get_nearest_matches method).
+
+        Arguments:
+            collection {str} -- The collection to search in.
+            query {str} -- The query to search for.
+            limit {int} -- The maximum number of results to return. (default: {1})
+            min_relevance_score {float} -- The minimum relevance score to return. (default: {0.0})
+            with_embeddings {bool} -- Whether to return the embeddings of the results. (default: {False})
+
+        Returns:
+            List[MemoryQueryResult] -- The list of MemoryQueryResult found.
+        """
         pass
 
     @abstractmethod
     async def get_collections_async(self) -> List[str]:
+        """Get the list of collections in the memory (calls the memory store's get_collections method).
+
+        Returns:
+            List[str] -- The list of all the memory collection names.
+        """
         pass