📝 Add docstrings to development

src/adapters/data.py

@@ -157,13 +157,13 @@ def get_observations_list(
 
     def get_observation_labels(self, brain_id: str = "default") -> list[str]:
         """
-        Retrieve all unique observation labels for the specified brain.
-
+        Get all unique observation labels for the specified brain.
+        
         Parameters:
-            brain_id (str): Identifier of the brain to query labels from.
-
+            brain_id (str): Identifier of the brain to query.
+        
         Returns:
-            list[str]: All unique labels present in observations for the specified brain.
+            list[str]: A list of unique observation label strings for the specified brain.
         """
         return self.data.get_observation_labels(brain_id=brain_id)
 
@@ -225,8 +225,15 @@ def update_structured_data(
         self, structured_data: StructuredData, brain_id: str = "default"
     ) -> StructuredData:
         """
-        Update a structured data.
+        Update an existing structured data entry.
+
+        Parameters:
+        	structured_data (StructuredData): The structured data object with updated information.
+        	brain_id (str): Identifier of the brain context for the update.
+
+        Returns:
+        	StructuredData: The updated structured data object.
         """
         return self.data.update_structured_data(
             structured_data=structured_data, brain_id=brain_id
-        )
+        )

src/adapters/embeddings.py

@@ -85,12 +85,24 @@ def search_similar_by_ids(
         limit: int = 10,
     ) -> dict[str, list[Vector]]:
         """
-        Search similar vectors by their IDs.
+        Finds vectors similar to the provided vector IDs within a specified store and brain.
+
+        Parameters:
+            vector_ids (list[str]): IDs of the source vectors to find similarities for.
+            brain_id (str): Identifier of the brain/namespace to search within.
+            store (str): Name of the vector store to query.
+            min_similarity (float): Minimum similarity threshold for returned vectors (inclusive).
+            limit (int): Maximum number of similar vectors to return per source ID.
+
+        Returns:
+            dict[str, list[Vector]]: Mapping from each source vector ID to a list of similar Vectors.
+            Each list contains at most `limit` items, includes only vectors with similarity >= `min_similarity`,
+            and is ordered by descending similarity.
         """
         return self.vector_store.search_similar_by_ids(
             vector_ids, brain_id, store, min_similarity, limit
         )
 
 
 _embeddings_adapter = EmbeddingsAdapter()
-_vector_store_adapter = VectorStoreAdapter()
+_vector_store_adapter = VectorStoreAdapter()

src/adapters/graph.py

@@ -132,22 +132,26 @@ def get_graph_entities(self, brain_id: str = "default") -> list[str]:
 
     def get_graph_relationships(self, brain_id: str = "default") -> list[str]:
         """
-        Retrieve the relationship types present in the graph.
-
+        Retrieve relationship type names available in the graph.
+        
         Parameters:
             brain_id (str): Identifier of the graph/brain to query.
-
+        
         Returns:
-            A list of relationship type names.
+            list[str]: Relationship type names present in the specified graph.
         """
         return self.graph.get_graph_relationships(brain_id)
 
     def get_by_uuid(self, uuid: str, brain_id: str = "default") -> Node:
         """
-        DEPRECATED: use get_by_uuids instead.
-
-        Retrieve the node with the specified UUID from the graph.
-
+        Retrieve a node by its UUID from the graph.
+
+        Deprecated: use `get_by_uuids` for batch retrieval.
+
+        Parameters:
+            uuid (str): UUID of the node to retrieve.
+            brain_id (str): Identifier of the graph/brain to query.
+
         Returns:
             Node: The node matching the provided UUID.
         """
@@ -316,19 +320,19 @@ def get_graph_relationship_types(self, brain_id: str = "default") -> list[str]:
 
     def get_graph_node_types(self, brain_id: str = "default") -> list[str]:
         """
-        Get all unique node types from the graph.
-
-        @returns:
-            A list of node type names available in the graph.
+        Get all unique node types stored in the graph.
+        
+        Returns:
+            list[str]: Node type names available in the graph.
         """
         return self.graph.get_graph_node_types(brain_id)
 
     def get_graph_node_properties(self, brain_id: str = "default") -> list[str]:
         """
-        Retrieve all unique node property keys present in the graph.
-
-        @returns
-            list[str]: A list of unique property key names present on nodes for the specified brain.
+        Return all unique node property keys present in the graph for the specified brain.
+        
+        Returns:
+            list[str]: Unique node property key names present in the specified brain's graph.
         """
         return self.graph.get_graph_node_properties(brain_id)
 
