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.

feat(search): pagination + search for relationships and entities

Christiande2620d3f2cc
diff --git a/src/adapters/graph.py b/src/adapters/graph.py
index bb093ba..cdc1ad6 100644
--- a/src/adapters/graph.py
+++ b/src/adapters/graph.py
@@ -10,7 +10,14 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
from typing import Optional, Tuple
from src.adapters.interfaces.graph import GraphClient
-from src.constants.kg import IdentificationParams, Node, Predicate, Triple
+from src.constants.kg import (
+ IdentificationParams,
+ Node,
+ Predicate,
+ SearchEntitiesResult,
+ SearchRelationshipsResult,
+ Triple,
+)
class GraphAdapter:
@@ -190,17 +197,47 @@ class GraphAdapter:
node=node, uuids=uuids, limit=limit, with_labels=with_labels
)
- def search_relationships(self, limit: int = 10, skip: int = 0) -> list[Triple]:
+ def search_relationships(
+ self,
+ limit: int = 10,
+ skip: int = 0,
+ relationship_types: Optional[list[str]] = None,
+ from_node_labels: Optional[list[str]] = None,
+ to_node_labels: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ query_search_target: Optional[str] = "all",
+ ) -> SearchRelationshipsResult:
"""
Search the relationships of the graph.
"""
- return self.graph.search_relationships(limit, skip)
+ relationship_uuids = []
+ # TODO: semantic search + src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py:165
+ return self.graph.search_relationships(
+ limit,
+ skip,
+ relationship_types,
+ from_node_labels,
+ to_node_labels,
+ relationship_uuids,
+ query_text,
+ query_search_target,
+ )
- def search_entities(self, limit: int = 10, skip: int = 0) -> list[Node]:
+ def search_entities(
+ self,
+ limit: int = 10,
+ skip: int = 0,
+ node_labels: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ ) -> SearchEntitiesResult:
"""
Search the entities of the graph.
"""
- return self.graph.search_entities(limit, skip)
+ node_uuids = []
+ # TODO: semantic search
+ return self.graph.search_entities(
+ limit, skip, node_labels, node_uuids, query_text
+ )
_graph_adapter = GraphAdapter()
diff --git a/src/adapters/interfaces/graph.py b/src/adapters/interfaces/graph.py
index e82d507..3abf31a 100644
--- a/src/adapters/interfaces/graph.py
+++ b/src/adapters/interfaces/graph.py
@@ -11,7 +11,13 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
from abc import ABC, abstractmethod
from typing import Optional, Tuple
-from src.constants.kg import IdentificationParams, Node, Predicate, Triple
+from src.constants.kg import (
+ IdentificationParams,
+ Node,
+ Predicate,
+ SearchEntitiesResult,
+ SearchRelationshipsResult,
+)
class GraphClient(ABC):
@@ -196,14 +202,34 @@ class GraphClient(ABC):
raise NotImplementedError("get_connected_nodes method not implemented")
@abstractmethod
- def search_relationships(self, limit: int = 10, skip: int = 0) -> list[Triple]:
+ def search_relationships(
+ self,
+ limit: int = 10,
+ skip: int = 0,
+ relationship_types: Optional[list[str]] = None,
+ from_node_labels: Optional[list[str]] = None,
+ to_node_labels: Optional[list[str]] = None,
+ relationship_uuids: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ query_search_target: Optional[
+ str
+ ] = "all", # Search into the relationship desc or node names or relationship desc
+ ) -> SearchRelationshipsResult:
"""
Search the relationships of the graph.
"""
raise NotImplementedError("search_relationships method not implemented")
@abstractmethod
- def search_entities(self, limit: int = 10, skip: int = 0) -> list[Node]:
+ def search_entities(
+ self,
+ limit: int = 10,
+ skip: int = 0,
+ node_labels: Optional[list[str]] = None,
+ node_uuids: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ ) -> SearchEntitiesResult:
"""
Search the entities of the graph.
"""
+ raise NotImplementedError("search_entities method not implemented")
diff --git a/src/constants/kg.py b/src/constants/kg.py
index 7fe58be..ea80b8f 100644
--- a/src/constants/kg.py
+++ b/src/constants/kg.py
@@ -111,3 +111,21 @@ class IdentificationParams(BaseModel):
)
model_config = ConfigDict(extra="allow")
+
+
+class SearchRelationshipsResult(BaseModel):
+ """
+ Search relationships result model.
+ """
+
+ results: List[Triple]
+ total: int
+
+
+class SearchEntitiesResult(BaseModel):
+ """
+ Search entities result model.
+ """
+
+ results: List[Node]
+ total: int
diff --git a/src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py b/src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py
index 8a5b4b0..700296b 100644
--- a/src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py
+++ b/src/core/agents/tools/kg_agent/KGAgentAddTripletsTool.py
@@ -162,6 +162,8 @@ class KGAgentAddTripletsTool(BaseTool):
triplet.object,
)
+ # TODO: save natural language relationship/predicate+s+o vector
+
# TODO: add changelog relationship created
return f"Triplets added successfully: {triplets}"
diff --git a/src/core/search/entities.py b/src/core/search/entities.py
index 2667d17..b026aa2 100644
--- a/src/core/search/entities.py
+++ b/src/core/search/entities.py
@@ -8,13 +8,19 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
-----
"""
-from src.constants.kg import Node
+from typing import Optional
+from src.constants.kg import SearchEntitiesResult
from src.services.kg_agent.main import graph_adapter
-def search_entities(limit: int = 10, skip: int = 0) -> list[Node]:
+def search_entities(
+ limit: int = 10,
+ skip: int = 0,
+ node_labels: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+) -> SearchEntitiesResult:
"""
Search the entities of the graph.
"""
- result = graph_adapter.search_entities(limit, skip)
+ result = graph_adapter.search_entities(limit, skip, node_labels, query_text)
return result
diff --git a/src/core/search/relationships.py b/src/core/search/relationships.py
index 622d892..47ce194 100644
--- a/src/core/search/relationships.py
+++ b/src/core/search/relationships.py
@@ -8,13 +8,30 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
-----
"""
-from src.constants.kg import Triple
+from typing import Optional
+from src.constants.kg import SearchRelationshipsResult
from src.services.kg_agent.main import graph_adapter
-def search_relationships(limit: int = 10, skip: int = 0) -> list[Triple]:
+def search_relationships(
+ limit: int = 10,
+ skip: int = 0,
+ relationship_types: Optional[list[str]] = None,
+ from_node_labels: Optional[list[str]] = None,
+ to_node_labels: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ query_search_target: Optional[str] = "all",
+) -> SearchRelationshipsResult:
"""
Search the relationships of the graph.
"""
- result = graph_adapter.search_relationships(limit, skip)
+ result = graph_adapter.search_relationships(
+ limit,
+ skip,
+ relationship_types,
+ from_node_labels,
+ to_node_labels,
+ query_text,
+ query_search_target,
+ )
return result
diff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.py
index 10f10e8..69b982c 100644
--- a/src/lib/neo4j/client.py
+++ b/src/lib/neo4j/client.py
@@ -13,7 +13,14 @@ from typing import Any, Optional, Tuple
from neo4j import GraphDatabase
from src.adapters.interfaces.graph import GraphClient
from src.config import config
-from src.constants.kg import IdentificationParams, Node, Predicate, Triple
+from src.constants.kg import (
+ IdentificationParams,
+ Node,
+ Predicate,
+ SearchEntitiesResult,
+ SearchRelationshipsResult,
+ Triple,
+)
from src.utils.logging import log
@@ -650,19 +657,79 @@ class Neo4jClient(GraphClient):
for record in result.records
]
- def search_relationships(self, limit: int = 10, skip: int = 0) -> list[Triple]:
+ def search_relationships(
+ self,
+ limit: int = 10,
+ skip: int = 0,
+ relationship_types: Optional[list[str]] = None,
+ from_node_labels: Optional[list[str]] = None,
+ to_node_labels: Optional[list[str]] = None,
+ relationship_uuids: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ query_search_target: Optional[str] = "all",
+ ) -> SearchRelationshipsResult:
"""
Search the relationships of the graph.
"""
+ filters = []
+ if relationship_types:
+ filters.append(
+ "type(r) IN [" + ",".join(f"'{t}'" for t in relationship_types) + "]"
+ )
+ if from_node_labels:
+ filters.append(
+ "ANY(lbl IN labels(n) WHERE lbl IN ["
+ + ",".join(
+ f"'{label}'" for label in self._clean_labels(from_node_labels)
+ )
+ + "])"
+ )
+ if to_node_labels:
+ filters.append(
+ "ANY(lbl IN labels(m) WHERE lbl IN ["
+ + ",".join(f"'{label}'" for label in self._clean_labels(to_node_labels))
+ + "])"
+ )
+ if relationship_uuids:
+ filters.append(
+ "r.uuid IN [" + ",".join(f"'{u}'" for u in relationship_uuids) + "]"
+ )
+ if query_text:
+ if query_search_target == "all":
+ filters.append(
+ f"(toLower(coalesce(n.name, n.Name, '')) CONTAINS toLower('{query_text}') OR "
+ f"toLower(coalesce(m.name, m.Name, '')) CONTAINS toLower('{query_text}') OR "
+ f"toLower(coalesce(r.description, r.Description, '')) CONTAINS toLower('{query_text}'))"
+ )
+ elif query_search_target == "node_name":
+ filters.append(f"toLower(n.name) CONTAINS toLower('{query_text}')")
+ elif query_search_target == "relationship_description":
+ filters.append(
+ f"toLower(r.description) CONTAINS toLower('{query_text}')"
+ )
+ elif query_search_target == "relationship_name":
+ filters.append(f"toLower(r.name) CONTAINS toLower('{query_text}')")
cypher_query = f"""
- MATCH (n)-[r]-(m)
- RETURN n.uuid as n_uuid, n.name as n_name, labels(n) as n_labels, n.description as n_description, properties(n) as n_properties,
- r as rel, type(r) as rel_type, r.description as rel_description,
- m.uuid as m_uuid, m.name as m_name, labels(m) as m_labels, m.description as m_description, properties(m) as m_properties
+ MATCH (n)-[r]->(m)
+ {"WHERE " + " AND ".join(filters) if filters else ""}
+ RETURN n.uuid AS n_uuid, n.name AS n_name, labels(n) AS n_labels,
+ n.description AS n_description, properties(n) AS n_properties,
+ r AS rel, type(r) AS rel_type, r.description AS rel_description,
+ m.uuid AS m_uuid, m.name AS m_name, labels(m) AS m_labels,
+ m.description AS m_description, properties(m) AS m_properties
SKIP {skip}
LIMIT {limit}
"""
+ cypher_count = """
+ MATCH ()-[r]-()
+ RETURN count(r) AS total
+ """
result = self.driver.execute_query(cypher_query)
+ count_result = self.driver.execute_query(cypher_count)
+ total = 0
+ if count_result and count_result.records:
+ total = count_result.records[0].get("total") or 0
+
triples: list[Triple] = []
for record in result.records:
relationship = record.get("rel")
@@ -745,19 +812,49 @@ class Neo4jClient(GraphClient):
),
)
)
- return triples
+ return SearchRelationshipsResult(results=triples, total=total)
- def search_entities(self, limit: int = 10, skip: int = 0) -> list[Node]:
+ def search_entities(
+ self,
+ limit: int = 10,
+ skip: int = 0,
+ node_labels: Optional[list[str]] = None,
+ node_uuids: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ ) -> SearchEntitiesResult:
"""
Search the entities of the graph.
"""
+ filters = []
+ if node_labels:
+ filters.append(
+ "ANY(lbl IN labels(n) WHERE lbl IN ["
+ + ",".join(f"'{label}'" for label in self._clean_labels(node_labels))
+ + "])"
+ )
+ if node_uuids:
+ filters.append(f"n.uuid IN [{','.join(node_uuids)}]")
+ if query_text:
+ filters.append(
+ f"(toLower(coalesce(n.name, n.Name, '')) CONTAINS toLower('{query_text}'))"
+ )
cypher_query = f"""
MATCH (n)
+ {"WHERE " + " AND ".join(filters) if filters else ""}
RETURN n.uuid as uuid, n.name as name, labels(n) as labels, n.description as description, properties(n) as properties
SKIP {skip}
LIMIT {limit}
"""
+ cypher_count = """
+ MATCH (n)
+ RETURN count(n) AS total
+ """
result = self.driver.execute_query(cypher_query)
+ count_result = self.driver.execute_query(cypher_count)
+ total = 0
+ if count_result and count_result.records:
+ total = count_result.records[0].get("total") or 0
+
nodes: list[Node] = []
for record in result.records:
properties_record = record.get("properties") or {}
@@ -784,7 +881,7 @@ class Neo4jClient(GraphClient):
properties=properties,
)
)
- return nodes
+ return SearchEntitiesResult(results=nodes, total=total)
_neo4j_client = Neo4jClient()
diff --git a/src/services/api/controllers/retrieve.py b/src/services/api/controllers/retrieve.py
index ecff7c6..99a0051 100644
--- a/src/services/api/controllers/retrieve.py
+++ b/src/services/api/controllers/retrieve.py
@@ -316,29 +316,55 @@ async def retrieve_neighbors_ai_mode(
return result
-async def get_relationships(limit: int = 10, skip: int = 0):
+async def get_relationships(
+ limit: int = 10,
+ skip: int = 0,
+ relationship_types: Optional[list[str]] = None,
+ from_node_labels: Optional[list[str]] = None,
+ to_node_labels: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ query_search_target: Optional[str] = "all",
+):
"""
Get the relationships of the graph.
"""
- relationships = await asyncio.to_thread(search_relationships, limit, skip)
+ relationships = await asyncio.to_thread(
+ search_relationships,
+ limit,
+ skip,
+ relationship_types,
+ from_node_labels,
+ to_node_labels,
+ query_text,
+ query_search_target,
+ )
return JSONResponse(
content={
"message": "Relationships retrieved successfully",
- "relationships": [r.model_dump(mode="json") for r in relationships],
+ "relationships": [r.model_dump(mode="json") for r in relationships.results],
+ "total": relationships.total,
}
)
-async def get_entities(limit: int = 10, skip: int = 0):
+async def get_entities(
+ limit: int = 10,
+ skip: int = 0,
+ node_labels: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+):
"""
Get the entities of the graph.
"""
- entities = await asyncio.to_thread(search_entities, limit, skip)
+ entities = await asyncio.to_thread(
+ search_entities, limit, skip, node_labels, query_text
+ )
return JSONResponse(
content={
"message": "Entities retrieved successfully",
- "entities": [e.model_dump(mode="json") for e in entities],
+ "entities": [e.model_dump(mode="json") for e in entities.results],
+ "total": entities.total,
}
)
diff --git a/src/services/api/routes/retrieve.py b/src/services/api/routes/retrieve.py
index 691f1df..d919265 100644
--- a/src/services/api/routes/retrieve.py
+++ b/src/services/api/routes/retrieve.py
@@ -8,6 +8,7 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
-----
"""
+from typing import Optional
from fastapi import APIRouter, Body, Query
from src.services.api.constants.requests import (
@@ -94,16 +95,45 @@ async def get_context(request):
@retrieve_router.get(path="/relationships")
-async def get_relationships(limit: int = 10, skip: int = 0):
+async def get_relationships(
+ limit: int = 10,
+ skip: int = 0,
+ relationship_types: Optional[str] = None,
+ from_node_labels: Optional[str] = None,
+ to_node_labels: Optional[str] = None,
+ query_text: Optional[str] = None,
+ query_search_target: Optional[str] = "all",
+):
"""
Get the relationships of the graph.
"""
- return await retrieve_get_relationships_controller(limit, skip)
+ if relationship_types:
+ relationship_types = relationship_types.split(",")
+ if from_node_labels:
+ from_node_labels = from_node_labels.split(",")
+ if to_node_labels:
+ to_node_labels = to_node_labels.split(",")
+ return await retrieve_get_relationships_controller(
+ limit,
+ skip,
+ relationship_types,
+ from_node_labels,
+ to_node_labels,
+ query_text,
+ query_search_target,
+ )
@retrieve_router.get(path="/entities")
-async def get_entities(limit: int = 10, skip: int = 0):
+async def get_entities(
+ limit: int = 10,
+ skip: int = 0,
+ node_labels: Optional[str] = None,
+ query_text: Optional[str] = None,
+):
"""
Get the entities of the graph.
"""
- return await retrieve_get_entities_controller(limit, skip)
+ if node_labels:
+ node_labels = node_labels.split(",")
+ return await retrieve_get_entities_controller(limit, skip, node_labels, query_text)