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.

wip(retrieval): neighbors

Christian648a6392eff0
diff --git a/src/adapters/embeddings.py b/src/adapters/embeddings.py
index 1c64a36..2106079 100644
--- a/src/adapters/embeddings.py
+++ b/src/adapters/embeddings.py
@@ -53,6 +53,22 @@ class VectorStoreAdapter:
"""
return self.vector_store.search_vectors(query, store, k)
+ def get_by_ids(self, ids: list[str], store: str) -> list[Vector]:
+ """
+ Get vectors by their IDs.
+ """
+ return self.vector_store.get_by_ids(ids, store)
+
+ def search_similar_by_ids(
+ self, vector_ids: list[str], store: str, min_similarity: float, limit: int = 10
+ ) -> list[Vector]:
+ """
+ Search similar vectors by their IDs.
+ """
+ return self.vector_store.search_similar_by_ids(
+ vector_ids, store, min_similarity, limit
+ )
+
_embeddings_adapter = EmbeddingsAdapter()
_vector_store_adapter = VectorStoreAdapter()
diff --git a/src/adapters/graph.py b/src/adapters/graph.py
index 9e7f184..98831c7 100644
--- a/src/adapters/graph.py
+++ b/src/adapters/graph.py
@@ -10,7 +10,7 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
from typing import Optional
from src.adapters.interfaces.graph import GraphClient
-from src.constants.kg import Node, Predicate
+from src.constants.kg import IdentificationParams, Node, Predicate
class GraphAdapter:
@@ -116,6 +116,18 @@ class GraphAdapter:
"""
return self.graph.get_graph_entities()
+ def get_graph_relationships(self) -> list[str]:
+ """
+ Get the relationships of the graph.
+ """
+ return self.graph.get_graph_relationships()
+
+ def get_graph_property_keys(self) -> list[str]:
+ """
+ Get the property keys of the graph.
+ """
+ return self.graph.get_graph_property_keys()
+
def get_by_uuid(self, uuid: str) -> Node:
"""
Get a node by its UUID.
@@ -128,5 +140,23 @@ class GraphAdapter:
"""
return self.graph.get_by_uuids(uuids)
+ def get_by_identification_params(
+ self,
+ identification_params: IdentificationParams,
+ entity_types: Optional[list[str]] = None,
+ ) -> Node:
+ """
+ Get a node by its identification params and entity types.
+ """
+ return self.graph.get_by_identification_params(
+ identification_params, entity_types
+ )
+
+ def get_neighbors(self, node: Node, limit: int) -> list[Node]:
+ """
+ Get the neighbors of a node.
+ """
+ return self.graph.get_neighbors(node, limit)
+
_graph_adapter = GraphAdapter()
diff --git a/src/adapters/interfaces/embeddings.py b/src/adapters/interfaces/embeddings.py
index f8ca339..9d10895 100644
--- a/src/adapters/interfaces/embeddings.py
+++ b/src/adapters/interfaces/embeddings.py
@@ -44,3 +44,19 @@ class VectorStoreClient(ABC):
Search vectors in the vector store and return the top k vectors.
"""
raise NotImplementedError("search_vectors method not implemented")
+
+ @abstractmethod
+ def get_by_ids(self, ids: list[str], store: str) -> list[Vector]:
+ """
+ Get vectors by their IDs.
+ """
+ raise NotImplementedError("get_by_ids method not implemented")
+
+ @abstractmethod
+ def search_similar_by_ids(
+ self, vector_ids: list[str], store: str, min_similarity: float, limit: int = 10
+ ) -> list[Vector]:
+ """
+ Search similar vectors by their IDs.
+ """
+ raise NotImplementedError("search_similar_by_ids method not implemented")
diff --git a/src/adapters/interfaces/graph.py b/src/adapters/interfaces/graph.py
index 642b929..e7e9673 100644
--- a/src/adapters/interfaces/graph.py
+++ b/src/adapters/interfaces/graph.py
@@ -11,7 +11,7 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
from abc import ABC, abstractmethod
from typing import Optional
-from src.constants.kg import Node, Predicate
+from src.constants.kg import IdentificationParams, Node, Predicate
class GraphClient(ABC):
@@ -105,6 +105,20 @@ class GraphClient(ABC):
"""
raise NotImplementedError("get_graph_entities method not implemented")
+ @abstractmethod
+ def get_graph_relationships(self) -> list[str]:
+ """
+ Get the relationships of the graph.
+ """
+ raise NotImplementedError("get_graph_relationships method not implemented")
+
+ @abstractmethod
+ def get_graph_property_keys(self) -> list[str]:
+ """
+ Get the property keys of the graph.
+ """
+ raise NotImplementedError("get_graph_property_keys method not implemented")
+
@abstractmethod
def get_by_uuid(
self,
@@ -124,3 +138,25 @@ class GraphClient(ABC):
Get nodes by their UUIDs.
"""
raise NotImplementedError("get_by_uuids method not implemented")
+
+ @abstractmethod
+ def get_by_identification_params(
+ self,
+ identification_params: IdentificationParams,
+ entity_types: Optional[list[str]] = None,
+ ) -> Node:
+ """
+ Get a node by its identification params.
+ """
+ raise NotImplementedError("get_by_identification_params method not implemented")
+
+ @abstractmethod
+ def get_neighbors(
+ self,
+ node: Node,
+ limit: int,
+ ) -> list[Node]:
+ """
+ Get the neighbors of a node.
+ """
+ raise NotImplementedError("get_neighbors method not implemented")
diff --git a/src/constants/kg.py b/src/constants/kg.py
index c04acea..519226a 100644
--- a/src/constants/kg.py
+++ b/src/constants/kg.py
@@ -52,6 +52,11 @@ class Predicate(BaseModel):
default=False, description="Whether the predicate is deprecated."
)
+ direction: Optional[Literal["in", "out"]] = Field(
+ default="out",
+ description="The direction of the predicate.",
+ )
+
class Triple(BaseModel):
"""
@@ -80,6 +85,10 @@ class IdentificationParams(BaseModel):
"""
name: str
+ entity_types: List[str] = Field(
+ default=[],
+ description="The types of the entity to identify.",
+ )
class Meta:
"""
diff --git a/src/constants/output_schemas.py b/src/constants/output_schemas.py
new file mode 100644
index 0000000..26934d6
--- /dev/null
+++ b/src/constants/output_schemas.py
@@ -0,0 +1,30 @@
+"""
+File: /output_schemas.py
+Created Date: Wednesday October 29th 2025
+Author: Christian Nonis <[email protected]>
+-----
+Last Modified: Wednesday October 29th 2025 7:50:18 pm
+Modified By: the developer formerly known as Christian Nonis at <[email protected]>
+-----
+"""
+
+from pydantic import BaseModel, Field
+
+
+class KGNeighbor(BaseModel):
+ """
+ Neighbor model.
+ """
+
+ uuid: str = Field(description="The UUID of the neighbor.")
+ similarities: list[str] = Field(
+ description="A list of string reasons that explain why the nodes are similar."
+ )
+
+
+class RetrieveNeighborsOutputSchema(BaseModel):
+ """
+ Output schema for the retrieve neighbors operation.
+ """
+
+ neighbors: list[KGNeighbor]
diff --git a/src/constants/prompts/kg_agent.py b/src/constants/prompts/kg_agent.py
index 5fb1e91..1c04e8f 100644
--- a/src/constants/prompts/kg_agent.py
+++ b/src/constants/prompts/kg_agent.py
@@ -91,5 +91,63 @@ Your workflow must be as follows:
4. Edit your original triplet to match any existing nodes in the knowledge graph.
5. Call the tool to add the triplet to the knowledge graph.
+{extra_system_prompt}
+
Begin!
"""
+
+KG_AGENT_RETRIEVE_NEIGHBORS_PROMPT = """
+You are a knowledge graph agent specialized in retrieving nodes similar to a given node.
+
+This is the main node you are looking for neighbors for:
+{main_node}
+
+{looking_for}
+
+You have a tool at your disposal to execute graph operations
+and search the knowledge graph for similar nodes of the same category type (same labels).
+
+You must return only the neighbors that are similar to the main node with the same category type (same labels),
+not any other nodes.
+
+The maximum number of neighbors you are looking for is: {limit}
+
+You must start by understanding the information about the main node and than start searching
+the knowledge graph for similar nodes. The similar nodes must share some information and not just be
+considered similar if they share only labels or generic information.
+
+You must operate as follows:
+1. Carefully read and understand the information about the main node.
+2. Start by looking what relationships and nodes are connected to the main node and what information they contain.
+3. If you already found some similar nodes, start considering them as return result.
+4. Continue if you haven't found the requested number of neighbors to look for nodes connected to the neighbors.
+5. Continue to surf the knowledge graph until you have found the requested number of neighbors.
+6. Return the neighbors found.
+
+Your output bust be a json object with a neighbors field that contains a list of neighbors.
+Each neighbor must be a json object with the uuid of the neighbor and a similarities fiels,
+that will be a list of string reasons that explain why the nodes are similar.
+
+Example output:
+{{
+ "neighbors": [
+ {{
+ "uuid": "123",
+ "similarities": [
+ "They both are interested in war politics since they ...",
+ "Both have graduated from UC Berkeley.",
+ "Both are interested in the same type of music and have attended at ...",
+ ]
+ }},
+ ...
+ {{
+ "uuid": "456",
+ "similarities": [
+ "The datacenters are located in the same country and are built considering the same ...",
+ "The tecnology used is the same and the teams faced ...",
+ ...
+ ]
+ }}
+ ]
+}}
+"""
diff --git a/src/core/agents/kg_agent.py b/src/core/agents/kg_agent.py
index d9dfcb8..9f0020d 100644
--- a/src/core/agents/kg_agent.py
+++ b/src/core/agents/kg_agent.py
@@ -11,18 +11,22 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
from typing import List, Optional
from langchain.agents import create_agent
from langchain.tools import BaseTool
+from pydantic import BaseModel
from src.adapters.cache import CacheAdapter
from src.adapters.graph import GraphAdapter
from src.adapters.llm import LLMAdapter
from src.constants.kg import Node
+from src.constants.output_schemas import RetrieveNeighborsOutputSchema
from src.constants.prompts.kg_agent import (
+ KG_AGENT_RETRIEVE_NEIGHBORS_PROMPT,
KG_AGENT_SYSTEM_PROMPT,
KG_AGENT_UPDATE_PROMPT,
KG_AGENT_UPDATE_STRUCTURED_PROMPT,
)
from src.core.agents.tools.kg_agent import (
KGAgentAddTripletsTool,
+ KGAgentExecuteGraphOperationTool,
KGAgentSearchGraphTool,
)
from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter
@@ -41,6 +45,7 @@ class KGAgent:
kg: GraphAdapter,
vector_store: VectorStoreAdapter,
embeddings: EmbeddingsAdapter,
+ database_desc: str,
):
self.llm_adapter = llm_adapter
self.cache_adapter = cache_adapter
@@ -48,6 +53,7 @@ class KGAgent:
self.vector_store = vector_store
self.embeddings = embeddings
self.agent = None
+ self.database_desc = database_desc
def _execute_graph_operation(self, operation: str) -> str:
try:
@@ -81,13 +87,23 @@ class KGAgent:
),
]
- def _get_agent(self, identification_params: dict, metadata: dict):
- system_prompt = KG_AGENT_SYSTEM_PROMPT
+ def _get_agent(
+ self,
+ identification_params: dict,
+ metadata: dict,
+ tools: Optional[List[BaseTool]] = None,
+ output_schema: Optional[BaseModel] = None,
+ extra_system_prompt: Optional[dict] = None,
+ ):
+ system_prompt = KG_AGENT_SYSTEM_PROMPT.format(
+ extra_system_prompt=extra_system_prompt if extra_system_prompt else ""
+ )
self.agent = create_agent(
model=self.llm_adapter.llm.langchain_model,
- tools=self._get_tools(identification_params, metadata),
+ tools=tools if tools else self._get_tools(identification_params, metadata),
system_prompt=system_prompt,
+ response_format=output_schema if output_schema else None,
)
def search_kg(self, query: str) -> str:
@@ -159,3 +175,65 @@ class KGAgent:
config={"recursion_limit": 50},
)
return response
+
+ def retrieve_neighbors(
+ self, node: Node, looking_for: Optional[str], limit: int
+ ) -> RetrieveNeighborsOutputSchema:
+ """
+ Retrieve the neighbors of a node.
+ """
+
+ graph_db_prop_keys = self.kg.get_graph_property_keys()
+ graph_db_relationships = self.kg.get_graph_relationships()
+ graph_db_entities = self.kg.get_graph_entities()
+
+ print("[graph_db_prop_keys]", graph_db_prop_keys)
+ print("[graph_db_relationships]", graph_db_relationships)
+ print("[graph_db_entities]", graph_db_entities)
+
+ extra_system_prompt_str = f"""
+ The following are the information and schemas about the db, you must only use the following information to operate with the db:
+ {{
+ "property_keys": {graph_db_prop_keys},
+ "relationships": {graph_db_relationships},
+ "entities": {graph_db_entities},
+ }}
+ """
+
+ self._get_agent(
+ identification_params={},
+ metadata={},
+ tools=[
+ KGAgentExecuteGraphOperationTool(
+ self,
+ self.kg,
+ self.database_desc,
+ )
+ ],
+ output_schema=RetrieveNeighborsOutputSchema,
+ extra_system_prompt=extra_system_prompt_str,
+ )
+
+ looking_for_prompt = f"""
+ You must look for neighbors for the main node considering this reasons:
+ {" ".join([f"- {reason}" for reason in looking_for])}
+ """
+
+ _response = self.agent.invoke(
+ {
+ "messages": [
+ {
+ "role": "user",
+ "content": KG_AGENT_RETRIEVE_NEIGHBORS_PROMPT.format(
+ main_node=node, looking_for=looking_for_prompt, limit=limit
+ ),
+ }
+ ],
+ },
+ config={"recursion_limit": 50},
+ print_mode="debug",
+ )
+
+ response = _response.get("structured_response")
+
+ return response
diff --git a/src/lib/milvus/client.py b/src/lib/milvus/client.py
index 783b692..8ba2149 100644
--- a/src/lib/milvus/client.py
+++ b/src/lib/milvus/client.py
@@ -158,5 +158,86 @@ class MilvusClient(VectorStoreClient):
Vector(id=result["id"], metadata=result["entity"]) for result in collection
]
+ def search_similar_by_ids(
+ self,
+ vector_ids: list[str],
+ store: str,
+ min_similarity: float,
+ limit: int = 10,
+ ) -> dict[str, list[Vector]]:
+ self._ensure_store(store)
+ try:
+ self.client.load_collection(store)
+ except Exception:
+ pass
+
+ if not vector_ids:
+ return {}
+
+ expr = "uuid in [" + ",".join(f"'{v}'" for v in vector_ids) + "]"
+ queried = self.client.query(
+ collection_name=store,
+ filter=expr,
+ output_fields=["embeddings", "$meta"],
+ )
+ id_to_emb: dict[str, list[float]] = {}
+
+ for item in queried or []:
+ emb = item.get("embeddings") or item.get("embeddings")
+ uuid = item.get("uuid")
+ if emb is not None and uuid:
+ id_to_emb[uuid] = emb
+
+ data_batch = [id_to_emb.get(v_id) for v_id in vector_ids]
+ if not any(data_batch):
+ return {v_id: [] for v_id in vector_ids}
+
+ batch_indices = [i for i, emb in enumerate(data_batch) if emb is not None]
+ batch_embeddings = [data_batch[i] for i in batch_indices]
+ batch_ids = [vector_ids[i] for i in batch_indices]
+
+ out: dict[str, list[Vector]] = {v_id: [] for v_id in vector_ids}
+ chunk_size = 10
+ for start in range(0, len(batch_embeddings), chunk_size):
+ end = start + chunk_size
+ chunk_embeddings = batch_embeddings[start:end]
+ chunk_ids = batch_ids[start:end]
+
+ raw_results = self.client.search(
+ collection_name=store,
+ data=chunk_embeddings,
+ limit=max(limit * 5, limit),
+ output_fields=["$meta"],
+ )
+
+ for idx, query_results in enumerate(raw_results or []):
+ origin_uuid = chunk_ids[idx]
+ if out.get(origin_uuid):
+ continue
+
+ collected: list[Vector] = []
+ for r in query_results or []:
+ r_entity = r.get("entity", {})
+ if r_entity.get("uuid") == origin_uuid:
+ continue
+ sim = 1.0 - float(r.get("distance", 0.0))
+ if sim >= min_similarity:
+ collected.append(
+ Vector(
+ id=str(r["id"]),
+ metadata={
+ k: v
+ for k, v in r.get("entity", {}).items()
+ if k not in ["id", "embeddings", "distance"]
+ },
+ distance=r["distance"],
+ )
+ )
+ if len(collected) >= limit:
+ break
+ out[origin_uuid] = collected
+
+ return out
+
_milvus_client = MilvusClient()
diff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.py
index 5b15a95..c6253ae 100644
--- a/src/lib/neo4j/client.py
+++ b/src/lib/neo4j/client.py
@@ -8,11 +8,11 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
-----
"""
-from typing import Optional
+from typing import Optional, Tuple
from neo4j import GraphDatabase
from src.adapters.interfaces.graph import GraphClient
from src.config import config
-from src.constants.kg import Node, Predicate
+from src.constants.kg import IdentificationParams, Node, Predicate
class Neo4jClient(GraphClient):
@@ -67,6 +67,22 @@ class Neo4jClient(GraphClient):
"""
return "The graph database is Neo4j. Cyphter is the language used to operate with it."
+ def _clean_labels(self, labels: list[str]) -> list[str]:
+ """
+ Clean a label to be used in a Cypher query.
+ """
+ return [
+ label.replace(" ", "_").upper().replace("-", "_").replace(".", "_")
+ for label in labels
+ ]
+
+ def _clean_property_key(self, property_key: str) -> str:
+ """
+ Clean a property key to be used in a Cypher query.
+ """
+ words = property_key.split()
+ return "".join(word.capitalize() for word in words)
+
def add_nodes(
self,
nodes: list[Node],
@@ -96,7 +112,11 @@ class Neo4jClient(GraphClient):
char in sanitized_key
for char in ["-", " ", ".", "+", "*", "/", "%", ":", "@", "#", "$"]
)
- cypher_key = f"`{sanitized_key}`" if needs_quoting else sanitized_key
+ cypher_key = (
+ f"`{self._clean_property_key(sanitized_key)}`"
+ if needs_quoting
+ else self._clean_property_key(sanitized_key)
+ )
if isinstance(value, str):
escaped_value = value.replace("'", "\\'")
@@ -113,9 +133,7 @@ class Neo4jClient(GraphClient):
properties_set = f"{', '.join(property_assignments)}"
- labels_expression = ":".join(
- label.replace(" ", "_") for label in node.labels
- )
+ labels_expression = ":".join(self._clean_labels(node.labels))
cypher_query = f"""
MERGE (n:{labels_expression} {identification_set})
SET {properties_set}
@@ -148,9 +166,9 @@ class Neo4jClient(GraphClient):
safe_desc = predicate.description.replace("'", "\\'")
cypher_query = f"""
- MATCH (a:{":".join([lb.replace(" ", "") for lb in subject.labels])}) WHERE a.name = '{subject.name}'
- MATCH (b:{":".join([lb.replace(" ", "") for lb in to_object.labels])}) WHERE b.name = '{to_object.name}'
- CREATE (a)-[:{predicate.name.replace(" ", "_").replace("-", "_").upper()} {{ description: '{safe_desc}' }}]->(b)
+ MATCH (a:{":".join(self._clean_labels(subject.labels))}) WHERE a.name = '{subject.name}'
+ MATCH (b:{":".join(self._clean_labels(to_object.labels))}) WHERE b.name = '{to_object.name}'
+ CREATE (a)-[:{":".join(self._clean_labels([predicate.name]))} {{ description: '{safe_desc}' }}]->(b)
RETURN a, b
"""
result = self.driver.execute_query(cypher_query)
@@ -165,7 +183,7 @@ class Neo4jClient(GraphClient):
queries = []
for node in nodes:
- query = f"""MATCH (n:{":".join(node.labels)}) WHERE n.name = '{node.name}'
+ query = f"""MATCH (n:{":".join(self._clean_labels(node.labels))}) WHERE n.name = '{node.name}'
OPTIONAL MATCH (n)-[r*1]-(m)
RETURN n, r, m"""
queries.append(query)
@@ -222,7 +240,7 @@ class Neo4jClient(GraphClient):
"""
if preferred_labels and len(preferred_labels) > 0:
cypher_query += f"""
- WHERE any(lbl IN labels(m) WHERE lbl IN ["{'","'.join(preferred_labels)}"])
+ WHERE any(lbl IN labels(m) WHERE lbl IN ["{'","'.join(self._clean_labels(preferred_labels))}"])
"""
cypher_query += """
WITH n, r, m
@@ -276,6 +294,17 @@ class Neo4jClient(GraphClient):
result = self.driver.execute_query(cypher_query)
return [label for record in result.records for label in record["labels"]]
+ def get_graph_relationships(self) -> list[str]:
+ """
+ Get the relationships of the graph.
+ """
+ cypher_query = """
+ CALL db.relationshipTypes() YIELD relationshipType
+ RETURN relationshipType
+ """
+ result = self.driver.execute_query(cypher_query)
+ return [record["relationshipType"] for record in result.records]
+
def get_by_uuid(self, uuid: str) -> Node:
"""
Get a node by its UUID.
@@ -317,5 +346,106 @@ class Neo4jClient(GraphClient):
for record in result.records
]
+ def get_by_identification_params(
+ self,
+ identification_params: IdentificationParams,
+ entity_types: Optional[list[str]] = None,
+ ) -> Node:
+ """
+ Get a node by its identification params and entity types.
+ """
+
+ params_dict = identification_params.model_dump(
+ mode="json", exclude={"entity_types"}
+ )
+
+ where_clauses = []
+
+ for key, value in params_dict.items():
+ where_clauses.append(f"n.{key} = '{value}'")
+
+ cypher_query = f"""
+ MATCH (n{(":" + ":".join(self._clean_labels(entity_types))) if entity_types else ""}) {("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""}
+ RETURN n.uuid as uuid, n.name as name, labels(n) as labels, n.description as description, properties(n) as properties
+ """
+ result = self.driver.execute_query(cypher_query)
+ return (
+ Node(
+ uuid=result.records[0]["uuid"],
+ name=result.records[0]["name"],
+ labels=result.records[0]["labels"],
+ description=result.records[0]["description"],
+ properties=result.records[0]["properties"],
+ )
+ if result.records
+ else None
+ )
+
+ def get_graph_property_keys(self) -> list[str]:
+ """
+ Get the property keys of the graph.
+ """
+ cypher_query = """
+ CALL db.propertyKeys() YIELD propertyKey
+ RETURN propertyKey
+ """
+ result = self.driver.execute_query(cypher_query)
+ return [record["propertyKey"] for record in result.records]
+
+ def get_neighbors(self, node: Node, limit: int) -> list[Tuple[Node, Predicate]]:
+ """
+ Get the neighbors of a node.
+ """
+ print("[node]", node.uuid, node.labels)
+ cypher_query = f"""
+ MATCH (n {{uuid: '{node.uuid}'}})-[r]-(c)-[r2]-(m)
+ WHERE size([l IN labels(n) WHERE l IN labels(m)]) > 0
+ RETURN m.uuid AS uuid, m.name AS name, labels(m) AS labels, m.description AS description, properties(m) AS properties, r2 AS rel
+ """
+ result = self.driver.execute_query(cypher_query)
+
+ neighbors = []
+ for record in result.records:
+ rel = record["rel"]
+ rel_type = getattr(rel, "type", None)
+ rel_desc = ""
+ try:
+ rel_desc = rel.get("description", "") # for mapping-like access
+ except Exception:
+ try:
+ rel_desc = rel["description"]
+ except Exception:
+ rel_desc = ""
+ direction = "out"
+ try:
+ start_node = rel.nodes[0]
+ start_uuid = None
+ try:
+ start_uuid = start_node.get("uuid", None)
+ except Exception:
+ start_uuid = start_node["uuid"]
+ if start_uuid != node.uuid:
+ direction = "in"
+ except Exception:
+ direction = "out"
+
+ neighbors.append(
+ (
+ Node(
+ uuid=record["uuid"],
+ name=record["name"],
+ labels=record["labels"],
+ description=record["description"],
+ properties=record["properties"],
+ ),
+ Predicate(
+ name=rel_type or "",
+ description=rel_desc or "",
+ direction=direction,
+ ),
+ )
+ )
+ return neighbors
+
_neo4j_client = Neo4jClient()
diff --git a/src/services/api/constants/requests.py b/src/services/api/constants/requests.py
index bc955a8..e24424c 100644
--- a/src/services/api/constants/requests.py
+++ b/src/services/api/constants/requests.py
@@ -8,6 +8,7 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
-----
"""
+from turtle import st
from typing import List, Any, Optional
from pydantic import BaseModel, Field, field_serializer
from src.constants.data import Observation, TextChunk
@@ -137,3 +138,31 @@ class RetrieveNeighborsRequestResponse(BaseModel):
"""
neighbors: List[RetrievedNeighborNode]
+
+
+class RetrieveNeighborsAiModeRequestBody(BaseModel):
+ """
+ Request body for the retrieve neighbors AI mode endpoint.
+ """
+
+ identification_params: IdentificationParams = Field(
+ ...,
+ description="The identification parameters of the entity to get neighbors for.",
+ )
+ limit: int = Field(10, description="The number of neighbors to return.")
+ looking_for: Optional[list[str]] = Field(
+ ...,
+ description="The description of the neighbors to look for.",
+ )
+
+
+class RetrieveNeighborsWithIdentificationParamsRequestBody(BaseModel):
+ """
+ Request body for the retrieve neighbors with identification params endpoint.
+ """
+
+ identification_params: IdentificationParams = Field(
+ ...,
+ description="The identification parameters of the entity to get neighbors for.",
+ )
+ limit: int = Field(10, description="The number of neighbors to return.")
diff --git a/src/services/api/controllers/retrieve.py b/src/services/api/controllers/retrieve.py
index 47824ad..efac318 100644
--- a/src/services/api/controllers/retrieve.py
+++ b/src/services/api/controllers/retrieve.py
@@ -9,17 +9,17 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
"""
import asyncio
-import json
+from typing import Optional
from fastapi import HTTPException
-from src.constants.kg import Node, Predicate, Relationship
+from src.constants.kg import IdentificationParams, Predicate, Relationship
from src.services.api.constants.requests import (
RetrieveRequestResponse,
RetrieveNeighborsRequestResponse,
RetrievedNeighborNode,
)
-from src.services.kg_agent.main import graph_adapter
+from src.services.kg_agent.main import graph_adapter, kg_agent
from src.services.data.main import data_adapter
from src.services.kg_agent.main import embeddings_adapter, vector_store_adapter
@@ -85,52 +85,111 @@ async def retrieve_data(
)
-async def retrieve_neighbors(uuid: str, limit: int) -> RetrieveNeighborsRequestResponse:
+async def retrieve_neighbors(
+ uuid: Optional[str] = None,
+ identification_params: Optional[IdentificationParams] = None,
+ limit: int = 10,
+) -> RetrieveNeighborsRequestResponse:
+ def _get_neighbors():
+ node = None
+ if uuid:
+ node = graph_adapter.get_by_uuid(uuid)
+ elif identification_params:
+ node = graph_adapter.get_by_identification_params(
+ identification_params, entity_types=identification_params.entity_types
+ )
+ if not node:
+ raise HTTPException(status_code=404, detail="Entity not found")
+
+ raw = graph_adapter.get_neighbors(node, limit)
+
+ normalized = []
+ for item in raw:
+ if isinstance(item, tuple) and len(item) >= 2:
+ n, pred = item[0], item[1]
+ else:
+ n, pred = item, None
+
+ if isinstance(pred, Predicate):
+ relation = Relationship(
+ direction=pred.direction or "out", predicate=pred
+ )
+ else:
+ relation = Relationship(
+ direction="out",
+ predicate=Predicate(name="RELATED_TO", description=""),
+ )
+
+ if not n.uuid == node.uuid:
+ # TODO: provide the common node too and maybe also observations
+ normalized.append(
+ RetrievedNeighborNode(
+ **n.model_dump(),
+ relation=relation,
+ observations=[],
+ )
+ )
+
+ if len(normalized) < limit:
+ neighbor_nodes = graph_adapter.get_nodes_by_uuid(
+ uuids=[n.uuid for n in normalized], with_relationships=True
+ )
+ v_neighbors = vector_store_adapter.search_similar_by_ids(
+ vector_ids=[n.get("node").uuid for n in neighbor_nodes],
+ store="nodes",
+ min_similarity=0.5,
+ limit=limit - len(normalized),
+ )
+ print("[v_neighbors]", v_neighbors)
+ # TODO: get v_neighbor nodes by ids and the k (the common)
+ # TODO + push to normalized
+ # TODO (directly the nodes with label same as main, the others search for neighbors with same label of main)
+
+ if len(normalized) < limit:
+ v_data = vector_store_adapter.search_similar_by_ids(
+ vector_ids=[n.uuid for n in normalized],
+ store="data",
+ min_similarity=0.5,
+ limit=limit - len(normalized),
+ )
+ print("[v_data]", v_data)
+ # TODO: get v_neighbor nodes by ids and the k (the common)
+ # TODO + push to normalized
+ # TODO (directly the nodes with label same as main, the others search for neighbors with same label of main)
+
+ return RetrieveNeighborsRequestResponse(neighbors=normalized)
+
+ return await asyncio.to_thread(_get_neighbors)
+
+
+async def retrieve_neighbors_ai_mode(
+ identification_params: IdentificationParams,
+ looking_for: Optional[list[str]],
+ limit: int,
+) -> RetrieveNeighborsRequestResponse:
"""
Retrieve neighbors of an entity from the knowledge graph.
"""
- node = graph_adapter.get_by_uuid(uuid)
- if not node:
- raise HTTPException(status_code=404, detail="Entity not found")
- results = graph_adapter.get_nodes_by_uuid(
- uuids=[node.uuid],
- with_relationships=True,
- relationships_depth=5,
- # preferred_labels=[node.label],
- )
- neighbors = []
-
- for result in results:
- related_node = result.get("related_nodes")
- relationships = result.get("relationships")
-
- if not related_node or not relationships:
- continue
-
- relationship = relationships[0] if relationships else None
-
- neighbor_node = RetrievedNeighborNode(
- uuid=related_node.get("uuid"),
- name=related_node.get("name"),
- labels=related_node.get("labels") if related_node.get("labels") else [],
- description=related_node.get("description"),
- properties=(
- related_node.get("properties") if related_node.get("properties") else {}
- ),
- observations=[],
- relation=Relationship(
- predicate=Predicate(
- name=(
- relationship.type
- if hasattr(relationship, "type")
- else str(relationship)
- ),
- description="",
- ),
- direction="in",
- ),
+ def _get_neighbors():
+ node = graph_adapter.get_by_identification_params(
+ identification_params, entity_types=identification_params.entity_types
)
- neighbors.append(neighbor_node)
+ print("[node]", node)
+ if not node:
+ raise HTTPException(status_code=404, detail="Entity not found")
+
+ result = kg_agent.retrieve_neighbors(node, looking_for, limit)
+ print("[result]", result)
+
+ ids = [neighbor.uuid for neighbor in result.neighbors]
+ descriptions = [neighbor.description for neighbor in result.neighbors]
+
+ nodes = graph_adapter.get_nodes_by_uuid(uuids=ids)
+ paired = list(zip(nodes, descriptions))
+
+ return RetrieveNeighborsRequestResponse(neighbors=paired)
+
+ result = await asyncio.to_thread(_get_neighbors)
- return RetrieveNeighborsRequestResponse(neighbors=neighbors)
+ return result
diff --git a/src/services/api/routes/retrieve.py b/src/services/api/routes/retrieve.py
index bfd6a44..e8d3bc1 100644
--- a/src/services/api/routes/retrieve.py
+++ b/src/services/api/routes/retrieve.py
@@ -8,14 +8,18 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
-----
"""
-from fastapi import APIRouter, Query
+from typing import Optional
+from fastapi import APIRouter, Body, Query
from src.services.api.constants.requests import (
+ RetrieveNeighborsAiModeRequestBody,
+ RetrieveNeighborsWithIdentificationParamsRequestBody,
RetrieveRequestResponse,
RetrieveNeighborsRequestResponse,
)
from src.services.api.controllers.retrieve import (
retrieve_neighbors as retrieve_neighbors_controller,
+ retrieve_neighbors_ai_mode as retrieve_neighbors_ai_mode_controller,
)
from src.services.api.controllers.retrieve import (
retrieve_data as retrieve_data_controller,
@@ -49,7 +53,36 @@ async def get_neighbors(
"""
Get the neighbors of an entity.
"""
- return await retrieve_neighbors_controller(uuid, limit)
+ return await retrieve_neighbors_controller(uuid=uuid, limit=limit)
+
+
+@retrieve_router.post(
+ "/entities/neighbors", response_model=RetrieveNeighborsRequestResponse
+)
+async def get_neighbors_with_identification_params(
+ request: RetrieveNeighborsWithIdentificationParamsRequestBody,
+):
+ """
+ Get the neighbors of an entity.
+ """
+ return await retrieve_neighbors_controller(
+ identification_params=request.identification_params, limit=request.limit
+ )
+
+
+@retrieve_router.post("/entities/neighbors/ai-mode")
+async def get_neighbors_ai_mode(
+ request: RetrieveNeighborsAiModeRequestBody = Body(
+ ...,
+ description="The request body for the retrieve neighbors AI mode endpoint.",
+ ),
+):
+ """
+ Get the neighbors of an entity in AI mode.
+ """
+ return await retrieve_neighbors_ai_mode_controller(
+ request.identification_params, request.looking_for, request.limit
+ )
@retrieve_router.post("/context")
diff --git a/src/services/kg_agent/main.py b/src/services/kg_agent/main.py
index 09cc5b6..43ed062 100644
--- a/src/services/kg_agent/main.py
+++ b/src/services/kg_agent/main.py
@@ -43,4 +43,5 @@ kg_agent = KGAgent(
kg=graph_adapter,
vector_store=vector_store_adapter,
embeddings=embeddings_adapter,
+ database_desc=_neo4j_client.graphdb_description,
)
diff --git a/src/services/webserver/docker-compose.yaml b/src/services/webserver/docker-compose.yaml
new file mode 100644
index 0000000..a144e45
--- /dev/null
+++ b/src/services/webserver/docker-compose.yaml
@@ -0,0 +1,19 @@
+version: "3.9"
+
+services:
+ nginx:
+ build:
+ context: ./nginx
+ image: local/nginx-8000:latest
+ container_name: nginx_8000
+ ports:
+ - "8000:8000"
+ volumes:
+ - ./html:/usr/share/nginx/html:ro
+ - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
+ restart: unless-stopped
+ healthcheck:
+ test: ["CMD", "nginx", "-t"]
+ interval: 30s
+ timeout: 5s
+ retries: 3
diff --git a/src/services/webserver/nginx.conf b/src/services/webserver/nginx.conf
deleted file mode 100644
index 11df10e..0000000
--- a/src/services/webserver/nginx.conf
+++ /dev/null
@@ -1,8 +0,0 @@
-server {
- listen 80;
- server_name localhost;
-
- location / {
- proxy_pass http://localhost:8000;
- }
-}
\ No newline at end of file
diff --git a/src/services/webserver/nginx/Dockerfile b/src/services/webserver/nginx/Dockerfile
new file mode 100644
index 0000000..5b2c7f7
--- /dev/null
+++ b/src/services/webserver/nginx/Dockerfile
@@ -0,0 +1,11 @@
+FROM nginx:1.27-alpine
+
+
+ENV TZ=UTC
+
+
+RUN mkdir -p /usr/share/nginx/html
+
+EXPOSE 8000
+
+CMD ["nginx", "-g", "daemon off;"]
diff --git a/src/services/webserver/nginx/nginx.conf b/src/services/webserver/nginx/nginx.conf
new file mode 100644
index 0000000..3532f6f
--- /dev/null
+++ b/src/services/webserver/nginx/nginx.conf
@@ -0,0 +1,64 @@
+worker_processes auto;
+
+events {
+ worker_connections 1024;
+}
+
+http {
+ include /etc/nginx/mime.types;
+ default_type application/octet-stream;
+
+ # Logs
+ access_log /var/log/nginx/access.log;
+ error_log /var/log/nginx/error.log warn;
+
+ # Basic hardening & sane buffers
+ sendfile on;
+ tcp_nopush on;
+ tcp_nodelay on;
+ keepalive_timeout 65;
+ types_hash_max_size 4096;
+ server_tokens off;
+ client_max_body_size 10m;
+
+ # Gzip (optional; enable if you want)
+ # gzip on;
+ # gzip_types text/plain text/css application/json application/javascript application/xml+rss;
+
+ # --- Server on port 8000 ---
+ server {
+ listen 8000 default_server;
+ listen [::]:8000 default_server;
+
+ # Static files root (mounted from ./html)
+ root /usr/share/nginx/html;
+ index index.html;
+
+ # Simple health endpoint
+ location = /healthz {
+ return 200 "ok\n";
+ add_header Content-Type text/plain;
+ }
+
+ # Try files, then 404
+ location / {
+ try_files $uri $uri/ =404;
+ }
+
+ # Example: uncomment to proxy a backend instead of static files
+ # upstream app_upstream { server host.docker.internal:8001; } # macOS/Windows Docker
+ # upstream app_upstream { server 172.17.0.1:8001; } # common Linux host
+ #
+ # location /api/ {
+ # proxy_pass http://app_upstream;
+ # proxy_set_header Host $host;
+ # proxy_set_header X-Real-IP $remote_addr;
+ # proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ # proxy_set_header X-Forwarded-Proto $scheme;
+ # }
+
+ # Error pages (optional)
+ error_page 404 /404.html;
+ location = /404.html { internal; }
+ }
+}
diff --git a/src/utils/nlp/names.py b/src/utils/nlp/names.py
index ec1529f..0e06ac6 100644
--- a/src/utils/nlp/names.py
+++ b/src/utils/nlp/names.py
@@ -66,6 +66,6 @@ def most_similar_name_with_labels_or_none(
print(
f"[SIMILARITY] {max_similarity} for {name} w/ labels {labels_a} and {most_similar_name} w/ labels {labels_list}"
)
- if max_similarity > 0.5:
+ if max_similarity > 0.75:
return most_similar_name
return None
diff --git a/src/workers/tasks/ingestion.py b/src/workers/tasks/ingestion.py
index 70aad6f..bb86fb5 100644
--- a/src/workers/tasks/ingestion.py
+++ b/src/workers/tasks/ingestion.py
@@ -139,7 +139,14 @@ def ingest_structured_data(self, args: dict):
uuid=uuid,
labels=element.types,
name=element.identification_params.name,
- properties=element.json_data,
+ properties={
+ **(element.json_data if element.json_data else {}),
+ **(
+ element.identification_params.model_dump(mode="json")
+ if element.identification_params
+ else {}
+ ),
+ },
)
],
identification_params=element.identification_params,