BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.
Python ai-agentsai-memoryknowledge-graphknowledge-managementknowledge-representationreccomendation-system
Refactor graph reduction flow and harden mutable defaults
Cursor Agent59f1b5a3f507
diff --git a/src/adapters/graph.py b/src/adapters/graph.pyindex d8dd3fb..a13c66e 100644--- a/src/adapters/graph.py+++ b/src/adapters/graph.py@@ -8,6 +8,7 @@ Modified By: Christian Nonis <[email protected]>-----"""+from abc import ABC, abstractmethodfrom typing import Dict, List, Literal, Optional, Tuplefrom src.adapters.interfaces.graph import GraphClient, PredicateWithFlowKeyfrom src.constants.embeddings import Vector@@ -25,13 +26,67 @@ from src.utils.normalization.list_reduction import reduce_listfrom src.utils.similarity.vectors import cosine_similarity+class NeighborVectorReductionStrategy(ABC):+ @abstractmethod+ def prefilter(+ self,+ vectors_with_desc: list[dict],+ averaged_vector: list[float],+ description: Optional[str],+ ) -> list[dict]:+ raise NotImplementedError+++class SimilarityOnlyReductionStrategy(NeighborVectorReductionStrategy):+ def prefilter(+ self,+ vectors_with_desc: list[dict],+ averaged_vector: list[float],+ description: Optional[str],+ ) -> list[dict]:+ return vectors_with_desc+++class DescriptionAwareReductionStrategy(NeighborVectorReductionStrategy):+ def prefilter(+ self,+ vectors_with_desc: list[dict],+ averaged_vector: list[float],+ description: Optional[str],+ ) -> list[dict]:+ if not description:+ return vectors_with_desc+ return reduce_list(+ vectors_with_desc,+ access_key="embeddings",+ similarity_threshold=0.8,+ by_vector=averaged_vector,+ rerank={+ "local": "description",+ "with_": description,+ },+ )+++class NeighborVectorReductionStrategyFactory:+ def create(self, description: Optional[str]) -> NeighborVectorReductionStrategy:+ if description:+ return DescriptionAwareReductionStrategy()+ return SimilarityOnlyReductionStrategy()++class GraphAdapter:"""Adapter for the graph client."""- def __init__(self):+ def __init__(+ self, reduction_strategy_factory: Optional[NeighborVectorReductionStrategyFactory] = None+ ):self.graph = None+ self._reduction_strategy_factory = (+ reduction_strategy_factory or NeighborVectorReductionStrategyFactory()+ )@propertydef graphdb_type(self) -> str:@@ -298,8 +353,8 @@ class GraphAdapter:uuid: str,updating: Literal["node", "relationship"],brain_id: str = "default",- new_properties: dict = {},- properties_to_remove: list[str] = [],+ new_properties: Optional[dict] = None,+ properties_to_remove: Optional[list[str]] = None,) -> Node | Predicate | None:"""Update properties on a graph node or relationship.@@ -314,6 +369,10 @@ class GraphAdapter:Returns:Node | Predicate | None: The updated entity, or `None` if the entity was not found."""+ if new_properties is None:+ new_properties = {}+ if properties_to_remove is None:+ properties_to_remove = []return self.graph.update_properties(uuid, updating, brain_id, new_properties, properties_to_remove)@@ -396,24 +455,46 @@ class GraphAdapter:similarity_threshold: float,description: Optional[str],) -> set[str]:- reduced_vectors = vectors_with_desc- if description:- reduced_vectors = reduce_list(- vectors_with_desc,- access_key="embeddings",- similarity_threshold=0.8,- by_vector=averaged_vector,- rerank={- "local": "description",- "with_": description,- },- )- return {- vector["metadata"]["uuid"]- for vector in reduced_vectors- if cosine_similarity(averaged_vector, vector["embeddings"])- >= similarity_threshold- }+ if not vectors_with_desc or not averaged_vector:+ return set()+ strategy = self._reduction_strategy_factory.create(description)+ reduced_vectors = strategy.prefilter(+ vectors_with_desc=vectors_with_desc,+ averaged_vector=averaged_vector,+ description=description,+ )+ filtered_uuids = set()+ for vector in reduced_vectors:+ vector_uuid = vector.get("metadata", {}).get("uuid")+ embeddings = vector.get("embeddings")+ if (+ not vector_uuid+ or not embeddings+ or not isinstance(embeddings, list)+ or len(embeddings) != len(averaged_vector)+ ):+ continue+ if cosine_similarity(averaged_vector, embeddings) >= similarity_threshold:+ filtered_uuids.add(vector_uuid)+ return filtered_uuids++ def _average_embeddings(self, vectors: list[Vector]) -> list[float]:+ valid_embeddings = [+ vector.embeddings for vector in vectors if isinstance(vector.embeddings, list) and vector.embeddings+ ]+ if not valid_embeddings:+ return []+ dimension = len(valid_embeddings[0])+ same_dimension_embeddings = [+ embedding for embedding in valid_embeddings if len(embedding) == dimension+ ]+ if not same_dimension_embeddings:+ return []+ return [+ sum(embedding[i] for embedding in same_dimension_embeddings)+ / len(same_dimension_embeddings)+ for i in range(dimension)+ ]def get_2nd_degree_hops(self,@@ -479,10 +560,10 @@ class GraphAdapter:print("[ ! ] No vectors found for nodes:", from_uuids)return []- averaged_vector = [- sum(v.embeddings[i] for v in vs) / len(vs)- for i in range(len(vs[0].embeddings))- ]+ averaged_vector = self._average_embeddings(vs)+ if len(averaged_vector) == 0:+ print("[ ! ] No valid embeddings found for nodes:", from_uuids)+ return []all_fd_nodes = self.get_neighbors(list(nodes_by_uuid.keys()), brain_id=brain_id)@@ -492,12 +573,14 @@ class GraphAdapter:for fd in fdsif fd[1].properties.get("v_id") is not None] # TODO: [missing_property] check why sometime v_id is not present- all_fd_vs = vector_store_adapter.get_by_ids(- all_fd_v_ids, brain_id=brain_id, store="nodes"+ all_fd_vs = (+ vector_store_adapter.get_by_ids(all_fd_v_ids, brain_id=brain_id, store="nodes")+ if len(all_fd_v_ids) > 0+ else [])fd_vs_by_uuid: Dict[str, Vector] = {v.metadata["uuid"]: v for v in all_fd_vs}- all_filtered_fd_uuids = []+ all_filtered_fd_uuids: set[str] = set()filtered_fd_by_origin: Dict[str, List[Tuple[Predicate, Node]]] = {}for node_uuid, fd_list in all_fd_nodes.items():@@ -525,9 +608,13 @@ class GraphAdapter:filtered_fd_by_origin[node_uuid] = [fd for fd in fd_list if fd[1].uuid in filtered_uuids]- all_filtered_fd_uuids.extend(filtered_uuids)+ all_filtered_fd_uuids.update(filtered_uuids)- all_sd_nodes = self.get_neighbors(all_filtered_fd_uuids, brain_id=brain_id)+ all_sd_nodes = (+ self.get_neighbors(list(all_filtered_fd_uuids), brain_id=brain_id)+ if len(all_filtered_fd_uuids) > 0+ else {}+ )all_sd_v_ids: List[str] = [getattr(sd[1], "properties", {}).get("v_id")@@ -537,8 +624,10 @@ class GraphAdapter:"v_id") # TODO: [missing_property] check why sometime v_id is not present]- all_sd_vs = vector_store_adapter.get_by_ids(- all_sd_v_ids, brain_id=brain_id, store="nodes"+ all_sd_vs = (+ vector_store_adapter.get_by_ids(all_sd_v_ids, brain_id=brain_id, store="nodes")+ if len(all_sd_v_ids) > 0+ else [])sd_vs_by_uuid = {v.metadata["uuid"]: v for v in all_sd_vs}diff --git a/src/services/api/controllers/entities.py b/src/services/api/controllers/entities.pyindex 55668a4..65774f4 100644--- a/src/services/api/controllers/entities.py+++ b/src/services/api/controllers/entities.py@@ -130,7 +130,7 @@ async def get_entity_sibilings(async def get_entity_status(target: str,- types: List[str] = [],+ types: List[str] | None = None,brain_id: str = "default",) -> GetEntityStatusResponse:"""@@ -145,6 +145,9 @@ async def get_entity_status(GetEntityStatusResponse: Response containing the matched node (or `None` if not found), `exists` indicating presence, `has_relationships` indicating whether the node has neighbors, `relationships` listing neighbor tuples, and `observations` associated with the node. When no matching node is found, `exists` is `False` and `relationships` and `observations` are empty."""+ if types is None:+ types = []+target_embeddings = embeddings_adapter.embed_text(target)target_node_vs = vector_store_adapter.search_vectors(target_embeddings.embeddings, store="nodes", brain_id=brain_id@@ -154,7 +157,10 @@ async def get_entity_status(for target_node_v in target_node_vs:target_node_id = target_node_v.metadata.get("uuid")- target_node = graph_adapter.get_by_uuids([target_node_id], brain_id=brain_id)[0]+ nodes = graph_adapter.get_by_uuids([target_node_id], brain_id=brain_id)+ if len(nodes) == 0:+ continue+ target_node = nodes[0]if len(types) > 0:if set(target_node.labels).intersection(set(types)):diff --git a/src/services/api/routes/retrieve.py b/src/services/api/routes/retrieve.pyindex afd9172..998326a 100644--- a/src/services/api/routes/retrieve.py+++ b/src/services/api/routes/retrieve.py@@ -493,7 +493,7 @@ async def get_entity_synergies(@retrieve_router.get(path="/entity/status")async def get_entity_status(target: str,- types: Optional[List[str]] = [],+ types: Optional[List[str]] = None,brain_id: str = Depends(get_brain_id),):"""@@ -507,4 +507,4 @@ async def get_entity_status(Returns:status (dict): A dictionary containing the entity's status details."""- return await get_entity_status_controller(target, types, brain_id)+ return await get_entity_status_controller(target, types or [], brain_id)diff --git a/src/utils/cleanup.py b/src/utils/cleanup.pyindex e1a697e..ce336c3 100644--- a/src/utils/cleanup.py+++ b/src/utils/cleanup.py@@ -51,7 +51,11 @@ def _extract_json_array_after_key(text: str, key: str):return None-def strip_properties(objs: list[dict], pop_also: list[str] = []) -> list[dict]:+def strip_properties(+ objs: list[dict], pop_also: list[str] | None = None+) -> list[dict]:+ if pop_also is None:+ pop_also = []cleaned_objs = []for obj in objs:if not isinstance(obj, dict):diff --git a/tests/test_architecture_refactors.py b/tests/test_architecture_refactors.pyindex d25ee57..102df56 100644--- a/tests/test_architecture_refactors.py+++ b/tests/test_architecture_refactors.py@@ -37,7 +37,9 @@ from src.adapters.embeddings import (RaiseEmbeddingFailureStrategy,)from src.adapters.graph import GraphAdapter+from src.constants.embeddings import Vectorfrom src.core.agents.core.runtime_agent_factory import RuntimeAgentFactory+from src.services.api.controllers.entities import get_entity_statusdef raise_embedding_error(*args, **kwargs):@@ -147,6 +149,62 @@ class GraphAdapterReductionTests(unittest.TestCase):reduced.assert_called_once()self.assertEqual(result, {"b"})+ def test_reduce_neighbor_vectors_skips_invalid_embeddings(self):+ adapter = GraphAdapter()+ vectors = [+ {"metadata": {"uuid": "a"}, "embeddings": [1.0, 0.0]},+ {"metadata": {"uuid": "b"}, "embeddings": [1.0]},+ {"metadata": {"uuid": "c"}, "embeddings": None},+ {"metadata": {}, "embeddings": [1.0, 0.0]},+ ]+ reduced = adapter._reduce_neighbor_vectors(+ vectors_with_desc=vectors,+ averaged_vector=[1.0, 0.0],+ similarity_threshold=0.5,+ description=None,+ )+ self.assertEqual(reduced, {"a"})++ def test_average_embeddings_ignores_invalid_and_mismatched_dimensions(self):+ adapter = GraphAdapter()+ vectors = [+ Vector(id="1", embeddings=[1.0, 2.0], metadata={}),+ Vector(id="2", embeddings=[3.0, 4.0], metadata={}),+ Vector(id="3", embeddings=[10.0], metadata={}),+ Vector(id="4", embeddings=None, metadata={}),+ Vector(id="5", embeddings=[], metadata={}),+ ]+ averaged = adapter._average_embeddings(vectors)+ self.assertEqual(averaged, [2.0, 3.0])+++class EntityStatusControllerTests(unittest.IsolatedAsyncioTestCase):+ async def test_get_entity_status_skips_missing_graph_nodes(self):+ fake_vector = type(+ "FakeVector",+ (),+ {"metadata": {"uuid": "missing-node"}, "embeddings": [0.1, 0.2]},+ )()+ with (+ patch(+ "src.services.api.controllers.entities.embeddings_adapter.embed_text",+ return_value=Vector(id="q", embeddings=[0.1, 0.2], metadata={}),+ ),+ patch(+ "src.services.api.controllers.entities.vector_store_adapter.search_vectors",+ return_value=[fake_vector],+ ),+ patch(+ "src.services.api.controllers.entities.graph_adapter.get_by_uuids",+ return_value=[],+ ),+ ):+ response = await get_entity_status("target", types=None, brain_id="default")+ self.assertFalse(response.exists)+ self.assertFalse(response.has_relationships)+ self.assertEqual(response.relationships, [])+ self.assertEqual(response.observations, [])+if __name__ == "__main__":unittest.main()