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(synergies): featured positive polarity sinergy retrieval

Christianc2c8eb059cc3
diff --git a/src/adapters/embeddings.py b/src/adapters/embeddings.py
index 7a82fc4..8dfc111 100644
--- a/src/adapters/embeddings.py
+++ b/src/adapters/embeddings.py
@@ -3,8 +3,8 @@ File: /embeddings.py
Created Date: Sunday October 19th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Sunday October 19th 2025 9:00:59 am
-Modified By: the developer formerly known as Christian Nonis at <[email protected]>
+Last Modified: Monday January 5th 2026 9:57:30 pm
+Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -83,7 +83,7 @@ class VectorStoreAdapter:
store: str,
min_similarity: float,
limit: int = 10,
- ) -> list[Vector]:
+ ) -> dict[str, list[Vector]]:
"""
Search similar vectors by their IDs.
"""
diff --git a/src/adapters/graph.py b/src/adapters/graph.py
index 58d2979..341c47e 100644
--- a/src/adapters/graph.py
+++ b/src/adapters/graph.py
@@ -531,5 +531,13 @@ class GraphAdapter:
"""
return self.graph.get_neighborhood(node, depth, brain_id)
+ 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.
+ """
+ return self.graph.get_next_by_flow_key(predicate_uuid, flow_key, brain_id)
+
_graph_adapter = GraphAdapter()
diff --git a/src/adapters/interfaces/embeddings.py b/src/adapters/interfaces/embeddings.py
index 469308e..68249e1 100644
--- a/src/adapters/interfaces/embeddings.py
+++ b/src/adapters/interfaces/embeddings.py
@@ -3,8 +3,8 @@ File: /embeddings.py
Created Date: Sunday October 19th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Sunday October 19th 2025 9:01:10 am
-Modified By: the developer formerly known as Christian Nonis at <[email protected]>
+Last Modified: Monday January 5th 2026 9:57:30 pm
+Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -64,7 +64,7 @@ class VectorStoreClient(ABC):
store: str,
min_similarity: float,
limit: int = 10,
- ) -> list[Vector]:
+ ) -> dict[str, list[Vector]]:
"""
Search similar vectors by their IDs.
"""
diff --git a/src/adapters/interfaces/graph.py b/src/adapters/interfaces/graph.py
index 2d11ced..a4002d1 100644
--- a/src/adapters/interfaces/graph.py
+++ b/src/adapters/interfaces/graph.py
@@ -410,3 +410,13 @@ class GraphClient(ABC):
Returns a nested structure where each neighbor contains its own neighbors.
"""
raise NotImplementedError("get_neighborhood method not implemented")
+
+ @abstractmethod
+ def get_next_by_flow_key(
+ self, predicate_uuid: str, flow_key: str, brain_id: str
+ ) -> List[Tuple[Node, Predicate, Node]]:
+ """
+ Get the next node by the flow key.
+ Returns a tuple where the first element is the connected node to the predicate, the second element is the next relationship by flow key and the third element is the next node.
+ """
+ raise NotImplementedError("get_next_by_flow_key method not implemented")
diff --git a/src/constants/kg.py b/src/constants/kg.py
index 4d91435..09ece84 100644
--- a/src/constants/kg.py
+++ b/src/constants/kg.py
@@ -9,7 +9,7 @@ Modified By: Christian Nonis <[email protected]>
"""
from datetime import datetime
-from typing import List, Literal, Optional
+from typing import List, Literal, Optional, Tuple
import uuid
from pydantic import BaseModel, ConfigDict, Extra, Field
@@ -151,3 +151,12 @@ class EntityInfo(BaseModel):
most_relevant_node: Node
relevant_nodes: List[Node]
+
+
+class EntitySynergy(BaseModel):
+ """
+ Entity synergy model.
+ """
+
+ node: Node
+ connected_by: Tuple[Node, Node]
diff --git a/src/core/search/entity_sibilings.py b/src/core/search/entity_sibilings.py
index d078a7c..9a31027 100644
--- a/src/core/search/entity_sibilings.py
+++ b/src/core/search/entity_sibilings.py
@@ -4,6 +4,117 @@ Created Date: Monday January 12th 2026
Author: Christian Nonis <[email protected]>
-----
Last Modified: Monday January 12th 2026 9:48:46 pm
-Modified By: the developer formerly known as Christian Nonis at <[email protected]>
+Modified By: Christian Nonis <[email protected]>
-----
"""
+
+from dataclasses import dataclass
+from typing import List, Literal, Tuple
+
+from src.constants.kg import EntitySynergy, Node
+from src.services.kg_agent.main import (
+ embeddings_adapter,
+ graph_adapter,
+ vector_store_adapter,
+)
+
+
+class EntitySinergyRetriever:
+ def __init__(self, brain_id: str = "default"):
+ self.brain_id = brain_id
+
+ def retrieve_sibilings(
+ self, target: str, polarity: Literal["same", "opposite"]
+ ) -> Tuple[Node, List[EntitySynergy]]:
+ """
+ Retrieve the siblings of an entity.
+ """
+ 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_id = target_node_vs[0].metadata.get("uuid")
+ target_node = graph_adapter.get_by_uuid(target_node_id, brain_id=self.brain_id)
+
+ if not target_node:
+ return None, []
+
+ _neighbors = graph_adapter.get_neighbors(
+ [target_node_id], brain_id=self.brain_id
+ )
+ neighbors = _neighbors[target_node_id]
+
+ positivep_connections: List[EntitySynergy] = []
+ seen_set = set()
+
+ for neighbor in neighbors:
+ similarity_seed_nodes = []
+
+ if "EVENT" in neighbor[1].labels:
+ flow_key = neighbor[0].flow_key or neighbor[0].properties.get(
+ "flow_key"
+ )
+ if not flow_key:
+ continue
+ next_rels = graph_adapter.get_next_by_flow_key(
+ neighbor[0].uuid, flow_key, brain_id=self.brain_id
+ )
+ similarity_seed_nodes.extend(t[2] for t in next_rels)
+ else:
+ similarity_seed_nodes.append(neighbor[1])
+
+ for similarity_seed_node in similarity_seed_nodes:
+ if target_node.labels in similarity_seed_node.labels:
+ positivep_connections.append(
+ EntitySynergy(
+ node=similarity_seed_node,
+ connected_by=(neighbor[1], neighbor[1]),
+ )
+ )
+ seen_set.add(similarity_seed_node.uuid)
+
+ similar_dict = vector_store_adapter.search_similar_by_ids(
+ [similarity_seed_node.properties["v_id"]],
+ brain_id=self.brain_id,
+ store="nodes",
+ min_similarity=0.5,
+ limit=10,
+ )
+ similar = similar_dict.get(similarity_seed_node.properties["v_id"], [])
+
+ for similar_node_v in similar:
+ # if similar_node_v.metadata["uuid"] == neighbor[1].uuid:
+ # continue
+ # if similar_node_v.metadata["uuid"] == similarity_seed_node.uuid:
+ # continue
+
+ similar_node_1 = graph_adapter.get_by_uuid(
+ similar_node_v.metadata["uuid"], brain_id=self.brain_id
+ )
+
+ if not similar_node_1:
+ continue
+
+ final_positivep_connection = graph_adapter.get_neighbors(
+ [similar_node_1.uuid],
+ brain_id=self.brain_id,
+ of_types=list(set(target_node.labels)),
+ )
+
+ for final_positivep_connection_tuple in final_positivep_connection[
+ similar_node_1.uuid
+ ]:
+ if final_positivep_connection_tuple[1].uuid in seen_set:
+ continue
+
+ seen_set.add(final_positivep_connection_tuple[1].uuid)
+
+ positivep_connections.append(
+ EntitySynergy(
+ node=final_positivep_connection_tuple[1],
+ connected_by=(similarity_seed_node, similar_node_1),
+ )
+ )
+
+ return target_node, positivep_connections
diff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.py
index 8ffc5e4..5d89c3f 100644
--- a/src/lib/neo4j/client.py
+++ b/src/lib/neo4j/client.py
@@ -588,10 +588,12 @@ class Neo4jClient(GraphClient):
cypher_query += """
RETURN n.uuid AS uuid, n.name AS name, labels(n) AS labels, n.description AS description, properties(n) AS properties, r AS rel,
CASE WHEN startNode(r) = n THEN 'out' ELSE 'in' END AS direction,
- type(r) AS rel_type, r.description AS rel_description, properties(r) AS rel_properties,
+ type(r) AS rel_type, r.description AS rel_description, properties(r) AS rel_properties, r.flow_key as rel_flowkey, r.uuid as rel_uuid,
c.uuid AS c_uuid, c.name AS c_name, labels(c) AS c_labels, c.description AS c_description, properties(c) AS c_properties
"""
-
+ print("========== cypher_query 1 ==========")
+ print(cypher_query, node_uuids, same_type_only, of_types)
+ print("========== cypher_query 1 ==========")
if limit:
cypher_query += f" LIMIT {limit}"
@@ -610,6 +612,8 @@ class Neo4jClient(GraphClient):
description=record.get("rel_description", "") or "",
direction=record.get("direction", "neutral"),
properties=record.get("rel_properties", {}) or {},
+ flow_key=record.get("rel_flowkey", "") or "",
+ uuid=record.get("rel_uuid", "") or "",
),
Node(
uuid=record.get("c_uuid", ""),
@@ -1434,5 +1438,54 @@ class Neo4jClient(GraphClient):
return neighbors
+ def get_next_by_flow_key(
+ self, predicate_uuid: str, flow_key: str, brain_id: str
+ ) -> List[Tuple[Node, Predicate, Node]]:
+ """
+ Get the next node by the flow key.
+ """
+ cypher_query = f"""
+ MATCH ()-[r]-(m)-[r2]-(b)
+ WHERE r.uuid = $predicate_uuid
+ AND r2.flow_key = $flow_key
+ RETURN
+ m.uuid as m_uuid, m.name as m_name, labels(m) as m_labels,
+ type(r2) as r2_type, r2.description as r2_description, properties(r2) as r2_properties,
+ CASE WHEN startNode(r2) = m THEN 'out' ELSE 'in' END AS r2_direction,
+ b.uuid as b_uuid, b.name as b_name, labels(b) as b_labels, b.description as b_description, properties(b) as b_properties
+ """
+ self.ensure_database(brain_id)
+ result = self.driver.execute_query(
+ cypher_query,
+ parameters_={
+ "predicate_uuid": predicate_uuid,
+ "flow_key": flow_key,
+ },
+ database_=brain_id,
+ )
+ return [
+ (
+ Node(
+ uuid=record.get("m_uuid", "") or "",
+ name=record.get("m_name", "") or "",
+ labels=record.get("m_labels", []) or [],
+ ),
+ Predicate(
+ name=record.get("r2_type", "") or "",
+ description=record.get("r2_description", "") or "",
+ direction=record.get("r2_direction", "neutral"),
+ properties=record.get("r2_properties", {}) or {},
+ ),
+ Node(
+ uuid=record.get("b_uuid", "") or "",
+ name=record.get("b_name", "") or "",
+ labels=record.get("b_labels", []) or [],
+ description=record.get("b_description", "") or "",
+ properties=record.get("b_properties", {}) or {},
+ ),
+ )
+ for record in result.records
+ ]
+
_neo4j_client = Neo4jClient()
diff --git a/src/services/api/constants/requests.py b/src/services/api/constants/requests.py
index d5d6933..b10da42 100644
--- a/src/services/api/constants/requests.py
+++ b/src/services/api/constants/requests.py
@@ -11,7 +11,7 @@ Modified By: Christian Nonis <[email protected]>
from typing import List, Any, Optional, Tuple
from pydantic import BaseModel, Field, field_serializer
from src.constants.data import Observation, TextChunk
-from src.constants.kg import IdentificationParams, Node, Predicate
+from src.constants.kg import EntitySynergy, IdentificationParams, Node, Predicate
from src.constants.tasks.ingestion import IngestionTaskArgs
from src.core.search.entity_info import MatchPath
@@ -244,3 +244,10 @@ class GetEntityContextResponse(BaseModel):
target_node: Optional[Node] = None
text_contexts: list[str] = []
natural_language_web: list[dict] = []
+
+
+class GetEntitySibilingsResponse(BaseModel):
+ """Response model for the get entity siblings endpoint."""
+
+ target_node: Node
+ synergies: List[EntitySynergy]
diff --git a/src/services/api/controllers/entities.py b/src/services/api/controllers/entities.py
index d864bce..031fcdf 100644
--- a/src/services/api/controllers/entities.py
+++ b/src/services/api/controllers/entities.py
@@ -9,12 +9,15 @@ Modified By: Christian Nonis <[email protected]>
-----
"""
+from typing import Literal
from src.core.search.entity_context import EntityContext
from src.core.search.entity_info import EventSynergyRetriever
from src.services.api.constants.requests import (
GetEntityInfoResponse,
GetEntityContextResponse,
+ GetEntitySibilingsResponse,
)
+from src.core.search.entity_sibilings import EntitySinergyRetriever
async def get_entity_info(
@@ -45,3 +48,19 @@ async def get_entity_context(
text_contexts=text_contexts,
natural_language_web=natural_language_web,
)
+
+
+async def get_entity_sibilings(
+ target: str,
+ polarity: Literal["same", "opposite"] = "same",
+ brain_id: str = "default",
+) -> GetEntitySibilingsResponse:
+ """
+ Get the entity siblings for a given target.
+ """
+ entity_sibilings = EntitySinergyRetriever(brain_id)
+ target_node, synergies = entity_sibilings.retrieve_sibilings(target, polarity)
+ return GetEntitySibilingsResponse(
+ target_node=target_node,
+ synergies=synergies,
+ )
diff --git a/src/services/api/routes/retrieve.py b/src/services/api/routes/retrieve.py
index 083297a..4a86af1 100644
--- a/src/services/api/routes/retrieve.py
+++ b/src/services/api/routes/retrieve.py
@@ -44,6 +44,7 @@ from src.services.api.controllers.changelogs import (
from src.services.api.controllers.entities import (
get_entity_info as get_entity_info_controller,
get_entity_context as get_entity_context_controller,
+ get_entity_sibilings as get_entity_sibilings_controller,
)
retrieve_router = APIRouter(prefix="/retrieve", tags=["retrieve"])
@@ -382,3 +383,15 @@ async def get_entity_context(
Get the entity context for a given target.
"""
return await get_entity_context_controller(target, context_depth, brain_id)
+
+
+@retrieve_router.get(path="/entity/synergies")
+async def get_entity_synergies(
+ target: str,
+ polarity: Literal["same", "opposite"] = "same",
+ brain_id: str = "default",
+):
+ """
+ Get the entity synergies for a given target.
+ """
+ return await get_entity_sibilings_controller(target, polarity, brain_id)