@@ -382,19 +386,32 @@ def get_2nd_degree_hops(
         similarity_threshold: float = 0.0,
     ) -> List[Tuple[Node, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]]:
         """
-        Get the 2nd degree hops for a list of nodes.
-
+        Compute second-degree neighbor hops for the given starting node UUIDs using vector-store–based filtering.
+        
         Parameters:
-            from_uuids: List[str]: The list of node UUIDs to start from.
-            flattened: bool: Whether to return simplified nodes and relationships.
-            vector_store_adapter: VectorStoreClient: The vector store adapter to use.
-            brain_id: str: The brain ID to use.
-
+            from_uuids: List[str] — UUIDs of the starting nodes to explore.
+            flattened: bool — When true, nodes and predicates are returned as lightweight dicts with core fields (`uuid`, `name`, `labels`/`direction`) instead of full objects.
+            vector_store_adapter: VectorStoreClient — Vector store used to fetch embeddings and perform similarity-based filtering.
+            brain_id: str — Identifier of the brain/graph space to query.
+            similarity_threshold: float — Optional threshold for additional similarity-based filtering (0.0 disables the extra check).
+
         Returns:
-            List[Tuple[Node, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]]: The list of 2nd degree hops.
+            List[Tuple[Node, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]] — A list where each item corresponds to a starting node and contains:
+                - the starting node (or its flattened representation),
+                - a list of first-degree entries, each being a tuple of (predicate, first-degree node, list of second-degree (predicate, node) tuples).
         """
 
         def flatten_node(n):
+            """
+            Return a flattened node representation when the surrounding `flattened` flag is true, otherwise return the original node.
+
+            Parameters:
+                n: Node
+                    The node to convert.
+
+            Returns:
+                dict: A dictionary with keys `uuid`, `labels`, and `name` when `flattened` is true, otherwise the original node object.
+            """
             return (
                 {"uuid": n.uuid, "labels": n.labels, "name": n.name} if flattened else n
             )
@@ -583,7 +600,16 @@ def check_node_existence(
         brain_id: str = "default",
     ) -> bool:
         """
-        Check if a node exists in the graph.
+        Determine whether a node with the given UUID, name, and labels exists in the graph.
+
+        Parameters:
+        	uuid (str): UUID of the node to check; may be empty if matching by name and labels.
+        	name (str): Name of the node to match.
+        	labels (list[str]): List of labels/types the node must have.
+        	brain_id (str): Identifier of the graph/brain to query; defaults to "default".
+
+        Returns:
+        	true if a matching node exists, false otherwise.
         """
         return self.graph.check_node_existence(uuid, name, labels, brain_id)
 
@@ -600,9 +626,17 @@ def get_next_by_flow_key(
         self, predicate_uuid: str, flow_key: str, brain_id: str = "default"
     ) -> List[Tuple[Node, Predicate, Node]]:
         """
-        Get the next node by the flow key.
+        Retrieve the next connected node tuple(s) for a relationship identified by a flow key.
+
+        Parameters:
+            predicate_uuid (str): UUID of the predicate (relationship) to search from.
+            flow_key (str): Flow key value used to select the next relationship target.
+            brain_id (str): Identifier of the brain/graph namespace to query.
+
+        Returns:
+            List[Tuple[Node, Predicate, Node]]: A list of (subject node, predicate, object node) tuples that are the next nodes matching the provided flow key; empty list if none are found.
         """
         return self.graph.get_next_by_flow_key(predicate_uuid, flow_key, brain_id)
 
 
-_graph_adapter = GraphAdapter()
+_graph_adapter = GraphAdapter()

src/adapters/interfaces/data.py

