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
feat(synergies): featured positive polarity sinergy retrieval
Christianc2c8eb059cc3
diff --git a/src/adapters/embeddings.py b/src/adapters/embeddings.pyindex 7a82fc4..8dfc111 100644--- a/src/adapters/embeddings.py+++ b/src/adapters/embeddings.py@@ -3,8 +3,8 @@ File: /embeddings.pyCreated Date: Sunday October 19th 2025Author: 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.pyindex 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.pyindex 469308e..68249e1 100644--- a/src/adapters/interfaces/embeddings.py+++ b/src/adapters/interfaces/embeddings.py@@ -3,8 +3,8 @@ File: /embeddings.pyCreated Date: Sunday October 19th 2025Author: 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.pyindex 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.pyindex 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, Tupleimport uuidfrom pydantic import BaseModel, ConfigDict, Extra, Field@@ -151,3 +151,12 @@ class EntityInfo(BaseModel):most_relevant_node: Noderelevant_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.pyindex 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 2026Author: 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_connectionsdiff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.pyindex 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.pyindex 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, Tuplefrom pydantic import BaseModel, Field, field_serializerfrom src.constants.data import Observation, TextChunk-from src.constants.kg import IdentificationParams, Node, Predicate+from src.constants.kg import EntitySynergy, IdentificationParams, Node, Predicatefrom src.constants.tasks.ingestion import IngestionTaskArgsfrom src.core.search.entity_info import MatchPath@@ -244,3 +244,10 @@ class GetEntityContextResponse(BaseModel):target_node: Optional[Node] = Nonetext_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.pyindex 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 Literalfrom src.core.search.entity_context import EntityContextfrom src.core.search.entity_info import EventSynergyRetrieverfrom src.services.api.constants.requests import (GetEntityInfoResponse,GetEntityContextResponse,+ GetEntitySibilingsResponse,)+from src.core.search.entity_sibilings import EntitySinergyRetrieverasync 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.pyindex 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)