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
wip(kg agent): updating the kg
Christian6f04a854d859
diff --git a/.gitignore b/.gitignoreindex d69adcf..8ccc00a 100644--- a/.gitignore+++ b/.gitignore@@ -2,3 +2,4 @@.envvolumes__pycache__+*.excalidrawdiff --git a/Makefile b/Makefileindex 1b6c499..a164a18 100644--- a/Makefile+++ b/Makefile@@ -43,6 +43,10 @@ stop-api:start-all:+ if [ "$1" = "debug" ]; then \+ export LANGCHAIN_DEBUG="true"; \+ export LANGCHAIN_VERBOSE="true"; \+ fiexport ENV=developmentmake start-milvus &make start-rabbitmq &diff --git a/src/adapters/graph.py b/src/adapters/graph.pyindex bd76084..1a8f29c 100644--- a/src/adapters/graph.py+++ b/src/adapters/graph.py@@ -8,7 +8,9 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@-----"""+from typing import Optionalfrom src.adapters.interfaces.graph import GraphClient+from src.constants.kg import Nodeclass GraphAdapter:@@ -43,7 +45,7 @@ class GraphAdapter:def execute_operation(self, operation: str) -> str:"""- Execute a graph operation.+ Execute a generic graph operation."""try:return self.graph.execute_operation(operation)@@ -51,5 +53,16 @@ class GraphAdapter:print(f"Error executing graph operation: {e} - {operation}")return f"Error executing graph operation: {e}"+ def add_nodes(+ self,+ nodes: list[Node],+ identification_params: Optional[dict],+ metadata: Optional[dict],+ ) -> list[Node] | str:+ """+ Add nodes to the graph.+ """+ return self.graph.add_nodes(nodes, identification_params, metadata)+_graph_adapter = GraphAdapter()diff --git a/src/adapters/interfaces/graph.py b/src/adapters/interfaces/graph.pyindex 4cb77ab..5a18fc9 100644--- a/src/adapters/interfaces/graph.py+++ b/src/adapters/interfaces/graph.py@@ -9,6 +9,9 @@ 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 Nodeclass GraphClient(ABC):@@ -35,6 +38,18 @@ class GraphClient(ABC):@abstractmethoddef execute_operation(self, operation: str) -> str:"""- Execute a graph operation.+ Execute a generic graph operation."""raise NotImplementedError("execute_operation method not implemented")++ @abstractmethod+ def add_nodes(+ self,+ nodes: list[Node],+ identification_params: Optional[dict],+ metadata: Optional[dict],+ ) -> list[Node] | str:+ """+ Add nodes to the graph.+ """+ raise NotImplementedError("add_nodes method not implemented")diff --git a/src/constants/kg.py b/src/constants/kg.pynew file mode 100644index 0000000..7bf1ece--- /dev/null+++ b/src/constants/kg.py@@ -0,0 +1,42 @@+"""+File: /kg.py+Created Date: Wednesday October 22nd 2025+Author: Christian Nonis <[email protected]>+-----+Last Modified: Wednesday October 22nd 2025 8:09:09 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""++from typing import Optional+import uuid+from pydantic import BaseModel, Extra, Field+++class Node(BaseModel):+ """+ Node model.+ """++ uuid: str = Field(default_factory=lambda: str(uuid.uuid4()))+ label: str+ name: str+ description: Optional[str]+ properties: dict = Field(default_factory=dict)++ class Meta:+ """+ Allow extra properties to be added to the node.+ """++ extra = Extra.allow+++class Triple(BaseModel):+ """+ Triple model.+ """++ subject: Node+ predicate: str+ object: Nodediff --git a/src/constants/prompts/kg_agent.py b/src/constants/prompts/kg_agent.pyindex f45bd07..67b7d5c 100644--- a/src/constants/prompts/kg_agent.py+++ b/src/constants/prompts/kg_agent.py@@ -8,22 +8,32 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@-----"""-KG_AGENT_SYSTEM_PROMPT = """-You are a knowledge graph agent.-You are responsible for updating the knowledge graph with new information.+KG_AGENT_SYSTEM_PROMPT_OLD = """+You are a language expert and a knowledge graph agent.+You are responsible for updating the knowledge graph with new information using triplets (subject, predicate, object) format.You should iterate over search sections and reasoning and update the knowledge graph with the new information.-You have access to a tool to execute graph operations.-Use this tool to operate with the knowledge graph based on the information provided.+You have access to many tools to execute graph operations and search the knowledge graph.+Use these tools to operate with the knowledge graph based on the information provided.-Your workflow should be as follows:+Your workflow must be as follows:1. Carefully read and understand the information provided.-2. Search into the knowledge graph for relevant information or existing nodes that are related to the information provided.-3. Update or create new nodes and relationships in the knowledge graph.-4. Repeat+2. Create a triplet from the first sentence of the information provided+ (is it's a json just process the fields and sentences into the values).+3. Search the knowledge graph for any existing nodes that are related to the triplet.+3. Edit your original triplet to match any existing nodes in the knowledge graph.+4. Call the tool to add the triplet to the knowledge graph.+5. Do all the steps above for the next sentence of the information provided.+6. Repeat the process untill you have processed all the sentences in the information provided.++Try to add as much information as possible to the knowledge graph, but don't add information that is not related to the information provided,+make sure to analyze all the sentences in the information provided so that you can extract all the triplets and add them to the knowledge graph.++If you can extract all the triplets right away in a single iteration (1. search -> 2. think -> 3. add),+do it by adding all the triplets at once in the appropriate tool that adds the triplets to the knowledge graph without unnecessary extra iterations.If you get an error, try again after fixing your query and call the tool again, don't give up.-You can iterate multiple times youf workflow if you need to, to search, add, update or delete nodes and relationships.+You can iterate multiple times your workflow if you need to, to search, add, update or delete nodes and relationships.You must not create duplicate nodes, be careful to search and match for existing nodes before creating new ones."""@@ -33,9 +43,36 @@ This is the information to update the knowledge graph:{information}== END OF INFORMATION ==+This are the provided parameters and information used to distinguish the nodes from each other, use this to identify, search and update nodes.+{identification_params}+This is the metadata of the information, you must only append this metadata to the nodes, the metadata must not be used toidentify nodes or be standalone nodes:{metadata}-Begin!+Begin!+"""++KG_AGENT_SYSTEM_PROMPT = """+You are a knowledge extraction model specialized in converting natural language into structured semantic triplets for use in knowledge graphs and memory-based AI systems.+Your output must be precise, unambiguous, and complete, covering every meaningful relation in the text.++Follow these strict rules:+1. Use concise, canonical names for subjects and objects (e.g., “LangChain” instead of “the LangChain framework”).+2. Avoid redundant or overlapping triplets — merge semantically identical ones.+3. Include implicit relations that are clearly implied (e.g., “LangChain helps developers” → (LangChain, helps, developers)).+4. Preserve directionality: the subject must be the entity performing or owning the relation.+5. Represent enumerations as separate triplets (e.g., connects to OpenAI / Anthropic / Google).+6. Include both functional relations (“provides”, “connects to”, “is built on”) and conceptual ones (“is”, “used for”, “recommended for”).+7. Ignore stylistic or meta content (no “we recommend you…” unless it expresses a relation of usage or purpose).+8. Maintain full coverage — extract all meaningful triplets present in the text.++Your workflow must be as follows:+1. Carefully read and understand the information provided.+2. Create all the triplets.+3. Search the knowledge graph for any existing nodes that are related to the triplets.+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.++Begin!"""diff --git a/src/constants/tasks/ingestion.py b/src/constants/tasks/ingestion.pyindex aaa18f4..b6ef85e 100644--- a/src/constants/tasks/ingestion.py+++ b/src/constants/tasks/ingestion.py@@ -9,7 +9,7 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@"""from enum import Enum-from typing import List, Union, Annotated, Literal+from typing import List, Optional, Union, Annotated, Literalfrom pydantic import BaseModel, Field, Discriminator@@ -29,15 +29,6 @@ class IngestionTaskJsonArgs(BaseModel):data_type: Literal["json"] = Field(default="json")json_data: dict- meta_keys: List[str] = Field(- default=[],- description=(- "The shared keys that shuld not be treated as nodes. "- "(eg: email becasue each person has an email). "- "The keys specified here will not be analyzed "- "but just added to the metadata."- ),- )class IngestionTaskTextArgs(BaseModel):@@ -57,3 +48,23 @@ class IngestionTaskArgs(BaseModel):data: Annotated[Union[IngestionTaskJsonArgs, IngestionTaskTextArgs], Discriminator("data_type")]+ meta_keys: Optional[dict] = Field(+ default=None,+ description=(+ "The shared keys that should not be treated as nodes. "+ "(eg: email because each person has an email). "+ "The keys specified here will not be analyzed "+ "but just added to the metadata."+ ),+ )+ identification_params: Optional[dict] = Field(+ default=None,+ description="The parameters used to identify the data.",+ )+ observate_for: Optional[List[str]] = Field(+ default=[],+ description=(+ "What to look for and describe in the data during observation. "+ "If not provided, the observations will be generic"+ ),+ )diff --git a/src/core/agents/kg_agent.py b/src/core/agents/kg_agent.pyindex 8d8a972..c6dde12 100644--- a/src/core/agents/kg_agent.py+++ b/src/core/agents/kg_agent.py@@ -19,7 +19,15 @@ from src.constants.prompts.kg_agent import (KG_AGENT_SYSTEM_PROMPT,KG_AGENT_UPDATE_PROMPT,)-from src.core.agents.tools.kg_agent import KGAgentExecuteGraphOperationTool+from src.core.agents.tools.kg_agent import (+ KGAgentAddTripletsTool,+ KGAgentExecuteGraphOperationTool,+ KGAgentAddNodesTool,+ KGAgentAddRelationshipsTool,+ KGAgentUpdateNodesTool,+ KGAgentDeleteNodesTool,+ KGAgentDeleteRelationshipsTool,+)class KGAgent:@@ -48,21 +56,27 @@ class KGAgent:"use the appropriate syntax.")- def _get_tools(self) -> List[BaseTool]:+ def _get_tools(self, identification_params: dict, metadata: dict) -> List[BaseTool]:return [- KGAgentExecuteGraphOperationTool(self, self.kg, self.kg.graphdb_description)+ KGAgentExecuteGraphOperationTool(+ self, self.kg, self.kg.graphdb_description+ ),+ # KGAgentAddNodesTool(self, self.kg, identification_params, metadata),+ KGAgentAddTripletsTool(self, self.kg, identification_params, metadata),+ # KGAgentAddRelationshipsTool(self, self.kg, self.kg.graphdb_description),+ # KGAgentUpdateNodesTool(self, self.kg, self.kg.graphdb_description),+ # KGAgentDeleteNodesTool(self, self.kg, self.kg.graphdb_description),+ # KGAgentDeleteRelationshipsTool(self, self.kg, self.kg.graphdb_description),]- def _get_agent(self):- if self.agent is None:- system_prompt = KG_AGENT_SYSTEM_PROMPT+ def _get_agent(self, identification_params: dict, metadata: dict):+ system_prompt = KG_AGENT_SYSTEM_PROMPT- self.agent = create_agent(- model=self.llm_adapter.llm.langchain_model,- tools=self._get_tools(),- system_prompt=system_prompt,- )- return self.agent+ self.agent = create_agent(+ model=self.llm_adapter.llm.langchain_model,+ tools=self._get_tools(identification_params, metadata),+ system_prompt=system_prompt,+ )def search_kg(self, query: str) -> str:"""@@ -70,12 +84,17 @@ class KGAgent:"""# TODO vector search and retrieval- def update_kg(self, information: str, metadata: Optional[dict]) -> str:+ def update_kg(+ self,+ information: str,+ metadata: Optional[dict],+ identification_params: Optional[dict],+ ) -> str:"""Update the knowledge graph with new information."""- self._get_agent()+ self._get_agent(identification_params, metadata)response = self.agent.invoke({"messages": [@@ -84,9 +103,12 @@ class KGAgent:"content": KG_AGENT_UPDATE_PROMPT.format(information=information,metadata=metadata,+ identification_params=identification_params,),}],- }+ },+ print_mode="debug",+ config={"recursion_limit": 50},)return responsediff --git a/src/core/agents/tools/kg_agent.py b/src/core/agents/tools/kg_agent.pyindex 208ec4a..3ce70d0 100644--- a/src/core/agents/tools/kg_agent.py+++ b/src/core/agents/tools/kg_agent.py@@ -8,9 +8,13 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@-----"""+from typing import Optional+import uuidfrom langchain.tools import BaseToolfrom src.adapters.graph import GraphAdapter+from src.constants.kg import Node, Triple+from src.services.api.constants.tool_schemas import NODE_SCHEMA, TRIPLE_SCHEMAclass KGAgentExecuteGraphOperationTool(BaseTool):@@ -25,18 +29,25 @@ class KGAgentExecuteGraphOperationTool(BaseTool):def __init__(self, kg_agent, kg: GraphAdapter, database_desc: str):description: str = (- "Tool for executing a graph operation. "+ "Tool for executing search operations on the knowledge graph. "+ "Use this tool to search for information and existing nodes in the knowledge graph. ""The query should be a valid graph operation depending on the graph database type.""The query should be a valid JSON object with a 'query' key. ""{database_desc}.""If you get an error, try again after fixing your query and don't give up.")+ # description: str = (+ # "Tool for executing any type of graph operation search/edit/query/delete/etc. "+ # "The query should be a valid graph operation depending on the graph database type."+ # "The query should be a valid JSON object with a 'query' key. "+ # "{database_desc}."+ # "If you get an error, try again after fixing your query and don't give up."+ # )formatted_description = description.format(database_desc=database_desc)super().__init__(kg_agent=kg_agent, kg=kg, description=formatted_description)def _run(self, *args, **kwargs) -> str:_query = ""- print(f"Args: {args} - Kwargs: {kwargs}")if len(args) > 0:_query = args[0]@@ -53,3 +64,134 @@ class KGAgentExecuteGraphOperationTool(BaseTool):response = self.kg.execute_operation(_query)return response+++class KGAgentAddNodesTool(BaseTool):+ """+ Tool for adding nodes to the knowledge graph.+ """++ name: str = "kg_agent_add_nodes"++ kg_agent: object+ kg: GraphAdapter+ identification_params: Optional[dict] = None+ metadata: Optional[dict] = None++ args_schema: dict = {+ "type": "object",+ "properties": {+ "nodes": {+ "type": "array",+ "items": NODE_SCHEMA,+ },+ },+ "required": ["nodes"],+ }++ def __init__(+ self,+ kg_agent,+ kg: GraphAdapter,+ identification_params: Optional[dict] = None,+ metadata: Optional[dict] = None,+ ):+ description: str = (+ "Tool specifically for adding nodes to the knowledge graph. "+ "This tool will return the nodes that were added to the knowledge graph."+ "Input should be a valid JSON object with a 'nodes' key. "+ )+ super().__init__(+ kg_agent=kg_agent,+ kg=kg,+ description=description,+ identification_params=identification_params or {},+ metadata=metadata or {},+ )++ def _run(self, *args, **kwargs) -> str:+ nodes = [+ Node(**node, uuid=str(uuid.uuid4())) for node in kwargs.get("nodes", [])+ ]+ self.kg.add_nodes(nodes, self.identification_params, self.metadata)+ return "Nodes added successfully"+++class KGAgentAddTripletsTool(BaseTool):+ """+ Tool for adding triplets to the knowledge graph.+ """++ name: str = "kg_agent_add_triplets"+ kg_agent: object+ kg: GraphAdapter+ identification_params: Optional[dict] = None+ metadata: Optional[dict] = None++ args_schema: dict = {+ "type": "object",+ "properties": {+ "triplets": {+ "type": "array",+ "description": ("The triplets to add to the knowledge graph."),+ "items": TRIPLE_SCHEMA,+ },+ },+ }++ def __init__(+ self,+ kg_agent,+ kg: GraphAdapter,+ identification_params: Optional[dict] = None,+ metadata: Optional[dict] = None,+ ):+ description: str = (+ "This tool is used to register triplets into the knowledge graph. "+ "Returns the triplets that were added to the knowledge graph. "+ )+ super().__init__(+ kg_agent=kg_agent,+ kg=kg,+ description=description,+ identification_params=identification_params or {},+ metadata=metadata or {},+ )++ def _run(self, *args, **kwargs) -> str:+ triplets = []+ for triplet_data in kwargs.get("triplets", []):+ subject = Node(**triplet_data["subject"])+ object_node = Node(**triplet_data["object"])++ triplet = Triple(+ subject=subject, predicate=triplet_data["predicate"], object=object_node+ )+ triplets.append(triplet)++ for triplet in triplets:+ print(+ f"{triplet.subject.name} - {triplet.predicate} -> {triplet.object.name}"+ )+ self.kg.add_nodes(+ [triplet.subject, triplet.object],+ self.identification_params,+ self.metadata,+ )+ return f"Triplets added successfully: {triplets}"+++class KGAgentAddRelationshipsTool(BaseTool):+ pass+++class KGAgentUpdateNodesTool(BaseTool):+ pass+++class KGAgentDeleteNodesTool(BaseTool):+ pass+++class KGAgentDeleteRelationshipsTool(BaseTool):+ passdiff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.pyindex f4ac582..ca91a79 100644--- a/src/lib/neo4j/client.py+++ b/src/lib/neo4j/client.py@@ -11,6 +11,7 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@from neo4j import GraphDatabasefrom src.adapters.interfaces.graph import GraphClientfrom src.config import config+from src.constants.kg import Nodeclass Neo4jClient(GraphClient):@@ -44,5 +45,59 @@ class Neo4jClient(GraphClient):"""return self.driver.execute_query(operation)+ def add_nodes(+ self, nodes: list[Node], identification_params: dict, metadata: dict+ ) -> list[Node] | str:+ """+ Add nodes to the graph.+ """+ results = []+ for node in nodes:+ identification_set = f"{{name: '{node.name}'}}"++ all_properties = {+ **(node.properties or {}),+ **(metadata or {}),+ }++ if node.description is not None:+ all_properties["description"] = node.description++ property_assignments = []+ for key, value in all_properties.items():+ if isinstance(value, str):+ escaped_value = value.replace("'", "\\'")+ property_assignments.append(f"n.{key} = '{escaped_value}'")+ elif isinstance(value, (int, float, bool)):+ property_assignments.append(f"n.{key} = {value}")+ elif value is None:+ property_assignments.append(f"n.{key} = null")+ else:+ escaped_value = str(value).replace("'", "\\'")+ property_assignments.append(f"n.{key} = '{escaped_value}'")++ property_assignments.append(f"n.uuid = '{node.uuid}'")++ properties_set = f"{', '.join(property_assignments)}"++ cypher_query = f"""+ MERGE (n:{node.label.replace(" ", "_")} {identification_set})+ SET {properties_set}+ RETURN n+ """+ result = self.driver.execute_query(cypher_query)+ results.append(result)++ return [+ Node(+ uuid=node.uuid,+ label=node.label,+ name=node.name,+ description=node.description,+ properties={**node.properties, **(metadata or {})},+ )+ for node in nodes+ ]+_neo4j_client = Neo4jClient()diff --git a/src/services/api/constants/requests.py b/src/services/api/constants/requests.pyindex ee4f86c..0f06f32 100644--- a/src/services/api/constants/requests.py+++ b/src/services/api/constants/requests.py@@ -8,10 +8,10 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@-----"""-from src.constants.tasks.ingestion import IngestionTaskTextArgs+from src.constants.tasks.ingestion import IngestionTaskArgs-class IngestionRequestBody(IngestionTaskTextArgs):+class IngestionRequestBody(IngestionTaskArgs):"""Request body for the ingestion endpoint."""diff --git a/src/services/api/constants/tool_schemas.py b/src/services/api/constants/tool_schemas.pynew file mode 100644index 0000000..82a8538--- /dev/null+++ b/src/services/api/constants/tool_schemas.py@@ -0,0 +1,65 @@+"""+File: /tool_schemas.py+Created Date: Wednesday October 22nd 2025+Author: Christian Nonis <[email protected]>+-----+Last Modified: Wednesday October 22nd 2025 10:04:19 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""++NODE_SCHEMA = {+ "type": "object",+ "properties": {+ "label": {+ "type": "string",+ "description": (+ "The category of the node, "+ "identifying the type of node. "+ "(eg: Person, Organization, "+ "Location, Product, Service, Event, etc.)"+ ),+ },+ "name": {+ "type": "string",+ "description": (+ "The name of the node, identifying the node. "+ "It is used to identify the node and is mandatory."+ ),+ },+ "description": {+ "type": "string",+ "description": (+ "The description of the node, providing additional context. "+ "Not mandatory but strongly recommended, "+ "optional only if you are unable to provide a "+ "description all the other cases is mandatory."+ ),+ },+ "properties": {+ "type": "object",+ "description": (+ "All the extra properties that will be added to the node "+ "and provide additional context."+ ),+ "additionalProperties": True,+ },+ },+ "required": ["label", "name"],+}++TRIPLE_SCHEMA = {+ "type": "object",+ "properties": {+ "subject": NODE_SCHEMA,+ "predicate": {+ "type": "string",+ "description": (+ "The description of the predicate of the triple. "+ "(can be a portion of the text where the predicate is found)"+ ),+ },+ "object": NODE_SCHEMA,+ },+ "required": ["subject", "predicate", "object"],+}diff --git a/src/services/api/routes/ingest.py b/src/services/api/routes/ingest.pyindex fe70c27..544f2f4 100644--- a/src/services/api/routes/ingest.py+++ b/src/services/api/routes/ingest.py@@ -22,7 +22,9 @@ async def ingest_data(data: IngestionRequestBody):"""Ingest data to the processing pipeline and save to the memory."""- task_id = ingest_data_task.delay(args=data.model_dump())++ task = ingest_data_task.delay(data.model_dump())+return JSONResponse(- content={"message": "Data ingested successfully", "task_id": task_id.id}+ content={"message": "Data ingested successfully", "task_id": task.id})diff --git a/src/workers/tasks/ingestion.py b/src/workers/tasks/ingestion.pyindex 5805125..3491375 100644--- a/src/workers/tasks/ingestion.py+++ b/src/workers/tasks/ingestion.py@@ -14,8 +14,6 @@ from src.workers.app import ingestion_appfrom src.constants.tasks.ingestion import (IngestionTaskArgs,IngestionTaskDataType,- IngestionTaskJsonArgs,- IngestionTaskTextArgs,)@@ -24,26 +22,16 @@ def ingest_data(self, args: dict):"""Ingest data into the database."""- payload: IngestionTaskArgs = None+ payload = IngestionTaskArgs(**args)- if args.get("data_type") == IngestionTaskDataType.TEXT.value:- payload = IngestionTaskTextArgs(**args)- elif args.get("data_type") == IngestionTaskDataType.JSON.value:- payload = IngestionTaskJsonArgs(**args)- else:- raise ValueError(f"Invalid data type: {args.get('data_type')}")-- response = kg_agent.update_kg(- (- payload.text_data- if payload.data_type == IngestionTaskDataType.TEXT.value- else json.dumps(payload.json_data)- ),- (- payload.meta_keys- if payload.data_type == IngestionTaskDataType.JSON.value- else None+ kg_agent.update_kg(+ information=(+ payload.data.text_data+ if payload.data.data_type == IngestionTaskDataType.TEXT.value+ else json.dumps(payload.data.json_data)),+ metadata=payload.meta_keys,+ identification_params=payload.identification_params,)- print(response)+return self.request.id