@@ -116,7 +116,17 @@ def get_structured_data_list(
         query_text: str = None,
     ) -> list[StructuredData]:
         """
-        Get a list of structured data.
+        Retrieve structured data entries for a specific brain with optional filtering and pagination.
+
+        Parameters:
+            brain_id (str): Identifier of the brain to query.
+            limit (int): Maximum number of items to return.
+            skip (int): Number of items to skip (offset) for pagination.
+            types (list[str] | None): If provided, restrict results to these structured data types.
+            query_text (str | None): If provided, filter entries that match the text query.
+
+        Returns:
+            list[StructuredData]: List of matching StructuredData objects.
         """
         raise NotImplementedError("get_structured_data_list method not implemented")
 
@@ -145,20 +155,31 @@ def get_observations_list(
         query_text: str = None,
     ) -> list[Observation]:
         """
-        Get a list of observations.
+        Retrieve a filtered, paginated list of observations for a specific brain.
+
+        Parameters:
+            brain_id (str): Identifier of the brain to query.
+            limit (int): Maximum number of observations to return.
+            skip (int): Number of observations to skip (offset) for pagination.
+            resource_id (str | None): If provided, restrict results to observations for this resource.
+            labels (list[str] | None): If provided, include only observations that have at least one of these labels.
+            query_text (str | None): If provided, include only observations whose text matches this query.
+
+        Returns:
+            observations (list[Observation]): A list of matching Observation objects ordered according to the backend's default sort.
         """
         raise NotImplementedError("get_observations_list method not implemented")
 
     @abstractmethod
     def get_observation_labels(self, brain_id: str) -> list[str]:
         """
-        Return all unique observation labels for the specified brain.
-
+        Retrieve all unique observation labels for the specified brain.
+        
         Parameters:
             brain_id (str): Identifier of the brain whose observation labels should be retrieved.
-
+        
         Returns:
-            labels (list[str]): A list of unique label strings present in the brain's observations.
+            list[str]: Unique label strings present in the brain's observations.
         """
         raise NotImplementedError("get_observation_labels method not implemented")
 
@@ -203,13 +224,13 @@ def get_changelogs_list(
     @abstractmethod
     def get_changelog_types(self, brain_id: str) -> list[str]:
         """
-        Return the set of unique changelog types associated with the specified brain.
-
+        Return the unique changelog types present for the specified brain.
+        
         Parameters:
-            brain_id (str): Identifier of the brain whose changelog types should be retrieved.
-
+            brain_id (str): Identifier of the brain to query.
+        
         Returns:
-            list[str]: A list of unique changelog type names (order not guaranteed).
+            list[str]: List of unique changelog type names for the brain (order not guaranteed).
         """
         raise NotImplementedError("get_changelog_types method not implemented")
 
@@ -218,6 +239,13 @@ def update_structured_data(
         self, structured_data: StructuredData, brain_id: str
     ) -> StructuredData:
         """
-        Update a structured data.
+        Update an existing StructuredData record for a specific brain.
+
+        Parameters:
+            structured_data (StructuredData): StructuredData object containing the updated content and identifier of the record to update.
+            brain_id (str): Identifier of the brain that owns the structured data.
+
+        Returns:
+            StructuredData: The stored StructuredData after the update.
         """
-        raise NotImplementedError("update_structured_data method not implemented")
+        raise NotImplementedError("update_structured_data method not implemented")

src/adapters/interfaces/embeddings.py

@@ -66,6 +66,16 @@ def search_similar_by_ids(
         limit: int = 10,
     ) -> dict[str, list[Vector]]:
         """
-        Search similar vectors by their IDs.
+        Finds vectors similar to the vectors identified by the given IDs.
+
+        Parameters:
+            vector_ids (list[str]): Identifiers of the vectors to find similarities for.
+            brain_id (str): Identifier for the brain/context containing the vectors.
+            store (str): Name of the vector store to query.
+            min_similarity (float): Minimum similarity threshold (e.g., 0.0–1.0) for returned results.
+            limit (int): Maximum number of similar vectors to return per input ID.
+
+        Returns:
+            dict[str, list[Vector]]: Mapping from each input vector ID to a list of similar `Vector` objects that meet or exceed `min_similarity`, with up to `limit` results per ID.
         """
-        raise NotImplementedError("search_similar_by_ids method not implemented")
+        raise NotImplementedError("search_similar_by_ids method not implemented")