Skip to content

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.

Refactor graph reduction flow and harden mutable defaults

Cursor Agent59f1b5a3f507
diff --git a/src/adapters/graph.py b/src/adapters/graph.py
index 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, abstractmethod
from typing import Dict, List, Literal, Optional, Tuple
from src.adapters.interfaces.graph import GraphClient, PredicateWithFlowKey
from src.constants.embeddings import Vector
@@ -25,13 +26,67 @@ from src.utils.normalization.list_reduction import reduce_list
from 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()
+ )
@property
def 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 fds
if 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.py
index 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.py
index 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.py
index 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.py
index 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 Vector
from src.core.agents.core.runtime_agent_factory import RuntimeAgentFactory
+from src.services.api.controllers.entities import get_entity_status
def 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()