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 vector search calls with facade and safe keywords

Cursor Agent480be1ac7207
diff --git a/src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py b/src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py
index 0bda98a..d7befe5 100644
--- a/src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py
+++ b/src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py
@@ -93,10 +93,16 @@ class KGAgentAddTripletsTool(BaseTool):
v_obj = self.embeddings.embed_text(object_node.name)
v_sim_sub = self.vector_store.search_vectors(
- v_sub.embeddings, "nodes", k=5, brain_id=self.brain_id
+ v_sub.embeddings,
+ store="nodes",
+ brain_id=self.brain_id,
+ k=5,
)
v_sim_obj = self.vector_store.search_vectors(
- v_obj.embeddings, "nodes", k=5, brain_id=self.brain_id
+ v_obj.embeddings,
+ store="nodes",
+ brain_id=self.brain_id,
+ k=5,
)
sim_sub = most_similar_name_with_labels_or_none(
diff --git a/src/core/agents/tools/kg_agent/KGAgentSearchGraphTool.py b/src/core/agents/tools/kg_agent/KGAgentSearchGraphTool.py
index 036f1fe..5c53348 100644
--- a/src/core/agents/tools/kg_agent/KGAgentSearchGraphTool.py
+++ b/src/core/agents/tools/kg_agent/KGAgentSearchGraphTool.py
@@ -111,10 +111,15 @@ class KGAgentSearchGraphTool(BaseTool):
if query:
query_embedding = self.embeddings.embed_text(query)
v_triplets_results = self.vector_store.search_vectors(
- query_embedding.embeddings, "triplets", k=5, brain_id=self.brain_id
+ query_embedding.embeddings,
+ store="triplets",
+ k=5,
+ brain_id=self.brain_id,
)
v_nodes_results = self.vector_store.search_vectors(
- query_embedding.embeddings, "nodes", brain_id=self.brain_id
+ query_embedding.embeddings,
+ store="nodes",
+ brain_id=self.brain_id,
)
nodes.extend(self.kg.node_text_search(query, brain_id=self.brain_id))
nodes.extend(
diff --git a/src/core/search/entity_context.py b/src/core/search/entity_context.py
index ec68e1f..52eed38 100644
--- a/src/core/search/entity_context.py
+++ b/src/core/search/entity_context.py
@@ -15,6 +15,9 @@ from src.services.kg_agent.main import (
vector_store_adapter,
graph_adapter,
)
+from src.utils.vector_search import VectorSearchFacade
+
+vector_search = VectorSearchFacade(vector_store_adapter)
class EntityContext:
@@ -50,8 +53,9 @@ class EntityContext:
natural_language_web = list()
target_embedding = embeddings_adapter.embed_text(self.target)
- target_node_vs = vector_store_adapter.search_vectors(
- target_embedding.embeddings, store="nodes", brain_id=self.brain_id
+ target_node_vs = vector_search.search_nodes(
+ target_embedding.embeddings,
+ brain_id=self.brain_id,
)
if not target_node_vs:
diff --git a/src/core/search/entity_info.py b/src/core/search/entity_info.py
index 94a60b4..041833e 100644
--- a/src/core/search/entity_info.py
+++ b/src/core/search/entity_info.py
@@ -19,9 +19,13 @@ from src.constants.kg import Node, Predicate
from src.services.kg_agent.main import graph_adapter
from src.services.kg_agent.main import embeddings_adapter
from src.services.kg_agent.main import vector_store_adapter
+from src.utils.vector_search import VectorSearchFacade
from src.utils.similarity.vectors import cosine_similarity
+vector_search = VectorSearchFacade(vector_store_adapter)
+
+
# ================================================================
# NOTE Currently not fully supported by the Event-Centric v2 kg
# Need to figure out how to handle this.
@@ -164,8 +168,8 @@ class EventSynergyRetriever:
query_embedding = embeddings_adapter.embed_text(query)
target_embedding = embeddings_adapter.embed_text(target)
- target_node_vs = vector_store_adapter.search_vectors(
- target_embedding.embeddings, store="nodes", brain_id=self.brain_id
+ target_node_vs = vector_search.search_nodes(
+ target_embedding.embeddings, brain_id=self.brain_id
)
if not target_node_vs:
diff --git a/src/core/search/entity_sibilings.py b/src/core/search/entity_sibilings.py
index f8be810..f0240f8 100644
--- a/src/core/search/entity_sibilings.py
+++ b/src/core/search/entity_sibilings.py
@@ -18,6 +18,7 @@ from src.services.kg_agent.main import (
graph_adapter,
vector_store_adapter,
)
+from src.utils.vector_search import VectorSearchFacade
from src.utils.similarity.numbers import wmean, wsim
from src.utils.similarity.vectors import cosine_similarity
@@ -33,6 +34,8 @@ FACTORS_INCREMENTAL_WEIGHT = 0.3
# Weight to strengthen the similarity by the comparison of the neighbor+target descriptions
NODE_SIM_DESC_INCREMENTAL_WEIGHT = 0.5
+vector_search = VectorSearchFacade(vector_store_adapter)
+
class EntitySinergyRetriever:
def __init__(self, brain_id: str = "default"):
@@ -358,9 +361,8 @@ class EntitySinergyRetriever:
_upsert_connection(seed_node, neighbor[1], neighbor[0])
target_embedding = embeddings_adapter.embed_text(target)
- target_node_vs = vector_store_adapter.search_vectors(
+ target_node_vs = vector_search.search_nodes(
target_embedding.embeddings,
- store="nodes",
brain_id=self.brain_id,
)
if not target_node_vs:
@@ -406,9 +408,8 @@ class EntitySinergyRetriever:
)
if seed_embedding is None:
continue
- similar_seed_vs = vector_store_adapter.search_vectors(
+ similar_seed_vs = vector_search.search_nodes(
seed_embedding,
- store="nodes",
brain_id=self.brain_id,
)
diff --git a/src/services/api/controllers/entities.py b/src/services/api/controllers/entities.py
index 65774f4..d6ebaf6 100644
--- a/src/services/api/controllers/entities.py
+++ b/src/services/api/controllers/entities.py
@@ -24,6 +24,9 @@ from src.core.search.entity_sibilings import EntitySinergyRetriever
from src.services.data.main import data_adapter
from src.services.input.agents import embeddings_adapter
from src.services.kg_agent.main import graph_adapter, vector_store_adapter
+from src.utils.vector_search import VectorSearchFacade
+
+vector_search = VectorSearchFacade(vector_store_adapter)
async def get_entity_info(
@@ -149,8 +152,9 @@ async def get_entity_status(
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
+ target_node_vs = vector_search.search_nodes(
+ target_embeddings.embeddings,
+ brain_id=brain_id,
)
target_node = None
diff --git a/src/services/api/controllers/kg.py b/src/services/api/controllers/kg.py
index 2dfda6f..adcb840 100644
--- a/src/services/api/controllers/kg.py
+++ b/src/services/api/controllers/kg.py
@@ -14,6 +14,9 @@ from src.services.kg_agent.main import (
graph_adapter,
vector_store_adapter,
)
+from src.utils.vector_search import VectorSearchFacade
+
+vector_search = VectorSearchFacade(vector_store_adapter)
async def get_hops(
@@ -25,8 +28,9 @@ async def get_hops(
Currently only supports 2nd degree hops.
"""
text_embeddings = embeddings_adapter.embed_text(query)
- data_vectors = vector_store_adapter.search_vectors(
- text_embeddings.embeddings, store="nodes", brain_id=brain_id
+ data_vectors = vector_search.search_nodes(
+ text_embeddings.embeddings,
+ brain_id=brain_id,
)
node_uuids = [v.metadata.get("uuid") for v in data_vectors]
print("[+] Getting 2nd degree hops for nodes:", node_uuids)
diff --git a/src/services/api/controllers/retrieve.py b/src/services/api/controllers/retrieve.py
index 8784763..8fd2e0d 100644
--- a/src/services/api/controllers/retrieve.py
+++ b/src/services/api/controllers/retrieve.py
@@ -19,6 +19,7 @@ from src.constants.embeddings import Vector
from src.constants.kg import IdentificationParams, Node, Predicate
from src.core.search.entities import search_entities
from src.core.search.relationships import search_relationships
+from src.utils.vector_search import VectorSearchFacade
from src.services.api.constants.requests import (
GetContextRequestBody,
GetContextResponse,
@@ -33,6 +34,8 @@ from src.services.kg_agent.main import embeddings_adapter, vector_store_adapter
from src.utils.similarity.vectors import cosine_similarity
from src.utils.nlp.ner import _entity_extractor
+vector_search = VectorSearchFacade(vector_store_adapter)
+
async def retrieve_data(
text: str, limit: int, preferred_entities: str, brain_id: str = "default"
@@ -50,11 +53,15 @@ async def retrieve_data(
def _get_data():
text_embeddings = embeddings_adapter.embed_text(text)
- data_vectors = vector_store_adapter.search_vectors(
- text_embeddings.embeddings, "data", brain_id, limit
+ data_vectors = vector_search.search_data(
+ text_embeddings.embeddings,
+ brain_id=brain_id,
+ k=limit,
)
- triple_vectors = vector_store_adapter.search_vectors(
- text_embeddings.embeddings, "triplets", brain_id, limit
+ triple_vectors = vector_search.search_triplets(
+ text_embeddings.embeddings,
+ brain_id=brain_id,
+ k=limit,
)
search_result = data_adapter.search(text, brain_id)
@@ -400,8 +407,9 @@ async def get_context(request: GetContextRequestBody) -> GetContextResponse:
if text in embeddings_map:
return embeddings_map[text]
text_embeddings = embeddings_adapter.embed_text(text)
- data_vectors = vector_store_adapter.search_vectors(
- text_embeddings.embeddings, store="nodes", brain_id=request.brain_id
+ data_vectors = vector_search.search_nodes(
+ text_embeddings.embeddings,
+ brain_id=request.brain_id,
)
neighbors = graph_adapter.get_event_centric_neighbors(
[v.metadata.get("uuid") for v in data_vectors], brain_id=request.brain_id
diff --git a/src/services/mcp/main.py b/src/services/mcp/main.py
index 6c28c88..724d844 100644
--- a/src/services/mcp/main.py
+++ b/src/services/mcp/main.py
@@ -23,8 +23,10 @@ from src.core.instances import (
)
from src.lib.neo4j.client import _neo4j_client
from src.services.mcp.utils import guard_brainpat
+from src.utils.vector_search import VectorSearchFacade
auth_token_var: ContextVar[str | None] = ContextVar("auth_token", default=None)
+vector_search = VectorSearchFacade(vector_store_adapter)
mcp = FastMCP("brainapi-mcp", stateless_http=True, host="0.0.0.0")
@@ -71,8 +73,10 @@ def _search_semantically_sync(query: str, brain_id: str) -> Any:
if not guard_brainpat(auth_token_var.get(), brain_id):
return "Unauthorized"
query_embedding = embeddings_adapter.embed_text(query)
- data_vectors = vector_store_adapter.search_vectors(
- query_embedding.embeddings, store="nodes", brain_id=brain_id, k=5
+ data_vectors = vector_search.search_nodes(
+ query_embedding.embeddings,
+ brain_id=brain_id,
+ k=5,
)
triplets = graph_adapter.get_event_centric_neighbors(
[v.metadata.get("uuid") for v in data_vectors], brain_id=brain_id
diff --git a/src/utils/vector_search.py b/src/utils/vector_search.py
new file mode 100644
index 0000000..4216938
--- /dev/null
+++ b/src/utils/vector_search.py
@@ -0,0 +1,58 @@
+from src.adapters.embeddings import VectorStoreAdapter
+from src.constants.embeddings import Vector
+
+
+class VectorSearchFacade:
+ def __init__(self, vector_store: VectorStoreAdapter):
+ self._vector_store = vector_store
+
+ def search(
+ self,
+ data_vector: list[float],
+ *,
+ store: str,
+ brain_id: str = "default",
+ k: int = 10,
+ ) -> list[Vector]:
+ return self._vector_store.search_vectors(
+ data_vector,
+ store=store,
+ brain_id=brain_id,
+ k=k,
+ )
+
+ def search_nodes(
+ self,
+ data_vector: list[float],
+ *,
+ brain_id: str = "default",
+ k: int = 10,
+ ) -> list[Vector]:
+ return self.search(data_vector, store="nodes", brain_id=brain_id, k=k)
+
+ def search_triplets(
+ self,
+ data_vector: list[float],
+ *,
+ brain_id: str = "default",
+ k: int = 10,
+ ) -> list[Vector]:
+ return self.search(data_vector, store="triplets", brain_id=brain_id, k=k)
+
+ def search_relationships(
+ self,
+ data_vector: list[float],
+ *,
+ brain_id: str = "default",
+ k: int = 10,
+ ) -> list[Vector]:
+ return self.search(data_vector, store="relationships", brain_id=brain_id, k=k)
+
+ def search_data(
+ self,
+ data_vector: list[float],
+ *,
+ brain_id: str = "default",
+ k: int = 10,
+ ) -> list[Vector]:
+ return self.search(data_vector, store="data", brain_id=brain_id, k=k)
diff --git a/tests/test_architecture_refactors.py b/tests/test_architecture_refactors.py
index 102df56..6fcaccf 100644
--- a/tests/test_architecture_refactors.py
+++ b/tests/test_architecture_refactors.py
@@ -38,8 +38,11 @@ from src.adapters.embeddings import (
)
from src.adapters.graph import GraphAdapter
from src.constants.embeddings import Vector
+from src.constants.data import Observation, TextChunk
from src.core.agents.core.runtime_agent_factory import RuntimeAgentFactory
from src.services.api.controllers.entities import get_entity_status
+from src.services.api.controllers.retrieve import retrieve_data
+from src.utils.vector_search import VectorSearchFacade
def raise_embedding_error(*args, **kwargs):
@@ -191,7 +194,7 @@ class EntityStatusControllerTests(unittest.IsolatedAsyncioTestCase):
return_value=Vector(id="q", embeddings=[0.1, 0.2], metadata={}),
),
patch(
- "src.services.api.controllers.entities.vector_store_adapter.search_vectors",
+ "src.services.api.controllers.entities.vector_search.search_nodes",
return_value=[fake_vector],
),
patch(
@@ -206,5 +209,91 @@ class EntityStatusControllerTests(unittest.IsolatedAsyncioTestCase):
self.assertEqual(response.observations, [])
+class VectorSearchFacadeTests(unittest.TestCase):
+ def test_facade_routes_search_arguments_with_keywords(self):
+ class FakeVectorStore:
+ def __init__(self):
+ self.calls = []
+
+ def search_vectors(self, data_vector, brain_id, store, k=10):
+ self.calls.append(
+ {
+ "data_vector": data_vector,
+ "brain_id": brain_id,
+ "store": store,
+ "k": k,
+ }
+ )
+ return [Vector(id="v1", embeddings=[0.1], metadata={"uuid": "n1"})]
+
+ fake = FakeVectorStore()
+ facade = VectorSearchFacade(fake)
+ result = facade.search_nodes([0.1, 0.2], brain_id="brain-a", k=7)
+ self.assertEqual(result[0].id, "v1")
+ self.assertEqual(
+ fake.calls[0],
+ {
+ "data_vector": [0.1, 0.2],
+ "brain_id": "brain-a",
+ "store": "nodes",
+ "k": 7,
+ },
+ )
+
+
+class RetrieveControllerVectorSearchTests(unittest.IsolatedAsyncioTestCase):
+ async def test_retrieve_data_uses_store_specific_vector_search(self):
+ fake_data_chunk = TextChunk(text="chunk", brain_version="1.0.0")
+ fake_observation = Observation(text="obs", resource_id="r1")
+ fake_search_result = type(
+ "SearchResult",
+ (),
+ {
+ "text_chunks": [fake_data_chunk],
+ "observations": [fake_observation],
+ },
+ )()
+ fake_data_vector = type("FakeVector", (), {"metadata": {"resource_id": "r1"}})()
+ fake_triplet_vector = type(
+ "FakeVector", (), {"metadata": {"node_ids": ["n1"], "predicate": "RELATED_TO"}}
+ )()
+ with (
+ patch(
+ "src.services.api.controllers.retrieve.embeddings_adapter.embed_text",
+ return_value=Vector(id="q", embeddings=[0.1, 0.2], metadata={}),
+ ),
+ patch(
+ "src.services.api.controllers.retrieve.vector_search.search_data",
+ return_value=[fake_data_vector],
+ ) as search_data,
+ patch(
+ "src.services.api.controllers.retrieve.vector_search.search_triplets",
+ return_value=[fake_triplet_vector],
+ ) as search_triplets,
+ patch(
+ "src.services.api.controllers.retrieve.data_adapter.search",
+ return_value=fake_search_result,
+ ),
+ patch(
+ "src.services.api.controllers.retrieve.data_adapter.get_text_chunks_by_ids",
+ return_value=([], []),
+ ),
+ patch(
+ "src.services.api.controllers.retrieve.graph_adapter.get_nodes_by_uuid",
+ return_value=[],
+ ),
+ ):
+ response = await retrieve_data(
+ text="sample",
+ limit=6,
+ preferred_entities="Person,Company",
+ brain_id="brain-a",
+ )
+ search_data.assert_called_once_with([0.1, 0.2], brain_id="brain-a", k=6)
+ search_triplets.assert_called_once_with([0.1, 0.2], brain_id="brain-a", k=6)
+ self.assertEqual(len(response.data), 1)
+ self.assertEqual(len(response.observations), 1)
+
+
if __name__ == "__main__":
unittest.main()