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(ingestion): - fixed duplicated nodes + relationships - working on 5th agent - reduced performance overhead + token overhead
Christianf88d33e018e5
diff --git a/Makefile b/Makefileindex 43d5852..79894fc 100644--- a/Makefile+++ b/Makefile@@ -35,6 +35,12 @@ stop-neo4j:delete-neo4j-volumes:docker compose -f src/lib/neo4j/docker-compose.yaml down -v --remove-orphans+build-neo4j-extension:+ docker run --rm -v $(PWD)/src/lib/neo4j:/app -w /app maven:3.9-eclipse-temurin-17 mvn compile++package-neo4j-extension:+ docker run --rm -v $(PWD)/src/lib/neo4j:/app -w /app maven:3.9-eclipse-temurin-17 mvn package -DskipTests+start-mongo:docker compose -f src/lib/mongo/docker-compose.yaml up -ddiff --git a/src/adapters/embeddings.py b/src/adapters/embeddings.pyindex 3eb3e73..42407b7 100644--- a/src/adapters/embeddings.py+++ b/src/adapters/embeddings.py@@ -3,14 +3,21 @@ File: /embeddings.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 5th 2026 9:57:30 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""import uuid+from tenacity import (+ retry,+ stop_after_attempt,+ wait_exponential,+ retry_if_exception_type,+)from src.adapters.interfaces.embeddings import EmbeddingsClient, VectorStoreClientfrom src.constants.embeddings import Vector+from src.lib.embeddings.client import EmbeddingErrorclass EmbeddingsAdapter:@@ -23,19 +30,49 @@ class EmbeddingsAdapter:"""self.embeddings = client+ @retry(+ stop=stop_after_attempt(5),+ wait=wait_exponential(multiplier=1, min=2, max=30),+ retry=retry_if_exception_type(EmbeddingError),+ )+ def _embed_text_with_retry(self, text: str) -> list[float]:+ return self.embeddings.embed_text(text)++ @retry(+ stop=stop_after_attempt(5),+ wait=wait_exponential(multiplier=1, min=2, max=30),+ retry=retry_if_exception_type(EmbeddingError),+ )+ def _embed_texts_with_retry(self, texts: list[str]) -> list[list[float]]:+ return self.embeddings.embed_texts(texts)+def embed_text(self, text: str) -> Vector:"""Embed a text and return a vector."""- from src.lib.embeddings.client import EmbeddingError-try:- embeddings = self.embeddings.embed_text(text)+ embeddings = self._embed_text_with_retry(text)return Vector(id=str(uuid.uuid4()), embeddings=embeddings, metadata={})except EmbeddingError as e:print(f"Embedding failed in adapter, returning empty vector: {e}")return Vector(id=str(uuid.uuid4()), embeddings=[], metadata={})+ def embed_texts(self, texts: list[str]) -> list[Vector]:+ """+ Embed a list of texts and return a list of vectors.+ """+ try:+ embeddings_list = self._embed_texts_with_retry(texts)+ return [+ Vector(id=str(uuid.uuid4()), embeddings=embeddings, metadata={})+ for embeddings in embeddings_list+ ]+ except EmbeddingError as e:+ print(f"Embedding failed in adapter, returning empty vectors: {e}")+ return [+ Vector(id=str(uuid.uuid4()), embeddings=[], metadata={}) for _ in texts+ ]+class VectorStoreAdapter:def __init__(self):@@ -86,14 +123,14 @@ class VectorStoreAdapter:) -> dict[str, list[Vector]]:"""Finds vectors similar to the provided vector IDs within a specified store and brain.-+Parameters:vector_ids (list[str]): IDs of the source vectors to find similarities for.brain_id (str): Identifier of the brain/namespace to search within.store (str): Name of the vector store to query.min_similarity (float): Minimum similarity threshold for returned vectors (inclusive).limit (int): Maximum number of similar vectors to return per source ID.-+Returns:dict[str, list[Vector]]: Mapping from each source vector ID to a list of similar Vectors.Each list contains at most `limit` items, includes only vectors with similarity >= `min_similarity`,@@ -103,6 +140,14 @@ class VectorStoreAdapter:vector_ids, brain_id, store, min_similarity, limit)+ def remove_vectors(+ self, ids: list[str], store: str, brain_id: str = "default"+ ) -> None:+ """+ Remove vectors from the vector store.+ """+ return self.vector_store.remove_vectors(ids, store, brain_id)+_embeddings_adapter = EmbeddingsAdapter()-_vector_store_adapter = VectorStoreAdapter()\ No newline at end of file+_vector_store_adapter = VectorStoreAdapter()diff --git a/src/adapters/graph.py b/src/adapters/graph.pyindex f6e72dd..9fbf2ac 100644--- a/src/adapters/graph.py+++ b/src/adapters/graph.py@@ -3,7 +3,7 @@ File: /graph.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 12th 2026 8:26:26 pm+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""@@ -14,7 +14,9 @@ from src.constants.embeddings import Vectorfrom src.constants.kg import (IdentificationParams,Node,+ NodeDict,Predicate,+ PredicateDict,SearchEntitiesResult,SearchRelationshipsResult,)@@ -133,10 +135,10 @@ class GraphAdapter:def get_graph_relationships(self, brain_id: str = "default") -> list[str]:"""Retrieve relationship type names available in the graph.-+Parameters:brain_id (str): Identifier of the graph/brain to query.-+Returns:list[str]: Relationship type names present in the specified graph."""@@ -145,13 +147,13 @@ class GraphAdapter:def get_by_uuid(self, uuid: str, brain_id: str = "default") -> Node:"""Retrieve a node by its UUID from the graph.-+Deprecated: use `get_by_uuids` for batch retrieval.-+Parameters:uuid (str): UUID of the node to retrieve.brain_id (str): Identifier of the graph/brain to query.-+Returns:Node: The node matching the provided UUID."""@@ -321,7 +323,7 @@ class GraphAdapter:def get_graph_node_types(self, brain_id: str = "default") -> list[str]:"""Get all unique node types stored in the graph.-+Returns:list[str]: Node type names available in the graph."""@@ -330,7 +332,7 @@ class GraphAdapter:def get_graph_node_properties(self, brain_id: str = "default") -> list[str]:"""Return all unique node property keys present in the graph for the specified brain.-+Returns:list[str]: Unique node property key names present in the specified brain's graph."""@@ -387,14 +389,14 @@ class GraphAdapter:) -> List[Tuple[Node, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]]:"""Compute second-degree neighbor hops for the given starting node UUIDs using vector-store–based filtering.-+Parameters:from_uuids: List[str] — UUIDs of the starting nodes to explore.flattened: bool — When true, nodes and predicates are returned as lightweight dicts with core fields (`uuid`, `name`, `labels`/`direction`) instead of full objects.vector_store_adapter: VectorStoreClient — Vector store used to fetch embeddings and perform similarity-based filtering.brain_id: str — Identifier of the brain/graph space to query.similarity_threshold: float — Optional threshold for additional similarity-based filtering (0.0 disables the extra check).-+Returns:List[Tuple[Node, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]] — A list where each item corresponds to a starting node and contains:- the starting node (or its flattened representation),@@ -404,11 +406,11 @@ class GraphAdapter:def flatten_node(n):"""Return a flattened node representation when the surrounding `flattened` flag is true, otherwise return the original node.-+Parameters:n: NodeThe node to convert.-+Returns:dict: A dictionary with keys `uuid`, `labels`, and `name` when `flattened` is true, otherwise the original node object."""@@ -427,10 +429,13 @@ class GraphAdapter:nodes_by_uuid = {n.uuid: n for n in nodes}v_ids = [- n.properties["v_id"] for n in nodes if getattr(n.properties, "v_id", None)+ n.properties["v_id"] for n in nodes if n.properties.get("v_id") is not None]if len(v_ids) == 0:- print("[ ! ] No v_ids found for nodes:", from_uuids)+ print(+ "[ ! ] No v_ids found for nodes:", from_uuids+ ) # TODO: no node without v_id exists in the graph, check why this is happening+ print(f"[DEBUG (get_2nd_degree_hops)]: Nodes: {nodes}")return []vs = vector_store_adapter.get_by_ids(v_ids, brain_id=brain_id, store="nodes")@@ -449,7 +454,7 @@ class GraphAdapter:fd[1].properties["v_id"]for fds in all_fd_nodes.values()for fd in fds- if fd[1].properties["v_id"]+ if fd[1].properties.get("v_id") is not None] # TODO: [missing_property] check why sometime v_id is not presentall_fd_vs = vector_store_adapter.get_by_ids(all_fd_v_ids, brain_id=brain_id, store="nodes"@@ -480,7 +485,7 @@ class GraphAdapter:filtered = reduce_list(fd_vs_with_desc,access_key="embeddings",- similarity_threshold=0.5,+ similarity_threshold=0.8,by_vector=averaged_vector,rerank={"local": "description",@@ -555,7 +560,7 @@ class GraphAdapter:reduced = reduce_list(sd_vs_with_desc,access_key="embeddings",- similarity_threshold=0.5,+ similarity_threshold=0.8,by_vector=averaged_vector,rerank={"local": "description",@@ -601,15 +606,15 @@ class GraphAdapter:) -> bool:"""Determine whether a node with the given UUID, name, and labels exists in the graph.-+Parameters:- uuid (str): UUID of the node to check; may be empty if matching by name and labels.- name (str): Name of the node to match.- labels (list[str]): List of labels/types the node must have.- brain_id (str): Identifier of the graph/brain to query; defaults to "default".-+ uuid (str): UUID of the node to check; may be empty if matching by name and labels.+ name (str): Name of the node to match.+ labels (list[str]): List of labels/types the node must have.+ brain_id (str): Identifier of the graph/brain to query; defaults to "default".+Returns:- true if a matching node exists, false otherwise.+ true if a matching node exists, false otherwise."""return self.graph.check_node_existence(uuid, name, labels, brain_id)@@ -627,16 +632,51 @@ class GraphAdapter:) -> List[Tuple[Node, Predicate, Node]]:"""Retrieve the next connected node tuple(s) for a relationship identified by a flow key.-+Parameters:predicate_uuid (str): UUID of the predicate (relationship) to search from.flow_key (str): Flow key value used to select the next relationship target.brain_id (str): Identifier of the brain/graph namespace to query.-+Returns:List[Tuple[Node, Predicate, Node]]: A list of (subject node, predicate, object node) tuples that are the next nodes matching the provided flow key; empty list if none are found."""return self.graph.get_next_by_flow_key(predicate_uuid, flow_key, brain_id)+ def get_triples_by_uuid(+ self, uuids: list[str], brain_id: str+ ) -> List[Tuple[Node, Predicate, Node]]:+ """+ Get triples by its UUIDs.+ """+ return self.graph.get_triples_by_uuid(uuids, brain_id)++ def remove_nodes(self, uuids: list[str], brain_id: str = "default") -> list[Node]:+ """+ Remove nodes from the graph.+ """+ return self.graph.remove_nodes(uuids, brain_id)++ def remove_relationships(+ self,+ relationships: list[Tuple[NodeDict, PredicateDict, NodeDict]],+ brain_id: str = "default",+ ) -> list[Tuple[Node, Predicate, Node]]:+ """+ Remove relationships from the graph.+ """+ return self.graph.remove_relationships(relationships, brain_id)++ def list_relationships(+ self,+ subject: str,+ object: str,+ brain_id: str = "default",+ ) -> list[Tuple[Node, Predicate, Node]]:+ """+ List the relationships between the subject and object.+ """+ return self.graph.list_relationships(subject, object, brain_id)+-_graph_adapter = GraphAdapter()\ No newline at end of file+_graph_adapter = GraphAdapter()diff --git a/src/adapters/interfaces/embeddings.py b/src/adapters/interfaces/embeddings.pyindex 9a50bd8..cafd623 100644--- a/src/adapters/interfaces/embeddings.py+++ b/src/adapters/interfaces/embeddings.py@@ -3,7 +3,7 @@ File: /embeddings.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 5th 2026 9:57:30 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -25,6 +25,13 @@ class EmbeddingsClient(ABC):"""raise NotImplementedError("embed method not implemented")+ @abstractmethod+ def embed_texts(self, texts: list[str]) -> list[list[float]]:+ """+ Embed a list of texts and return a list of lists of floats.+ """+ raise NotImplementedError("embed_texts method not implemented")+class VectorStoreClient(ABC):"""@@ -67,15 +74,22 @@ class VectorStoreClient(ABC):) -> dict[str, list[Vector]]:"""Finds vectors similar to the vectors identified by the given IDs.-+Parameters:vector_ids (list[str]): Identifiers of the vectors to find similarities for.brain_id (str): Identifier for the brain/context containing the vectors.store (str): Name of the vector store to query.min_similarity (float): Minimum similarity threshold (e.g., 0.0–1.0) for returned results.limit (int): Maximum number of similar vectors to return per input ID.-+Returns:dict[str, list[Vector]]: Mapping from each input vector ID to a list of similar `Vector` objects that meet or exceed `min_similarity`, with up to `limit` results per ID."""- raise NotImplementedError("search_similar_by_ids method not implemented")\ No newline at end of file+ raise NotImplementedError("search_similar_by_ids method not implemented")++ @abstractmethod+ def remove_vectors(self, ids: list[str], store: str, brain_id: str) -> None:+ """+ Remove vectors from the vector store.+ """+ raise NotImplementedError("remove_vectors method not implemented")diff --git a/src/adapters/interfaces/graph.py b/src/adapters/interfaces/graph.pyindex aa01956..ede2268 100644--- a/src/adapters/interfaces/graph.py+++ b/src/adapters/interfaces/graph.py@@ -3,7 +3,7 @@ File: /graph.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 12th 2026 8:26:26 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -14,7 +14,9 @@ from typing import Dict, List, Literal, Optional, Tuplefrom src.constants.kg import (IdentificationParams,Node,+ NodeDict,Predicate,+ PredicateDict,SearchEntitiesResult,SearchRelationshipsResult,)@@ -279,14 +281,14 @@ class GraphClient(ABC):) -> Node | Predicate | None:"""Update properties on a node or relationship in the graph.-+Parameters:uuid (str): UUID of the target node or relationship.updating (Literal["node", "relationship"]): Which entity type to update.brain_id (str): Identifier of the graph/brain containing the entity.new_properties (dict): Properties to set or overwrite on the entity.properties_to_remove (list[str]): Property keys to remove from the entity.-+Returns:Node | Predicate | None: The updated node or relationship if changes were applied, `None` if the entity was not found or no update occurred."""@@ -344,7 +346,7 @@ class GraphClient(ABC):) -> Node | None:"""Update a node's identifying fields, labels, and properties.-+Parameters:uuid (str): UUID of the node to update.brain_id (str): Identifier of the graph or brain containing the node.@@ -353,7 +355,7 @@ class GraphClient(ABC):new_labels (Optional[list[str]]): New labels to replace existing labels.new_properties (Optional[dict]): Properties to add or update on the node.properties_to_remove (Optional[list[str]]): Property keys to remove from the node.-+Returns:Node | None: The updated node, or `None` if no matching node exists."""@@ -375,20 +377,20 @@ class GraphClient(ABC):) -> Dict[str, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]:"""Return second-degree hops for each starting node.-+Parameters:- from_ (List[str]): List of starting node UUIDs or identifiers to expand.- flattened (bool): If true, return lightweight results with non-essential metadata removed.- vector_store_adapter (VectorStoreClient): Adapter used to resolve or enrich nodes via the vector store.- brain_id (str): Identifier of the brain/graph to query.-+ from_ (List[str]): List of starting node UUIDs or identifiers to expand.+ flattened (bool): If true, return lightweight results with non-essential metadata removed.+ vector_store_adapter (VectorStoreClient): Adapter used to resolve or enrich nodes via the vector store.+ brain_id (str): Identifier of the brain/graph to query.+Returns:- hops_by_start (Dict[str, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]):- Mapping from each starting node identifier in `from_` to a list of first-degree entries.- Each first-degree entry is a tuple of:- - `Predicate`: relationship from the starting node to the first-hop node,- - `Node`: the first-hop node,- - `List[Tuple[Predicate, Node]]`: list of second-degree hops where each item is a `(Predicate, Node)` tuple representing the relationship and the second-hop node.+ hops_by_start (Dict[str, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]):+ Mapping from each starting node identifier in `from_` to a list of first-degree entries.+ Each first-degree entry is a tuple of:+ - `Predicate`: relationship from the starting node to the first-hop node,+ - `Node`: the first-hop node,+ - `List[Tuple[Predicate, Node]]`: list of second-degree hops where each item is a `(Predicate, Node)` tuple representing the relationship and the second-hop node."""raise NotImplementedError("get_2nd_degree_hops not implemented")@@ -402,13 +404,13 @@ class GraphClient(ABC):) -> bool:"""Determine whether a node with the given identity exists in the specified brain.-+Parameters:uuid (str): UUID of the node to check.name (str): Name of the node to match.labels (list[str]): List of labels/types the node must have.brain_id (str): Identifier of the brain (graph) to search within.-+Returns:true if a node matching the provided uuid, name, and labels exists in the brain, false otherwise."""@@ -420,12 +422,12 @@ class GraphClient(ABC):) -> list[dict]:"""Retrieve the neighborhood of a node up to a specified depth.-+Parameters:node (Node | str): The starting node or its UUID.depth (int): Maximum distance from the starting node to include (1 = immediate neighbors).brain_id (str): Identifier of the brain/graph to query.-+Returns:list[dict]: A nested list of dictionaries representing the neighborhood; each dictionary represents a node and contains its neighbors as nested structures up to the requested depth."""@@ -437,8 +439,47 @@ class GraphClient(ABC):) -> List[Tuple[Node, Predicate, Node]]:"""Retrieve the next connected node and the relationship identified by a flow key for a given predicate.-+Returns:List[Tuple[Node, Predicate, Node]]: A list of triples where each triple is (connected node to the predicate, relationship that matches the provided flow_key, next node reached via that relationship)."""- raise NotImplementedError("get_next_by_flow_key method not implemented")\ No newline at end of file+ raise NotImplementedError("get_next_by_flow_key method not implemented")++ @abstractmethod+ def get_triples_by_uuid(+ self, uuids: list[str], brain_id: str+ ) -> List[Tuple[Node, Predicate, Node]]:+ """+ Get triples by its UUIDs.+ """+ raise NotImplementedError("get_triples_by_uuid method not implemented")++ @abstractmethod+ def remove_nodes(self, uuids: list[str], brain_id: str) -> list[Node]:+ """+ Remove nodes from the graph.+ """+ raise NotImplementedError("remove_nodes method not implemented")++ @abstractmethod+ def remove_relationships(+ self,+ relationships: list[Tuple[NodeDict, PredicateDict, NodeDict]],+ brain_id: str,+ ) -> list[Tuple[Node, Predicate, Node]]:+ """+ Remove relationships from the graph.+ """+ raise NotImplementedError("remove_relationships method not implemented")++ @abstractmethod+ def list_relationships(+ self,+ brain_id: str,+ subject: str,+ object: str,+ ) -> list[Tuple[Node, Predicate, Node]]:+ """+ List the relationships between the subject and object.+ """+ raise NotImplementedError("list_relationships method not implemented")diff --git a/src/config.py b/src/config.pyindex 56a5026..efb66da 100644--- a/src/config.py+++ b/src/config.py@@ -14,9 +14,10 @@ import osimport dotenvfrom pathlib import Path-dotenv.load_dotenv(- dotenv_path=f".env{'.' + os.getenv('ENV') if os.getenv('ENV') else ''}"-)+_project_root = Path(__file__).resolve().parent.parent+_env_name = os.getenv("ENV")+_env_path = _project_root / f".env{'.' + _env_name if _env_name else ''}"+dotenv.load_dotenv(dotenv_path=_env_path)class AzureConfig:diff --git a/src/constants/agents.py b/src/constants/agents.pyindex 6c254c8..33f09cd 100644--- a/src/constants/agents.py+++ b/src/constants/agents.py@@ -143,3 +143,4 @@ class TokenDetail(BaseModel):output: TokenOutputDetailgrand_total: inteffective_total: int+ grouped_by_agent: Dict[str, "TokenDetail"] = Field(default_factory=dict)diff --git a/src/constants/kg.py b/src/constants/kg.pyindex fb67266..a117040 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, Tuple+from typing import List, Literal, Optional, Tuple, TypedDictimport uuidfrom pydantic import BaseModel, ConfigDict, Extra, Field@@ -182,3 +182,14 @@ class EntitySynergy(BaseModel):node: Nodeconnected_by: Tuple[Node, Node]+++class NodeDict(TypedDict, total=False):+ uuid: str+ name: str+ labels: list[str]+++class PredicateDict(TypedDict, total=False):+ uuid: str+ name: strdiff --git a/src/constants/prompts/architect_agent.py b/src/constants/prompts/architect_agent.pyindex 3dbf500..a7a239e 100644--- a/src/constants/prompts/architect_agent.py+++ b/src/constants/prompts/architect_agent.py@@ -3,7 +3,7 @@ File: /architect_agent.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Tuesday December 23rd 2025 9:24:20 pm+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""@@ -159,6 +159,8 @@ LOGIC CHECKLIST:- If any quantity is specified in the text and the scout identified a Unit, attach the quantity value as 'amount' to the relationship properties.- Nodes/Entities MUST be atomic and not composite (phrases) (eg: "Went to San Francisco" is not atomic, "Went to" + "San Francisco" is atomic)+Remember that the uuids are STANDARD uuids 8-4-4-4-12 hexadecimal character strings.+Return ONLY JSON like the examples above."""@@ -175,7 +177,7 @@ Entities Found by Scout: {entities}Begin!"""-ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT = """+ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT_UNCOMPRESSED = """You are a "Structural Graph Architect." Your goal is to map information into an Active Vector Graph.THE TRIANGLE OF ATTRIBUTION:@@ -227,6 +229,7 @@ Example architect_agent_create_relationship tool input 1:"subject": "uuid_1","predicate": "ACCOMPLISHED_ACTION","description": "John knew 12 new friends in New York City",+ "amount": 12, // You must add the amount TO THE RELATIONSHIP PROPERTIES if there is any quantity specified in the text."object": "uuid_4"}},{{@@ -240,13 +243,10 @@ Example architect_agent_create_relationship tool input 1:"predicate": "TARGETED","description": "John knew 12 new friends in New York City","object": "uuid_5"+ "amount": 12, // You must add the amount TO THE RELATIONSHIP PROPERTIES if there is any quantity specified in the text.}},- {{- "subject": "uuid_4",- "predicate": "TARGETED",- "description": "John knew 12 new friends in New York City",- "object": "uuid_5"- }}+ ... more relationships (remember that you must map all the entities found by the scout) ...+ }}]Example architect_agent_create_relationship tool output:"OK"@@ -299,7 +299,7 @@ LOGIC CHECKLIST:- Identify the Actor (Origin).- Identify the Event Hub (Action Instance).- Identify the Target (Destination).-- If any quantity is specified in the text and the scout identified a Unit, attach the quantity value as 'amount' to the relationship properties.+- If any quantity is specified in the text and the scout identified a Unit, attach the quantity value as 'amount' to the relationship properties of the relationship with the Unit node.- Nodes/Entities MUST be atomic and not composite (phrases) (eg: "Went to San Francisco" is not atomic, "Went to" + "San Francisco" is atomic)Your workflow must be:@@ -315,6 +315,47 @@ Your workflow must be:10. If it happens that less then 2 entities are left you can call the architect_agent_check_used_entities tool to check if the entities used previously can be connected with the last entity.11. Done"""+ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT = """+## Role: Structural Graph Architect+**Objective:** Map input text/entities into an "Active Vector Graph" using the **Triangle of Attribution** logic.++### 1. The Triangle of Attribution (Mandatory)+Every action must flow through a central **EVENT hub**:+1. **Initiation Vector:** `[Source/Actor] --(predicate)--> [Event Instance]`+ - *Property:* Include `amount: [value]` if quantity exists in text.+2. **Target Vector:** `[Event Instance] --(predicate)--> [Object/Recipient]`+ - *Property:* Mirror `amount: [value]` for cross-reference.+3. **Context Vector:** `[Event Instance] --(predicate)--> [Broad Anchor/Context]`++**Note:** For static facts (no action), link entities directly without an Event hub.++### 2. Constraints & Logic+- **Atomicity:** Predicates/Nodes must be single concepts, not phrases (e.g., "MOVED_TO", not "Went to San Francisco").+- **Directional Slot-Filling:** - `subject`: Origin/Source.+ - `object`: Destination/Target.+- **Forbidden:** - No direct Actor-to-Target links for actions (must use Event hub).+ - No dedicated nodes for numbers; store quantities as `amount` properties on relationships.+- **Entity Coverage:** Use 100% of Scout-provided entities. Reuse entities across contexts as needed.+- **UUIDS:** Use the standard uuids 8-4-4-4-12 hexadecimal character strings.+- **Relationship Names:** Use general relationship names (eg: "TARGET_PRODUCT_OBJECT_CROISSANTS"=wrong, "TARGETED"=correct)+- **Properties:** Append the properties to the object relationship, never append them to the relationship name.++### 3. Workflow (The Loop)+1. **Fetch:** Call `architect_agent_get_remaining_entities_to_process`.+2. **Contextualize:** Group entities by narrative context.+3. **Map:** Define atomic relationships.+4. **Execute:** Call `architect_agent_create_relationship`.+ - *On Error:* Fix relationships based on instructions until "OK".+5. **Clean:** Mark finished entities via `architect_agent_mark_entities_as_used`.+6. **Re-evaluate:** Check for remaining entities. If $<2$ remain, use `architect_agent_check_used_entities` to find historical bridge nodes.+7. **Terminate:** Stop when no entities remain. If Scout returns 0 entities initially, state "Empty list" and exit.++### 4. Toolset Summary+- `get_remaining_entities`: List entities awaiting mapping.+- `create_relationship`: Submit relationship array. (Returns "OK" or instructions).+- `mark_entities_as_used`: Archive processed entities.+- `check_used_entities`: Retrieve archived entities for cross-context bridging.+"""ARCHITECT_AGENT_TOOLER_CREATE_RELATIONSHIPS_PROMPT = """Role: Graph Structural Architect.diff --git a/src/constants/prompts/janitor_agent.py b/src/constants/prompts/janitor_agent.pyindex 8803711..d3c6584 100644--- a/src/constants/prompts/janitor_agent.py+++ b/src/constants/prompts/janitor_agent.py@@ -3,7 +3,7 @@ File: /janitor_agent.pyCreated Date: Tuesday December 23rd 2025Author: Christian Nonis <[email protected]>------Last Modified: Tuesday December 23rd 2025 10:00:46 pm+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""@@ -45,7 +45,7 @@ Return ONLY JSON:}}"""-JANITOR_AGENT_GRAPH_NORMALIZATOR_SYSTEM_PROMPT = """+JANITOR_AGENT_GRAPH_NORMALIZATOR_SYSTEM_PROMPT_UNCOMPRESSED = """You are the Janitor of a Knowledge Graph. You are responsible for ensuring graph consistency and quality.YOUR RESPONSIBILITIES ARE:@@ -66,7 +66,11 @@ YOUR RESPONSIBILITIES ARE:The graph ontology must not include amount-nodes, amounts must be added to the relationships where they are missing.(eg1: (COMPANY:Startup Inc.)-[RAISED]->(EVENT:Funding)-[TARGETED]->(MONEY:100000000) must become (COMPANY:Startup Inc.)-[RAISED]-(EVENT:Funding)-[TARGETED {{ "amount": 100000000 }}]->(FUND_RAISE:Series A) with the amount added to the relationship properties)(eg2: (COMPANY:Startup Inc.)-[RAISED]->(EVENT:Funding {{ "description": "The startup raised $100 million in funding" }})-[TARGETED]->(MONEY) must become (COMPANY:Startup Inc.)-[RAISED]-(EVENT:Funding)-[TARGETED {{ "amount": 100000000 }}]->(FUND_RAISE:Series A) with the amount added to the relationship properties since it was missing but was specified in the description)-++REMEMBER:+1. Relationships must contain in the properties the "amount" property if the relationship talks about a quantity.+2. Relationship names must be simple, any extra detail can be added to the properties.+3. If a relationship name is not completely wrong don't waste time changing it, just leave it as is.Your output must be a JSON object with a "tasks" argument containing a list of detailed string descriptions representing the tasks that needs to be done if there are any, to fix the graph.Each task should include info in also the nodes/relationships/properties/triplets that are involved in the task so that the kg_agent can execute the tasks and reffer to the correct nodes/relationships/properties/triplets.@@ -85,6 +89,43 @@ If there are no tasks to be done return an empty list:}}"""+JANITOR_AGENT_GRAPH_NORMALIZATOR_SYSTEM_PROMPT = """+## Role: Knowledge Graph Janitor (Consistency & Quality)+**Objective:** Audit the graph to enforce event-centricity, deduplication, and property-based quantitative mapping.++### 1. Core Transformation Rules+* **Event-Centricity:** Convert direct Actor → Object links into the **Triangle of Attribution**.+ * *Example:* `(Person)-[WENT_TO]->(City)` becomes `(Person)-[MOVED]->(Event)-[TARGETED_LOCATION]->(City)`.+* **Deduplication:** Merge nodes and triplets that represent the same semantic event (e.g., "Trip" and "Went to" regarding the same journey).+* **Entity Unification:** Identify and merge identical entities (like the same City) appearing in different contexts; create bridging relationships (e.g., `HAPPENED_WITHIN`) between related events.+* **Amount Migration:** **FORBIDDEN:** Amount-specific nodes.+ * **Action:** Delete "Amount" or "Money" nodes. Extract values from names or descriptions and inject them into the relationship as an `amount` property.++### 2. Guardrails+1. **Property Priority:** Move details from relationship names into properties; keep relationship labels simple and atomic.+2. **Naming Tolerance:** If a relationship name is functional/understandable, do not change it. Avoid pedantic renaming.+3. **Contextual Linking:** Proactively connect distant nodes if they share a logical context.++### 3. Output Format+Return a JSON object with a `tasks` array. Each task must be a high-context string identifying specific UUIDs, nodes, and the required fix.++**If issues are found:**+```json+{{+ "tasks": [+ "Convert (PERSON:{{uuid_1}})-[WENT_TO]->(CITY:{{uuid_2}}) to event-centric structure.",+ "Merge duplicate Event nodes {{uuid_3}} ('Trip') and {{uuid_5}} ('Went to').",+ "Extract amount '100000000' from description of {{uuid_4}} and move to relationship property."+ ]+}}+```++**If the graph is clean:**+```json+{{ "tasks": [] }}+```+"""+JANITOR_AGENT_GRAPH_NORMALIZATOR_PROMPT = """Role: Perform Global Review. You have been provided with a "Neighborhood Snapshot" of the existing Knowledge Graph relevant to the new dataand you can browse the graph with your tools to have a better picture.@@ -93,8 +134,8 @@ NEW_DATA_UNITS: {units}GRAPH_SNAPSHOT: {snapshot_json}"""-ATOMIC_JANITOR_AGENT_SYSTEM_PROMPT = """-You are the "Knowledge Graph Janitor." You resolve entities, enforce directional logic, and preserve semantic intent.+ATOMIC_JANITOR_AGENT_SYSTEM_PROMPT_UNCOMPRESSED = """+You are an efficient "Knowledge Graph Janitor." You resolve entities, enforce directional logic, and preserve semantic intent.REVISION PROTOCOL:1. IDENTITY RESOLUTION: Use `search_entities` to search into the knowledge graph if tips and tails already exist in the knowledge graph. If a match exists, replace UUID/Name with existing values.@@ -132,7 +173,7 @@ If you identified something wrong with the relationships return a JSON object wi- wrong_relationships: a list containing JSON objects with the following fields:- relationship: the relationship that is wrong- reason: the reason for the wrong relationship- - instructions: the instructions with context on how to fix the wrong relationship+ - instructions: the instructions with context on how to fix the wrong relationship, each instruction is isolated so must have all the information to be executed independently.Example output if everything is correct:{{@@ -155,13 +196,56 @@ Example output if there are any errors:{{"relationship": {{...}}, // You must return here the relationship that is wrong as you received it."reason": "<<The reason for the wrong relationship>>",- "instructions": "<<The instructions with context on how to fix the wrong relationship>>"+ "instructions": "<<The instructions with context on how to fix the wrong relationship, each instruction is isolated so must have all the information to be executed independently.>>"}},... more wrong relationships ...], // if everything is correct or you already fixed the relationships you must return an empty list here.}}"""+ATOMIC_JANITOR_AGENT_SYSTEM_PROMPT = """+## Role: Knowledge Graph Janitor+**Objective:** Resolve entities, audit directional logic, and enforce schema integrity.++### 1. Revision Protocol+* **Identity Resolution:** Use `search_entities` to match input nodes with existing graph nodes. Replace UUIDs/Names with matches.+* **Directional Audit:** * **Actor-Centric (MADE, PERFORMED):** [Subject/Actor] → [EVENT].+ * **Impact-Centric (TARGETED, RESULTED_IN):** [EVENT] → [Object/Target].+ * **Rule:** Swap direction *only* if logic is inverted; never change the semantic label.+* **Property Extraction:** Strip numbers from names (e.g., "10 Tasks" → "Tasks") and move to `amount` or `count` properties.+* **Instance Protection:** Never merge `EVENT` nodes; preserve unique historical instances.+* **Schema Alignment:** Use `get_schema` (target: `relationship_types`) to normalize relationship labels.+* **UUIDS:** Ensure that the UUIDs are the standard UUIDs 8-4-4-4-12 hexadecimal character strings.++### 2. Operational Instructions+1. **Exhaustive Search:** If `search_entities` returns nothing, treat as a new entity. Perform varied search queries before concluding.+2. **Autonomous Fixes:** Directly update entity names/types and swap relationship directions without flagging an error if the fix is minor.+3. **Semantic Validation:** Ensure "Actor → Event" and "Event → Target" flows.+4. **Preservation:** Maintain original intent and JSON descriptions.++### 3. Output Schema (JSON)+If graph state is valid after your autonomous fixes:+```json+{{ "status": "OK" }}+```++If complex errors remain or new nodes are required:+```json+{{+ "status": "ERROR",+ "required_new_nodes": [ {{ "name": "...", "type": "...", "description": "...", "properties": {{}} }} ],+ "fixed_relationships": [ {{ "relationship_object": {{}} }} ],+ "wrong_relationships": [+ {{+ "relationship": {{ "original_object" }},+ "reason": "Specific logic violation",+ "instructions": "Isolated, context-rich fix instructions"+ }}+ ]+}}+```+"""+ATOMIC_JANITOR_AGENT_PROMPT = """Role: Normalize and Repair a set of single graph units.diff --git a/src/constants/prompts/kg_agent.py b/src/constants/prompts/kg_agent.pyindex 2327840..e784f6f 100644--- a/src/constants/prompts/kg_agent.py+++ b/src/constants/prompts/kg_agent.py@@ -3,7 +3,7 @@ File: /kg_agent.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Sunday October 19th 2025 10:38:27 am+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""@@ -155,14 +155,29 @@ Example output:KG_AGENT_GRAPH_CONSOLIDATOR_SYSTEM_PROMPT = """You are a knowledge graph agent specialized in consolidating the knowledge graph.-You have a tool at your disposal to execute graph operations.+You have access to a set of tools that you can use to execute the task.+To create/delete nodes and relationships you MUST ONLY use the dedicated tools:+- kg_agent_create_node+- kg_agent_create_relationship+- kg_agent_remove_node+- kg_agent_remove_relationship++For all the other operations you can use the kg_agent_execute_graph_operation tool.+You must ONLY strictly follow the instructions of the task.-Use the tool at your disposal to execute the task in your best effort, in case of syntax error fix your syntax and try again until you succeed.+Follow those rules:+1. If you are replacing a relationship/node remember than (if not specified otherwise) the new relationship/node must have the same properties as the old one.+2. If you are replacing a relationship/node remember than (if not specified otherwise) the old node/relationship must be deleted.+3. You can use use your tool to browse the knowledge graph, and find the nodes/relationships the task is referring to if you are not able to find them directly with the instructions of the task.+4. You are not allowed to verify that your added relationships and nodes are being added correctly, the tools will handle that for you.+5. You are not supposed to verify that the nodes/relationships the task is talking about exist in first place, you just need to execute the task.++Use the tools at your disposal to execute the task in your best effort, in case of syntax error fix your syntax and try again until you succeed.When you are done executing the task return 'OK'.-If you can't find the elements the task is talking about just return 'OK' anyway.+If you can't find the elements the task is talking about, just return 'OK' and consider the task executed successfully."""KG_AGENT_GRAPH_CONSOLIDATOR_PROMPT = """@@ -171,7 +186,7 @@ This is the task to consolidate the knowledge graph:{task}== END OF TASK ==-When you are done executing the task return 'OK'.+When you are done executing the task you MUSTreturn a textual description of the reason you weren't able to execute the task without iterating over the task again.Begin!"""diff --git a/src/core/agents/architect_agent.py b/src/core/agents/architect_agent.pyindex e31e9eb..6909793 100644--- a/src/core/agents/architect_agent.py+++ b/src/core/agents/architect_agent.py@@ -3,7 +3,7 @@ File: /architect_agent.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 5th 2026 9:57:30 pm+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""@@ -11,7 +11,6 @@ Modified By: Christian Nonis <[email protected]>from typing import Dict, List, Literal, Optional, Tuplefrom langchain.agents import create_agentfrom langchain.tools import BaseTool-from langchain_core.messages import RemoveMessagefrom pydantic import BaseModelimport osfrom concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError@@ -53,7 +52,8 @@ from src.core.agents.tools.architect_agent.ArchitectAgentMarkEntitiesAsUsedToolArchitectAgentMarkEntitiesAsUsedTool,)from src.core.saving.ingestion_manager import IngestionManager-from src.utils.tokens import token_detail_from_token_counts+from src.utils.cleanup import strip_properties+from src.utils.tokens import merge_token_details, token_detail_from_token_counts# from src.core.agents.tools.kg_agent import (# KGAgentSearchGraphTool,@@ -83,7 +83,7 @@ class ArchitectAgent:):"""Initialize the ArchitectAgent with the required adapters and managers and prepare internal runtime state.-+Parameters:llm_adapter (LLMAdapter): Adapter for interacting with the language model.cache_adapter (CacheAdapter): Adapter used for cache reads/writes.@@ -91,7 +91,7 @@ class ArchitectAgent:vector_store (VectorStoreAdapter): Adapter for vector storage and retrieval.embeddings (EmbeddingsAdapter): Adapter that produces vector embeddings for content.ingestion_manager (IngestionManager): Manager responsible for ingesting external data into the system.-+The constructor initializes internal tracking state including token counters (input, output, cached, reasoning),message/agent state, and containers for discovered relationships and used entities."""@@ -107,8 +107,11 @@ class ArchitectAgent:self.cached_tokens = 0self.reasoning_tokens = 0self.relationships_set: List[ArchitectAgentRelationship] = []- self.used_entities_set = []+ self.used_entities_dict = {}self.ingestion_manager = ingestion_manager+ self.session_id: Optional[str] = None+ self.janitor_agent = None+ self._janitor_agent_brain_id = None# self.database_desc = database_descdef _get_tools(@@ -118,16 +121,15 @@ class ArchitectAgent:brain_id: str = "default",targeting: Optional[Node] = None,) -> List[BaseTool]:-"""Builds the set of tools the agent uses for relationship creation and entity tracking.-+Parameters:text (Optional[str]): Optional prompt or context text passed to the create-relationship tool.entities (Optional[Dict[str, ScoutEntity]]): Optional mapping of entity UUIDs to ScoutEntity instances for context.brain_id (str): Identifier for the knowledge brain/namespace to scope KG operations.targeting (Optional[Node]): Optional target node context to guide relationship creation.-+Returns:List[BaseTool]: A list containing:- ArchitectAgentCreateRelationshipTool configured with the provided context,@@ -155,6 +157,33 @@ class ArchitectAgent:),]+ def _content_only_history(+ self, messages: Optional[list], keep_last: Optional[int] = None+ ) -> list:+ if not messages:+ return []+ pruned = messages+ if keep_last is not None and len(pruned) > keep_last:+ pruned = pruned[-keep_last:]+ content_only = []+ for msg in pruned:+ if isinstance(msg, dict):+ content = msg.get("content")+ role = msg.get("role") or "assistant"+ else:+ content = getattr(msg, "content", None)+ msg_type = getattr(msg, "type", None)+ if msg_type in ("human", "user"):+ role = "user"+ elif msg_type == "system":+ role = "system"+ else:+ role = "assistant"+ if content is None:+ continue+ content_only.append({"role": role, "content": content})+ return content_only+def _get_agent(self,type_: Literal["single", "tooler"],@@ -168,7 +197,7 @@ class ArchitectAgent:):"""Configure and create the internal LangChain agent and store it on self.agent.-+Parameters:type_ (Literal["single", "tooler"]): Chooses agent mode. "single" uses a structured response prompt and no tools; "tooler" uses the tooler system prompt and enables tools.tools (Optional[List[BaseTool]]): Explicit tool list to attach when type_ is "tooler". If omitted for "tooler", a default tool set is created from provided context.@@ -178,7 +207,7 @@ class ArchitectAgent:entities (Optional[Dict[str, ScoutEntity]]): Entity context forwarded to default tool construction when tools are not provided.brain_id (str): Identifier forwarded to default tool construction when tools are not provided.targeting (Optional[Node]): Targeting context forwarded to default tool construction when tools are not provided.-+Side effects:Creates an agent via create_agent and assigns it to self.agent."""@@ -227,7 +256,7 @@ class ArchitectAgent:) -> ArchitectAgentResponse:"""Orchestrates the agent to discover relationships and new nodes for the provided entities based on the input text.-+Parameters:text (str): Natural-language description or instructions guiding relationship discovery.entities (List[ScoutEntity]): Entities to process; each entity should include a UUID.@@ -235,7 +264,7 @@ class ArchitectAgent:brain_id (str): Identifier for the knowledge brain or workspace to use.timeout (int): Maximum seconds to wait for a single LLM invocation before timing out.max_retries (int): Number of retry attempts for timed-out LLM invocations.-+Returns:ArchitectAgentResponse: Contains:- new_nodes: list of newly discovered nodes produced by the agent.@@ -264,43 +293,31 @@ class ArchitectAgent:):"""Builds a message history including the provided entities and previously created relationships, invokes the configured agent with that history, and returns the agent's response.-+Parameters:ent (list[ScoutEntity]): Entities to include in the prompt.all_rels (list[ArchitectAgentRelationship]): Previously created relationships to include in the prompt.previous_messages (list, optional): Prior message objects to include as conversation history; may be trimmed to fit history limits.-+Returns:The agent's response object containing the model's reply and associated metadata."""- from langchain_core.messages import HumanMessage-- messages_list = []- if previous_messages:- messages = previous_messages- if len(messages) > 10:- delete_count = len(messages) - 5- delete_ids = [msg.id for msg in messages[:delete_count]]- messages_list.extend(- [RemoveMessage(id=msg_id) for msg_id in delete_ids]- )- messages_list.extend(messages[delete_count:])- else:- messages_list.extend(messages)-- user_message = HumanMessage(- content=ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT.format(- text=text,- entities=[entity.model_dump(mode="json") for entity in ent],- previously_created_relationships=(- f"""- Previously Created Relationships: {[rel.model_dump(mode="json") for rel in all_rels]}+ messages_list = self._content_only_history(previous_messages, keep_last=5)+ messages_list.append(+ {+ "role": "user",+ "content": ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT.format(+ text=text,+ entities=[entity.model_dump(mode="json") for entity in ent],+ previously_created_relationships=(+ f"""+ Previously Created Relationships: {strip_properties([rel.model_dump(mode="json") for rel in all_rels])}"""- if len(all_rels) > 0- else ""- ),- targeting=(- f"""+ if len(all_rels) > 0+ else ""+ ),+ targeting=(+ f"""The information is related to the following node:Name: {targeting.name}UUID: {targeting.uuid}@@ -308,14 +325,20 @@ class ArchitectAgent:Description: {targeting.description}{targeting.properties}"""- if targeting- else ""+ if targeting+ else ""+ ),),- )+ })- messages_list.append(user_message)- response = self.agent.invoke({"messages": messages_list})+ response = self.agent.invoke(+ {"messages": messages_list},+ config={+ "tags": ["architect_agent"],+ "metadata": {"agent": "architect_agent", "brain_id": brain_id},+ },+ )return responsedef _process_response(@@ -328,7 +351,7 @@ class ArchitectAgent:) -> set:"""Extracts newly created relationships and nodes from a structured agent response and updates the provided tracking collections.-+Parameters:response (dict): Agent response containing a `structured_response` with optional `relationships` and `new_nodes`.connected_entity_uuids (set): Set of UUIDs already known to be connected; will be updated with newly connected UUIDs.@@ -336,7 +359,7 @@ class ArchitectAgent:all_new_nodes (list): List to append any new node objects reported in the response.entities (List[ScoutEntity]): Source entities to check membership of relationship endpoints (used to mark endpoints as connected).seen_relationship_keys (set): Set of (tail_uuid, tip_uuid, relationship_name) tuples used to deduplicate relationships.-+Returns:set: The set of entity UUIDs that became connected as a result of processing this response iteration."""@@ -391,14 +414,14 @@ class ArchitectAgent:):"""Invoke the architect agent with a single-worker executor and timeout, and update token counts from any returned messages.-+Parameters:unconnected_entities_list (List[ScoutEntity]): Entities to include in the agent invocation.previous_messages (list): Message history to send to the agent.-+Returns:dict: The response dictionary returned by the agent invocation.-+Raises:TimeoutError: If the agent call does not complete within the configured timeout."""@@ -414,11 +437,17 @@ class ArchitectAgent:for m in response.get("messages", []):if hasattr(m, "usage_metadata"):self._update_token_counts(m.usage_metadata)- self.token_detail = token_detail_from_token_counts(- self.input_tokens,- self.output_tokens,- self.cached_tokens,- self.reasoning_tokens,+ self.token_detail = merge_token_details(+ [+ self.token_detail,+ token_detail_from_token_counts(+ self.input_tokens,+ self.output_tokens,+ self.cached_tokens,+ self.reasoning_tokens,+ "architect_agent",+ ),+ ])return responseexcept FutureTimeoutError:@@ -432,14 +461,14 @@ class ArchitectAgent:):"""Invoke the agent for the provided unconnected entities, append any returned messages to the accumulated message history, and process the agent's response to determine which entities became connected.-+Parameters:unconnected_entities_list (List[ScoutEntity]): Entities to include in this agent invocation.previous_messages (list): Message history to send with the invocation.-+Returns:set: UUID strings of entities that were connected as a result of this invocation.-+Raises:TimeoutError: If the agent invocation exhausts retries or times out."""@@ -449,7 +478,7 @@ class ArchitectAgent:)messages = response.get("messages", [])if messages:- accumulated_messages.extend(messages)+ accumulated_messages.extend(self._content_only_history(messages))return _process_response(response,connected_entity_uuids,@@ -505,12 +534,13 @@ class ArchitectAgent:brain_id: str = "default",timeout: int = 3600,max_retries: int = 3,+ ingestion_session_id: Optional[str] = None,) -> List[ArchitectAgentRelationship]:"""Drive the architect agent in "tooler" mode to iteratively discover relationships using available tools and collect the results.-+This invokes the agent with the provided text and entities, manages message history trimming, updates token accounting from message metadata, and accumulates relationships produced by tool-driven agent actions.-+Parameters:text (str): Natural-language prompt or instructions for relationship discovery.entities (List[ScoutEntity]): Candidate entities the agent may connect; each entity must include a UUID.@@ -518,15 +548,23 @@ class ArchitectAgent:brain_id (str): Identifier for the knowledge brain/context to use.timeout (int): Maximum seconds to wait for a single agent invocation before raising a timeout.max_retries (int): Maximum number of retry attempts for timed or retried invocations.-+Returns:List[ArchitectAgentRelationship]: The relationships discovered and collected by the agent during this run.-+Raises:TimeoutError: If the agent fails to produce a response within `timeout` after the allowed retry attempts."""+ import uuid+ from src.lib.redis.client import _redis_client- entities_dict = {entity.uuid: entity for entity in entities}+ self.session_id = str(uuid.uuid4())+ self.relationships_set.clear()++ entities_dict = {+ entity.uuid: strip_properties([entity.model_dump(mode="json")])[0]+ for entity in entities+ }self.entities = entities_dictself._get_agent(@@ -542,34 +580,24 @@ class ArchitectAgent:def _invoke_agent(previous_messages: list = None):"""Prepare a pruned message history, append a formatted human prompt for the "tooler" flow, and invoke the agent.-+Parameters:previous_messages (list | None): Prior messages to include in the history; if the count exceeds HISTORY_MAX_MESSAGES,the oldest messages are removed via RemoveMessage entries and the remaining messages are preserved.-+Returns:The response object returned by self.agent.invoke when called with the constructed message list."""- from langchain_core.messages import HumanMessage-- messages_list = []- if previous_messages:- messages = previous_messages- if len(messages) > HISTORY_MAX_MESSAGES:- delete_count = len(messages) - HISTORY_MAX_MESSAGES_DELETE- delete_ids = [msg.id for msg in messages[:delete_count]]- messages_list.extend(- [RemoveMessage(id=msg_id) for msg_id in delete_ids]- )- messages_list.extend(messages[delete_count:])- else:- messages_list.extend(messages)-- user_message = HumanMessage(- content=ARCHITECT_AGENT_TOOLER_CREATE_RELATIONSHIPS_PROMPT.format(- text=text,- targeting=(- f"""+ messages_list = self._content_only_history(+ previous_messages, keep_last=HISTORY_MAX_MESSAGES_DELETE+ )+ messages_list.append(+ {+ "role": "user",+ "content": ARCHITECT_AGENT_TOOLER_CREATE_RELATIONSHIPS_PROMPT.format(+ text=text,+ targeting=(+ f"""The information is related to the following node:Name: {targeting.name}UUID: {targeting.uuid}@@ -577,16 +605,26 @@ class ArchitectAgent:Description: {targeting.description}{targeting.properties}"""- if targeting- else ""+ if targeting+ else ""+ ),),- )+ })- messages_list.append(user_message)+ metadata = {+ "agent": "architect_agent",+ "brain_id": brain_id,+ }+ if ingestion_session_id:+ metadata["ingestion_session_id"] = ingestion_session_idreturn self.agent.invoke({"messages": messages_list},- config={"recursion_limit": MAX_RECURSION_LIMIT},+ config={+ "recursion_limit": MAX_RECURSION_LIMIT,+ "tags": ["architect_agent", "architect_tooler"],+ "metadata": metadata,+ },)@retry(@@ -598,13 +636,13 @@ class ArchitectAgent:def _invoke_agent_with_retry(previous_messages: list):"""Invoke the agent in a worker thread, enforce the configured timeout, and update token counters from any returned message usage metadata.-+Parameters:previous_messages (list): Message history to pass to the agent invocation.-+Returns:dict: The agent response object as returned by the underlying _invoke_agent call.-+Raises:TimeoutError: If the agent invocation exceeds the configured timeout."""@@ -615,11 +653,17 @@ class ArchitectAgent:for m in response.get("messages", []):if hasattr(m, "usage_metadata"):self._update_token_counts(m.usage_metadata)- self.token_detail = token_detail_from_token_counts(- self.input_tokens,- self.output_tokens,- self.cached_tokens,- self.reasoning_tokens,+ self.token_detail = merge_token_details(+ [+ self.token_detail,+ token_detail_from_token_counts(+ self.input_tokens,+ self.output_tokens,+ self.cached_tokens,+ self.reasoning_tokens,+ "architect_agent",+ ),+ ])return responseexcept FutureTimeoutError:@@ -631,13 +675,13 @@ class ArchitectAgent:def _invoke_and_process(previous_messages: list):"""Invoke the agent with retry logic and append any returned messages to the outer `accumulated_messages` list.-+Parameters:previous_messages (list): Message history to send to the agent.-+Returns:response (dict): The agent's response object; may include a "messages" key containing new messages.-+Raises:TimeoutError: If the agent invocation times out or fails after all retry attempts."""@@ -645,7 +689,15 @@ class ArchitectAgent:response = _invoke_agent_with_retry(previous_messages)messages = response.get("messages", [])if messages:- accumulated_messages.extend(messages)+ response_history = self._content_only_history(messages)+ prior_history = self._content_only_history(previous_messages)+ if (+ prior_history+ and response_history[: len(prior_history)] == prior_history+ ):+ response_history = response_history[len(prior_history) :]+ if response_history:+ accumulated_messages.extend(response_history)return responseexcept RetryError as e:last_attempt = e.last_attempt@@ -663,7 +715,7 @@ class ArchitectAgent:def _update_token_counts(self, usage_metadata: dict):"""Update the agent's token counters from an LLM usage metadata dictionary.-+Parameters:usage_metadata (dict): Metadata containing token usage details. Expected keys:- "input_tokens": integer count of input tokens.@@ -681,4 +733,4 @@ class ArchitectAgent:# Output details (reasoning)output_details = usage_metadata.get("output_token_details", {})- self.reasoning_tokens += output_details.get("reasoning", 0)\ No newline at end of file+ self.reasoning_tokens += output_details.get("reasoning", 0)diff --git a/src/core/agents/janitor_agent.py b/src/core/agents/janitor_agent.pyindex 6a45066..2eb8290 100644--- a/src/core/agents/janitor_agent.py+++ b/src/core/agents/janitor_agent.py@@ -3,7 +3,7 @@ File: /janitor_agent.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Tuesday December 23rd 2025 9:24:20 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -15,7 +15,6 @@ from typing import List, Literal, Optional, Tuple, Unionfrom langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategyfrom langchain.tools import BaseTool-from langchain_core.messages import RemoveMessagefrom pydantic import BaseModelfrom concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutErrorfrom tenacity import (@@ -50,6 +49,10 @@ from src.core.agents.tools.janitor_agent import (JanitorAgentExecuteGraphReadOperationTool,JanitorAgentExecuteGraphOperationTool,)+from src.core.agents.tools.janitor_agent.JanitorAgentSearchRelationshipTool import (+ JanitorAgentSearchRelationshipsTool,+)+from src.utils.cleanup import strip_propertiesfrom src.utils.tokens import token_detail_from_token_counts@@ -83,14 +86,14 @@ class JanitorAgent:):"""Initialize the JanitorAgent with required adapters and a database description.-+Parameters:- llm_adapter (LLMAdapter): Adapter for language model interactions.- kg (GraphAdapter): Adapter for graph database operations.- vector_store (VectorStoreAdapter): Adapter for vector search and retrieval.- embeddings (EmbeddingsAdapter): Adapter to compute embeddings for text.- database_desc (str): Human-readable description of the target database.-+ llm_adapter (LLMAdapter): Adapter for language model interactions.+ kg (GraphAdapter): Adapter for graph database operations.+ vector_store (VectorStoreAdapter): Adapter for vector search and retrieval.+ embeddings (EmbeddingsAdapter): Adapter to compute embeddings for text.+ database_desc (str): Human-readable description of the target database.+Initializes internal token counters and token detail storage."""self.llm_adapter = llm_adapter@@ -108,10 +111,10 @@ class JanitorAgent:def _get_tools(self, brain_id: str = "default") -> List[BaseTool]:"""Assembles the set of tools the Janitor agent uses, scoped to the specified brain.-+Parameters:brain_id (str): Identifier of the brain/context used to instantiate each tool.-+Returns:List[BaseTool]: A list containing the schema access tool, the entity search tool (using embeddings and vector store), and the graph read-operation tool configured for this agent and brain_id."""@@ -134,6 +137,11 @@ class JanitorAgent:self.database_desc,brain_id=brain_id,),+ JanitorAgentSearchRelationshipsTool(+ self,+ self.kg,+ brain_id=brain_id,+ ),]def _get_agent(@@ -147,9 +155,9 @@ class JanitorAgent:):"""Configure and instantiate the internal LangChain agent and assign it to `self.agent`.-+Constructs a system prompt based on `type_` ("janitor", "graph-janitor", or "atomic-janitor"), derives a response schema from `output_schema` or `output_schemas` (merging multiple schemas into a Union when needed and wrapping complex schemas in `ToolStrategy`), and calls `create_agent` with the selected model, tools, system prompt, response format, and debug flag.-+Parameters:tools (Optional[List[BaseTool]]): Optional list of tools to expose to the agent; if omitted, the agent's default tools for `brain_id` are used.output_schema (Optional[BaseModel]): Single response schema or a tuple of schemas to use as the agent's response format.@@ -157,7 +165,7 @@ class JanitorAgent:extra_system_prompt (Optional[dict]): Optional dictionary whose contents are formatted into the selected system prompt.brain_id (str): Identifier for the knowledge brain used when resolving default tools.type_ (str): Agent mode controlling system prompt selection; supported values are "janitor", "graph-janitor", and "atomic-janitor".-+"""system_prompt = Noneif type_ == "janitor":@@ -207,6 +215,33 @@ class JanitorAgent:debug=os.environ.get("DEBUG", "false").lower() == "true",)+ def _content_only_history(+ self, messages: Optional[list], keep_last: Optional[int] = None+ ) -> list:+ if not messages:+ return []+ pruned = messages+ if keep_last is not None and len(pruned) > keep_last:+ pruned = pruned[-keep_last:]+ content_only = []+ for msg in pruned:+ if isinstance(msg, dict):+ content = msg.get("content")+ role = msg.get("role") or "assistant"+ else:+ content = getattr(msg, "content", None)+ msg_type = getattr(msg, "type", None)+ if msg_type in ("human", "user"):+ role = "user"+ elif msg_type == "system":+ role = "system"+ else:+ role = "assistant"+ if content is None:+ continue+ content_only.append({"role": role, "content": content})+ return content_only+def run_graph_consolidator(self,new_relationships: List[ArchitectAgentRelationship],@@ -216,16 +251,16 @@ class JanitorAgent:) -> list[str]:"""Run graph-level consolidation for the provided relationships against a KG snapshot.-+Parameters:new_relationships (List[ArchitectAgentRelationship]): Relationships to normalize and consolidate into the graph.brain_id (str): Identifier of the knowledge brain/context to use.timeout (int): Maximum seconds to wait for a single agent invocation before timing out.max_retries (int): Number of retry attempts for agent invocation on timeout.-+Returns:list[str]: Consolidation tasks produced by the graph janitor; returns an empty list if no tasks were produced.-+Raises:TimeoutError: If the agent invocation times out or fails after the configured number of retries."""@@ -264,41 +299,40 @@ class JanitorAgent:def _invoke_agent(previous_messages: list = None):"""Builds a message history (pruning older entries when it exceeds HISTORY_MAX_MESSAGES), appends a user message containing a graph-normalization prompt populated with the current hops snapshot and the provided new relationships, and invokes the configured agent with that message sequence.-+Parameters:previous_messages (list): Optional sequence of prior messages to include in the history. When the sequence length exceeds HISTORY_MAX_MESSAGES, older messages are replaced with RemoveMessage objects to trim the history.-+Returns:The agent's response object returned by self.agent.invoke for the assembled messages."""- from langchain_core.messages import HumanMessage-- messages_list = []- if previous_messages:- messages = previous_messages- if len(messages) > HISTORY_MAX_MESSAGES:- delete_count = len(messages) - HISTORY_MAX_MESSAGES_DELETE- delete_ids = [msg.id for msg in messages[:delete_count]]- messages_list.extend(- [RemoveMessage(id=msg_id) for msg_id in delete_ids]- )- messages_list.extend(messages[delete_count:])- else:- messages_list.extend(messages)-- user_message = HumanMessage(- content=JANITOR_AGENT_GRAPH_NORMALIZATOR_PROMPT.format(- snapshot_json=json.dumps(hops),- units=json.dumps(- [rel.model_dump(mode="json") for rel in new_relationships]+ messages_list = self._content_only_history(+ previous_messages, keep_last=HISTORY_MAX_MESSAGES_DELETE+ )+ messages_list.append(+ {+ "role": "user",+ "content": JANITOR_AGENT_GRAPH_NORMALIZATOR_PROMPT.format(+ snapshot_json=json.dumps(hops),+ units=json.dumps(+ strip_properties(+ [+ rel.model_dump(mode="json")+ for rel in new_relationships+ ]+ )+ ),),- )+ })- messages_list.append(user_message)return self.agent.invoke({"messages": messages_list},- config={"recursion_limit": 100},+ config={+ "recursion_limit": 100,+ "tags": ["janitor_agent"],+ "metadata": {"agent": "janitor_agent", "brain_id": brain_id},+ },)@retry(@@ -310,13 +344,13 @@ class JanitorAgent:def _invoke_agent_with_retry(previous_messages: list):"""Invoke the configured agent in a thread pool, update the agent's token counters from any returned message usage metadata, and return the agent response.-+Parameters:previous_messages (list): The accumulated message history to provide to the agent for this invocation.-+Returns:dict: The agent's response object (expected to contain a "messages" list and optional usage metadata).-+Raises:TimeoutError: If the agent invocation does not complete within the configured timeout."""@@ -332,6 +366,7 @@ class JanitorAgent:self.output_tokens,self.cached_tokens,self.reasoning_tokens,+ "janitor_agent",)return responseexcept FutureTimeoutError:@@ -343,13 +378,13 @@ class JanitorAgent:def _invoke_and_process(previous_messages: list):"""Invoke the agent with retry handling and append any returned messages to the accumulated_messages history.-+Parameters:previous_messages (list): The list of messages to send to the agent as the current context.-+Returns:dict: The raw response object returned by the agent invocation.-+Raises:TimeoutError: If the agent invocation exhausts retries or a timeout occurs; the exception message includes the last attempt's error."""@@ -357,7 +392,7 @@ class JanitorAgent:response = _invoke_agent_with_retry(previous_messages)messages = response.get("messages", [])if messages:- accumulated_messages.extend(messages)+ accumulated_messages.extend(self._content_only_history(messages))return responseexcept RetryError as e:last_attempt = e.last_attempt@@ -396,7 +431,7 @@ class JanitorAgent:) -> JanitorAgentInputOutput:"""Normalize a single insertion unit using the janitor agent.-+Parameters:input_output (JanitorAgentInputOutput): The unit of work to normalize (relationship, virtual node, or entity).text (str): Human-provided text that guides the normalization.@@ -404,10 +439,10 @@ class JanitorAgent:brain_id (str): Identifier of the brain/knowledge scope to use.timeout (int): Maximum seconds to wait for a single agent invocation before raising a TimeoutError.max_retries (int): Maximum number of retry attempts for transient invocation timeouts.-+Returns:JanitorAgentInputOutput: A container populated with `relationship`, `virtual_node`, and/or `entity` extracted from the agent's structured response; fields are set to `None` when not provided by the agent.-+Raises:TimeoutError: If the agent invocation times out or fails after the configured number of retries."""@@ -421,48 +456,42 @@ class JanitorAgent:def _invoke_agent(previous_messages: list = None):"""Builds a message list (with optional history pruning) and invokes the configured agent with a normalization prompt.-+Parameters:- previous_messages (list | None): Prior conversation messages to include in the invocation; when provided and longer than HISTORY_MAX_MESSAGES, older messages are removed via deletion markers before sending.-+ previous_messages (list | None): Prior conversation messages to include in the invocation; when provided and longer than HISTORY_MAX_MESSAGES, older messages are removed via deletion markers before sending.+Returns:- agent_response: The result returned by the agent's invoke call (the agent's response object).+ agent_response: The result returned by the agent's invoke call (the agent's response object)."""- from langchain_core.messages import HumanMessage-- messages_list = []- if previous_messages:- messages = previous_messages- if len(messages) > HISTORY_MAX_MESSAGES:- delete_count = len(messages) - HISTORY_MAX_MESSAGES_DELETE- delete_ids = [msg.id for msg in messages[:delete_count]]- messages_list.extend(- [RemoveMessage(id=msg_id) for msg_id in delete_ids]- )- messages_list.extend(messages[delete_count:])- else:- messages_list.extend(messages)-- user_message = HumanMessage(- content=JANITOR_AGENT_NORMALIZE_INSERTION_PROMPT.format(- unit_of_work=input_output.model_dump_json(),- text=text,- targeting=(- f"""+ messages_list = self._content_only_history(+ previous_messages, keep_last=HISTORY_MAX_MESSAGES_DELETE+ )+ messages_list.append(+ {+ "role": "user",+ "content": JANITOR_AGENT_NORMALIZE_INSERTION_PROMPT.format(+ unit_of_work=input_output.model_dump_json(),+ text=text,+ targeting=(+ f"""The information is related to:"{targeting.name}": {targeting.description}{targeting.properties}"""- if targeting- else ""+ if targeting+ else ""+ ),),- )+ })- messages_list.append(user_message)return self.agent.invoke({"messages": messages_list},- config={"recursion_limit": 100},+ config={+ "recursion_limit": 100,+ "tags": ["janitor_agent"],+ "metadata": {"agent": "janitor_agent", "brain_id": brain_id},+ },)@retry(@@ -474,13 +503,13 @@ class JanitorAgent:def _invoke_agent_with_retry(previous_messages: list):"""Invoke the configured agent with the provided message history, update the agent's token counters from any returned message usage metadata, and return the raw agent response.-+Parameters:previous_messages (list): Accumulated conversation messages to send to the agent.-+Returns:dict: The agent's raw response object (may contain a "messages" list and other metadata).-+Raises:TimeoutError: If the agent call exceeds the configured timeout."""@@ -496,6 +525,7 @@ class JanitorAgent:self.output_tokens,self.cached_tokens,self.reasoning_tokens,+ "janitor_agent",)return responseexcept FutureTimeoutError:@@ -507,13 +537,13 @@ class JanitorAgent:def _invoke_and_process(previous_messages: list):"""Invoke the agent with retry logic and process its response into the accumulated message history.-+Parameters:previous_messages (list): The message history passed to the agent for this invocation.-+Returns:dict: The raw agent response object returned by the retry wrapper; may contain a "messages" key whose items are appended to the outer `accumulated_messages`.-+Raises:TimeoutError: If the retry wrapper exhausts attempts or a timeout occurs; when retries are exhausted the exception message includes the last attempt number and its error."""@@ -521,7 +551,7 @@ class JanitorAgent:response = _invoke_agent_with_retry(previous_messages)messages = response.get("messages", [])if messages:- accumulated_messages.extend(messages)+ accumulated_messages.extend(self._content_only_history(messages))return responseexcept RetryError as e:last_attempt = e.last_attempt@@ -567,7 +597,7 @@ class JanitorAgent:) -> AtomicJanitorAgentInputOutput | str:"""Validate and produce correction instructions for a set of atomic relationships using the atomic janitor agent.-+Parameters:input_relationships (List[ArchitectAgentRelationship]): The relationships (units of work) to validate.text (str): Human-readable context or explanation to guide validation.@@ -575,10 +605,10 @@ class JanitorAgent:brain_id (str): Identifier of the brain/knowledge context to run the agent against.timeout (int): Maximum seconds to wait for a single agent invocation before raising a timeout.max_retries (int): Maximum number of retry attempts for agent invocation on timeout.-+Returns:AtomicJanitorAgentInputOutput | str: `'OK'` if all relationships are valid; otherwise an AtomicJanitorAgentInputOutput containing instructions or corrections.-+Raises:TimeoutError: If the agent invocation times out or fails after the configured retry attempts."""@@ -594,50 +624,49 @@ class JanitorAgent:def _invoke_agent(previous_messages: list = None):"""Assemble a trimmed message history, append an atomic-janitor user message built from the current units of work, text, and optional targeting, then invoke the agent.-+Parameters:previous_messages (list | None): Prior messages to include in the invocation; if the list exceeds HISTORY_MAX_MESSAGES, older messages are removed via RemoveMessage objects before sending.-+Returns:The raw response returned by self.agent.invoke for the assembled messages."""- from langchain_core.messages import HumanMessage-- messages_list = []- if previous_messages:- messages = previous_messages- if len(messages) > HISTORY_MAX_MESSAGES:- delete_count = len(messages) - HISTORY_MAX_MESSAGES_DELETE- delete_ids = [msg.id for msg in messages[:delete_count]]- messages_list.extend(- [RemoveMessage(id=msg_id) for msg_id in delete_ids]- )- messages_list.extend(messages[delete_count:])- else:- messages_list.extend(messages)-- user_message = HumanMessage(- content=ATOMIC_JANITOR_AGENT_PROMPT.format(- units_of_work=json.dumps(- [rel.model_dump(mode="json") for rel in input_relationships]- ),- text=text,- targeting=(- f"""+ messages_list = self._content_only_history(+ previous_messages, keep_last=HISTORY_MAX_MESSAGES_DELETE+ )+ messages_list.append(+ {+ "role": "user",+ "content": ATOMIC_JANITOR_AGENT_PROMPT.format(+ units_of_work=json.dumps(+ strip_properties(+ [+ rel.model_dump(mode="json")+ for rel in input_relationships+ ]+ )+ ),+ text=text,+ targeting=(+ f"""The information is related to:"{targeting.name}": {targeting.description}{targeting.properties}"""- if targeting- else ""+ if targeting+ else ""+ ),),- )+ })- messages_list.append(user_message)return self.agent.invoke({"messages": messages_list},- config={"recursion_limit": 100},+ config={+ "recursion_limit": 100,+ "tags": ["janitor_agent"],+ "metadata": {"agent": "janitor_agent", "brain_id": brain_id},+ },)@retry(@@ -649,13 +678,13 @@ class JanitorAgent:def _invoke_agent_with_retry(previous_messages: list):"""Invoke the agent using the provided message history, update token counters from any returned usage metadata, and return the agent's response.-+Parameters:previous_messages (list): Accumulated conversation messages to send as context to the agent.-+Returns:dict: The agent's response object; expected to include a "messages" list containing response message objects.-+Raises:TimeoutError: If the invocation exceeds the configured timeout or if retries are exhausted; the exception message contains timing or last-attempt error details."""@@ -671,6 +700,7 @@ class JanitorAgent:self.output_tokens,self.cached_tokens,self.reasoning_tokens,+ "janitor_agent",)return responseexcept FutureTimeoutError:@@ -690,13 +720,13 @@ class JanitorAgent:def _invoke_and_process(previous_messages: list):"""Invoke the agent with retry logic, append any returned messages to the outer `accumulated_messages` list, and return the agent response.-+Parameters:previous_messages (list): Messages to include in the invocation request.-+Returns:response (dict): The agent's response object; may include a `messages` key with returned messages.-+Raises:TimeoutError: If the invocation exhausts retry attempts or a timeout occurs."""@@ -704,7 +734,7 @@ class JanitorAgent:response = _invoke_agent_with_retry(previous_messages)messages = response.get("messages", [])if messages:- accumulated_messages.extend(messages)+ accumulated_messages.extend(self._content_only_history(messages))return responseexcept RetryError as e:last_attempt = e.last_attempt@@ -736,7 +766,7 @@ class JanitorAgent:def _update_token_counts(self, usage_metadata: dict):"""Update the agent's cumulative token counters from a message's usage metadata.-+Parameters:usage_metadata (dict): A mapping containing token usage information. Recognized keys:- "input_tokens": number to add to `input_tokens`@@ -754,4 +784,4 @@ class JanitorAgent:# Output details (reasoning)output_details = usage_metadata.get("output_token_details", {})- self.reasoning_tokens += output_details.get("reasoning", 0)\ No newline at end of file+ self.reasoning_tokens += output_details.get("reasoning", 0)diff --git a/src/core/agents/kg_agent.py b/src/core/agents/kg_agent.pyindex 0666bec..e2fb37f 100644--- a/src/core/agents/kg_agent.py+++ b/src/core/agents/kg_agent.py@@ -3,16 +3,18 @@ File: /kg_agent.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 12th 2026 8:26:26 pm+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""+import osfrom typing import Iterable, List, Literal, Optional, Unionfrom langchain.agents import create_agentfrom langchain.tools import BaseToolfrom pydantic import BaseModelfrom concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError+from langgraph.errors import GraphRecursionErrorfrom tenacity import (retry,stop_after_attempt,@@ -42,8 +44,19 @@ from src.core.agents.tools.kg_agent import (KGAgentUpdatePropertiesTool,)from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter+from src.core.agents.tools.kg_agent.KGAgentRemoveRelationshipTool import (+ KGAgentRemoveRelationshipTool,+)+from src.core.agents.tools.kg_agent.KGAgentRemoveNodeTool import KGAgentRemoveNodeTool+from src.core.agents.tools.kg_agent.KGAgentCreateRelationshipTool import (+ KGAgentCreateRelationshipTool,+)+from src.core.agents.tools.kg_agent.KGAgentCreateNodeTool import KGAgentCreateNodeToolfrom src.utils.tokens import token_detail_from_token_counts+MAX_RECURSION_LIMIT = 50+MAX_RECURSION_LIMIT_GRAPH_CONSOLIDATOR = 50+class KGAgent:"""@@ -62,10 +75,10 @@ class KGAgent:):"""Initialize the KGAgent with required adapters, storage, and a human-readable database description.-+Parameters:database_desc (str): A brief description of the knowledge graph or database this agent will operate on.-+Description:Stores provided adapters and clients on the instance, sets the agent to None, and initializes token accounting fields:`input_tokens`, `output_tokens`, `cached_tokens`, `reasoning_tokens` set to 0 and `token_detail` set to None.@@ -82,11 +95,13 @@ class KGAgent:self.cached_tokens = 0self.reasoning_tokens = 0self.token_detail = None+ self._agent_type = None+ self._agent_brain_id = Nonedef _execute_graph_operation(self, operation: str) -> str:"""Execute a graph operation string against the configured knowledge graph.-+Returns:str: A human-readable status message indicating success, or an error message containing the exception text and the graph database type when execution fails."""@@ -148,9 +163,9 @@ class KGAgent:):"""Configure and create the LLM agent instance used by the KGAgent.-+This method selects an appropriate system prompt based on `type_`, constructs or uses the provided toolset, applies an optional output schema, and assigns the created agent to `self.agent`.-+Parameters:type_ (Literal["normal", "graph-consolidator"]): Agent mode determining which system prompt to use.identification_params (dict): Identification details (IDs, names) used when building default tools.@@ -179,7 +194,10 @@ class KGAgent:),system_prompt=system_prompt,response_format=output_schema if output_schema else None,+ debug=os.environ.get("DEBUG", "false").lower() == "true",)+ self._agent_type = type_+ self._agent_brain_id = brain_iddef search_kg(self, query: str) -> str:"""@@ -227,7 +245,11 @@ class KGAgent:],},print_mode="debug",- config={"recursion_limit": 50},+ config={+ "recursion_limit": MAX_RECURSION_LIMIT,+ "tags": ["kg_agent"],+ "metadata": {"agent": "kg_agent", "brain_id": brain_id},+ },)return response@@ -262,7 +284,11 @@ class KGAgent:],},print_mode="debug",- config={"recursion_limit": 50},+ config={+ "recursion_limit": MAX_RECURSION_LIMIT,+ "tags": ["kg_agent"],+ "metadata": {"agent": "kg_agent", "brain_id": brain_id},+ },)return response@@ -275,12 +301,12 @@ class KGAgent:) -> RetrieveNeighborsOutputSchema:"""Retrieve neighboring nodes and relationship information for a given node, filtered by optional criteria and capped by a maximum result count.-+Parameters:node (Node): The main node whose neighbors should be retrieved.looking_for (Optional[Union[str, Iterable[str]]]): A single reason string or an iterable of reason strings used to filter or prioritize which neighbors to return; if None, no extra filtering is applied.limit (int): Maximum number of neighbor entries to return.-+Returns:RetrieveNeighborsOutputSchema: Structured neighbor data containing the matching nodes, relationships, and associated properties."""@@ -336,7 +362,11 @@ class KGAgent:}],},- config={"recursion_limit": 50},+ config={+ "recursion_limit": MAX_RECURSION_LIMIT,+ "tags": ["kg_agent"],+ "metadata": {"agent": "kg_agent", "brain_id": brain_id},+ },print_mode="debug",)@@ -350,43 +380,76 @@ class KGAgent:brain_id: str = "default",timeout: int = 180,max_retries: int = 3,+ reuse_agent: bool = True,) -> str:"""Invoke the graph-consolidator agent to perform a consolidation task on the knowledge graph.-+Parameters:task (str): Natural-language instruction describing the consolidation operation to run.brain_id (str): Identifier of the knowledge graph brain to target; defaults to "default".timeout (int): Maximum seconds to wait for a single agent invocation before timing out.max_retries (int): Maximum number of retry attempts for the agent invocation when timeouts occur.-+Returns:status (str): `"OK"` when the consolidator completes successfully.-+Raises:TimeoutError: If a single invocation exceeds `timeout` seconds or if all retry attempts fail."""- self._get_agent(- type_="graph-consolidator",- identification_params={},- metadata={},- tools=[- KGAgentExecuteGraphOperationTool(- self,- self.kg,- self.database_desc,- brain_id=brain_id,- )- ],- )+ if (+ not reuse_agent+ or self.agent is None+ or self._agent_type != "graph-consolidator"+ or self._agent_brain_id != brain_id+ ):+ self._get_agent(+ type_="graph-consolidator",+ identification_params={},+ metadata={},+ tools=[+ KGAgentExecuteGraphOperationTool(+ self,+ self.kg,+ self.database_desc,+ brain_id=brain_id,+ ),+ KGAgentCreateNodeTool(+ self,+ self.kg,+ self.embeddings,+ self.vector_store,+ brain_id=brain_id,+ ),+ KGAgentCreateRelationshipTool(+ self,+ self.kg,+ self.embeddings,+ self.vector_store,+ brain_id=brain_id,+ ),+ KGAgentRemoveNodeTool(+ self,+ self.kg,+ self.vector_store,+ brain_id=brain_id,+ ),+ KGAgentRemoveRelationshipTool(+ self,+ self.kg,+ self.vector_store,+ brain_id=brain_id,+ ),+ ],+ )def _invoke_agent():"""Invoke the configured agent with the graph-consolidator prompt for the current task.-+Sends a user message containing the graph-consolidator task prompt to the agent and returns the agent's response.-+Returns:dict: Agent response containing generated message content and associated metadata (for example, token usage and model output)."""@@ -401,6 +464,11 @@ class KGAgent:}],},+ config={+ "recursion_limit": MAX_RECURSION_LIMIT_GRAPH_CONSOLIDATOR,+ "tags": ["kg_agent", "kg_graph_consolidator"],+ "metadata": {"agent": "kg_agent", "brain_id": brain_id},+ },)@retry(@@ -412,12 +480,12 @@ class KGAgent:def _invoke_agent_with_retry():"""Invoke the graph-consolidator agent with a timeout and update token accounting from the response.-+Waits up to `timeout` seconds for the agent invocation to complete. For any returned message that contains `usage_metadata`, updates the agent's token counters and `token_detail`. Returns the agent response dictionary.-+Returns:dict: The agent response.-+Raises:TimeoutError: If the agent invocation does not complete within `timeout` seconds."""@@ -433,6 +501,7 @@ class KGAgent:self.output_tokens,self.cached_tokens,self.reasoning_tokens,+ "kg_agent",)return responseexcept FutureTimeoutError:@@ -443,6 +512,11 @@ class KGAgent:try:response = _invoke_agent_with_retry()+ except GraphRecursionError as e:+ raise ValueError(+ "Graph consolidator hit recursion limit without reaching a stop condition. "+ "Consider increasing recursion_limit or simplifying the consolidation task."+ ) from eexcept RetryError as e:last_attempt = e.last_attemptraise TimeoutError(@@ -457,11 +531,11 @@ class KGAgent:def _update_token_counts(self, usage_metadata: dict):"""Update the agent's token counters from LLM usage metadata.-+Reads token counts from the provided `usage_metadata` mapping and increments the agent'sinternal counters: `input_tokens`, `output_tokens`, `cached_tokens`, and `reasoning_tokens`.Missing entries are treated as zero.-+Parameters:usage_metadata (dict): Usage metadata containing any of the following keys:- "input_tokens": total input token count (int)@@ -479,4 +553,4 @@ class KGAgent:# Output details (reasoning)output_details = usage_metadata.get("output_token_details", {})- self.reasoning_tokens += output_details.get("reasoning", 0)\ No newline at end of file+ self.reasoning_tokens += output_details.get("reasoning", 0)diff --git a/src/core/agents/scout_agent.py b/src/core/agents/scout_agent.pyindex 215d450..9f79ce4 100644--- a/src/core/agents/scout_agent.py+++ b/src/core/agents/scout_agent.py@@ -91,7 +91,7 @@ class ScoutAgent:):"""Initialize a ScoutAgent with the provided adapters and reset internal agent and token-tracking state.-+Stores the provided LLM, cache, knowledge graph, vector store, and embeddings adapters on the instance, sets the agent and token_detail to None, and initializes input_tokens, output_tokens, cached_tokens, and reasoning_tokens counters to zero."""self.llm_adapter = llm_adapter@@ -109,10 +109,10 @@ class ScoutAgent:def _get_tools(self, brain_id: str = "default") -> List[BaseTool]:"""Provide the list of tools available to the agent for a given brain identifier.-+Parameters:brain_id (str): Identifier of the brain/context to retrieve tools for; defaults to "default".-+Returns:List[BaseTool]: A list of BaseTool instances available to the agent for the specified brain."""@@ -144,25 +144,26 @@ class ScoutAgent:brain_id: str = "default",timeout: int = 90,max_retries: int = 3,+ ingestion_session_id: Optional[str] = None,) -> ScoutAgentResponse:"""Extract entities from the provided text using the Scout agent and return a structured response containing the entities and token usage.-+Performs an LLM invocation (with optional targeting context), applies retries with exponential backoff on timeouts, enforces a per-invocation timeout, and accumulates token usage from the agent responses.-+Parameters:text: The input text to extract entities from.targeting: Optional Node providing contextual targeting information (name, description, properties) to bias extraction.brain_id: Identifier for the agent/brain configuration to use.timeout: Maximum seconds to wait for a single agent invocation before treating it as a timeout.max_retries: Maximum number of retry attempts for timed-out invocations using exponential backoff.-+Returns:A ScoutAgentResponse containing:- entities: list of extracted ScoutEntity objects.- input_tokens: accumulated input token count observed during the run.- output_tokens: accumulated output token count observed during the run.-+Raises:TimeoutError: If a single invocation exceeds `timeout`, or if all retry attempts fail due to timeouts."""@@ -193,6 +194,18 @@ class ScoutAgent:}],},+ config={+ "tags": ["scout_agent"],+ "metadata": {+ "agent": "scout_agent",+ "brain_id": brain_id,+ **(+ {"ingestion_session_id": ingestion_session_id}+ if ingestion_session_id+ else {}+ ),+ },+ },)@retry(@@ -204,10 +217,10 @@ class ScoutAgent:def _invoke_agent_with_retry():"""Invoke the agent in a separate thread, enforce the configured timeout, and update token accounting from the agent's response.-+Returns:dict: The agent response dictionary.-+Raises:TimeoutError: If the agent invocation exceeds the specified timeout."""@@ -223,6 +236,7 @@ class ScoutAgent:self.output_tokens,self.cached_tokens,self.reasoning_tokens,+ "scout_agent",)return responseexcept FutureTimeoutError:@@ -254,7 +268,7 @@ class ScoutAgent:def _update_token_counts(self, usage_metadata: dict):"""Update the agent's accumulated token counters from a usage metadata dictionary.-+Parameters:usage_metadata (dict): Metadata containing token counts. Expected keys:- "input_tokens": integer count to add to input_tokens (defaults to 0)@@ -272,4 +286,4 @@ class ScoutAgent:# Output details (reasoning)output_details = usage_metadata.get("output_token_details", {})- self.reasoning_tokens += output_details.get("reasoning", 0)\ No newline at end of file+ self.reasoning_tokens += output_details.get("reasoning", 0)diff --git a/src/core/agents/tools/architect_agent/ArchitectAgentCheckUsedEntitiesTool.py b/src/core/agents/tools/architect_agent/ArchitectAgentCheckUsedEntitiesTool.pyindex 4c79a66..f35b4a5 100644--- a/src/core/agents/tools/architect_agent/ArchitectAgentCheckUsedEntitiesTool.py+++ b/src/core/agents/tools/architect_agent/ArchitectAgentCheckUsedEntitiesTool.py@@ -4,7 +4,7 @@ Project: architect_agentCreated Date: Saturday January 17th 2026Author: Christian Nonis <[email protected]>------Last Modified: Saturday January 17th 2026 12:37:32 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -12,6 +12,8 @@ Modified By: Christian Nonis <[email protected]>import jsonfrom langchain.tools import BaseTool+from src.utils.cleanup import strip_properties+class ArchitectAgentCheckUsedEntitiesTool(BaseTool):name: str = "architect_agent_check_used_entities"@@ -23,9 +25,9 @@ class ArchitectAgentCheckUsedEntitiesTool(BaseTool):):"""Initialize the tool with the given architect agent and set its description.-+This tool inspects the architect agent's used_entities_set to report entities that have been used; it should be invoked after relationships are created and entities are marked as used.-+Parameters:architect_agent (object): The architect agent instance whose used entities the tool will check."""@@ -42,15 +44,19 @@ class ArchitectAgentCheckUsedEntitiesTool(BaseTool):def _run(self, *args, **kwargs) -> str:"""Collect the set of entities marked as used by the architect agent and return them as a JSON string.-+Each entity is converted to a plain mapping by calling `model_dump()` if present on the entity, otherwise `dict()`, and the resulting list of mappings is serialized to JSON.-+Returns:json_str (str): JSON-formatted string containing a list of serialized entity mappings."""entities_list = [- entity.model_dump() if hasattr(entity, "model_dump") else entity.dict()- for entity in self.architect_agent.used_entities_set+ (+ strip_properties([entity.model_dump(mode="json")])[0]+ if hasattr(entity, "model_dump")+ else entity+ )+ for entity in self.architect_agent.used_entities_dict.values()]print("[DEBUG (architect_agent_check_used_entities)]: ", entities_list)- return json.dumps(entities_list)\ No newline at end of file+ return json.dumps(entities_list)diff --git a/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py b/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.pyindex 6b6e5a7..75a6c99 100644--- a/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py+++ b/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py@@ -3,13 +3,12 @@ File: /ArchitectAgentCreateRelationshipTool.pyCreated Date: Wednesday January 14th 2026Author: Christian Nonis <[email protected]>------Last Modified: Wednesday January 14th 2026 10:22:53 pm+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""from dataclasses import dataclass-import jsonfrom typing import Dict, List, Optionalimport uuidfrom langchain.tools import BaseTool@@ -31,6 +30,7 @@ from src.services.input.agents import (vector_store_adapter,)from src.lib.neo4j.client import _neo4j_client+from src.utils.cleanup import strip_propertiesfrom src.utils.nlp.names import levenshtein_similarityfrom src.utils.similarity.vectors import cosine_similarityfrom src.utils.tokens import merge_token_details, token_detail_from_token_counts@@ -53,7 +53,7 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):},"predicate": {"type": "string",- "description": "The name of the relationship",+ "description": "The generic name of the relationship (eg: 'TARGET_PRODUCT_OBJECT_CROISSANTS' = wrong, 'TARGETED' = correct)",},"object": {"type": "string",@@ -63,6 +63,10 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):"type": "string","description": "The description of the relationship",},+ "amount": {+ "type": "number",+ "description": "The amount of the relationship (eg: 12 for 'John knew 12 new friends in New York City')",+ },},"required": ["subject", "predicate", "object", "description"],},@@ -88,7 +92,7 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):):"""Initialize the tool for creating a set of relationships between entities for a single phrase.-+Parameters:architect_agent (object): The owning architect agent instance that this tool will update (holds state like entities, token details, and relationships).text (str): The source text or phrase that the relationships represent.@@ -122,24 +126,62 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):object: strdescription: str+ def _most_similar_entities(self, query: str, limit: int = 5) -> list[str]:+ def _e_attr(e, k):+ return e.get(k) if isinstance(e, dict) else getattr(e, k, None)++ all_entities = list(self.entities.values()) + list(+ self.architect_agent.used_entities_dict.values()+ )+ scored = []+ for entity in all_entities:+ uuid_val = _e_attr(entity, "uuid")+ name_val = _e_attr(entity, "name")+ if not uuid_val and not name_val:+ continue+ uuid_sim = levenshtein_similarity(query, str(uuid_val)) if uuid_val else 0.0+ name_sim = levenshtein_similarity(query, str(name_val)) if name_val else 0.0+ best = max(uuid_sim, name_sim)+ scored.append((entity, best))+ scored.sort(key=lambda x: x[1], reverse=True)+ result = []+ uuids = [_e_attr(s[0], "uuid") for s in scored[:limit] if _e_attr(s[0], "uuid")]+ nodes_by_uuid = {}+ if uuids:+ try:+ nodes = self.kg.get_by_uuids(uuids, brain_id=self.brain_id)+ nodes_by_uuid = {n.uuid: n for n in nodes}+ except Exception:+ pass+ for entity, _ in scored[:limit]:+ e_uuid = _e_attr(entity, "uuid")+ e_name = _e_attr(entity, "name")+ part = f"{e_name} ({e_uuid})"+ node = nodes_by_uuid.get(e_uuid) if e_uuid else None+ if node:+ labels = ", ".join(node.labels) if node.labels else "?"+ part += f" -> node: {node.name} [{labels}]"+ result.append(part)+ return result+def _run(self, *args, **kwargs) -> str:"""Validate and create architect relationships from the provided input, normalize them via the JanitorAgent, enqueue ingestion, and return the operation result.-+Parameters:- relationships (list[dict], optional): A list of relationship objects provided either as the first positional argument (or as args[0]["relationships"]) or via the "relationships" keyword. Each relationship dict should include:- - subject: UUID or name of the subject entity (required)- - predicate: relationship name/label- - object: UUID or name of the object entity (required)- - description: textual description of the relationship- - amount: optional numeric value associated with the relationship- - properties: optional dict of additional properties- The method resolves subject and object against the tool's entity map and the architect_agent's used_entities_set.-+ relationships (list[dict], optional): A list of relationship objects provided either as the first positional argument (or as args[0]["relationships"]) or via the "relationships" keyword. Each relationship dict should include:+ - subject: UUID or name of the subject entity (required)+ - predicate: relationship name/label+ - object: UUID or name of the object entity (required)+ - description: textual description of the relationship+ - amount: optional numeric value associated with the relationship+ - properties: optional dict of additional properties+ The method resolves subject and object against the tool's entity map and the architect_agent's used_entities_set.+Returns:- A success JSON string on successful creation: '{"status": "success", "message": "relationships created successfully"}'.- An error string if the required "relationships" parameter is missing or if a subject/object cannot be resolved (e.g., 'Subject not found in entities: ...').- A dict with status "ERROR" when the JanitorAgent reports wrong relationships; the dict includes keys "wrong_relationships" and "newly_created_nodes".+ A success JSON string on successful creation: '{"status": "success"}'.+ An error string if the required "relationships" parameter is missing or if a subject/object cannot be resolved (e.g., 'Subject not found in entities: ...').+ A dict with status "ERROR" when the JanitorAgent reports wrong relationships; the dict includes keys "wrong_relationships" and "newly_created_nodes"."""rel_key = str(uuid.uuid4())@@ -183,63 +225,83 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):if isinstance(object, str):object = object.strip()- subj_entity = self.entities.get(subject)- if not subj_entity:- for ent in self.architect_agent.used_entities_set:- if ent.uuid == subject:- subj_entity = ent- break+ def _resolve_entity(ref: str):+ entity = self.entities.get(ref)+ if entity:+ return entity+ entity = self.architect_agent.used_entities_dict.get(ref)+ if entity:+ return entity+ all_ents = list(self.entities.values()) + list(+ self.architect_agent.used_entities_dict.values()+ )+ for e in all_ents:+ e_uuid = (+ e.get("uuid")+ if isinstance(e, dict)+ else getattr(e, "uuid", None)+ )+ e_name = (+ e.get("name")+ if isinstance(e, dict)+ else getattr(e, "name", None)+ )+ if ref in (e_uuid, e_name):+ return e+ return None- obj_entity = self.entities.get(object)- if not obj_entity:- for ent in self.architect_agent.used_entities_set:- if ent.uuid == object:- obj_entity = ent- break+ subj_entity = _resolve_entity(subject)+ obj_entity = _resolve_entity(object)if subj_entity is None:- print(- "[DEBUG (architect_agent_create_relationship)]: Subject not found in entities: ",- subject,- ". Available entities: ",- list(self.entities.keys()),+ similar = self._most_similar_entities(subject, limit=3)+ msg = (+ f"Subject not found in entities: {subject}. Most similar: {similar}")- return f"Subject not found in entities: {subject}. Available entities: {list(self.entities.keys())}"++ print(f"[DEBUG (architect_agent_create_relationship)]: {msg}")+ return msgif obj_entity is None:- print(- "[DEBUG (architect_agent_create_relationship)]: Object not found in entities: ",- object,- ". Available entities: ",- list(self.entities.keys()),+ similar = self._most_similar_entities(object, limit=3)+ msg = f"Object not found in entities: {object}. Most similar: {similar}"++ print(f"[DEBUG (architect_agent_create_relationship)]: {msg}")+ return msg++ def _attr(e, k, default=None):+ return (+ e.get(k, default) if isinstance(e, dict) else getattr(e, k, default))- return f"Object not found in entities: {object}. Available entities: {list(self.entities.keys())}"++ def _props(e):+ return _attr(e, "properties") or {}subj = ArchitectAgentEntity(- uuid=subj_entity.uuid,- name=subj_entity.name,- type=subj_entity.type,- description=subj_entity.description,+ uuid=_attr(subj_entity, "uuid"),+ name=_attr(subj_entity, "name"),+ type=_attr(subj_entity, "type"),+ description=_attr(subj_entity, "description"),**(- {"happened_at": subj_entity.properties.get("happened_at")}- if subj_entity.properties.get("happened_at")+ {"happened_at": _props(subj_entity).get("happened_at")}+ if _props(subj_entity).get("happened_at")else {}),- properties=subj_entity.properties,- polarity=subj_entity.polarity if subj_entity.polarity else "neutral",+ properties=_props(subj_entity),+ polarity=_attr(subj_entity, "polarity") or "neutral",)obj = ArchitectAgentEntity(- uuid=obj_entity.uuid,- name=obj_entity.name,- type=obj_entity.type,- description=obj_entity.description,+ uuid=_attr(obj_entity, "uuid"),+ name=_attr(obj_entity, "name"),+ type=_attr(obj_entity, "type"),+ description=_attr(obj_entity, "description"),**(- {"happened_at": obj_entity.properties.get("happened_at")}- if obj_entity.properties.get("happened_at")+ {"happened_at": _props(obj_entity).get("happened_at")}+ if _props(obj_entity).get("happened_at")else {}),- properties=obj_entity.properties,- polarity=obj_entity.polarity if obj_entity.polarity else "neutral",+ properties=_props(obj_entity),+ polarity=_attr(obj_entity, "polarity") or "neutral",)input_rels.append(@@ -262,13 +324,24 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):from src.core.agents.janitor_agent import JanitorAgent- janitor_agent = JanitorAgent(- llm_small_adapter,- kg=graph_adapter,- vector_store=vector_store_adapter,- embeddings=embeddings_adapter,- database_desc=_neo4j_client.graphdb_description,+ janitor_agent = getattr(self.architect_agent, "janitor_agent", None)+ janitor_agent_brain_id = getattr(+ self.architect_agent, "_janitor_agent_brain_id", None)+ if janitor_agent is None or janitor_agent_brain_id != self.brain_id:+ janitor_agent = JanitorAgent(+ llm_small_adapter,+ kg=graph_adapter,+ vector_store=vector_store_adapter,+ embeddings=embeddings_adapter,+ database_desc=_neo4j_client.graphdb_description,+ )+ self.architect_agent.janitor_agent = janitor_agent+ self.architect_agent._janitor_agent_brain_id = self.brain_id+ start_input_tokens = janitor_agent.input_tokens+ start_output_tokens = janitor_agent.output_tokens+ start_cached_tokens = janitor_agent.cached_tokens+ start_reasoning_tokens = janitor_agent.reasoning_tokensjanitor_response: AtomicJanitorAgentInputOutput = (janitor_agent.run_atomic_janitor(@@ -287,10 +360,11 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):)janitor_token_detail = token_detail_from_token_counts(- self.architect_agent.input_tokens,- self.architect_agent.output_tokens,- self.architect_agent.cached_tokens,- self.architect_agent.reasoning_tokens,+ janitor_agent.input_tokens - start_input_tokens,+ janitor_agent.output_tokens - start_output_tokens,+ janitor_agent.cached_tokens - start_cached_tokens,+ janitor_agent.reasoning_tokens - start_reasoning_tokens,+ "janitor_agent",)self.architect_agent.token_detail = merge_token_details([self.architect_agent.token_detail, janitor_token_detail]@@ -311,13 +385,14 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):self.architect_agent.entities.update({scout_entity.uuid: scout_entity})newly_created_nodes.append(scout_entity.model_dump(mode="json"))- fixed_rels_sets = []+ fixed_rels_sets = set()fixed_relationships = getattr(janitor_response, "fixed_relationships", []) or []if fixed_relationships:- fixed_rels_sets = [- set((fr.tip.uuid, fr.tail.uuid, fr.name)) for fr in fixed_relationships- ]+ fixed_rels_sets = set(+ frozenset((fr.tip.uuid, fr.tail.uuid, fr.name))+ for fr in fixed_relationships+ )output_rels.extend([ArchitectAgentRelationship(@@ -337,71 +412,67 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):])- fixed_rels_vs = {}- input_rels_vs = {}+ # Batch embed texts for similarity comparison+ texts_to_embed = set()+ for rel in input_rels:+ texts_to_embed.add(rel.description if rel.description else rel.name)+ for rel in fixed_relationships:+ texts_to_embed.add(rel.description if rel.description else rel.name)++ text_to_embedding = {}+ if texts_to_embed:+ texts_list = list(texts_to_embed)+ vectors = embeddings_small_adapter.embed_texts(texts_list)+ for text, vector in zip(texts_list, vectors):+ text_to_embedding[text] = vector.embeddingsfor rel in input_rels:have_similar_relation = False- if set((rel.tip.uuid, rel.tail.uuid, rel.name)) in fixed_rels_sets:+ if frozenset((rel.tip.uuid, rel.tail.uuid, rel.name)) in fixed_rels_sets:have_similar_relation = Trueelse:rels_with_same_subject_and_object = [- [r, rel]- for r in fixed_relationships- if r.tip.uuid == rel.tip.uuid- and r.tail.uuid == rel.tail.uuid- or r.tip.uuid == rel.tail.uuid- and r.tail.uuid == rel.tip.uuid+ fr+ for fr in fixed_relationships+ if (fr.tip.uuid == rel.tip.uuid and fr.tail.uuid == rel.tail.uuid)+ or (fr.tip.uuid == rel.tail.uuid and fr.tail.uuid == rel.tip.uuid)]if rels_with_same_subject_and_object:- for fr, _rel in rels_with_same_subject_and_object:- fixed_rels_vs[f"{fr.name}-{fixed_relationships.index(fr)}"] = (- fixed_rels_vs.get(- f"{fr.name}-{fixed_relationships.index(fr)}",- {- "r": fr,- "embeddings": embeddings_small_adapter.embed_text(- fr.name- ).embeddings,- },+ input_rel_text = rel.description if rel.description else rel.name+ input_embedding = text_to_embedding.get(input_rel_text)++ candidates = []+ for fr in rels_with_same_subject_and_object:+ fixed_rel_text = fr.description if fr.description else fr.name+ fixed_embedding = text_to_embedding.get(fixed_rel_text)++ if input_embedding and fixed_embedding:+ candidates.append(+ (+ cosine_similarity(fixed_embedding, input_embedding),+ fr,+ ))- )- input_rels_vs[f"{_rel.name}-{input_rels.index(_rel)}"] = (- input_rels_vs.get(- f"{_rel.name}-{input_rels.index(_rel)}",- {- "r": _rel,- "embeddings": embeddings_small_adapter.embed_text(- _rel.name- ).embeddings,- },- )- )- target_embedding = input_rels_vs[- f"{rel.name}-{input_rels.index(rel)}"- ]["embeddings"]- candidates = [- (cosine_similarity(cand["embeddings"], target_embedding), cand)- for cand in fixed_rels_vs.values()- ]- similarity_score, most_similar_fixed_rel = max(- candidates, key=lambda x: x[0]- )+ if candidates:+ similarity_score, most_similar_fixed_rel = max(+ candidates, key=lambda x: x[0]+ )- if (- similarity_score > 0.90- ): # TODO: [similarity_threshold] check if this is the suitable threshold- have_similar_relation = True- print(- "[DEBUG (architect_agent_create_relationship)]: Have similar relation: ",- have_similar_relation,- "similarity_score: ",- similarity_score,- "most_similar_fixed_rel: ",- most_similar_fixed_rel,- )+ if (+ similarity_score > 0.90+ ): # TODO: [similarity_threshold] check if this is the suitable threshold+ have_similar_relation = True+ print(+ "[DEBUG (architect_agent_create_relationship)]: Have similar relation: ",+ have_similar_relation,+ "similarity_score: ",+ similarity_score,+ "rels: ",+ most_similar_fixed_rel,+ rel,+ )if not have_similar_relation:output_rels.append(@@ -428,19 +499,47 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):if relationships_data:from src.workers.tasks.ingestion import process_architect_relationships+ from src.lib.redis.client import _redis_clientprint("[DEBUG (architect_agent_create_relationship)]: Sending relationships to ingestion task")- process_architect_relationships.delay(++ session_id = getattr(self.architect_agent, "session_id", None)+ if session_id:+ _redis_client.client.incr(+ f"{self.brain_id}:session:{session_id}:pending_tasks"+ )++ task_result = process_architect_relationships.delay({"relationships": relationships_data,"brain_id": self.brain_id,+ "session_id": session_id,})+ print(+ f"[DEBUG (architect_agent_create_relationship)]: Task {task_result.id} queued for session {session_id}"+ )self.architect_agent.relationships_set.extend(output_rels)+ session_id = getattr(self.architect_agent, "session_id", None)+ if session_id and output_rels:+ from src.lib.redis.client import _redis_client+ import json++ relationships_data = [+ rel.model_dump(mode="json")+ for rel in self.architect_agent.relationships_set+ ]+ _redis_client.set(+ f"session:{session_id}:relationships",+ json.dumps(relationships_data),+ brain_id=self.brain_id,+ expires_in=3600,+ )+wrong_relationships = []if getattr(janitor_response, "wrong_relationships", []):wrong_relationships = getattr(janitor_response, "wrong_relationships", [])@@ -452,8 +551,15 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):)return {"status": "ERROR",- "wrong_relationships": janitor_response.wrong_relationships,- "newly_created_nodes": newly_created_nodes,+ "wrong_relationships": strip_properties(+ [+ rel.model_dump(mode="json")+ for rel in janitor_response.wrong_relationships+ ]+ ),+ "newly_created_nodes": strip_properties(+ [node for node in newly_created_nodes]+ ),}# for entity_uuid in used_entity_uuids:@@ -462,6 +568,4 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):# return natural_lang- return json.dumps(- {"status": "success", "message": "relationships created successfully"}- )\ No newline at end of file+ return json.dumps({"status": "success"})diff --git a/src/core/agents/tools/architect_agent/ArchitectAgentGetRemainingEntitiesToProcessTool.py b/src/core/agents/tools/architect_agent/ArchitectAgentGetRemainingEntitiesToProcessTool.pyindex c9b1009..38db045 100644--- a/src/core/agents/tools/architect_agent/ArchitectAgentGetRemainingEntitiesToProcessTool.py+++ b/src/core/agents/tools/architect_agent/ArchitectAgentGetRemainingEntitiesToProcessTool.py@@ -4,7 +4,7 @@ Project: architect_agentCreated Date: Friday January 16th 2026Author: Christian Nonis <[email protected]>------Last Modified: Friday January 16th 2026 10:55:16 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -12,6 +12,8 @@ Modified By: Christian Nonis <[email protected]>import jsonfrom langchain.tools import BaseTool+from src.utils.cleanup import strip_properties+class ArchitectAgentGetRemainingEntitiesToProcessTool(BaseTool):name: str = "architect_agent_get_remaining_entities_to_process"@@ -23,7 +25,7 @@ class ArchitectAgentGetRemainingEntitiesToProcessTool(BaseTool):):"""Initialize the tool with an architect agent whose entities will be inspected to determine remaining work.-+Parameters:architect_agent (object): The architect agent instance that exposes an `entities` mapping; each entity is expected to support `model_dump(mode="json")` for serialization."""@@ -41,13 +43,22 @@ class ArchitectAgentGetRemainingEntitiesToProcessTool(BaseTool):def _run(self, *args, **kwargs) -> str:"""Get a JSON string listing the remaining entities to process.-+Returns:str: A JSON array string where each element is the serialized representation of an entity produced by calling `model_dump(mode="json")` on each entity in `self.architect_agent.entities`."""remaining_entities = json.dumps([- entity.model_dump(mode="json")+ strip_properties(+ [+ (+ entity.model_dump(mode="json")+ if hasattr(entity, "model_dump")+ else entity+ )+ ],+ pop_also=["description", "polarity"],+ )[0]for entity in self.architect_agent.entities.values()])@@ -55,4 +66,4 @@ class ArchitectAgentGetRemainingEntitiesToProcessTool(BaseTool):"[DEBUG (architect_agent_get_remaining_entities_to_process)]: ",remaining_entities,)- return remaining_entities\ No newline at end of file+ return remaining_entitiesdiff --git a/src/core/agents/tools/architect_agent/ArchitectAgentMarkEntitiesAsUsedTool.py b/src/core/agents/tools/architect_agent/ArchitectAgentMarkEntitiesAsUsedTool.pyindex b78c416..06cb857 100644--- a/src/core/agents/tools/architect_agent/ArchitectAgentMarkEntitiesAsUsedTool.py+++ b/src/core/agents/tools/architect_agent/ArchitectAgentMarkEntitiesAsUsedTool.py@@ -4,7 +4,7 @@ Project: architect_agentCreated Date: Saturday January 17th 2026Author: Christian Nonis <[email protected]>------Last Modified: Saturday January 17th 2026 12:37:22 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -12,6 +12,8 @@ Modified By: Christian Nonis <[email protected]>import jsonfrom langchain.tools import BaseTool+from src.utils.cleanup import strip_properties+class ArchitectAgentMarkEntitiesAsUsedTool(BaseTool):name: str = "architect_agent_mark_entities_as_used"@@ -37,7 +39,7 @@ class ArchitectAgentMarkEntitiesAsUsedTool(BaseTool):):"""Initialize the tool with a reference to the architect agent whose entities may be marked as used.-+Parameters:architect_agent (object): The architect agent instance whose `entities` and `used_entities_set` this tool will update."""@@ -54,9 +56,9 @@ class ArchitectAgentMarkEntitiesAsUsedTool(BaseTool):def _run(self, *args, **kwargs) -> str:"""Mark the given entity UUIDs as used on the associated architect agent.-+Accepts several input shapes to identify the UUIDs to mark: a dict argument with the key "entity_uuids", a keyword "entity_uuids", a list passed as the first positional argument, or keywords "entities" or "uuids". If a single string is provided it will be treated as a single UUID. If no recognizable input is provided, no entities are marked.-+Parameters:*args: Positional arguments; supported forms include:- A dict containing the key "entity_uuids" with a list of UUID strings.@@ -64,10 +66,10 @@ class ArchitectAgentMarkEntitiesAsUsedTool(BaseTool):**kwargs: Keyword arguments; supported keys include:- "entity_uuids", "entities", or "uuids" with a list (or single string) of UUIDs.- If exactly one keyword is provided, its value is used as the UUID list.-+Returns:result (str): The string "OK" after processing.-+Side effects:For each provided UUID found in self.architect_agent.entities, the entity is removed from that mapping and appended to self.architect_agent.used_entities_set."""@@ -99,7 +101,14 @@ class ArchitectAgentMarkEntitiesAsUsedTool(BaseTool):if entity_uuid in self.architect_agent.entities:removed_entity = self.architect_agent.entities.pop(entity_uuid)if removed_entity:- self.architect_agent.used_entities_set.append(removed_entity)+ _ent = (+ removed_entity.model_dump(mode="json")+ if hasattr(removed_entity, "model_dump")+ else removed_entity+ )+ self.architect_agent.used_entities_dict[_ent["uuid"]] = (+ strip_properties([_ent])[0]+ )else:print("[DEBUG (architect_agent_mark_entities_as_used)]: Entity found but not removed: ",@@ -113,8 +122,8 @@ class ArchitectAgentMarkEntitiesAsUsedTool(BaseTool):print("[DEBUG (architect_agent_mark_entities_as_used)]: Used entities: ",- self.architect_agent.used_entities_set,+ list(self.architect_agent.used_entities_dict.keys()),entities_to_mark,)- return "OK"\ No newline at end of file+ return "OK"diff --git a/src/core/agents/tools/janitor_agent/JanitorAgentSearchEntitiesTool.py b/src/core/agents/tools/janitor_agent/JanitorAgentSearchEntitiesTool.pyindex 5925390..0d76c80 100644--- a/src/core/agents/tools/janitor_agent/JanitorAgentSearchEntitiesTool.py+++ b/src/core/agents/tools/janitor_agent/JanitorAgentSearchEntitiesTool.py@@ -3,7 +3,7 @@ File: /JanitorAgentSearchEntitiesTool.pyCreated Date: Tuesday December 23rd 2025Author: Christian Nonis <[email protected]>------Last Modified: Tuesday December 23rd 2025 11:21:54 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -15,6 +15,7 @@ from langchain.tools import BaseToolfrom src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapterfrom src.adapters.graph import GraphAdapterfrom src.constants.kg import Node+from src.utils.cleanup import strip_propertiesclass JanitorAgentSearchEntitiesTool(BaseTool):@@ -54,9 +55,9 @@ class JanitorAgentSearchEntitiesTool(BaseTool):):"""Initialize the JanitorAgentSearchEntitiesTool with the required adapters and configuration.-+This tool performs plain-text searches against the knowledge graph and an optional vector store, aggregating results into a mapping from a sanitized query key to the list of matching entities.-+Parameters:brain_id (str): Identifier of the brain (knowledge scope) to use for searches. Defaults to "default"."""@@ -79,22 +80,41 @@ class JanitorAgentSearchEntitiesTool(BaseTool):def _run(self, *args, **kwargs) -> str:"""Search multiple query strings for matching entities in the knowledge graph and vector store, and return the aggregated results as a JSON-formatted mapping keyed by a sanitized query string.-+Parameters:args: If provided, the first positional argument is treated as the list of query strings to process.kwargs:queries (List[str]): List of query strings to search for when not passed as a positional argument.-+Returns:str: A JSON string mapping each sanitized query to either a list of found entity objects (each serialized to JSON) or a message indicating no matches were found."""-+_queries = []-+if len(args) > 0:- _queries = args[0] if isinstance(args[0], list) else [args[0]]- else:+ arg_val = args[0]+ if isinstance(arg_val, list):+ _queries = arg_val+ elif isinstance(arg_val, str):+ try:+ parsed = json.loads(arg_val)+ if isinstance(parsed, dict) and parsed.get("queries"):+ _queries = parsed.get("queries", [])+ else:+ _queries = [arg_val]+ except (json.JSONDecodeError, TypeError):+ _queries = [arg_val]+ else:+ _queries = [arg_val]++ if not _queries and len(kwargs) > 0:_queries = kwargs.get("queries", [])++ if not isinstance(_queries, list):+ _queries = [_queries] if _queries else []++ if not _queries:return "No queries provided in the arguments or kwargs"found_entities: Dict[str, Union[str, List[Node]]] = {}@@ -102,15 +122,15 @@ class JanitorAgentSearchEntitiesTool(BaseTool):def _clean_query(query: str) -> str:"""Sanitizes a query string into a normalized key suitable for dictionary lookup.-+Removes common punctuation, trims leading/trailing whitespace, converts to lowercase,and replaces spaces and hyphens with underscores.-+Parameters:- query (str): The input query text to normalize.-+ query (str): The input query text to normalize.+Returns:- sanitized (str): The normalized query string with punctuation removed, spaces and hyphens replaced by underscores, trimmed and lowercased.+ sanitized (str): The normalized query string with punctuation removed, spaces and hyphens replaced by underscores, trimmed and lowercased."""chars_to_remove = "'.\"()[]{}\\|*/+=<>,!?:;"chars_to_underscore = " -"@@ -132,6 +152,7 @@ class JanitorAgentSearchEntitiesTool(BaseTool):query_vector.embeddings,store="nodes",brain_id=self.brain_id,+ k=3,)if len(v_results) > 0:founds.extend(@@ -153,7 +174,11 @@ class JanitorAgentSearchEntitiesTool(BaseTool):)else:found_entities[_clean_query(_query)] = [- f.model_dump(mode="json") for f in founds+ strip_properties(+ [f.model_dump(mode="json")],+ pop_also=["last_updated", "v_id", "properties"],+ )[0]+ for f in founds]- return json.dumps(found_entities, indent=4)\ No newline at end of file+ return json.dumps(found_entities, indent=4)diff --git a/src/core/agents/tools/janitor_agent/JanitorAgentSearchRelationshipTool.py b/src/core/agents/tools/janitor_agent/JanitorAgentSearchRelationshipTool.pynew file mode 100644index 0000000..00ba1dc--- /dev/null+++ b/src/core/agents/tools/janitor_agent/JanitorAgentSearchRelationshipTool.py@@ -0,0 +1,151 @@+"""+File: /JanitorAgentSearchRelationshipTool.py+Project: janitor_agent+Created Date: Sunday February 1st 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Sunday February 1st 2026 2:40:43 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++import json+from typing import Dict, List, Tuple, Union+from langchain.tools import BaseTool++from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter+from src.adapters.graph import GraphAdapter+from src.constants.kg import Node, Predicate+from src.utils.cleanup import strip_properties+++class JanitorAgentSearchRelationshipsTool(BaseTool):+ """+ Tool for searching the relationships of the knowledge graph.+ """++ name: str = "list_relationships"+ janitor_agent: object+ kg: GraphAdapter+ brain_id: str = "default"++ args_schema: dict = {+ "type": "object",+ "properties": {+ "queries": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "subject": {+ "type": "string",+ "description": "The uuid of the subject",+ },+ "object": {+ "type": "string",+ "description": "The uuid of the object",+ },+ },+ "required": ["subject", "object"],+ },+ "description": "Lists the relationships between the subject and object.",+ },+ },+ "required": ["queries"],+ }++ def __init__(+ self,+ janitor_agent,+ kg: GraphAdapter,+ brain_id: str = "default",+ ):+ """+ Initialize the JanitorAgentSearchEntitiesTool with the required adapters and configuration.++ This tool performs plain-text searches against the knowledge graph and an optional vector store, aggregating results into a mapping from a sanitized query key to the list of matching entities.++ Parameters:+ brain_id (str): Identifier of the brain (knowledge scope) to use for searches. Defaults to "default".+ """+ description: str = (+ "Tool to list the relationships between the subject and object."+ "This tool will return the a list of relationships that were found in the knowledge graph between two entities."+ 'Example input: { "queries": [{"subject": "123e4567-e89b-12d3-a456-426614174000", "object": "123e4567-e89b-12d3-a456-426614174000"}] }'+ )+ super().__init__(+ janitor_agent=janitor_agent,+ kg=kg,+ description=description,+ brain_id=brain_id,+ )++ def _run(self, *args, **kwargs) -> str:+ """+ List the relationships between the subject and object.++ Parameters:+ args: If provided, the first positional argument is treated as the list of relationships to process.+ kwargs:+ relationships (List[dict]): List of relationships to search for when not passed as a positional argument.++ Returns:+ str: A JSON string mapping each relationship to either a list of found relationship objects (each serialized to JSON) or a message indicating no matches were found.+ """++ _queries = []++ if len(args) > 0:+ arg_val = args[0]+ if isinstance(arg_val, list):+ _queries = arg_val+ elif isinstance(arg_val, str):+ try:+ parsed = json.loads(arg_val)+ if isinstance(parsed, dict) and parsed.get("queries"):+ _queries = parsed.get("queries", [])+ else:+ _queries = [arg_val]+ except (json.JSONDecodeError, TypeError):+ _queries = [arg_val]+ else:+ _queries = [arg_val]++ if not _queries and len(kwargs) > 0:+ _queries = kwargs.get("queries", [])++ if not isinstance(_queries, list):+ _queries = [_queries] if _queries else []++ if not _queries:+ return "No queries provided in the arguments or kwargs"++ found_relationships: Dict[+ str, Union[str, List[Tuple[Node, Predicate, Node]]]+ ] = {}++ for _query in _queries:+ founds = []+ kg_results = self.kg.list_relationships(+ brain_id=self.brain_id,+ subject=_query.get("subject"),+ object=_query.get("object"),+ )+ founds.extend(kg_results)++ if len(founds) == 0:+ found_relationships[+ _query.get("subject") + " -> " + _query.get("object")+ ] = "Graph does not contain any relationships between the subject and object"+ else:+ found_relationships[+ _query.get("subject") + " -> " + _query.get("object")+ ] = [+ strip_properties(+ [f.model_dump(mode="json")],+ pop_also=["last_updated", "v_id", "properties"],+ )[0]+ for f in founds+ ]++ return json.dumps(found_relationships, indent=4)diff --git a/src/core/agents/tools/kg_agent/KGAgentCreateNodeTool.py b/src/core/agents/tools/kg_agent/KGAgentCreateNodeTool.pynew file mode 100644index 0000000..d114d73--- /dev/null+++ b/src/core/agents/tools/kg_agent/KGAgentCreateNodeTool.py@@ -0,0 +1,115 @@+"""+File: /KGAgentCreateNodeTool.py+Project: kg_agent+Created Date: Saturday January 31st 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Saturday January 31st 2026 11:18:17 am+Modified By: Christian Nonis <[email protected]>+-----+"""++from langchain.tools import BaseTool++from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter+from src.adapters.graph import GraphAdapter+from src.constants.kg import Node+++class KGAgentCreateNodeTool(BaseTool):+ """+ Tool for creating a node in the knowledge graph.+ """++ name: str = "kg_agent_create_node"++ kg_agent: object+ kg: GraphAdapter+ embeddings_adapter: EmbeddingsAdapter+ vector_store_adapter: VectorStoreAdapter+ brain_id: str = "default"++ args_schema: dict = {+ "type": "object",+ "properties": {+ "node": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "The name of the tail node.",+ },+ "labels": {+ "type": "array",+ "description": "The labels of the tail node.",+ "items": {+ "type": "string",+ },+ },+ "description": {+ "type": "string",+ "description": "The description of the tail node.",+ },+ "polarity": {+ "type": "string",+ "description": "The polarity of the node, describing if the node rapresents a good thing or bad.",+ "enum": ["positive", "negative", "neutral"],+ },+ },+ "required": ["name", "labels"],+ },+ },+ "required": ["node"],+ }++ def __init__(+ self,+ kg_agent,+ kg: GraphAdapter,+ embeddings_adapter: EmbeddingsAdapter,+ vector_store_adapter: VectorStoreAdapter,+ brain_id: str = "default",+ ):+ description: str = (+ "Use this tool to create a node in the knowledge graph. "+ "The argument should be a valid JSON object with a 'node' key. "+ "The 'node' key should be the node to create. "+ )+ super().__init__(+ kg_agent=kg_agent,+ kg=kg,+ embeddings_adapter=embeddings_adapter,+ vector_store_adapter=vector_store_adapter,+ description=description,+ brain_id=brain_id,+ )++ def _run(self, *args, **kwargs) -> str:+ """+ Create a node in the knowledge graph.+ """++ _node_arg = None+ if len(args) > 0:+ _node_arg = args[0]+ if len(kwargs) > 0:+ _node_arg = kwargs.get("node", {})+ if _node_arg is None:+ return "No node provided in the arguments or kwargs"+ try:+ _node = Node(**_node_arg)+ except Exception as e:+ return f"Error creating node: {e}"++ embedding_v = self.embeddings_adapter.embed_text(_node.name)+ vs = self.vector_store_adapter.add_vectors(+ [embedding_v], store="nodes", brain_id=self.brain_id+ )+ _node.properties = {+ **(_node.properties or {}),+ "v_id": vs[0],+ }++ self.kg.add_nodes([_node], brain_id=self.brain_id)++ return "Node created successfully"diff --git a/src/core/agents/tools/kg_agent/KGAgentCreateRelationshipTool.py b/src/core/agents/tools/kg_agent/KGAgentCreateRelationshipTool.pynew file mode 100644index 0000000..dfb494c--- /dev/null+++ b/src/core/agents/tools/kg_agent/KGAgentCreateRelationshipTool.py@@ -0,0 +1,174 @@+"""+File: /KGAgentCreateRelationshipTool.py+Project: kg_agent+Created Date: Saturday January 31st 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Saturday January 31st 2026 11:17:56 am+Modified By: Christian Nonis <[email protected]>+-----+"""++import uuid+from langchain.tools import BaseTool++from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter+from src.adapters.graph import GraphAdapter+from src.constants.kg import Node, Predicate+++class KGAgentCreateRelationshipTool(BaseTool):+ """+ Tool for creating a relationship in the knowledge graph.+ """++ name: str = "kg_agent_create_relationship"++ kg_agent: object+ kg: GraphAdapter+ brain_id: str = "default"+ embeddings_adapter: EmbeddingsAdapter+ vector_store_adapter: VectorStoreAdapter++ args_schema: dict = {+ "type": "object",+ "properties": {+ "tail": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "The name of the tail node.",+ },+ "labels": {+ "type": "array",+ "description": "The labels of the tail node.",+ "items": {+ "type": "string",+ },+ },+ "description": {+ "type": "string",+ "description": "The description of the tail node.",+ },+ "polarity": {+ "type": "string",+ "description": "The polarity of the node, describing if the node rapresents a good thing or bad.",+ "enum": ["positive", "negative", "neutral"],+ },+ },+ "required": ["name", "labels"],+ },+ "predicate": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "The name of the predicate.",+ },+ "description": {+ "type": "string",+ "description": "The description of the predicate.",+ },+ "amount": {+ "type": "number",+ "description": "The amount of the predicate.",+ },+ },+ "required": ["name", "description"],+ },+ "head": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "The name of the tail node.",+ },+ "labels": {+ "type": "array",+ "description": "The labels of the tail node.",+ "items": {+ "type": "string",+ },+ },+ "description": {+ "type": "string",+ "description": "The description of the tail node.",+ },+ "polarity": {+ "type": "string",+ "description": "The polarity of the node, describing if the node rapresents a good thing or bad.",+ "enum": ["positive", "negative", "neutral"],+ },+ },+ "required": ["name", "labels"],+ },+ },+ "required": ["tail", "predicate", "head"],+ }++ def __init__(+ self,+ kg_agent,+ kg: GraphAdapter,+ embeddings_adapter: EmbeddingsAdapter,+ vector_store_adapter: VectorStoreAdapter,+ brain_id: str = "default",+ ):+ description: str = (+ "Use this tool to create a relationship in the knowledge graph. "+ "The argument should be a valid JSON object with a 'tail', 'predicate', and 'head' keys. "+ "The 'tail' key should be the tail node of the relationship. "+ "The 'predicate' key should be the predicate of the relationship. "+ "The 'head' key should be the head node of the relationship. "+ )+ super().__init__(+ kg_agent=kg_agent,+ kg=kg,+ embeddings_adapter=embeddings_adapter,+ vector_store_adapter=vector_store_adapter,+ description=description,+ brain_id=brain_id,+ )++ def _run(self, *args, **kwargs) -> str:+ """+ Create a node in the knowledge graph.+ """+ _tail: Node = None+ _predicate: Predicate = None+ _head: Node = None++ flow_key = str(uuid.uuid4())++ if len(kwargs) > 0:+ args_tail = kwargs.get("tail", {})+ if isinstance(args_tail, dict):+ _tail = Node(**args_tail)+ args_predicate = kwargs.get("predicate", {})+ if isinstance(args_predicate, dict):+ if not args_predicate.get("name"):+ return "Error: predicate name is required"+ if not args_predicate.get("description"):+ return "Error: predicate description is required"+ _predicate = Predicate(**args_predicate)+ args_head = kwargs.get("head", {})+ if isinstance(args_head, dict):+ _head = Node(**args_head)++ if _tail is None or _predicate is None or _head is None:+ return "Error: tail, predicate, and head are required"++ embedding_v = self.embeddings_adapter.embed_text(_predicate.description)+ vs = self.vector_store_adapter.add_vectors(+ [embedding_v], store="relationships", brain_id=self.brain_id+ )+ _predicate.properties = {+ **(_predicate.properties or {}),+ "v_id": vs[0],+ }+ _predicate.flow_key = flow_key++ self.kg.add_relationship(_tail, _predicate, _head, brain_id=self.brain_id)++ return "Relationship created successfully"diff --git a/src/core/agents/tools/kg_agent/KGAgentExecuteGraphOperationTool.py b/src/core/agents/tools/kg_agent/KGAgentExecuteGraphOperationTool.pyindex e9a16ef..af4d252 100644--- a/src/core/agents/tools/kg_agent/KGAgentExecuteGraphOperationTool.py+++ b/src/core/agents/tools/kg_agent/KGAgentExecuteGraphOperationTool.py@@ -3,11 +3,12 @@ File: /KGAgentExecuteGraphOperationTool.pyCreated Date: Thursday October 23rd 2025Author: Christian Nonis <[email protected]>------Last Modified: Thursday October 23rd 2025 9:26:22 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""+import jsonfrom langchain.tools import BaseToolfrom src.adapters.graph import GraphAdapter@@ -29,7 +30,7 @@ class KGAgentExecuteGraphOperationTool(BaseTool):):"""Initialize the KGAgentExecuteGraphOperationTool with the specified components and configuration.-+Parameters:kg_agent: The knowledge graph agent to execute operations.kg (GraphAdapter): The graph adapter managing the graph database interface.@@ -58,25 +59,71 @@ class KGAgentExecuteGraphOperationTool(BaseTool):brain_id=brain_id,)+ def _serialize_response(self, response) -> str:+ if response is None:+ return ""++ if hasattr(response, "records"):+ records = response.records or []+ if len(records) > 20:+ records = records[:20]+ serialized_records = []+ for record in records:+ if hasattr(record, "data"):+ serialized_records.append(record.data())+ else:+ try:+ serialized_records.append(dict(record))+ except Exception:+ serialized_records.append(str(record))+ keys = None+ try:+ keys = list(response.keys())+ except Exception:+ try:+ keys = list(response.keys)+ except Exception:+ keys = None+ payload = {"records": serialized_records}+ if keys is not None:+ payload["keys"] = keys+ payload["truncated"] = len(response.records or []) > 20+ return json.dumps(payload, default=str)++ return json.dumps(response, default=str)+def _run(self, *args, **kwargs) -> str:"""Execute a graph operation using a query extracted from the provided arguments and return the KG adapter's response.-+The function accepts several argument shapes to locate the query:- positional: first positional argument is used as the query string.- kwargs 'args' as dict: use the value of the 'query' key.- kwargs 'args' as list: use the first element if it's a string, or the first element's 'query' value if it's a dict.-+Returns:The result returned by the graph adapter's execute_operation for the resolved query, or the string "No query provided in the arguments or kwargs" if no query could be found."""_query = ""if len(args) > 0:- _query = args[0]+ arg_val = args[0]+ if isinstance(arg_val, str):+ try:+ parsed = json.loads(arg_val)+ if isinstance(parsed, dict) and parsed.get("query"):+ _query = parsed.get("query", "")+ else:+ _query = arg_val+ except (json.JSONDecodeError, TypeError):+ _query = arg_val+ elif isinstance(arg_val, dict):+ _query = arg_val.get("query", "")+ else:+ _query = arg_val- if len(kwargs) > 0:+ if not _query and len(kwargs) > 0:args_query = kwargs.get("args", {})- if isinstance(args_query, dict):+ if isinstance(args_query, dict) and args_query.get("query"):_query = args_query.get("query", "")elif isinstance(args_query, list) and len(args_query) > 0:first_arg = args_query[0]@@ -84,20 +131,29 @@ class KGAgentExecuteGraphOperationTool(BaseTool):_query = first_argelif isinstance(first_arg, dict):_query = first_arg.get("query", "")+ if not _query:+ _query = kwargs.get("query", "")- if len(_query) == 0:- return "No query provided in the arguments or kwargs"+ _query = _query or ""print(- "[DEBUG (kg_agent_execute_graph_operation)]: Executing query: ",- _query,+ f"[DEBUG (kg_agent_execute_graph_operation)]: kwargs: {kwargs} args: {args}")- response = self.kg.execute_operation(_query, brain_id=self.brain_id)+ if not _query:+ return "No query provided in the arguments or kwargs"print(- "[DEBUG (kg_agent_execute_graph_operation)]: Response: ",- response,+ "[DEBUG (kg_agent_execute_graph_operation)]: Executing query: ",+ _query,)- return response\ No newline at end of file+ try:+ response = self.kg.execute_operation(_query, brain_id=self.brain_id)+ except Exception as e:+ print(+ f"[DEBUG (kg_agent_execute_graph_operation)]: Error executing query: {e}"+ )+ return f"Error executing query: {e}"++ return self._serialize_response(response)diff --git a/src/core/agents/tools/kg_agent/KGAgentRemoveNodeTool.py b/src/core/agents/tools/kg_agent/KGAgentRemoveNodeTool.pynew file mode 100644index 0000000..592828b--- /dev/null+++ b/src/core/agents/tools/kg_agent/KGAgentRemoveNodeTool.py@@ -0,0 +1,114 @@+"""+File: /KGAgentRemoveNodeTool.py+Project: kg_agent+Created Date: Friday January 30th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Friday January 30th 2026 9:53:12 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++from langchain.tools import BaseTool++from src.adapters.embeddings import VectorStoreAdapter+from src.adapters.graph import GraphAdapter+++class KGAgentRemoveNodeTool(BaseTool):+ """+ Tool for removing a node from the knowledge graph.+ """++ name: str = "kg_agent_remove_node"++ kg_agent: object+ kg: GraphAdapter+ vector_store: VectorStoreAdapter+ brain_id: str = "default"++ args_schema: dict = {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "description": "The UUID of the node to remove.",+ },+ },+ }++ def __init__(+ self,+ kg_agent,+ kg: GraphAdapter,+ vector_store: VectorStoreAdapter,+ brain_id: str = "default",+ ):+ """+ Initialize the KGAgentExecuteGraphOperationTool with the specified components and configuration.++ Parameters:+ kg_agent: The knowledge graph agent to execute operations.+ kg (GraphAdapter): The graph adapter managing the graph database interface.+ vector_store (VectorStoreAdapter): The vector store adapter managing the vector store interface.+ brain_id (str): Identifier for the brain context to use, defaults to "default".+ """+ description: str = (+ "Use this tool to remove a node from the knowledge graph. "+ "The node should be a valid node in the knowledge graph. "+ "The argument should be a valid JSON object with a 'uuid' key. "+ "The 'uuid' key should be the UUID of the node to remove. "+ )++ super().__init__(+ kg_agent=kg_agent,+ kg=kg,+ vector_store=vector_store,+ description=description,+ brain_id=brain_id,+ )++ def _run(self, *args, **kwargs) -> str:+ """+ Remove a node from the knowledge graph.++ The function accepts several argument shapes to locate the node:+ - positional: first positional argument is used as the UUID of the node to remove.+ - kwargs 'args' as dict: use the value of the 'uuid' key.+ - kwargs 'args' as list: use the first element if it's a string, or the first element's 'uuid' value if it's a dict.++ Returns:+ The result returned by the graph adapter's execute_operation for the resolved query, or the string "No query provided in the arguments or kwargs" if no query could be found.+ """+ _query = ""+ if len(args) > 0:+ _query = args[0]++ if len(kwargs) > 0:+ args_uuid = kwargs.get("args", {})+ if isinstance(args_uuid, dict):+ _uuid = args_uuid.get("uuid", "")+ elif isinstance(args_uuid, list) and len(args_uuid) > 0:+ first_arg = args_uuid[0]+ if isinstance(first_arg, str):+ _uuid = first_arg+ elif isinstance(first_arg, dict):+ _uuid = first_arg.get("uuid", "")++ print(f"[DEBUG (kg_agent_remove_node)]: kwargs: {kwargs} args: {args}")++ if len(_query) == 0:+ return "No UUID provided in the arguments or kwargs"++ print(f"[DEBUG (kg_agent_remove_node)]: Removing node: {_uuid}")+ removed_nodes = self.kg.remove_nodes(uuids=[_uuid], brain_id=self.brain_id)++ if len(removed_nodes) > 0:+ v_ids = [n for n in removed_nodes if n.properties.get("v_id")]+ if len(v_ids) > 0:+ self.vector_store.remove_vectors(+ v_ids, store="nodes", brain_id=self.brain_id+ )++ # Returning success in any case to prevent the kg_agent to iterate across ghost nodes+ return "Operation completed successfully"diff --git a/src/core/agents/tools/kg_agent/KGAgentRemoveRelationshipTool.py b/src/core/agents/tools/kg_agent/KGAgentRemoveRelationshipTool.pynew file mode 100644index 0000000..7877d03--- /dev/null+++ b/src/core/agents/tools/kg_agent/KGAgentRemoveRelationshipTool.py@@ -0,0 +1,184 @@+"""+File: /KGAgentRemoveRelationshipTool.py+Project: kg_agent+Created Date: Friday January 30th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Friday January 30th 2026 9:52:56 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++from langchain.tools import BaseTool++from src.adapters.embeddings import VectorStoreAdapter+from src.adapters.graph import GraphAdapter+from src.constants.kg import NodeDict, PredicateDict+++class KGAgentRemoveRelationshipTool(BaseTool):+ """+ Tool for removing a relationship from the knowledge graph.+ """++ name: str = "kg_agent_remove_relationship"++ kg_agent: object+ kg: GraphAdapter+ vector_store: VectorStoreAdapter+ brain_id: str = "default"++ args_schema: dict = {+ "type": "object",+ "properties": {+ "relationship": {+ "type": "string",+ "description": "The UUID of the relationship to remove.",+ },+ "tail": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "description": "The UUID of the tail node.",+ },+ "name": {+ "type": "string",+ "description": "The name of the tail node.",+ },+ "labels": {+ "type": "array",+ "description": "The labels of the tail node.",+ "items": {+ "type": "string",+ },+ },+ },+ "description": "The tail node of the relationship to remove. Can contain the UUID of the tail node, OR the name AND labels of the tail node.",+ },+ "head": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "description": "The UUID of the head node.",+ },+ "name": {+ "type": "string",+ "description": "The name of the head node.",+ },+ "labels": {+ "type": "array",+ "description": "The labels of the head node.",+ "items": {+ "type": "string",+ },+ },+ },+ "description": "The head node of the relationship to remove. Can contain the UUID of the head node, OR the name AND labels of the head node.",+ },+ "relationship_name": {+ "type": "string",+ "description": "The name of the relationship to remove to be provided along with the tail and head nodes.",+ },+ },+ "description": "The relationship to remove. Can contain the UUID of the relationship, OR the tail and head nodes and the relationship name.",+ }++ def __init__(+ self,+ kg_agent,+ kg: GraphAdapter,+ vector_store: VectorStoreAdapter,+ brain_id: str = "default",+ ):+ """+ Initialize the KGAgentRemoveRelationshipTool with the specified components and configuration.++ Parameters:+ kg_agent: The knowledge graph agent to execute operations.+ kg (GraphAdapter): The graph adapter managing the graph database interface.+ vector_store (VectorStoreAdapter): The vector store adapter managing the vector store interface.+ brain_id (str): Identifier for the brain context to use, defaults to "default".+ """+ description: str = (+ "Use this tool to remove a relationship from the knowledge graph. "+ "The relationship should be a valid relationship in the knowledge graph. "+ "The argument must be a valid JSON object that can contain a 'uuid' key OR a 'tail' and 'head' keys and the 'relationship_name' key. "+ "The 'tail' and 'tip' parameters can contain the UUID of the tail and tip nodes, or the name and labels of the tail and tip nodes. "+ )++ super().__init__(+ kg_agent=kg_agent,+ kg=kg,+ vector_store=vector_store,+ description=description,+ brain_id=brain_id,+ )++ def _run(self, *args, **kwargs) -> str:+ """+ Remove a relationship from the knowledge graph.+ """+ _rel_uuid: str = None+ _tail: NodeDict = None+ _head: NodeDict = None+ _relationship_name: str = None+ print(f"[DEBUG (kg_agent_remove_relationship)]: kwargs: {kwargs} args: {args}")+ if len(kwargs) > 0:+ args_uuid = kwargs.get("args", {})+ if isinstance(args_uuid, dict):+ if "uuid" in args_uuid:+ _rel_uuid = args_uuid.get("uuid", "")+ if "tail" in args_uuid and "head" in args_uuid:+ _tail = args_uuid.get("tail", {})+ _head = args_uuid.get("head", {})+ elif isinstance(args_uuid, list) and len(args_uuid) > 0:+ first_arg = args_uuid[0]+ if isinstance(first_arg, dict):+ if "uuid" in first_arg:+ _rel_uuid = first_arg.get("uuid", "")+ if "tail" in first_arg and "head" in first_arg:+ _tail = first_arg.get("tail", {})+ _head = first_arg.get("head", {})+ if "relationship_name" in first_arg:+ _relationship_name = first_arg.get("relationship_name", "")++ print(+ f"[DEBUG (kg_agent_remove_relationship)]: Removing relationship: {_rel_uuid} - {_tail} - {_head} - {_relationship_name}"+ )+ try:+ removed_relationships = self.kg.remove_relationships(+ relationships=[+ (+ _tail,+ PredicateDict(+ {+ **({"uuid": _rel_uuid} if _rel_uuid else {}),+ **(+ {"name": _relationship_name}+ if _relationship_name+ else {}+ ),+ }+ ),+ _head,+ )+ ],+ brain_id=self.brain_id,+ )+ except Exception as e:+ print(+ f"[DEBUG (kg_agent_remove_relationship)]: Error removing relationship: {e}"+ )+ return f"Error removing relationship: {e}"++ if len(removed_relationships) > 0:+ v_ids = [r for _, r, _ in removed_relationships if r.properties.get("v_id")]+ if len(v_ids) > 0:+ self.vector_store.remove_vectors(+ v_ids, store="relationships", brain_id=self.brain_id+ )++ # Returning success in any case to prevent the kg_agent to iterate across ghost relationships+ return "Operation completed successfully"diff --git a/src/core/layers/graph_consolidation/graph_consolidation.py b/src/core/layers/graph_consolidation/graph_consolidation.pyindex 2a2055f..c969728 100644--- a/src/core/layers/graph_consolidation/graph_consolidation.py+++ b/src/core/layers/graph_consolidation/graph_consolidation.py@@ -4,7 +4,7 @@ Project: graph_consolidationCreated Date: Saturday January 24th 2026Author: Christian Nonis <[email protected]>------Last Modified: Saturday January 24th 2026 11:13:43 am+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -68,12 +68,12 @@ def consolidate_graph() -> ConsolidationResponse:"""Consolidates and normalizes a collection of new knowledge-graph relationships across the graph.-+Processes the provided relationships in batches to perform macroscopic fixes such as name normalization, connection normalization, and deduplication across multiple relationships and graph areas. Collects and merges token usage metrics produced during consolidation.-+Parameters:brain_id (str): Identifier of the target knowledge graph/brain to consolidate into (defaults to "default").-+Returns:ConsolidationResponse: Response containing merged token usage details for the consolidation run."""@@ -119,30 +119,41 @@ def consolidate_graph(janitor_agent.output_tokens,janitor_agent.cached_tokens,janitor_agent.reasoning_tokens,+ "janitor_agent",))# 2. ~~Something to review and approve/reject what janitor proposed~~# Another agent that reviews the porposed fixes and approves or rejects them .. what ?+ kg_agent = KGAgent(+ llm_adapter=llm_small_adapter,+ cache_adapter=cache_adapter,+ kg=graph_adapter,+ vector_store=vector_store_adapter,+ embeddings=embeddings_adapter,+ database_desc=_neo4j_client.graphdb_description,+ )for task in tasks:- kg_agent = KGAgent(- llm_adapter=llm_small_adapter,- cache_adapter=cache_adapter,- kg=graph_adapter,- vector_store=vector_store_adapter,- embeddings=embeddings_adapter,- database_desc=_neo4j_client.graphdb_description,- )- token_details.append(- token_detail_from_token_counts(- kg_agent.input_tokens,- kg_agent.output_tokens,- kg_agent.cached_tokens,- kg_agent.reasoning_tokens,+ try:+ kg_agent.run_graph_consolidator_operator(+ task, brain_id=brain_id, reuse_agent=True)+ except Exception as e:+ print(+ "[DEBUG (consolidate_graph)]: Exception error for kg_agent.run_graph_consolidator_operator(task, brain_id=brain_id)"+ )+ print(e)+ continue+ token_details.append(+ token_detail_from_token_counts(+ kg_agent.input_tokens,+ kg_agent.output_tokens,+ kg_agent.cached_tokens,+ kg_agent.reasoning_tokens,+ "kg_agent",)- kg_agent.run_graph_consolidator_operator(task, brain_id=brain_id)+ )token_detail = merge_token_details(token_details)@@ -157,4 +168,4 @@ def consolidate_graph(return ConsolidationResponse(token_detail=token_detail,- )\ No newline at end of file+ )diff --git a/src/core/saving/auto_kg.py b/src/core/saving/auto_kg.pyindex 0f2a992..b3c6794 100644--- a/src/core/saving/auto_kg.py+++ b/src/core/saving/auto_kg.py@@ -3,11 +3,13 @@ File: /auto_kg.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Tuesday December 23rd 2025 9:24:20 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""+import os+import uuidfrom typing import Optionalfrom src.config import config@@ -25,22 +27,40 @@ from src.services.input.agents import ()from src.utils.tokens import merge_token_details, token_detail_from_token_counts+import langsmith+def enrich_kg_from_input(input: str, targeting: Optional[Node] = None, brain_id: str = "default") -> str:"""Orchestrates enrichment of the knowledge graph from a free-text input.-+Runs the scout and architect agents to extract entities and relationships from the provided input, optionally consolidates the resulting relationships into the graph, and reports token usage and cost metrics. Side effects include updating the knowledge graph and printing debug and cost summaries to standard output.-+Parameters:input (str): Free-text content to process and ingest into the knowledge graph.targeting (Optional[Node]): Optional target node guiding where or how the input should be applied within the graph.brain_id (str): Identifier for the processing context/brain to use for agent operations and consolidation.-+"""+ ingestion_session_id = str(uuid.uuid4())+ project_name = os.getenv("LANGSMITH_PROJECT", "brainapi")+ with langsmith.tracing_context(+ project_name=project_name,+ enabled=True,+ tags=["enrich_kg", "scout", "architect"],+ metadata={+ "ingestion_session_id": ingestion_session_id,+ "brain_id": brain_id,+ "flow": "enrich_kg_from_input",+ },+ ):+ _enrich_kg_impl(input, targeting, brain_id, ingestion_session_id)+++def _enrich_kg_impl(input: str, targeting, brain_id: str, ingestion_session_id: str):ingestion_manager = IngestionManager(embeddings_adapter, vector_store_adapter, graph_adapter)@@ -62,14 +82,21 @@ def enrich_kg_from_input()token_details = []+ print(f"[DEBUG (ingestion_session_id)]: {ingestion_session_id}")- entities = scout_agent.run(input, targeting=targeting, brain_id=brain_id)+ entities = scout_agent.run(+ input,+ targeting=targeting,+ brain_id=brain_id,+ ingestion_session_id=ingestion_session_id,+ )token_details.append(token_detail_from_token_counts(scout_agent.input_tokens,scout_agent.output_tokens,scout_agent.cached_tokens,scout_agent.reasoning_tokens,+ "scout_agent",))@@ -81,6 +108,7 @@ def enrich_kg_from_input(targeting=targeting,brain_id=brain_id,timeout=360 * len(input),+ ingestion_session_id=ingestion_session_id,)token_details.append(token_detail_from_token_counts(@@ -88,26 +116,64 @@ def enrich_kg_from_input(architect_agent.output_tokens,architect_agent.cached_tokens,architect_agent.reasoning_tokens,+ "architect_agent",))- consolidation_response = None+ if config.run_graph_consolidator and architect_agent.session_id:+ from src.lib.redis.client import _redis_client+ import time++ print(+ f"[DEBUG (enrich_kg_from_input)]: Waiting for async tasks to complete for session {architect_agent.session_id}"+ )++ max_wait_time = 300+ check_interval = 2+ elapsed_time = 0++ while elapsed_time < max_wait_time:+ pending_count = _redis_client.client.get(+ f"{brain_id}:session:{architect_agent.session_id}:pending_tasks"+ )++ if pending_count is None or int(pending_count) == 0:+ print(+ f"[DEBUG (enrich_kg_from_input)]: All async tasks completed after {elapsed_time}s"+ )+ break++ print(+ f"[DEBUG (enrich_kg_from_input)]: {pending_count} tasks still pending, waiting..."+ )+ time.sleep(check_interval)+ elapsed_time += check_interval+ else:+ print(+ f"[DEBUG (enrich_kg_from_input)]: Timeout waiting for tasks to complete after {max_wait_time}s"+ )- if config.run_graph_consolidator:print("[DEBUG (consolidate_graph)]: Consolidating graph with ",len(architect_agent.relationships_set)," relationships",)- consolidation_response = consolidate_graph(- architect_agent.relationships_set, brain_id=brain_id++ from src.workers.tasks.ingestion import consolidate_graph_async++ task_result = consolidate_graph_async.delay(+ session_id=architect_agent.session_id,+ brain_id=brain_id,+ ingestion_session_id=ingestion_session_id,+ )+ print(+ f"[DEBUG (enrich_kg_from_input)]: Consolidation task {task_result.id} queued")token_details = merge_token_details([scout_agent.token_detail,architect_agent.token_detail,- *([consolidation_response.token_detail] if consolidation_response else []),])@@ -124,4 +190,12 @@ def enrich_kg_from_input(print(f"> Cost/Character -> ${((token_details.input.total * config.pricing.input_token_price + token_details.output.total * config.pricing.output_token_price) / len(input)):.12f}")- print("-----------------------------------")\ No newline at end of file+ print("> Token details: ", token_details.model_dump_json(indent=2))+ print("-----------------------------------")++ try:+ from langchain_core.tracers.langchain import wait_for_all_tracers++ wait_for_all_tracers()+ except ImportError:+ passdiff --git a/src/lib/embeddings/client.py b/src/lib/embeddings/client.pyindex 2268a5c..97b6e7c 100644--- a/src/lib/embeddings/client.py+++ b/src/lib/embeddings/client.py@@ -63,6 +63,41 @@ class EmbeddingsClient(EmbeddingsClient):result = list(struct.unpack(f"<{len(decoded_bytes)//4}f", decoded_bytes))return result+ @retry(+ stop=stop_after_attempt(5),+ wait=wait_exponential(multiplier=1, min=2, max=30),+ retry=retry_if_exception_type((ConnectionError, Timeout)),+ reraise=False,+ )+ def _embed_texts_with_retry(self, texts: list[str]) -> list[list[float]]:+ """+ Internal method to embed multiple texts with retry logic for network errors.+ """+ response = requests.post(+ config.azure.embedding_full_endpoint,+ json={"input": texts, "encoding_format": "base64"},+ headers={+ "api-key": config.azure.embedding_key,+ "Content-Type": "application/json",+ },+ timeout=60.0,+ )+ response.raise_for_status()++ data = response.json()["data"]+ # Ensure we return results in the same order as input+ # Azure/OpenAI usually guarantees order in 'data' list+ data.sort(key=lambda x: x["index"])++ results = []+ for item in data:+ _b64_result = item["embedding"]+ decoded_bytes = base64.b64decode(_b64_result)+ result = list(struct.unpack(f"<{len(decoded_bytes)//4}f", decoded_bytes))+ results.append(result)++ return results+def embed_text(self, text: str) -> list[float]:"""Embed a text and return a list of floats.@@ -91,5 +126,33 @@ class EmbeddingsClient(EmbeddingsClient):print(f"Embedding encoding failed: {error_msg}")raise EmbeddingError(error_msg) from e+ def embed_texts(self, texts: list[str]) -> list[list[float]]:+ """+ Embed a list of texts and return a list of lists of floats.+ Handles connection errors with retry logic.+ """+ try:+ return self._embed_texts_with_retry(texts)+ except RetryError as e:+ last_attempt = e.last_attempt+ error_msg = (+ f"Embedding failed after {last_attempt.attempt_number} attempts. "+ f"Last error: {last_attempt.exception()}"+ )+ print(f"Embedding encoding failed: {error_msg}")+ raise EmbeddingError(error_msg) from last_attempt.exception()+ except (ConnectionError, Timeout) as e:+ error_msg = f"Network error during embedding: {e}"+ print(f"Embedding encoding failed: {error_msg}")+ raise EmbeddingError(error_msg) from e+ except RequestException as e:+ error_msg = f"Request error during embedding: {e}"+ print(f"Embedding encoding failed: {error_msg}")+ raise EmbeddingError(error_msg) from e+ except Exception as e:+ error_msg = f"Unexpected error during embedding: {e}"+ print(f"Embedding encoding failed: {error_msg}")+ raise EmbeddingError(error_msg) from e+_embeddings_client = EmbeddingsClient()diff --git a/src/lib/embeddings/client_small.py b/src/lib/embeddings/client_small.pyindex 7fad0e9..3904c4c 100644--- a/src/lib/embeddings/client_small.py+++ b/src/lib/embeddings/client_small.py@@ -23,15 +23,28 @@ class EmbeddingsClientSmall(EmbeddingsClient):def embed_text(self, text: str) -> list[float]:"""Return the embedding vector for the given text using the configured model.-+Parameters:text (str): Input text to encode.-+Returns:list[float]: Dense embedding vector representing the input text."""embedding = self.model.encode(text, convert_to_numpy=True)return embedding.tolist()+ def embed_texts(self, texts: list[str]) -> list[list[float]]:+ """+ Return the embedding vectors for the given texts using the configured model.++ Parameters:+ texts (list[str]): Input texts to encode.++ Returns:+ list[list[float]]: Dense embedding vectors representing the input texts.+ """+ embeddings = self.model.encode(texts, convert_to_numpy=True)+ return embeddings.tolist()+-_embeddings_small_client = EmbeddingsClientSmall()\ No newline at end of file+_embeddings_small_client = EmbeddingsClientSmall()diff --git a/src/lib/milvus/client.py b/src/lib/milvus/client.pyindex a4309da..a6a8547 100644--- a/src/lib/milvus/client.py+++ b/src/lib/milvus/client.py@@ -358,5 +358,19 @@ class MilvusClient(VectorStoreClient):return out+ def remove_vectors(self, ids: list[str], store: str, brain_id: str) -> None:+ """+ Remove vectors from the vector store.+ """+ if not ids:+ return None+ client = self._get_client(brain_id)+ self._ensure_store(store, brain_id)+ try:+ client.delete(store, ids=ids)+ except Exception:+ pass+ return None+_milvus_client = MilvusClient()diff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.pyindex 5930b0a..c199c82 100644--- a/src/lib/neo4j/client.py+++ b/src/lib/neo4j/client.py@@ -3,7 +3,7 @@ File: /client.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 12th 2026 8:26:26 pm+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""@@ -11,7 +11,7 @@ Modified By: Christian Nonis <[email protected]>from datetime import datetime, timezoneimport osimport time-from typing import Any, Dict, List, Literal, Optional, Tuple+from typing import Any, Dict, List, Literal, Optional, Tuple, TypedDictfrom neo4j import GraphDatabasefrom neo4j.exceptions import ClientErrorfrom src.adapters.interfaces.embeddings import VectorStoreClient@@ -20,7 +20,9 @@ from src.config import configfrom src.constants.kg import (IdentificationParams,Node,+ NodeDict,Predicate,+ PredicateDict,SearchEntitiesResult,SearchRelationshipsResult,Triple,@@ -145,7 +147,20 @@ class Neo4jClient(GraphClient):Clean a label to be used in a Cypher query."""return [- label.replace(" ", "_").upper().replace("-", "_").replace(".", "_")+ label.replace(" ", "_")+ .upper()+ .replace("-", "_")+ .replace(".", "_")+ .replace(",", "_")+ .replace(":", "_")+ .replace(";", "_")+ .replace("(", "_")+ .replace(")", "_")+ .replace("[", "_")+ .replace("]", "_")+ .replace("{", "_")+ .replace("}", "_")+ .replace("'", "_")for label in labels]@@ -192,13 +207,13 @@ class Neo4jClient(GraphClient):) -> list[Node] | str:"""Insert multiple nodes into the specified brain's graph and return representations of the created nodes.-+Ensures the target database exists, merges or creates each node by its identification properties (at minimum the node's name), sets node properties and standard attributes (description, happened_at, last_updated, metadata, observations, polarity, and uuid), and retries on transient database-not-found errors.-+Parameters:identification_params (dict, optional): Additional property keys and values used to identify (MERGE) nodes besides name; keys will be normalized to property-style keys.metadata (dict, optional): Metadata to attach to each node; this metadata is merged with any existing node.metadata for the returned Node objects.-+Returns:list[Node]: A list of Node objects representing the added nodes. Each returned Node preserves the original node fields and has its metadata set to the merge of the node's own metadata and the provided `metadata`."""@@ -287,17 +302,17 @@ class Neo4jClient(GraphClient):) -> str:"""Create or update a relationship of the given predicate type between two existing nodes and set relationship attributes.-+Matches the source node by its labels and name (from `subject`) and the target node by its labels and name (from `to_object`), merges a relationship of type `predicate.name` between them, and sets relationship fields (including `uuid`, `description`, `v_id`, and any provided `properties`, `happened_at`, `flow_key`, `last_updated`) from the supplied `predicate`, `subject`, and `to_object` objects. Ensures the target database exists before executing the query.-+Parameters:- subject (Node): Source node whose labels and `name` are used to find the relationship start.- predicate (Predicate): Relationship descriptor whose `name` determines the relationship type and whose fields supply relationship attributes to set.- to_object (Node): Target node whose labels and `name` are used to find the relationship end.- brain_id (str): Database name to run the query against.-+ subject (Node): Source node whose labels and `name` are used to find the relationship start.+ predicate (Predicate): Relationship descriptor whose `name` determines the relationship type and whose fields supply relationship attributes to set.+ to_object (Node): Target node whose labels and `name` are used to find the relationship end.+ brain_id (str): Database name to run the query against.+Returns:- query_result: The raw result returned by the Neo4j driver for the executed Cypher query.+ query_result: The raw result returned by the Neo4j driver for the executed Cypher query."""objects = [subject, to_object, predicate]@@ -307,6 +322,7 @@ class Neo4jClient(GraphClient):"happened_at","flow_key","last_updated",+ "amount",]extra_ops = ""@@ -322,7 +338,11 @@ class Neo4jClient(GraphClient):MATCH (a:{":".join(self._clean_labels(subject.labels))}) WHERE a.name = {self._format_value(subject.name)}MATCH (b:{":".join(self._clean_labels(to_object.labels))}) WHERE b.name = {self._format_value(to_object.name)}MERGE (a)-[r:{":".join(self._clean_labels([predicate.name]))}]->(b)- ON CREATE SET r.description = {self._format_value(predicate.description)}, r.uuid = {self._format_value(predicate.uuid)}, r.v_id = {self._format_value(predicate.properties.get("v_id"))}+ ON CREATE+ SET r.description = {self._format_value(predicate.description)},+ r.uuid = {self._format_value(predicate.uuid)},+ r.v_id = {self._format_value(predicate.properties.get("v_id"))},+ r.flow_key = {self._format_value(predicate.flow_key)}{extra_ops}RETURN a, b"""@@ -482,13 +502,13 @@ class Neo4jClient(GraphClient):def get_by_uuid(self, uuid: str, brain_id: str) -> Node:"""Retrieve a node by its UUID.-+Deprecated: use `get_by_uuids` which returns richer node data and supports batching.-+Parameters:uuid (str): The UUID of the node to retrieve.brain_id (str): Target database/brain identifier.-+Returns:Node or None: The matching node, or `None` if no node with the given UUID exists."""@@ -516,11 +536,11 @@ class Neo4jClient(GraphClient):def get_by_uuids(self, uuids: list[str], brain_id: str) -> list[Node]:"""Retrieve nodes that match the given UUIDs from the specified database.-+Parameters:uuids (list[str]): Node UUIDs to fetch.brain_id (str): Name of the Neo4j database to query.-+Returns:list[Node]: Nodes with identifiers, names, labels, descriptions, and properties; includes, when available, polarity, happened_at, last_updated, observations, and metadata."""@@ -637,14 +657,14 @@ class Neo4jClient(GraphClient):) -> Dict[str, List[Tuple[Predicate, Node]]]:"""Retrieve neighboring nodes connected to each given node, grouped by source node UUID.-+Parameters:nodes (list[Node | str]): List of Node objects or node UUID strings to find neighbors for.brain_id (str): Database identifier to query.same_type_only (bool): If True, include only neighbors whose labels share at least one label with the source node.limit (int | None): Optional maximum number of neighbor records to return (applies to the entire result set).of_types (Optional[list[str]]): Optional list of node label names to filter neighbors by those labels.-+Returns:Dict[str, List[Tuple[Predicate, Node]]]: Mapping from each source node UUID to a list of tuples (Predicate, Node),where Predicate describes the relationship (including direction, properties, flow key, and UUID) between the source@@ -1393,10 +1413,10 @@ class Neo4jClient(GraphClient):def get_schema(self, brain_id: str) -> dict:"""Retrieve the graph schema for the given brain, including node labels, relationship types, and event names.-+Parameters:brain_id (str): Identifier of the Neo4j database/brain to query.-+Returns:dict: A dictionary with keys:- "labels": list of node label names (str).@@ -1440,13 +1460,13 @@ class Neo4jClient(GraphClient):) -> Dict[str, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]:"""Retrieve second-degree neighbor nodes from the given starting nodes.-+Parameters:from_ (List[str]): List of node UUIDs to start the hop from.flattened (bool): Whether to flatten the result structure.vector_store_adapter (VectorStoreClient): Adapter to the vector store.brain_id (str): Identifier of the brain or graph context.-+Returns:Dict[str, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]: Mapping from each starting node UUID to a list of tuples containinga predicate to a neighbor node, the neighbor node itself, and a list of tuples for that neighbor's predicates and their connected nodes.@@ -1464,13 +1484,13 @@ class Neo4jClient(GraphClient):) -> bool:"""Determine whether a node with the given UUID, name, and labels exists in the specified database.-+Parameters:uuid (str): Node identifier to match.name (str): Node name to match.labels (list[str]): All labels the node must have.brain_id (str): Target database name.-+Returns:bool: True if a node matching the UUID, name, and labels exists, False otherwise."""@@ -1491,12 +1511,12 @@ class Neo4jClient(GraphClient):) -> list[dict]:"""Retrieve the neighborhood of a node up to a specified depth as a nested structure.-+Parameters:node (Node | str): The starting node or its UUID.depth (int): Maximum number of hops to traverse; must be >= 1.brain_id (str): Identifier for the brain/graph to scope the query.-+Returns:list[dict]: A list of neighbor dictionaries. Each dictionary contains the keys`node` (the neighboring Node), `predicate` (the connecting Predicate),@@ -1513,13 +1533,13 @@ class Neo4jClient(GraphClient):) -> list[dict]:"""Recursively collects neighboring nodes and their connecting predicates up to the specified depth.-+Parameters:node_uuid (str): UUID of the node to start traversal from.depth (int): Maximum number of hops to traverse; values less than 1 result in no neighbors.brain_id (str): Database/brain identifier to run the query against.path_visited (set[str]): Set of node UUIDs already visited in the current traversal path; used to prevent cycles.-+Returns:list[dict]: A list of neighbor entries. Each entry is a dict with keys:- "predicate": a Predicate instance describing the relationship from the current node to the neighbor.@@ -1595,12 +1615,12 @@ class Neo4jClient(GraphClient):) -> List[Tuple[Node, Predicate, Node]]:"""Finds subsequent nodes in a flow that follow a relationship identified by a predicate UUID and share the given flow key.-+Parameters:predicate_uuid (str): UUID of the reference relationship whose adjacent segment is the starting point.flow_key (str): Flow key used to match the subsequent relationship.brain_id (str): Database name (brain) to execute the query against.-+Returns:List[Tuple[Node, Predicate, Node]]: A list of tuples each containing the middle node, the matching relationship (predicate) that has the flow_key, and the connected target node. Each tuple represents a directed hop from the middle node through the matched predicate to the target node; the predicate includes its direction and properties."""@@ -1647,5 +1667,227 @@ class Neo4jClient(GraphClient):for record in result.records]+ def get_triples_by_uuid(+ self, uuids: list[str], brain_id: str+ ) -> List[Tuple[Node, Predicate, Node]]:+ """+ Get triples by its UUID.+ """+ cypher_query = f"""+ MATCH (n)-[r]-(m) WHERE r.uuid IN [{",".join([f'"{uuid}"' for uuid in uuids])}]+ 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.uuid as r_uuid, type(r) as r_type, r.description as r_description, properties(r) as r_properties,+ 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+ """+ self.ensure_database(brain_id)+ result = self.driver.execute_query(+ cypher_query,+ database_=brain_id,+ )+ return [+ (+ Node(+ uuid=record.get("n_uuid", "") or "",+ name=record.get("n_name", "") or "",+ labels=record.get("n_labels", []) or [],+ description=record.get("n_description", "") or "",+ properties=record.get("n_properties", {}) or {},+ ),+ Predicate(+ name=record.get("r_type", "") or "",+ description=record.get("r_description", "") or "",+ direction=record.get("r_direction", "neutral"),+ properties=record.get("r_properties", {}) or {},+ ),+ Node(+ uuid=record.get("m_uuid", "") or "",+ name=record.get("m_name", "") or "",+ labels=record.get("m_labels", []) or [],+ description=record.get("m_description", "") or "",+ properties=record.get("m_properties", {}) or {},+ ),+ )+ for record in result.records+ ]++ def remove_nodes(self, uuids: list[str], brain_id: str) -> list[Node]:+ """+ Remove nodes from the graph.+ """+ cypher_query = f"""+ MATCH (n) WHERE n.uuid IN [{",".join([f'"{uuid}"' for uuid in uuids])}]+ WITH n, {{+ uuid: n.uuid,+ name: n.name,+ labels: labels(n),+ description: n.description,+ properties: properties(n),+ polarity: n.polarity,+ metadata: n.metadata,+ happened_at: n.happened_at,+ last_updated: n.last_updated,+ observations: n.observations+ }} AS node+ DELETE n+ RETURN node+ """+ self.ensure_database(brain_id)+ result = self.driver.execute_query(+ cypher_query,+ database_=brain_id,+ )+ return [Node(**record.get("node", {})) for record in result.records]++ def remove_relationships(+ self,+ relationships: list[Tuple[NodeDict, PredicateDict, NodeDict]],+ brain_id: str,+ ) -> list[Tuple[Node, Predicate, Node]]:+ """+ Remove relationships from the graph. Matches each relationship either by+ predicate uuid (r.uuid) or by tip/tail node identifiers (node uuid or+ name + labels). Returns the list of deleted triples (tail, predicate, head).+ """+ self.ensure_database(brain_id)+ deleted: list[Tuple[Node, Predicate, Node]] = []+ by_rel_uuid: list[str] = []+ by_tip_tail: list[Tuple[NodeDict, PredicateDict, NodeDict]] = []+ for tail, pred, head in relationships:+ if pred.get("uuid"):+ by_rel_uuid.append(pred["uuid"])+ else:+ by_tip_tail.append((tail, pred, head))+ with_fields = """+ 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.uuid AS r_uuid, type(r) AS r_type, r.description AS r_description, properties(r) AS r_properties,+ 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+ """+ return_list = "n_uuid, n_name, n_labels, n_description, n_properties, r_uuid, r_type, r_description, r_properties, m_uuid, m_name, m_labels, m_description, m_properties"+ if by_rel_uuid:+ cypher = f"""+ MATCH (n)-[r]-(m) WHERE r.uuid IN [{",".join([self._format_value(u) for u in by_rel_uuid])}]+ WITH n, r, m, {with_fields.strip()}+ DELETE r+ RETURN {return_list}+ """+ result = self.driver.execute_query(cypher, database_=brain_id)+ for record in result.records:+ deleted.append(self._record_to_triple(record))+ for tail, pred, head in by_tip_tail:+ tail_match = self._node_match_cypher("n", tail)+ head_match = self._node_match_cypher("m", head)+ rel_type = pred.get("name")+ if rel_type:+ rel_part = f"[r:{':'.join(self._clean_labels([rel_type]))}]"+ else:+ rel_part = "[r]"+ cypher = f"""+ MATCH {tail_match}+ MATCH {head_match}+ MATCH (n){rel_part}-(m)+ WITH n, r, m, {with_fields.strip()}+ DELETE r+ RETURN {return_list}+ """+ result = self.driver.execute_query(cypher, database_=brain_id)+ for record in result.records:+ deleted.append(self._record_to_triple(record))+ return deleted++ def _record_to_triple(self, record: Any) -> Tuple[Node, Predicate, Node]:+ return (+ Node(+ uuid=record.get("n_uuid", "") or "",+ name=record.get("n_name", "") or "",+ labels=record.get("n_labels", []) or [],+ description=record.get("n_description", "") or "",+ properties=record.get("n_properties", {}) or {},+ ),+ Predicate(+ uuid=record.get("r_uuid", "") or "",+ name=record.get("r_type", "") or "",+ description=record.get("r_description", "") or "",+ direction="neutral",+ properties=record.get("r_properties", {}) or {},+ ),+ Node(+ uuid=record.get("m_uuid", "") or "",+ name=record.get("m_name", "") or "",+ labels=record.get("m_labels", []) or [],+ description=record.get("m_description", "") or "",+ properties=record.get("m_properties", {}) or {},+ ),+ )++ def _node_match_cypher(self, alias: str, node: NodeDict) -> str:+ if not node:+ return f"({alias})"+ if node.get("uuid"):+ return f"({alias}) WHERE {alias}.uuid = {self._format_value(node['uuid'])}"+ labels = node.get("labels") or []+ name = node.get("name") or ""+ if labels:+ labels_part = ":".join(self._clean_labels(labels))+ return f"({alias}:{labels_part}) WHERE {alias}.name = {self._format_value(name)}"+ if name:+ return f"({alias}) WHERE {alias}.name = {self._format_value(name)}"+ return f"({alias})"++ def list_relationships(+ self, subject: str, object: str, brain_id: str+ ) -> list[Tuple[Node, Predicate, Node]]:+ """+ List the relationships between the subject and object.+ """+ cypher_query = f"""+ MATCH (n)-[r]-(m) WHERE n.uuid = {self._format_value(subject)} AND m.uuid = {self._format_value(object)}+ 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, n.polarity as n_polarity, n.metadata as n_metadata, n.happened_at as n_happened_at, n.last_updated as n_last_updated, n.observations as n_observations,+ r.uuid as r_uuid, type(r) as r_type, r.description as r_description, properties(r) as r_properties, r.flow_key as r_flow_key, r.last_updated as r_last_updated, r.observations as r_observations, r.amount as r_amount,+ 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, m.polarity as m_polarity, m.metadata as m_metadata, m.happened_at as m_happened_at, m.last_updated as m_last_updated, m.observations as m_observations+ """+ self.ensure_database(brain_id)+ result = self.driver.execute_query(cypher_query, database_=brain_id)+ return [+ (+ Node(+ uuid=record.get("n_uuid", "") or "",+ name=record.get("n_name", "") or "",+ labels=record.get("n_labels", []) or [],+ description=record.get("n_description", "") or "",+ properties=record.get("n_properties", {}) or {},+ polarity=record.get("n_polarity", "neutral"),+ metadata=record.get("n_metadata", {}) or {},+ happened_at=record.get("n_happened_at", "") or "",+ last_updated=record.get("n_last_updated", "") or "",+ observations=record.get("n_observations", []) or [],+ ),+ Predicate(+ uuid=record.get("r_uuid", "") or "",+ name=record.get("r_type", "") or "",+ description=record.get("r_description", "") or "",+ direction="neutral",+ properties=record.get("r_properties", {}) or {},+ flow_key=record.get("r_flow_key", "") or "",+ last_updated=record.get("r_last_updated", "") or "",+ observations=record.get("r_observations", []) or [],+ amount=record.get("r_amount"),+ ),+ Node(+ uuid=record.get("m_uuid", "") or "",+ name=record.get("m_name", "") or "",+ labels=record.get("m_labels", []) or [],+ description=record.get("m_description", "") or "",+ properties=record.get("m_properties", {}) or {},+ polarity=record.get("m_polarity", "neutral"),+ metadata=record.get("m_metadata", {}) or {},+ happened_at=record.get("m_happened_at", "") or "",+ last_updated=record.get("m_last_updated", "") or "",+ observations=record.get("m_observations", []) or [],+ ),+ )+ for record in result.records+ ]+-_neo4j_client = Neo4jClient()\ No newline at end of file+_neo4j_client = Neo4jClient()diff --git a/src/services/api/app.py b/src/services/api/app.pyindex b1520ae..9d0dfb8 100644--- a/src/services/api/app.py+++ b/src/services/api/app.py@@ -9,6 +9,12 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@"""import os+from pathlib import Path++import dotenv++_project_root = Path(__file__).resolve().parent.parent.parent+dotenv.load_dotenv(_project_root / ".env")from fastapi import FastAPI, Responsefrom fastapi.middleware.cors import CORSMiddleware@@ -43,6 +49,7 @@ app.include_router(model_router)app.include_router(system_router)app.include_router(tasks_router)+@app.get("/")async def root():return Response(content="ok", status_code=200)diff --git a/src/services/observations/main.py b/src/services/observations/main.pyindex 73711e0..40b914d 100644--- a/src/services/observations/main.py+++ b/src/services/observations/main.py@@ -4,16 +4,16 @@ Created Date: Thursday October 23rd 2025Author: Christian Nonis <[email protected]>-----Last Modified: Thursday October 23rd 2025 10:19:44 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Modified By: Christian Nonis <[email protected]>-----"""from src.adapters.llm import LLMAdapterfrom src.core.agents.observations_agent import ObservationsAgent-from src.lib.llm.client_large import _llm_large_client+from src.lib.llm.client_small import _llm_small_clientllm_adapter = LLMAdapter()-llm_adapter.add_client(_llm_large_client)+llm_adapter.add_client(_llm_small_client)observations_agent = ObservationsAgent(llm_adapter)diff --git a/src/utils/cleanup.py b/src/utils/cleanup.pynew file mode 100644index 0000000..4e6ef6c--- /dev/null+++ b/src/utils/cleanup.py@@ -0,0 +1,59 @@+"""+File: /cleanup.py+Project: utils+Created Date: Saturday January 31st 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Saturday January 31st 2026 9:44:03 pm+Modified By: Christian Nonis <[email protected]>+-----+"""+++def strip_properties(objs: list[dict], pop_also: list[str] = []) -> list[dict]:+ cleaned_objs = []+ for obj in objs:+ if not isinstance(obj, dict):+ cleaned_objs.append(obj)+ continue+ cleaned_obj = obj.copy()++ keys_to_pop = []+ for key, value in cleaned_obj.items():+ if key in pop_also:+ keys_to_pop.append(key)+ continue++ # Python's bool type are subclasses of int, False is 0 and True is 1.+ # This can lead to unexpected behavior if '0' or '1' are used as keys.+ if isinstance(key, bool):+ continue++ if isinstance(value, dict):+ if len(value.keys()) == 0:+ keys_to_pop.append(key)+ else:+ cleaned_obj[key] = strip_properties([value], pop_also)[0]+ elif isinstance(value, list):+ if len(value) == 0:+ keys_to_pop.append(key)+ else:+ new_list = []+ for item in value:+ if isinstance(item, dict):+ new_list.append(strip_properties([item], pop_also)[0])+ else:+ new_list.append(item)+ cleaned_obj[key] = new_list+ elif isinstance(value, str):+ if len(value.strip()) == 0:+ keys_to_pop.append(key)+ elif value is None:+ keys_to_pop.append(key)++ for key in keys_to_pop:+ cleaned_obj.pop(key)++ cleaned_objs.append(cleaned_obj)++ return cleaned_objsdiff --git a/src/utils/serialization/data.py b/src/utils/serialization/data.pyindex cdc06bf..56a3c1b 100644--- a/src/utils/serialization/data.py+++ b/src/utils/serialization/data.py@@ -4,7 +4,7 @@ Created Date: Friday October 24th 2025Author: Christian Nonis <[email protected]>-----Last Modified: Friday October 24th 2025 6:52:20 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Modified By: Christian Nonis <[email protected]>-----"""@@ -12,10 +12,12 @@ import jsonimport re-def str_to_json(text: str, empty_fallback: bool = False) -> list[str]:+def str_to_json(text: str | None, empty_fallback: bool = False) -> list[str]:"""Convert a string to a json list of strings."""+ if not text:+ return []text = text.strip().replace("```json", "").replace("```", "")try:return json.loads(text)diff --git a/src/utils/tokens.py b/src/utils/tokens.pyindex 5575e23..21e27f4 100644--- a/src/utils/tokens.py+++ b/src/utils/tokens.py@@ -12,36 +12,54 @@ Modified By: Christian Nonis <[email protected]>from src.constants.agents import TokenDetail, TokenInputDetail, TokenOutputDetail+def _build_token_detail(+ input_tokens: int,+ output_tokens: int,+ cached_tokens: int,+ reasoning_tokens: int,+ grouped_by_agent: dict[str, TokenDetail] | None = None,+) -> TokenDetail:+ if grouped_by_agent is None:+ grouped_by_agent = {}+ return TokenDetail(+ input=TokenInputDetail(+ total=input_tokens,+ uncached=input_tokens - cached_tokens,+ cached=cached_tokens,+ cache_percentage=(+ (cached_tokens / input_tokens * 100) if input_tokens > 0 else 0.0+ ),+ ),+ output=TokenOutputDetail(+ total=output_tokens,+ regular=output_tokens - reasoning_tokens,+ reasoning=reasoning_tokens,+ reasoning_percentage=(+ (reasoning_tokens / output_tokens * 100) if output_tokens > 0 else 0.0+ ),+ ),+ grand_total=input_tokens + output_tokens,+ effective_total=input_tokens - cached_tokens + output_tokens,+ grouped_by_agent=grouped_by_agent,+ )++def merge_token_details(token_details: list[TokenDetail]) -> TokenDetail:"""Aggregate a list of TokenDetail objects into a single merged TokenDetail.-+Parameters:token_details (list[TokenDetail]): List of TokenDetail objects to merge. None entries are ignored; if the list is empty or contains only None, a TokenDetail with all zero/default fields is returned.-+Returns:TokenDetail: A merged TokenDetail where input and output counts are summed across entries, cache_percentage is (total cached / total input * 100) or 0.0 if total input is zero, reasoning_percentage is (total reasoning / total output * 100) or 0.0 if total output is zero, and grand_total and effective_total are the sums of their respective values."""if not token_details:- return TokenDetail(- input=TokenInputDetail(total=0, uncached=0, cached=0, cache_percentage=0.0),- output=TokenOutputDetail(- total=0, regular=0, reasoning=0, reasoning_percentage=0.0- ),- grand_total=0,- effective_total=0,- )+ return _build_token_detail(0, 0, 0, 0)token_details = [detail for detail in token_details if detail is not None]if not token_details:- return TokenDetail(- input=TokenInputDetail(total=0, uncached=0, cached=0, cache_percentage=0.0),- output=TokenOutputDetail(- total=0, regular=0, reasoning=0, reasoning_percentage=0.0- ),- grand_total=0,- effective_total=0,- )+ return _build_token_detail(0, 0, 0, 0)total_input = sum(detail.input.total for detail in token_details)total_uncached = sum(detail.input.uncached for detail in token_details)@@ -58,6 +76,16 @@ def merge_token_details(token_details: list[TokenDetail]) -> TokenDetail:grand_total = sum(detail.grand_total for detail in token_details)effective_total = sum(detail.effective_total for detail in token_details)+ grouped_by_agent: dict[str, TokenDetail] = {}+ for detail in token_details:+ for agent_name, agent_detail in detail.grouped_by_agent.items():+ if agent_name in grouped_by_agent:+ grouped_by_agent[agent_name] = merge_token_details(+ [grouped_by_agent[agent_name], agent_detail]+ )+ else:+ grouped_by_agent[agent_name] = agent_detail+return TokenDetail(input=TokenInputDetail(total=total_input,@@ -73,21 +101,26 @@ def merge_token_details(token_details: list[TokenDetail]) -> TokenDetail:),grand_total=grand_total,effective_total=effective_total,+ grouped_by_agent=grouped_by_agent,)def token_detail_from_token_counts(- input_tokens: int, output_tokens: int, cached_tokens: int, reasoning_tokens: int+ input_tokens: int,+ output_tokens: int,+ cached_tokens: int,+ reasoning_tokens: int,+ agent_name: str | None = None,) -> TokenDetail:"""Constructs a TokenDetail summarizing input and output token counts with cached and reasoning breakdowns.-+Parameters:input_tokens (int): Total number of input tokens.output_tokens (int): Total number of output tokens.cached_tokens (int): Number of input tokens served from cache.reasoning_tokens (int): Number of output tokens classified as reasoning.-+Returns:TokenDetail: Aggregated token details containing:- input: TokenInputDetail with total, uncached, cached, and cache_percentage.@@ -95,23 +128,15 @@ def token_detail_from_token_counts(- grand_total: Sum of input and output tokens.- effective_total: Sum of output tokens plus input tokens not served from cache."""- return TokenDetail(- input=TokenInputDetail(- total=input_tokens,- uncached=input_tokens - cached_tokens,- cached=cached_tokens,- cache_percentage=(- (cached_tokens / input_tokens * 100) if input_tokens > 0 else 0.0- ),- ),- output=TokenOutputDetail(- total=output_tokens,- regular=output_tokens - reasoning_tokens,- reasoning=reasoning_tokens,- reasoning_percentage=(- (reasoning_tokens / output_tokens * 100) if output_tokens > 0 else 0.0- ),- ),- grand_total=input_tokens + output_tokens,- effective_total=input_tokens - cached_tokens + output_tokens,- )\ No newline at end of file+ base_detail = _build_token_detail(+ input_tokens, output_tokens, cached_tokens, reasoning_tokens+ )+ if agent_name:+ return _build_token_detail(+ input_tokens,+ output_tokens,+ cached_tokens,+ reasoning_tokens,+ grouped_by_agent={agent_name: base_detail},+ )+ return base_detaildiff --git a/src/workers/app.py b/src/workers/app.pyindex f7abc2a..8fb0627 100644--- a/src/workers/app.py+++ b/src/workers/app.py@@ -9,6 +9,13 @@ Modified By: Christian Nonis <[email protected]>"""import os+from pathlib import Path++import dotenv++_project_root = Path(__file__).resolve().parent.parent.parent+dotenv.load_dotenv(_project_root / ".env")+from celery import Celeryfrom src.config import configdiff --git a/src/workers/tasks/ingestion.py b/src/workers/tasks/ingestion.pyindex 13a7695..b8fc957 100644--- a/src/workers/tasks/ingestion.py+++ b/src/workers/tasks/ingestion.py@@ -3,16 +3,17 @@ File: /ingestion.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 5th 2026 7:57:27 pm+Last Modified: Thursday January 29th 2026 8:44:06 pmModified By: Christian Nonis <[email protected]>-----"""+import datetimeimport jsonimport tomllibfrom pathlib import Pathfrom uuid import uuid4-from typing import List, Tuple+from typing import List, Optional, Tuplefrom concurrent.futures import (Future,ThreadPoolExecutor,@@ -71,10 +72,10 @@ def format_textual_data(data: dict, include_keys: bool = True) -> str:def ingest_data(self, args: dict):"""Ingest a payload into the system, persist its content and metadata, generate embeddings and observations, and trigger knowledge-graph enrichment.-+Parameters:args (dict): Raw task arguments parsed into an IngestionTaskArgs model; must include a brain_id and data payload.-+Returns:task_id (str): The identifier of the ingestion task (Celery request id) that was created/updated."""@@ -194,18 +195,18 @@ def ingest_data(self, args: dict):def process_architect_relationships(self, args: dict):"""Process a batch of architect relationships and ingest corresponding nodes, vectors, and graph edges.-+Parameters:args (dict): Task payload containing:- "relationships" (List[dict]): List of relationship payloads convertible to ArchitectAgentRelationship.- "brain_id" (str, optional): Target brain identifier; defaults to "default".-+Description:For each relationship in `args["relationships"]`, the task generates embeddings for the relationship (and for any missing subject/object nodes), creates or updates graph nodes, and adds the relationship edge to the knowledge graph. Progress and final status are stored in the task cache under the current task id. Individual relationship or node failures (including timeouts) are skipped so remaining items continue processing.-+Returns:str: The Celery task id for the ingestion run.-+Raises:Exception: Any unhandled exception is recorded to the task cache with status "failed" and then re-raised."""@@ -218,6 +219,7 @@ def process_architect_relationships(self, args: dict):relationships_data: List[dict] = args.get("relationships", [])brain_id: str = args.get("brain_id", "default")+ session_id: Optional[str] = args.get("session_id")try:cache_adapter.set(@@ -273,6 +275,40 @@ def process_architect_relationships(self, args: dict):labels=[relationship.tip.type],brain_id=brain_id,)+ similar_v_rels = []+ if v_rel_id is not None:+ rel_vectors = vector_store_adapter.get_by_ids(+ [str(v_rel_id)],+ store="relationships",+ brain_id=brain_id,+ )+ if rel_vectors and getattr(rel_vectors[0], "embeddings", None):+ similar_v_rels = vector_store_adapter.search_vectors(+ rel_vectors[0].embeddings,+ brain_id=brain_id,+ store="relationships",+ k=10,+ )+ if similar_v_rels and similar_v_rels[0].distance > 0.9:+ similar_rel = graph_adapter.get_triples_by_uuid(+ [similar_v_rels[0].metadata.get("uuid")],+ brain_id=brain_id,+ )+ if similar_rel:+ similar_tail, _, similar_tip = similar_rel[0]+ if (+ similar_tail.uuid == relationship.tail.uuid+ and similar_tip.uuid == relationship.tip.uuid+ ) or (+ similar_tail.uuid == relationship.tip.uuid+ and similar_tip.uuid == relationship.tail.uuid+ ):+ vector_store_adapter.remove_vectors(+ [v_rel_id],+ store="relationships",+ brain_id=brain_id,+ )+ continuenode_embedding_futures = []print(f"> Subject exists: {subject_exists}")@@ -353,6 +389,8 @@ def process_architect_relationships(self, args: dict):**(relationship.properties or {}),"v_id": v_rel_id,},+ last_updated=datetime.datetime.now(),+ amount=relationship.amount,),Node(uuid=relationship.tip.uuid,@@ -394,6 +432,16 @@ def process_architect_relationships(self, args: dict):expires_in=3600 * 24 * 7,)+ if session_id:+ from src.lib.redis.client import _redis_client++ remaining = _redis_client.client.decr(+ f"{brain_id}:session:{session_id}:pending_tasks"+ )+ print(+ f"[DEBUG (process_architect_relationships)]: Session {session_id} has {remaining} remaining tasks"+ )+return self.request.idexcept Exception as e:@@ -411,6 +459,11 @@ def process_architect_relationships(self, args: dict):expires_in=3600 * 24 * 7,)+ if session_id:+ from src.lib.redis.client import _redis_client++ _redis_client.client.decr(f"{brain_id}:session:{session_id}:pending_tasks")+raise@@ -418,7 +471,7 @@ def process_architect_relationships(self, args: dict):def ingest_structured_data(self, args: dict):"""Ingest structured elements into the knowledge graph by creating nodes, embedding and storing vectors, generating observations, and saving structured-data records.-+Parses `args` into an IngestionStructuredRequestBody and for each element:- creates a graph node with properties and metadata,- records node property change logs (KG changes),@@ -427,13 +480,13 @@ def ingest_structured_data(self, args: dict):- merges and saves structured-data records,- calls knowledge-graph enrichment for the element,and updates a task status cache with "started" and "completed" entries.-+Parameters:args (dict): The raw task payload parsed into IngestionStructuredRequestBody (must include brain_id and data elements).-+Returns:str: The task id for this ingestion (self.request.id).-+Exceptions:On exception, stores a "failed" task status with error details in the cache and re-raises the exception."""@@ -520,15 +573,6 @@ def ingest_structured_data(self, args: dict):)data_adapter.save_kg_changes(kg_changes, brain_id=payload.brain_id)- vector = embeddings_adapter.embed_text(node.name)- vector.id = node.uuid- vector.metadata = {- "labels": node.labels,- "name": node.name,- "uuid": node.uuid,- }- vector_store_adapter.add_vectors(vectors=[vector], store="nodes")-existing_structured_data = data_adapter.get_structured_data_by_id(id=uuid, brain_id=payload.brain_id)@@ -562,6 +606,22 @@ def ingest_structured_data(self, args: dict):},)# TODO: update the changelogs here+ else:+ vector = embeddings_adapter.embed_text(node.name)+ vector.id = node.uuid+ vector.metadata = {+ "labels": node.labels,+ "name": node.name,+ "uuid": node.uuid,+ }+ vector_store_adapter.add_vectors(vectors=[vector], store="nodes")+ new_structured_data = StructuredData(+ id=uuid,+ data=element.json_data,+ types=element.types,+ metadata=element.metadata,+ brain_version=BRAIN_VERSION,+ )data_adapter.save_structured_data(structured_data=new_structured_data,@@ -654,4 +714,86 @@ def ingest_structured_data(self, args: dict):expires_in=3600 * 24 * 7,)- raise\ No newline at end of file+ raise+++@ingestion_app.task(bind=True)+def consolidate_graph_async(+ self,+ session_id: str,+ brain_id: str = "default",+ ingestion_session_id: str = None,+):+ """+ Consolidate graph after all processing tasks complete.+ """+ import os+ import langsmith+ from src.core.layers.graph_consolidation.graph_consolidation import (+ consolidate_graph,+ )+ from src.lib.redis.client import _redis_client+ from src.config import config++ print(+ f"[DEBUG (consolidate_graph_async)]: Starting consolidation for session {session_id}"+ )++ if not config.run_graph_consolidator:+ print(+ "[DEBUG (consolidate_graph_async)]: Graph consolidator is disabled, skipping"+ )+ return++ relationships_data_str = _redis_client.get(+ f"session:{session_id}:relationships", brain_id=brain_id+ )+ if not relationships_data_str:+ print(+ f"[DEBUG (consolidate_graph_async)]: No relationships data found for session {session_id}"+ )+ return++ relationships_data = json.loads(relationships_data_str)+ relationships = [+ ArchitectAgentRelationship(**rel_data) for rel_data in relationships_data+ ]++ print(+ f"[DEBUG (consolidate_graph_async)]: Consolidating graph with {len(relationships)} relationships"+ )++ project_name = os.getenv("LANGSMITH_PROJECT", "brainapi")+ tracing_metadata = {"brain_id": brain_id, "flow": "consolidate_graph"}+ if ingestion_session_id:+ tracing_metadata["ingestion_session_id"] = ingestion_session_id++ try:+ with langsmith.tracing_context(+ project_name=project_name,+ enabled=True,+ tags=["consolidate_graph", "janitor", "kg_agent"],+ metadata=tracing_metadata,+ ):+ consolidation_response = consolidate_graph(relationships, brain_id=brain_id)+ try:+ from langchain_core.tracers.langchain import wait_for_all_tracers++ wait_for_all_tracers()+ except ImportError:+ pass+ print(+ f"[DEBUG (consolidate_graph_async)]: Consolidation completed for session {session_id}"+ )+ _redis_client.delete(f"session:{session_id}:relationships", brain_id=brain_id)+ _redis_client.client.delete(f"{brain_id}:session:{session_id}:pending_tasks")+ return (+ consolidation_response.model_dump(mode="json")+ if hasattr(consolidation_response, "model_dump")+ else None+ )+ except Exception as e:+ print(+ f"[DEBUG (consolidate_graph_async)]: Consolidation failed for session {session_id}: {e}"+ )+ raise