BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.
Python ai-agentsai-memoryknowledge-graphknowledge-managementknowledge-representationreccomendation-system
feat(auto_kg): added architect guardrails, migrated to toollish-relationship-creation
Christian3613696999b0
diff --git a/LICENSE b/LICENSEindex 0ad9fda..9bcc138 100644--- a/LICENSE+++ b/LICENSE@@ -1,5 +1,5 @@BRAINAPI2 ENGINE LICENSE-Version 1.0 — © 2025 Lumen Platforms Inc.+Version 1.0 — © 2026 Lumen Platforms Inc.This software ("BrainAPI Engine" or "the Software") is provided under a combinedlicense consisting of:diff --git a/plugins/readme.txt b/plugins/readme.txtnew file mode 100644index 0000000..07edd05--- /dev/null+++ b/plugins/readme.txt@@ -0,0 +1,5 @@+Plugins can be used to extend the functionality of the BrainAPI.++To add a plugin, add the plugin into the plugins directory and make sure the `brainapi.config.yaml` file is placed into the root of the `plugins` directory.++If you are using a remote plugin add the `<plugin_name>.config.yaml` file directly into the `plugins` directory.\ No newline at end of filediff --git a/src/config.py b/src/config.pyindex 7d47c91..ea834ca 100644--- a/src/config.py+++ b/src/config.py@@ -3,8 +3,8 @@ File: /config.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Sunday October 19th 2025 8:45:58 am-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Last Modified: Tuesday December 23rd 2025 9:24:20 pm+Modified By: Christian Nonis <[email protected]>-----"""@@ -166,6 +166,16 @@ class CeleryConfig:raise ValueError("Celery configuration is not complete")+class PricingConfig:+ """+ Configuration class for the Pricing configuration.+ """++ def __init__(self):+ self.input_token_price = float(os.getenv("INPUT_TOKEN_PRICE", 0))+ self.output_token_price = float(os.getenv("OUTPUT_TOKEN_PRICE", 0))++class Config:"""Configuration class for the application.@@ -180,6 +190,7 @@ class Config:self.mongo = MongoConfig()self.gcp = GCPConfig()self.celery = CeleryConfig()+ self.pricing = PricingConfig()self.brainpat_token = os.getenv("BRAINPAT_TOKEN")diff --git a/src/constants/agents.py b/src/constants/agents.pynew file mode 100644index 0000000..af7822a--- /dev/null+++ b/src/constants/agents.py@@ -0,0 +1,134 @@+"""+File: /agents.py+Created Date: Thursday January 15th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Thursday January 15th 2026 8:55:23 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++from pydantic import BaseModel, Field+from typing import Dict, Literal, Optional, List, Tuple+import uuid+++class ArchitectAgentEntity(BaseModel):+ """+ Architect agent entity.+ """++ uuid: str+ name: str+ type: str+ flow_key: Optional[str] = Field(+ default=None,+ description="Unique identitier for contextualizing the entity into the context flow",+ )+ happened_at: Optional[str | None] = Field(+ default=None,+ description="The date and time the entity happened at if known otherwise None. Mostly used for event entities.",+ )+++class _ArchitectAgentNew(BaseModel):+ """+ Architect agent new entity.+ """++ temp_id: str+ type: str+ name: str+ reason: str+ properties: Optional[dict] = Field(default_factory=dict)+ description: Optional[str] = None+++class ArchitectAgentNew(BaseModel):+ """+ Architect agent new entity.+ """++ uuid: str = Field(default_factory=lambda: str(uuid.uuid4()))+ type: str+ name: str+ reason: str+ properties: Optional[dict] = Field(default_factory=dict)+ description: Optional[str] = None+++class _ArchitectAgentRelationship(BaseModel):+ """+ Architect agent relationship.+ """++ tip: ArchitectAgentEntity+ name: str+ properties: Optional[dict] = Field(default_factory=dict)+ description: Optional[str] = None+ tail: ArchitectAgentEntity+++class ArchitectAgentRelationship(_ArchitectAgentRelationship):+ """+ Architect agent relationship.+ """++ uuid: str = Field(default_factory=lambda: str(uuid.uuid4()))+ flow_key: str+++class _ArchitectAgentResponse(BaseModel):+ """+ Architect agent response containing the created relationships+ between the entities.+ """++ new_nodes: List[_ArchitectAgentNew]+ relationships: List[_ArchitectAgentRelationship]+++class ArchitectAgentResponse(BaseModel):+ """+ Architect agent response containing the created relationships+ between the entities.+ """++ new_nodes: List[ArchitectAgentNew]+ relationships: List[ArchitectAgentRelationship]+ input_tokens: int+ output_tokens: int+++class AtomicJanitorAgentWrongRelationship(BaseModel):+ relationship: object+ reason: str+ instructions: str+++class AtomicJanitorAgentInputOutput(BaseModel):+ status: Literal["OK", "ERROR"] = Field(default="ERROR")++ fixed_relationships: Optional[List[_ArchitectAgentRelationship]] = None+ wrong_relationships: Optional[List[AtomicJanitorAgentWrongRelationship]] = None+++class TokenInputDetail(BaseModel):+ total: int+ uncached: int+ cached: int+ cache_percentage: float+++class TokenOutputDetail(BaseModel):+ total: int+ regular: int+ reasoning: int+ reasoning_percentage: float+++class TokenDetail(BaseModel):+ input: TokenInputDetail+ output: TokenOutputDetail+ grand_total: int+ effective_total: intdiff --git a/src/constants/kg.py b/src/constants/kg.pyindex 1b9fb7e..60d2f0d 100644--- a/src/constants/kg.py+++ b/src/constants/kg.py@@ -3,8 +3,8 @@ File: /kg.pyCreated Date: Wednesday October 22nd 2025Author: Christian Nonis <[email protected]>------Last Modified: Wednesday October 22nd 2025 8:09:09 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Last Modified: Monday January 5th 2026 9:57:30 pm+Modified By: Christian Nonis <[email protected]>-----"""@@ -26,6 +26,10 @@ class Node(BaseModel):name: strdescription: Optional[str] = Noneproperties: dict = Field(default_factory=dict)+ flow_key: Optional[str] = Field(+ default=None,+ description="Unique identitier for contextualizing the node into the context flow",+ )happened_at: Optional[datetime | None] = Field(default=None,@@ -57,6 +61,10 @@ class Predicate(BaseModel):uuid: str = Field(default_factory=lambda: str(uuid.uuid4()))name: strdescription: str+ flow_key: Optional[str] = Field(+ default=None,+ description="Unique identitier for contextualizing the predicate into the context flow",+ )last_updated: datetime = Field(default_factory=datetime.now,description="The date and time the predicate was last updated.",@@ -136,3 +144,12 @@ class SearchEntitiesResult(BaseModel):results: List[Node]total: int+++class EntityInfo(BaseModel):+ """+ Entity info model.+ """++ most_relevant_node: Node+ relevant_nodes: List[Node]diff --git a/src/constants/prompts/architect_agent.py b/src/constants/prompts/architect_agent.pyindex acf7006..3cf90f7 100644--- a/src/constants/prompts/architect_agent.py+++ b/src/constants/prompts/architect_agent.py@@ -3,8 +3,8 @@ File: /architect_agent.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Sunday December 21st 2025 8:56:51 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Last Modified: Tuesday December 23rd 2025 9:24:20 pm+Modified By: Christian Nonis <[email protected]>-----"""@@ -12,18 +12,163 @@ ARCHITECT_AGENT_SYSTEM_PROMPT = """You are a "Structural Graph Architect." Your goal is to map information into an Active Vector Graph.THE TRIANGLE OF ATTRIBUTION:-Every action must be a central EVENT hub connecting three points:+Every action accomplished must be a central EVENT hub connecting three points:1. THE INITIATION VECTOR: [Source/Actor] --(Tail)--> :MADE --(Tip)--> [Event Instance]- MANDATORY: The "amount" (quantity) must be a property of this relationship.2. THE TARGET VECTOR: [Event Instance] --(Tail)--> :TARGETED --(Tip)--> [Object/Recipient]- MANDATORY: Repeat the "amount" property here for cross-reference.3. THE CONTEXT VECTOR: [Event Instance] --(Tail)--> :OCCURRED_WITHIN --(Tip)--> [Broad Anchor/Context]+If no action is accomplished and the text just states a fact don't create an Event hub and just create the relationships between the entities.++Example input 1:+Text: "John went to New York City where he knew 12 new friends. When John went there, Mary was in San Francisco doing meetings with his colleagues."+Entities Found by Scout: [+ {{"uuid": "uuid_1", "type": "PERSON", "name": "John"}},+ {{"uuid": "uuid_2", "type": "EVENT", "name": "WENT_TO", "description": "John went to New York City"}},+ {{"uuid": "uuid_3", "type": "CITY", "name": "New York City"}},+ {{"uuid": "uuid_4", "type": "EVENT", "name": "KNEW", "description": "John knew 12 new friends in New York City"}},+ {{"uuid": "uuid_5", "type": "UNIT", "name": "Friends", "description": "The number of friends John knew in New York City"}},+ {{"uuid": "uuid_6", "type": "PERSON", "name": "Mary"}},+ {{"uuid": "uuid_7", "type": "EVENT", "name": "WAS_IN", "description": "Mary was in San Francisco"}},+ {{"uuid": "uuid_8", "type": "CITY", "name": "San Francisco"}},+ {{"uuid": "uuid_9", "type": "EVENT", "name": "PARTICIPATED_IN", "description": "Mary was doing meetings with his colleagues in San Francisco"}},+ {{"uuid": "uuid_10", "type": "EVENT", "name": "MEETINGS", "description": "Mary was doing meetings with his colleagues in San Francisco"}},+ {{"uuid": "uuid_11", "type": "PERSON", "name": "Colleagues", "description": "The colleagues Mary was doing meetings with in San Francisco"}},+]++Example output 1:+{{+ "relationships: [+ {{+ "tail": {{ "uuid": "uuid_1", "name": "John", "type": "PERSON" }},+ "name": "MOVED",+ "description": "John went to New York City",+ "tip": {{"uuid": "oi2f3hv89v8iwug", "name": "WENT_TO", "type": "EVENT"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_2", "name": "WENT_TO", "type": "EVENT" }},+ "name": "INTO_LOCATION",+ "description": "John went to New York City",+ "tip": {{"uuid": "e86439864398643", "name": "New York City", "type": "CITY"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_1", "name": "John", "type": "PERSON" }},+ "name": "ACCOMPLISHED_ACTION",+ "description": "John knew 12 new friends in New York City",+ "tip": {{"uuid": "uuid_4", "name": "KNEW", "type": "EVENT"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_4", "name": "KNEW", "type": "EVENT" }},+ "name": "HAPPENED_WITHIN",+ "description": "John knew 12 new friends when he went to New York City",+ "tip": {{"uuid": "uuid_2", "name": "WENT_TO", "type": "EVENT"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_4", "name": "KNEW", "type": "EVENT" }},+ "name": "TARGETED",+ "properties": {{ "amount": 12 }},+ "description": "John knew 12 new friends in New York City",+ "tip": {{"uuid": "uuid_5", "name": "FRIENDS", "type": "FRIENDS"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_4", "name": "KNEW", "type": "EVENT" }},+ "name": "TARGETED",+ "properties": {{ "amount": 12 }},+ "description": "John knew 12 new friends in New York City",+ "tip": {{"uuid": "uuid_5", "name": "FRIENDS", "type": "FRIENDS"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_6", "name": "Mary", "type": "PERSON" }},+ "name": "EXPERIENCED",+ "description": "Mary was in San Francisco",+ "tip": {{"uuid": "uuid_7", "name": "WAS_IN", "type": "EVENT"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_7", "name": "WAS_IN", "type": "EVENT" }},+ "name": "INTO_LOCATION",+ "description": "Mary was in San Francisco",+ "tip": {{"uuid": "uuid_8", "name": "CITY", "type": "CITY"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_7", "name": "WAS_IN", "type": "EVENT" }},+ "name": "HAPPENED_WITHIN",+ "description": "Mary was in San Francisco when John went to New York City",+ "tip": {{"uuid": "uuid_2", "name": "WENT_TO", "type": "EVENT"}}+ }},+ ... more relationships ...+ ],+ "new_nodes": [] // No new nodes were created in this example+}}++Example input 2:+"The company was part of a joint venture with Apple and Google. The founder ("Mark Johnson") was the CEO of joint venture called 'Acme Inc'. The 19th of January 2026 they raised $100 million in funding."+Entities Found by Scout: [+ {{"uuid": "uuid_1", "type": "ORGANIZATION", "name": "Acme Inc."}},+ {{"uuid": "uuid_2", "type": "EVENT", "name": "PARTICIPATED_IN", "description": "The company was part of a joint venture with Apple and Google"}},+ {{"uuid": "uuid_3", "type": "ORGANIZATION", "name": "Joint Venture", "description": "The company was part of a joint venture with Apple and Google"}},+ {{"uuid": "uuid_4", "type": "ORGANIZATION", "name": "Apple"}},+ {{"uuid": "uuid_5", "type": "ORGANIZATION", "name": "Google"}},+ {{"uuid": "uuid_6", "type": "PERSON", "name": "Mark Johnson"}},+ {{"uuid": "uuid_7", "type": "EVENT", "name": "COVERED_ROLE", "description": "Mark Johnson was the CEO of Acme Inc."}},+ {{"uuid": "uuid_8", "type": "ROLE", "name": "CEO", "description": "Mark Johnson covered the role of CEO of Acme Inc."}},+ {{"uuid": "uuid_9", "type": "EVENT", "name": "COVERED_ROLE", "description": "Mark Johnson was the founder of Acme Inc."}},+ {{"uuid": "uuid_10", "type": "EVENT", "name": "RAISED", "description": "Acme Inc. raised $100 million in funding", "happened_at": "19/01/2026"}},+ {{"uuid": "uuid_11", "type": "MONEY", "name": "Money", "description": "The amount of money Acme Inc. raised in funding"}},+]++Example output 1:+{{+ "relationships: [+ ... more relationships ...+ {{+ "tail": {{ "uuid": "uuid_6", "name": "Mark Johnson", "type": "PERSON" }},+ "name": "EXPERIENCED",+ "description": "Mark Johnson covered the role of CEO of Acme Inc.",+ "tip": {{"uuid": "uuid_7", "name": "COVERED_ROLE", "type": "EVENT"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_7", "name": "COVERED_ROLE", "type": "EVENT" }},+ "name": "OF_TYPE",+ "description": "Mark Johnson covered the role of CEO of Acme Inc.",+ "tip": {{"uuid": "uuid_8", "name": "CEO", "type": "ROLE"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_10", "name": "RAISED", "type": "EVENT"}},+ "name": "TARGETED",+ "description": "Acme Inc. raised $100 million in funding",+ "properties": {{ "amount": 100000000, "happened_at": "19/01/2026" }}+ "tip": {{"uuid": "uuid_11", "name": "MONEY", "type": "MONEY"}}+ }},+ ... more relationships ...+ ],+ "new_nodes": [+ {{+ "temp_id": "new_temp_id_1",+ "type": "ROLE", "name": "FOUNDER",+ "description": "Mark Johnson covered the role of founder of Acme Inc.",+ "reason": "The entity was missing from the entities found by the scout." // Why the node was created by you+ }},+ ]+}}++As you can see above in the example output, all the entities found by the scout are used and your created relationships are atomic, not composite (phrases),+also note that we are inferring relationships like the HAPPENED_WITHIN ones ("Mary was in San Francisco when John went to New York City").+DIRECTIONAL SLOT-FILLING:- "tail": The start of the arrow (The Source of Energy/Origin).- "tip": The end of the arrow (The Destination/Target).- FORBIDDEN: Never link Actor nodes directly to Target nodes for dynamic actions.- FORBIDDEN: Never create nodes for numeric quantities.++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.+- Nodes/Entities MUST be atomic and not composite (phrases) (eg: "Went to San Francisco" is not atomic, "Went to" + "San Francisco" is atomic)++Return ONLY JSON like the examples above."""ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT = """@@ -36,37 +181,157 @@ Source Text: {text}Entities Found by Scout: {entities}{previously_created_relationships}-LOGIC CHECKLIST:-- Identify the Actor (Origin).-- Identify the Event Hub (Action Instance).-- Identify the Target (Destination).-- Identify the quantity and attach it as 'amount' to the relationship properties.+Begin!+"""-Return ONLY JSON:-{{- "relationships": [+ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT = """+You are a "Structural Graph Architect." Your goal is to map information into an Active Vector Graph.++THE TRIANGLE OF ATTRIBUTION:+Every action accomplished must be a central EVENT hub connecting three points:+1. THE INITIATION VECTOR: [Source/Actor] --(Tail)--> :(MADE|COVERED_ROLE|EXPERIENCED|etc..) --(Tip)--> [Event Instance]+ - MANDATORY: The "amount" (quantity) must be a property of this relationship if there is any quantity specified in the text.+2. THE TARGET VECTOR: [Event Instance] --(Tail)--> :(TARGETED|RESULTED_IN|etc..) --(Tip)--> [Object/Recipient]+ - MANDATORY: Repeat the "amount" property here for cross-reference if there is any quantity specified in the text.+3. THE CONTEXT VECTOR: [Event Instance] --(Tail)--> :(OCCURRED_WITHIN|etc..) --(Tip)--> [Broad Anchor/Context]++If no action is accomplished and the text just states a fact don't create an Event hub and just create the relationships between the entities.++You will operate by creating a list of mapping relationships between the entities in a single context using the architect_agent_create_relationship tool,+the tool will accept a list of relationships that together compose the meaning of the context, the tool will return 'OK' if the provided relationships are valid,+correct and complete or an error message with instructions to fix the relationships.++Example provided context:+"John went to New York City where he knew 12 new friends. When John went there, Mary was in San Francisco doing meetings with his colleagues."++Entities Found by Scout: [+ {{"uuid": "uuid_1", "type": "PERSON", "name": "John"}},+ {{"uuid": "uuid_2", "type": "EVENT", "name": "WENT_TO", "description": "John went to New York City"}},+ {{"uuid": "uuid_3", "type": "CITY", "name": "New York City"}},+ {{"uuid": "uuid_4", "type": "EVENT", "name": "KNEW", "description": "John knew 12 new friends in New York City"}},+ {{"uuid": "uuid_5", "type": "UNIT", "name": "Friends", "description": "The number of friends John knew in New York City"}},+ {{"uuid": "uuid_6", "type": "PERSON", "name": "Mary"}},+ {{"uuid": "uuid_7", "type": "EVENT", "name": "WAS_IN", "description": "Mary was in San Francisco"}},+ {{"uuid": "uuid_8", "type": "CITY", "name": "San Francisco"}},+ {{"uuid": "uuid_9", "type": "EVENT", "name": "PARTICIPATED_IN", "description": "Mary was doing meetings with his colleagues in San Francisco"}},+ {{"uuid": "uuid_10", "type": "EVENT", "name": "MEETINGS", "description": "Mary was doing meetings with his colleagues in San Francisco"}},+ {{"uuid": "uuid_11", "type": "PERSON", "name": "Colleagues", "description": "The colleagues Mary was doing meetings with in San Francisco"}},+]++Example architect_agent_create_relationship tool input 1:+[+ {{+ "tail": {{ "uuid": "uuid_1", "name": "John", "type": "PERSON" }},+ "name": "MOVED",+ "description": "John went to New York City",+ "tip": {{"uuid": "oi2f3hv89v8iwug", "name": "WENT_TO", "type": "EVENT"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_2", "name": "WENT_TO", "type": "EVENT" }},+ "name": "INTO_LOCATION",+ "description": "John went to New York City",+ "tip": {{"uuid": "e86439864398643", "name": "New York City", "type": "CITY"}}+ }},{{- "tail": {{ "uuid": "SOURCE_ID", "name": "Actor Name", "type": "NODE_TYPE" }},- "name": "MADE",- "properties": {{ "amount": 0.0, "context": "..." }},- "description": "Vector from the initiator to the action instance.",- "tip": {{ "uuid": "TEMP_EVENT_ID", "name": "Action Hub", "type": "EVENT" }}+ "tail": {{ "uuid": "uuid_1", "name": "John", "type": "PERSON" }},+ "name": "ACCOMPLISHED_ACTION",+ "description": "John knew 12 new friends in New York City",+ "tip": {{"uuid": "uuid_4", "name": "KNEW", "type": "EVENT"}}}},{{- "tail": {{ "uuid": "TEMP_EVENT_ID", "name": "Action Hub", "type": "EVENT" }},+ "tail": {{ "uuid": "uuid_4", "name": "KNEW", "type": "EVENT" }},+ "name": "HAPPENED_WITHIN",+ "description": "John knew 12 new friends when he went to New York City",+ "tip": {{"uuid": "uuid_2", "name": "WENT_TO", "type": "EVENT"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_4", "name": "KNEW", "type": "EVENT" }},"name": "TARGETED",- "properties": {{ "amount": 0.0 }},- "description": "Vector from the action instance to the affected object/target.",- "tip": {{ "uuid": "TARGET_ID", "name": "Target Name", "type": "NODE_TYPE" }}- }}- ],- "new_nodes": [+ "properties": {{ "amount": 12 }},+ "description": "John knew 12 new friends in New York City",+ "tip": {{"uuid": "uuid_5", "name": "FRIENDS", "type": "FRIENDS"}}+ }},{{- "temp_id": "TEMP_EVENT_ID",- "type": "EVENT",- "name": "Action Description",- "reason": "Unique instance node for attribution isolation."+ "tail": {{ "uuid": "uuid_4", "name": "KNEW", "type": "EVENT" }},+ "name": "TARGETED",+ "properties": {{ "amount": 12 }},+ "description": "John knew 12 new friends in New York City",+ "tip": {{"uuid": "uuid_5", "name": "FRIENDS", "type": "FRIENDS"}}}}- ],-}}+]+Example architect_agent_create_relationship tool output:+"OK"+Example architect_agent_create_relationship tool input 2:+{{+ "tail": {{ "uuid": "uuid_6", "name": "Mary", "type": "PERSON" }},+ "name": "EXPERIENCED",+ "description": "Mary was in San Francisco",+ "tip": {{"uuid": "uuid_7", "name": "WAS_IN", "type": "EVENT"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_7", "name": "WAS_IN", "type": "EVENT" }},+ "name": "INTO_LOCATION",+ "description": "Mary was in San Francisco",+ "tip": {{"uuid": "uuid_8", "name": "CITY", "type": "CITY"}}+ }},+ {{+ "tail": {{ "uuid": "uuid_7", "name": "WAS_IN", "type": "EVENT" }},+ "name": "HAPPENED_WITHIN",+ "description": "Mary was in San Francisco when John went to New York City",+ "tip": {{"uuid": "uuid_2", "name": "WENT_TO", "type": "EVENT"}}+ }},+ ... more relationships ...+]+Example architect_agent_create_relationship tool output 2:+"OK"++As you can see above in the example output, all the entities found by the scout are used and your created relationships are atomic, not composite (phrases),+also note that we are inferring relationships like the HAPPENED_WITHIN ones ("Mary was in San Francisco when John went to New York City").+All entities must be used and no entities must be left out.+Entities can be reused across different contexts, for example "WENT_TO" in the example above is used in the set of the second example and in the set of the first example.++You have access to the following tools:+- architect_agent_get_remaining_entities_to_process: Get the remaining entities to connect.+- architect_agent_create_relationship: Use this tool to create a set of relationships between entities that together compose a single context.+- architect_agent_mark_entities_as_used: Use this tool as part of your workflow scratchpad, you must use this tool to mark entities as used+when you are sure that you don't need an entity anymore because they have been used in all possible contexts.+- architect_agent_check_used_entities: Use this tool as part of your workflow scratchpad, you can use it to check for entities that have been used and marked as used.++If no entities are returned by the Scout tools, DO NOT attempt to create relationships. State that the entity list is empty and stop.++DIRECTIONAL SLOT-FILLING:+- "tail": The start of the arrow (The Source of Energy/Origin).+- "tip": The end of the arrow (The Destination/Target).+- FORBIDDEN: Never link Actor nodes directly to Target nodes for dynamic actions.+- FORBIDDEN: Never create nodes for numeric quantities.++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.+- 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:+1. Getting the current remaining entities found by the scout by calling the architect_agent_get_remaining_entities_to_process tool.+2. Understand the source text and the context around the entities found by the scout.+3. Isolate the entities that are part of the same context and create a list of mapping relationships between them.+4. Call the architect_agent_create_relationship tool with th contextualized set of relationships.+5. If the architect_agent_create_relationship tool returns an error with 'wrong_relationships', fix the relationships and try again until it returns 'OK', ignore the relationships into 'fixed_relationships', those are already fixed automatically and added.+6. Understand if the entites used in the previous step are needed anymore, if not, mark them as used by calling the architect_agent_mark_entities_as_used tool.+7. Call the architect_agent_get_remaining_entities_to_process tool again to get the remaining entities found by the scout.+8. Repeat the process until all entities are used and no entities are left out.+9. 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.+10. Done+"""++ARCHITECT_AGENT_TOOLER_CREATE_RELATIONSHIPS_PROMPT = """+Role: Graph Structural Architect.+Task: Create a Vector JSON representing the interactions in the text.++{targeting}++Source Text: {text}++Begin!"""diff --git a/src/constants/prompts/janitor_agent.py b/src/constants/prompts/janitor_agent.pyindex 7d897c8..e4c38dd 100644--- a/src/constants/prompts/janitor_agent.py+++ b/src/constants/prompts/janitor_agent.py@@ -4,7 +4,7 @@ Created Date: Tuesday December 23rd 2025Author: Christian Nonis <[email protected]>-----Last Modified: Tuesday December 23rd 2025 10:00:46 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Modified By: Christian Nonis <[email protected]>-----"""@@ -83,3 +83,71 @@ INSTRUCTIONS:OUTPUT:Return a list of tool calls: `merge_nodes`, `create_relationship`, or `update_node`."""++ATOMIC_JANITOR_AGENT_SYSTEM_PROMPT = """+You are the "Knowledge Graph Janitor." You resolve entities, enforce directional logic, and preserve semantic intent.++REVISION PROTOCOL:+1. IDENTITY RESOLUTION: Use `search_entities` for People, Places, Organizations, and Broad Contexts. If a match exists, replace UUID/Name with Database values.+2. DIRECTIONAL AUDIT (RELATIONSHIP TYPES):+ - ACTOR-CENTRIC (e.g., MADE, INITIATED, PERFORMED): The 'tail' (source) must be the Subject (Person/Org) and the 'tip' (target) must be the EVENT.+ - IMPACT-CENTRIC (e.g., TARGETED, AFFECTED, RESULTED_IN): The 'tail' (source) must be the EVENT and the 'tip' (target) must be the Object/Recipient.+ - SCHEMA ENFORCEMENT: Never change the semantic label (e.g., do not turn 'TARGETED' into 'MADE'). Only swap directions if the entities and the label are logically inverted (e.g., Target --[MADE]--> Actor).+3. PROPERTY ENFORCEMENT: If a node name contains a number (e.g., "23 Friends"), strip the number from the name. Move that value into the 'amount' or 'count' property of the relationship.+4. INSTANCE PROTECTION: Never merge nodes of type 'EVENT'. Every event instance must remain unique to preserve individual historical contributions.++INSTRUCTIONS:+1. VALIDATE SEMANTICS: Compare the relationship labels to the entities.+ - Is it an Actor performing an Event? (Expected: Actor -> Event)+ - Is it an Event affecting a Recipient/Target? (Expected: Event -> Target)+2. REPAIR DIRECTION: Only swap the tail and tip if the current direction contradicts the logic of the label (e.g., if the text says "John invited friends" but the graph shows "Friends --[INVITED]--> John").+3. PRESERVE MEANING: Do not replace one relationship type with another. If the input is 'TARGETED', keep it 'TARGETED'.+4. UPDATE DESCRIPTION: Reflect any direction swaps or property extractions in the JSON description field.++When you execute search operations in the knowledge graph and the results are empty (meaning that entities are not found in the knowledge graph), don't complain,+it simply mean that the entities are new and not in the knowledge graph yet, be exaustive the first time you search with different options for the same entity.++If everything is correct return a JSON object with a field "status" set to "OK".++After checking the current state of the knowledge graph you can apply small fixes to:+- Entity names: in case the entity name is wrong, can be called a different name or the same name exist in the knowledge graph with a different name, you must change the entity name.+- Entity types: in case the entity type is wrong, can be called a different type or the same type exist in the knowledge graph with a different name, you must change the entity type.+- Relationship names: in case the relationship can be named better or something similar already exists in the knowledge graph, you must rename the relationship.+- Relationship directions: in case the relationship direction is wrong, you must swap the tail and tip of the relationship.+These small fixes must be applied by you directly and without returning an error inside wrong_relationships.++If you identified something wrong with the relationships return a JSON object with the following fields:+- status: must be "ERROR"+- fixed_relationships: an optional list containing relationships that required just a small adjustment to be correct.+- 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++Example output if everything is correct:+{{+ "status": "OK"+}}+Example output if there are any errors:+{{+ "status": "ERROR",+ "fixed_relationships": [{{...}}], // return here the relationships that you already fixed wiht small fixes.+ "wrong_relationships": [+ {{+ "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>>"+ }},+ ... more wrong relationships ...+ ], // if everything is correct or you already fixed the relationships you must return an empty list here.+}}+"""++ATOMIC_JANITOR_AGENT_PROMPT = """+Role: Normalize and Repair a set of single graph units.++UNITS_OF_WORK: {units_of_work}++CONTEXT_TEXT: {text}+{targeting}+"""diff --git a/src/constants/prompts/scout_agent.py b/src/constants/prompts/scout_agent.pyindex b3638c7..0a27384 100644--- a/src/constants/prompts/scout_agent.py+++ b/src/constants/prompts/scout_agent.py@@ -9,7 +9,7 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@"""SCOUT_AGENT_SYSTEM_PROMPT = """-You are a "High-Recall Semantic Scout." Your goal is to decompose raw text into its fundamental building blocks: Entities, Quantities, and Events.+You are a "High-Recall Semantic Scout." Your goal is to decompose raw text into its fundamental building blocks: Entities, Quantities, and Events.ENTITY VS. PROPERTY LOGIC:- STATIC ATTRIBUTES: Things that are unique to a specific entity and do not change often (e.g., ID numbers, telephone numbers, emails, descriptive text) must be stored as PROPERTIES of that entity.@@ -20,6 +20,43 @@ DECISION CRITERIA:1. Does it change frequently? YES -> Entity.2. Is it shared by many entities? YES -> Entity.3. Is it a unique identifier or a narrative description? YES -> Property.++Example input 1:+"John went to New York City where he knew 12 new friends. When John went there, Mary was in San Francisco doing meetings with his colleagues."++Example output 1:+[+ {{"type": "PERSON", "name": "John"}},+ {{"type": "EVENT", "name": "WENT_TO", "description": "John went to New York City"}},+ {{"type": "CITY", "name": "New York City"}},+ {{"type": "EVENT", "name": "KNEW", "description": "John knew 12 new friends in New York City"}},+ {{"type": "FRIENDS", "name": "Friends", "description": "The number of friends John knew in New York City"}},+ {{"type": "PERSON", "name": "Mary"}},+ {{"type": "EVENT", "name": "WAS_IN", "description": "Mary was in San Francisco"}},+ {{"type": "CITY", "name": "San Francisco"}},+ {{"type": "EVENT", "name": "PARTICIPATED_IN", "description": "Mary was doing meetings with his colleagues in San Francisco"}},+ {{"type": "EVENT", "name": "MEETINGS", "description": "Mary was doing meetings with his colleagues in San Francisco"}},+ {{"type": "PERSON", "name": "Colleagues", "description": "The colleagues Mary was doing meetings with in San Francisco"}},+]++Example input 2:+"The company was part of a joint venture with Apple and Google. The founder ("Mark Johnson") was the CEO of joint venture called 'Acme Inc'. The 19th of January 2026 they raised $100 million in funding."++Example output 2:+[+ {{"type": "ORGANIZATION", "name": "Acme Inc."}},+ {{"type": "EVENT", "name": "PARTICIPATED_IN", "description": "The company was part of a joint venture with Apple and Google"}},+ {{"type": "ORGANIZATION", "name": "Joint Venture", "description": "The company was part of a joint venture with Apple and Google"}},+ {{"type": "ORGANIZATION", "name": "Apple"}},+ {{"type": "ORGANIZATION", "name": "Google"}},+ {{"type": "PERSON", "name": "Mark Johnson"}},+ {{"type": "EVENT", "name": "COVERED_ROLE", "description": "Mark Johnson was the CEO of Acme Inc."}},+ {{"type": "ROLE", "name": "CEO", "description": "Mark Johnson covered the role of CEO of Acme Inc."}},+ {{"type": "EVENT", "name": "COVERED_ROLE", "description": "Mark Johnson was the founder of Acme Inc."}},+ {{"type": "ROLE", "name": "FOUNDER", "description": "Mark Johnson covered the role of founder of Acme Inc."}},+ {{"type": "EVENT", "name": "RAISED", "description": "Acme Inc. raised $100 million in funding", "properties": {{ "amount": 100000000, "happened_at": "19/01/2026" }}}},+ {{"type": "MONEY", "name": "Money"}},+]"""SCOUT_AGENT_EXTRACT_ENTITIES_PROMPT = """@@ -32,12 +69,9 @@ Text: {text}OUTPUT RULES:- Return a JSON list of objects.- Each object must include: "type", "name", and optional "properties" and "description".-- For actions (e.g., a move, a payment, an invitation), create an entity of type "EVENT".+- Nodes/Entities MUST be atomic and not composite (phrases) (eg: "Went to San Francisco" is not atomic, "Went to" + "San Francisco" is atomic)+- Dates must be in the format "DD/MM/YYYY" and be stored as "happened_at" in the properties of the event nodes.+- You must extract all the building blocks without omitting any concepts.-Example:-[- {{"type": "ACTOR_TYPE", "name": "Unique Name", "properties": {{"key": "value"}}}},- {{"type": "EVENT", "name": "Action Instance Name", "description": "Context of what happened"}},- {{"type": "UNIT", "name": "Measurement Unit (e.g. USD, People)"}}-]+Begin!"""diff --git a/src/core/agents/architect_agent.py b/src/core/agents/architect_agent.pyindex 12c2c49..1468730 100644--- a/src/core/agents/architect_agent.py+++ b/src/core/agents/architect_agent.py@@ -3,16 +3,16 @@ File: /architect_agent.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Sunday December 21st 2025 2:28:05 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Last Modified: Monday January 5th 2026 9:57:30 pm+Modified By: Christian Nonis <[email protected]>-----"""-from typing import List, Optional-import uuid+from typing import Dict, List, Literal, Optional, Tuplefrom langchain.agents import create_agentfrom langchain.tools import BaseTool-from pydantic import BaseModel, Field+from langchain_core.messages import RemoveMessage+from pydantic import BaseModelimport osfrom concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutErrorfrom tenacity import (@@ -28,92 +28,38 @@ from src.adapters.graph import GraphAdapterfrom src.adapters.llm import LLMAdapterfrom src.constants.kg import Nodefrom src.constants.prompts.architect_agent import (- ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT,+ ARCHITECT_AGENT_TOOLER_CREATE_RELATIONSHIPS_PROMPT,+ ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT,ARCHITECT_AGENT_SYSTEM_PROMPT,+ ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT,)from src.core.agents.scout_agent import ScoutEntity+from src.constants.agents import (+ _ArchitectAgentResponse,+ ArchitectAgentResponse,+ ArchitectAgentNew,+ ArchitectAgentRelationship,+)+from src.core.agents.tools.architect_agent.ArchitectAgentCheckUsedEntitiesTool import (+ ArchitectAgentCheckUsedEntitiesTool,+)+from src.core.agents.tools.architect_agent.ArchitectAgentCreateRelationshipTool import (+ ArchitectAgentCreateRelationshipTool,+)+from src.core.agents.tools.architect_agent.ArchitectAgentGetRemainingEntitiesToProcessTool import (+ ArchitectAgentGetRemainingEntitiesToProcessTool,+)+from src.core.agents.tools.architect_agent.ArchitectAgentMarkEntitiesAsUsedTool import (+ ArchitectAgentMarkEntitiesAsUsedTool,+)+from src.utils.tokens import token_detail_from_token_counts# from src.core.agents.tools.kg_agent import (# KGAgentSearchGraphTool,# )--class ArchitectAgentEntity(BaseModel):- """- Architect agent entity.- """-- uuid: str- name: str- type: str---class _ArchitectAgentNew(BaseModel):- """- Architect agent new entity.- """-- temp_id: str- type: str- name: str- reason: str- properties: Optional[dict] = Field(default_factory=dict)- description: Optional[str] = None---class ArchitectAgentNew(BaseModel):- """- Architect agent new entity.- """-- uuid: str = Field(default_factory=lambda: str(uuid.uuid4()))- type: str- name: str- reason: str- properties: Optional[dict] = Field(default_factory=dict)- description: Optional[str] = None---class _ArchitectAgentRelationship(BaseModel):- """- Architect agent relationship.- """-- tip: ArchitectAgentEntity- name: str- properties: Optional[dict] = Field(default_factory=dict)- description: Optional[str] = None- tail: ArchitectAgentEntity---class ArchitectAgentRelationship(_ArchitectAgentRelationship):- """- Architect agent relationship.- """-- uuid: str = Field(default_factory=lambda: str(uuid.uuid4()))---class _ArchitectAgentResponse(BaseModel):- """- Architect agent response containing the created relationships- between the entities.- """-- new_nodes: List[_ArchitectAgentNew]- relationships: List[_ArchitectAgentRelationship]---class ArchitectAgentResponse(BaseModel):- """- Architect agent response containing the created relationships- between the entities.- """-- new_nodes: List[ArchitectAgentNew]- relationships: List[ArchitectAgentRelationship]- input_tokens: int- output_tokens: int+HISTORY_MAX_MESSAGES = 25+HISTORY_MAX_MESSAGES_DELETE = 8class ArchitectAgent:@@ -121,6 +67,8 @@ class ArchitectAgent:Architect agent."""+ entities: Dict[str, ScoutEntity]+def __init__(self,llm_adapter: LLMAdapter,@@ -136,38 +84,79 @@ class ArchitectAgent:self.vector_store = vector_storeself.embeddings = embeddingsself.agent = None+ self.token_detail = None+ self.input_tokens = 0+ self.output_tokens = 0+ self.cached_tokens = 0+ self.reasoning_tokens = 0+ self.relationships_set = []+ self.used_entities_set = []# self.database_desc = database_desc- def _get_tools(self, brain_id: str = "default") -> List[BaseTool]:- return []- # Currently not using the knowledge graph tools- # return [- # KGAgentSearchGraphTool(- # self,- # self.kg,- # self.vector_store,- # self.embeddings,- # metadata=metadata,- # brain_id=brain_id,- # ),- # ]+ def _get_tools(+ self,+ entities: Optional[Dict[str, ScoutEntity]] = None,+ brain_id: str = "default",+ targeting: Optional[Node] = None,+ ) -> List[BaseTool]:++ return [+ ArchitectAgentCreateRelationshipTool(+ self,+ entities=entities,+ kg=self.kg,+ brain_id=brain_id,+ targeting=targeting,+ ),+ ArchitectAgentGetRemainingEntitiesToProcessTool(+ self,+ ),+ ArchitectAgentCheckUsedEntitiesTool(+ self,+ ),+ ArchitectAgentMarkEntitiesAsUsedTool(+ self,+ ),+ ]def _get_agent(self,+ type_: Literal["single", "tooler"],tools: Optional[List[BaseTool]] = None,output_schema: Optional[BaseModel] = None,extra_system_prompt: Optional[dict] = None,+ entities: Optional[Dict[str, ScoutEntity]] = None,brain_id: str = "default",+ targeting: Optional[Node] = None,):- system_prompt = ARCHITECT_AGENT_SYSTEM_PROMPT.format(- extra_system_prompt=extra_system_prompt if extra_system_prompt else ""- )+ if type_ == "single":+ system_prompt = ARCHITECT_AGENT_SYSTEM_PROMPT.format(+ extra_system_prompt=extra_system_prompt if extra_system_prompt else ""+ )+ elif type_ == "tooler":+ system_prompt = ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT.format(+ extra_system_prompt=extra_system_prompt if extra_system_prompt else ""+ )self.agent = create_agent(model=self.llm_adapter.llm.langchain_model,- tools=(tools if tools else self._get_tools(brain_id)),+ tools=(+ (+ tools+ if tools+ else self._get_tools(+ entities=entities, brain_id=brain_id, targeting=targeting+ )+ )+ if type_ == "tooler"+ else []+ ),system_prompt=system_prompt,- response_format=output_schema if output_schema else None,+ response_format=(+ (output_schema if output_schema else None)+ if type_ == "single"+ else None+ ),debug=os.environ.get("DEBUG", "false").lower() == "true",)@@ -184,51 +173,68 @@ class ArchitectAgent:Run the architect agent."""+ entities_dict = {entity.uuid: entity for entity in entities}+ self.entities = entities_dict+self._get_agent(output_schema=_ArchitectAgentResponse,brain_id=brain_id,+ targeting=targeting,+ type_="single",)self.input_tokens = 0self.output_tokens = 0def _invoke_agent(- ent: list[ScoutEntity], all_rels: list[ArchitectAgentRelationship]+ ent: list[ScoutEntity],+ all_rels: list[ArchitectAgentRelationship],+ previous_messages: list = None,):- return self.agent.invoke(- {- "messages": [- {- "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: {[rel.model_dump(mode="json") for rel in all_rels]}- """- if len(all_rels) > 0- else ""- ),- targeting=(- f"""- The information is related to the following node:- Name: {targeting.name}- UUID: {targeting.uuid}- Type: {targeting.labels}- Description: {targeting.description}- {targeting.properties}- """- if targeting- else ""- ),- ),- }- ],- },+ 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]}+ """+ if len(all_rels) > 0+ else ""+ ),+ targeting=(+ f"""+ The information is related to the following node:+ Name: {targeting.name}+ UUID: {targeting.uuid}+ Type: {targeting.labels}+ Description: {targeting.description}+ {targeting.properties}+ """+ if targeting+ else ""+ ),+ ))+ messages_list.append(user_message)++ response = self.agent.invoke({"messages": messages_list})+ return responsedef _process_response(response: dict,@@ -236,55 +242,47 @@ class ArchitectAgent:all_relationships: list,all_new_nodes: list,entities: List[ScoutEntity],+ seen_relationship_keys: set,) -> set:structured_response = response.get("structured_response", {})iteration_connected = set()if hasattr(structured_response, "relationships"):+ new_relationships = []for rel in structured_response.relationships:- if hasattr(rel, "tip") and hasattr(rel.tip, "uuid"):+ if (+ hasattr(rel, "tip")+ and hasattr(rel.tip, "uuid")+ and hasattr(rel, "tail")+ and hasattr(rel.tail, "uuid")+ ):tip_uuid = rel.tip.uuid- if any(e.uuid == tip_uuid for e in entities):- iteration_connected.add(tip_uuid)- if hasattr(rel, "tail") and hasattr(rel.tail, "uuid"):tail_uuid = rel.tail.uuid- if any(e.uuid == tail_uuid for e in entities):- iteration_connected.add(tail_uuid)+ rel_key = (tail_uuid, tip_uuid, rel.name)+ if rel_key not in seen_relationship_keys:+ seen_relationship_keys.add(rel_key)+ new_relationships.append(rel)+ if any(e.uuid == tip_uuid for e in entities):+ iteration_connected.add(tip_uuid)+ if any(e.uuid == tail_uuid for e in entities):+ iteration_connected.add(tail_uuid)if iteration_connected:connected_entity_uuids.update(iteration_connected)- all_relationships.extend(structured_response.relationships)+ all_relationships.extend(new_relationships)if hasattr(structured_response, "new_nodes"):all_new_nodes.extend(structured_response.new_nodes)- def _extract_tokens(r):- response_metadata = r.get("response_metadata", {})- token_usage = response_metadata.get("token_usage", {})- if token_usage:- return token_usage.get("prompt_tokens", 0), token_usage.get(- "completion_tokens", 0- )- usage_metadata = r.get("usage_metadata", {})- if usage_metadata:- return usage_metadata.get("input_tokens", 0), usage_metadata.get(- "output_tokens", 0- )- input_tokens = r.get("input_tokens", 0)- output_tokens = r.get("output_tokens", 0)- return input_tokens, output_tokens-- it, ot = _extract_tokens(response)- self.input_tokens += it- self.output_tokens += ot-return iteration_connectedconnected_entity_uuids = set()all_relationships = []all_new_nodes = []+ seen_relationship_keys = set()max_iterations = 3iteration = 0+ accumulated_messages = []@retry(stop=stop_after_attempt(max_retries),@@ -292,13 +290,21 @@ class ArchitectAgent:retry=retry_if_exception_type(TimeoutError),reraise=True,)- def _invoke_agent_with_retry(unconnected_entities_list: List[ScoutEntity]):+ def _invoke_agent_with_retry(+ unconnected_entities_list: List[ScoutEntity], previous_messages: list+ ):try:with ThreadPoolExecutor(max_workers=1) as executor:future = executor.submit(- _invoke_agent, unconnected_entities_list, all_relationships+ _invoke_agent,+ unconnected_entities_list,+ all_relationships,+ previous_messages,)response = future.result(timeout=timeout)+ for m in response.get("messages", []):+ if hasattr(m, "usage_metadata"):+ self.get_token_summary(m.usage_metadata)return responseexcept FutureTimeoutError:raise TimeoutError(@@ -306,15 +312,23 @@ class ArchitectAgent:"This may indicate a network issue or the LLM service is unresponsive.")- def _invoke_and_process(unconnected_entities_list: List[ScoutEntity]):+ def _invoke_and_process(+ unconnected_entities_list: List[ScoutEntity], previous_messages: list+ ):try:- response = _invoke_agent_with_retry(unconnected_entities_list)+ response = _invoke_agent_with_retry(+ unconnected_entities_list, previous_messages+ )+ messages = response.get("messages", [])+ if messages:+ accumulated_messages.extend(messages)return _process_response(response,connected_entity_uuids,all_relationships,all_new_nodes,entities,+ seen_relationship_keys,)except RetryError as e:last_attempt = e.last_attempt@@ -329,15 +343,11 @@ class ArchitectAgent:entity for entity in entities if entity.uuid not in connected_entity_uuids]- while len(unconnected_entities) > 0 and iteration <= max_iterations:- ret = _invoke_and_process(unconnected_entities)+ while len(unconnected_entities) > 0 and iteration < max_iterations:+ ret = _invoke_and_process(unconnected_entities, accumulated_messages)unconnected_entities = list(filter(lambda e: e.uuid not in ret, unconnected_entities))- print("----------------------------------------------------------")- from pprint import pprint-- pprint(unconnected_entities)iteration += 1if not all_relationships and not all_new_nodes:@@ -357,6 +367,127 @@ class ArchitectAgent:ArchitectAgentRelationship(**relationship.model_dump(mode="json"))for relationship in all_relationships],- input_tokens=self.input_tokens,- output_tokens=self.output_tokens,)++ def run_tooler(+ self,+ text: str,+ entities: List[ScoutEntity],+ targeting: Optional[Node] = None,+ brain_id: str = "default",+ timeout: int = 3600,+ max_retries: int = 3,+ ) -> List[ArchitectAgentRelationship]:+ """+ Run the architect agent tooler.+ """++ entities_dict = {entity.uuid: entity for entity in entities}+ self.entities = entities_dict++ self._get_agent(+ type_="tooler",+ brain_id=brain_id,+ entities=entities_dict,+ targeting=targeting,+ )++ accumulated_messages = []++ def _invoke_agent(previous_messages: list = None):+ 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"""+ The information is related to the following node:+ Name: {targeting.name}+ UUID: {targeting.uuid}+ Type: {targeting.labels}+ Description: {targeting.description}+ {targeting.properties}+ """+ if targeting+ else ""+ ),+ )+ )+ messages_list.append(user_message)++ return self.agent.invoke({"messages": messages_list})++ @retry(+ stop=stop_after_attempt(max_retries),+ wait=wait_exponential(multiplier=1, min=2, max=30),+ retry=retry_if_exception_type(TimeoutError),+ reraise=True,+ )+ def _invoke_agent_with_retry(previous_messages: list):+ try:+ with ThreadPoolExecutor(max_workers=1) as executor:+ future = executor.submit(_invoke_agent, previous_messages)+ response = future.result(timeout=timeout)+ 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,+ )+ return response+ except FutureTimeoutError:+ raise TimeoutError(+ f"Architect agent invoke timed out after {timeout} seconds. "+ "This may indicate a network issue or the LLM service is unresponsive."+ )++ def _invoke_and_process(previous_messages: list):+ try:+ response = _invoke_agent_with_retry(previous_messages)+ messages = response.get("messages", [])+ if messages:+ accumulated_messages.extend(messages)+ return response+ except RetryError as e:+ last_attempt = e.last_attempt+ raise TimeoutError(+ f"Architect agent invoke failed after {last_attempt.attempt_number} attempts. "+ f"Last error: {last_attempt.exception()}"+ ) from last_attempt.exception()+ except TimeoutError:+ raise++ _invoke_and_process(accumulated_messages)++ return list(self.relationships_set)++ def _update_token_counts(self, usage_metadata: dict):+ """Extract all token counts from usage metadata"""+ # Base counts+ self.input_tokens += usage_metadata.get("input_tokens", 0)+ self.output_tokens += usage_metadata.get("output_tokens", 0)++ # Input details (caching)+ input_details = usage_metadata.get("input_token_details", {})+ self.cached_tokens += input_details.get("cache_read", 0)++ # Output details (reasoning)+ output_details = usage_metadata.get("output_token_details", {})+ self.reasoning_tokens += output_details.get("reasoning", 0)diff --git a/src/core/agents/chat_agent.py b/src/core/agents/chat_agent.pynew file mode 100644index 0000000..72be0f9--- /dev/null+++ b/src/core/agents/chat_agent.py@@ -0,0 +1,9 @@+"""+File: /chat_agent.py+Created Date: Sunday January 11th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Sunday January 11th 2026 9:53:46 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/core/agents/janitor_agent.py b/src/core/agents/janitor_agent.pyindex 3193476..87d8eed 100644--- a/src/core/agents/janitor_agent.py+++ b/src/core/agents/janitor_agent.py@@ -3,15 +3,19 @@ File: /janitor_agent.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Sunday December 21st 2025 2:28:14 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Last Modified: Tuesday December 23rd 2025 9:24:20 pm+Modified By: Christian Nonis <[email protected]>-----"""+import jsonimport os-from typing import List, Literal, Optional, Tuple+from functools import reduce+from typing import List, Literal, Optional, Tuple, Unionfrom langchain.agents import create_agent+from 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 (@@ -25,8 +29,11 @@ from tenacity import (from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapterfrom src.adapters.graph import GraphAdapterfrom src.adapters.llm import LLMAdapter+from src.constants.agents import AtomicJanitorAgentInputOutputfrom src.constants.kg import Nodefrom src.constants.prompts.janitor_agent import (+ ATOMIC_JANITOR_AGENT_PROMPT,+ ATOMIC_JANITOR_AGENT_SYSTEM_PROMPT,JANITOR_AGENT_NORMALIZE_INSERTION_PROMPT,JANITOR_AGENT_SYSTEM_PROMPT,JANITOR_AGENT_GRAPH_NORMALIZATOR_PROMPT,@@ -43,6 +50,11 @@ from src.core.agents.tools.janitor_agent import (JanitorAgentExecuteGraphReadOperationTool,JanitorAgentExecuteGraphOperationTool,)+from src.utils.tokens import token_detail_from_token_counts+++HISTORY_MAX_MESSAGES = 25+HISTORY_MAX_MESSAGES_DELETE = 8class JanitorAgentInputOutput(BaseModel):@@ -54,8 +66,6 @@ class JanitorAgentInputOutput(BaseModel):relationship: Optional[ArchitectAgentRelationship] = Nonevirtual_node: Optional[ArchitectAgentNew] = Noneentity: Optional[ScoutEntity] = None- input_tokens: Optional[int] = None- output_tokens: Optional[int] = Noneclass JanitorAgent:@@ -77,6 +87,11 @@ class JanitorAgent:self.embeddings = embeddingsself.agent = Noneself.database_desc = database_desc+ self.input_tokens = 0+ self.output_tokens = 0+ self.cached_tokens = 0+ self.reasoning_tokens = 0+ self.token_detail = Nonedef _get_tools(self, brain_id: str = "default") -> List[BaseTool]:return [@@ -104,6 +119,7 @@ class JanitorAgent:self,tools: Optional[List[BaseTool]] = None,output_schema: Optional[BaseModel] = None,+ output_schemas: Optional[Union[BaseModel, Tuple[BaseModel, ...]]] = None,extra_system_prompt: Optional[dict] = None,brain_id: str = "default",type_: str = Literal["janitor", "graph-janitor"],@@ -117,18 +133,46 @@ class JanitorAgent:system_prompt = JANITOR_AGENT_GRAPH_NORMALIZATOR_SYSTEM_PROMPT.format(extra_system_prompt=extra_system_prompt if extra_system_prompt else "")+ elif type_ == "atomic-janitor":+ system_prompt = ATOMIC_JANITOR_AGENT_SYSTEM_PROMPT.format(+ extra_system_prompt=extra_system_prompt if extra_system_prompt else ""+ )else:raise ValueError(f"Invalid type: {type_}")+ response_format = None+ if output_schemas:+ if isinstance(output_schemas, tuple):+ if len(output_schemas) == 1:+ union_schema = output_schemas[0]+ elif len(output_schemas) == 2:+ union_schema = Union[output_schemas[0], output_schemas[1]]+ else:+ union_schema = reduce(lambda x, y: Union[x, y], output_schemas)+ else:+ union_schema = output_schemas+ response_format = ToolStrategy(schema=union_schema)+ elif output_schema:+ if isinstance(output_schema, tuple):+ if len(output_schema) == 1:+ union_schema = output_schema[0]+ elif len(output_schema) == 2:+ union_schema = Union[output_schema[0], output_schema[1]]+ else:+ union_schema = reduce(lambda x, y: Union[x, y], output_schema)+ response_format = ToolStrategy(schema=union_schema)+ else:+ response_format = output_schema+self.agent = create_agent(model=self.llm_adapter.llm.langchain_model,tools=(tools if tools else self._get_tools(brain_id)),system_prompt=system_prompt,- response_format=output_schema if output_schema else None,+ response_format=response_format,debug=os.environ.get("DEBUG", "false").lower() == "true",)- def run_graph_normalizator(+ def run_graph_consolidator(self,new_nodes: List[ScoutEntity | ArchitectAgentNew],text: str,@@ -137,11 +181,10 @@ class JanitorAgent:max_retries: int = 3,) -> Tuple[int, int]:"""- Runs a final janitor normalization across the kg snapshot+ Runs a final janitor consolidation across the kg snapshot"""- input_tokens = 0- output_tokens = 0+ accumulated_messages = []hops = self.kg.get_2nd_degree_hops([n.uuid for n in new_nodes],@@ -163,19 +206,32 @@ class JanitorAgent:type_="graph-janitor",)- def _invoke_agent():+ def _invoke_agent(previous_messages: list = None):+ 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(+ hops=hops,+ text=text,+ )+ )+ messages_list.append(user_message)+return self.agent.invoke(- {- "messages": [- {- "role": "user",- "content": JANITOR_AGENT_GRAPH_NORMALIZATOR_PROMPT.format(- hops=hops,- text=text,- ),- }- ],- },+ {"messages": messages_list},config={"recursion_limit": 25},)@@ -185,11 +241,20 @@ class JanitorAgent:retry=retry_if_exception_type(TimeoutError),reraise=True,)- def _invoke_agent_with_retry():+ def _invoke_agent_with_retry(previous_messages: list):try:with ThreadPoolExecutor(max_workers=1) as executor:- future = executor.submit(_invoke_agent)+ future = executor.submit(_invoke_agent, previous_messages)response = future.result(timeout=timeout)+ 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,+ )return responseexcept FutureTimeoutError:raise TimeoutError(@@ -197,8 +262,24 @@ class JanitorAgent:"This may indicate a network issue or the LLM service is unresponsive.")+ def _invoke_and_process(previous_messages: list):+ try:+ response = _invoke_agent_with_retry(previous_messages)+ messages = response.get("messages", [])+ if messages:+ accumulated_messages.extend(messages)+ return response+ except RetryError as e:+ last_attempt = e.last_attempt+ raise TimeoutError(+ f"Graph janitor normalizer agent invoke failed after {last_attempt.attempt_number} attempts. "+ f"Last error: {last_attempt.exception()}"+ ) from last_attempt.exception()+ except TimeoutError:+ raise+try:- response = _invoke_agent_with_retry()+ response = _invoke_and_process(accumulated_messages)except RetryError as e:last_attempt = e.last_attemptraise TimeoutError(@@ -207,25 +288,7 @@ class JanitorAgent:) from last_attempt.exception()except TimeoutError:raise-- def _extract_tokens(r):- response_metadata = r.get("response_metadata", {})- token_usage = response_metadata.get("token_usage", {})- if token_usage:- return token_usage.get("prompt_tokens", 0), token_usage.get(- "completion_tokens", 0- )- usage_metadata = r.get("usage_metadata", {})- if usage_metadata:- return usage_metadata.get("input_tokens", 0), usage_metadata.get(- "output_tokens", 0- )- input_tokens = r.get("input_tokens", 0)- output_tokens = r.get("output_tokens", 0)- return input_tokens, output_tokens-- input_tokens, output_tokens = _extract_tokens(response)- return input_tokens, output_tokens+ return responsedef run(self,@@ -244,28 +307,43 @@ class JanitorAgent:output_schema=JanitorAgentInputOutput, brain_id=brain_id, type_="janitor")- def _invoke_agent():+ accumulated_messages = []++ def _invoke_agent(previous_messages: list = None):+ 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"""+ The information is related to:+ "{targeting.name}": {targeting.description}+ {targeting.properties}+ """+ if targeting+ else ""+ ),+ )+ )+ messages_list.append(user_message)+return self.agent.invoke(- {- "messages": [- {- "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 ""- ),- ),- }- ],- },+ {"messages": messages_list},config={"recursion_limit": 25},)@@ -275,11 +353,20 @@ class JanitorAgent:retry=retry_if_exception_type(TimeoutError),reraise=True,)- def _invoke_agent_with_retry():+ def _invoke_agent_with_retry(previous_messages: list):try:with ThreadPoolExecutor(max_workers=1) as executor:- future = executor.submit(_invoke_agent)+ future = executor.submit(_invoke_agent, previous_messages)response = future.result(timeout=timeout)+ 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,+ )return responseexcept FutureTimeoutError:raise TimeoutError(@@ -287,8 +374,24 @@ class JanitorAgent:"This may indicate a network issue or the LLM service is unresponsive.")+ def _invoke_and_process(previous_messages: list):+ try:+ response = _invoke_agent_with_retry(previous_messages)+ messages = response.get("messages", [])+ if messages:+ accumulated_messages.extend(messages)+ return response+ except RetryError as e:+ last_attempt = e.last_attempt+ raise TimeoutError(+ f"Janitor agent invoke failed after {last_attempt.attempt_number} attempts. "+ f"Last error: {last_attempt.exception()}"+ ) from last_attempt.exception()+ except TimeoutError:+ raise+try:- response = _invoke_agent_with_retry()+ response = _invoke_and_process(accumulated_messages)except RetryError as e:last_attempt = e.last_attemptraise TimeoutError(@@ -297,38 +400,161 @@ class JanitorAgent:) from last_attempt.exception()except TimeoutError:raise-- def _extract_tokens(r):- response_metadata = r.get("response_metadata", {})- token_usage = response_metadata.get("token_usage", {})- if token_usage:- return token_usage.get("prompt_tokens", 0), token_usage.get(- "completion_tokens", 0- )- usage_metadata = r.get("usage_metadata", {})- if usage_metadata:- return usage_metadata.get("input_tokens", 0), usage_metadata.get(- "output_tokens", 0- )- input_tokens = r.get("input_tokens", 0)- output_tokens = r.get("output_tokens", 0)- return input_tokens, output_tokens-- input_tokens, output_tokens = _extract_tokens(response)structured_response = response.get("structured_response")if structured_response:return JanitorAgentInputOutput(relationship=structured_response.relationship,virtual_node=structured_response.virtual_node,entity=structured_response.entity,- input_tokens=input_tokens,- output_tokens=output_tokens,)else:return JanitorAgentInputOutput(relationship=None,virtual_node=None,entity=None,- input_tokens=input_tokens,- output_tokens=output_tokens,)++ def run_atomic_janitor(+ self,+ input_relationships: List[ArchitectAgentRelationship],+ text: str,+ targeting: Optional[Node] = None,+ brain_id: str = "default",+ timeout: int = 90,+ max_retries: int = 3,+ ) -> AtomicJanitorAgentInputOutput | str:+ """+ Run the atomic janitor agent.+ Can return istructions on how to correct the wrong relationships or 'OK' if the relationships are correct.+ """++ self._get_agent(+ output_schemas=AtomicJanitorAgentInputOutput,+ brain_id=brain_id,+ type_="atomic-janitor",+ )++ accumulated_messages = []++ def _invoke_agent(previous_messages: list = None):+ 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"""+ The information is related to:+ "{targeting.name}": {targeting.description}+ {targeting.properties}+ """+ if targeting+ else ""+ ),+ )+ )+ messages_list.append(user_message)++ return self.agent.invoke(+ {"messages": messages_list},+ config={"recursion_limit": 25},+ )++ @retry(+ stop=stop_after_attempt(max_retries),+ wait=wait_exponential(multiplier=1, min=2, max=30),+ retry=retry_if_exception_type(TimeoutError),+ reraise=True,+ )+ def _invoke_agent_with_retry(previous_messages: list):+ try:+ with ThreadPoolExecutor(max_workers=1) as executor:+ future = executor.submit(_invoke_agent, previous_messages)+ response = future.result(timeout=timeout)+ 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,+ )+ return response+ except FutureTimeoutError:+ raise TimeoutError(+ f"Atomic janitor agent invoke timed out after {timeout} seconds. "+ "This may indicate a network issue or the LLM service is unresponsive."+ )+ except RetryError as e:+ last_attempt = e.last_attempt+ raise TimeoutError(+ f"Atomic janitor agent invoke failed after {last_attempt.attempt_number} attempts. "+ f"Last error: {last_attempt.exception()}"+ ) from last_attempt.exception()+ except:+ raise++ def _invoke_and_process(previous_messages: list):+ try:+ response = _invoke_agent_with_retry(previous_messages)+ messages = response.get("messages", [])+ if messages:+ accumulated_messages.extend(messages)+ return response+ except RetryError as e:+ last_attempt = e.last_attempt+ raise TimeoutError(+ f"Atomic janitor agent invoke failed after {last_attempt.attempt_number} attempts. "+ f"Last error: {last_attempt.exception()}"+ ) from last_attempt.exception()+ except TimeoutError:+ raise++ try:+ response = _invoke_and_process(accumulated_messages)+ except RetryError as e:+ last_attempt = e.last_attempt+ raise TimeoutError(+ f"Atomic janitor agent invoke failed after {last_attempt.attempt_number} attempts. "+ f"Last error: {last_attempt.exception()}"+ ) from last_attempt.exception()+ except TimeoutError:+ raise++ structured_response = response.get("structured_response")++ if structured_response and structured_response.status == "OK":+ return "OK"+ else:+ return structured_response++ def _update_token_counts(self, usage_metadata: dict):+ """Extract all token counts from usage metadata"""+ # Base counts+ self.input_tokens += usage_metadata.get("input_tokens", 0)+ self.output_tokens += usage_metadata.get("output_tokens", 0)++ # Input details (caching)+ input_details = usage_metadata.get("input_token_details", {})+ self.cached_tokens += input_details.get("cache_read", 0)++ # Output details (reasoning)+ output_details = usage_metadata.get("output_token_details", {})+ self.reasoning_tokens += output_details.get("reasoning", 0)diff --git a/src/core/agents/scout_agent.py b/src/core/agents/scout_agent.pyindex e8388d4..813f816 100644--- a/src/core/agents/scout_agent.py+++ b/src/core/agents/scout_agent.py@@ -3,8 +3,8 @@ File: /scout_agent.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Sunday December 21st 2025 2:27:56 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Last Modified: Monday January 5th 2026 9:57:30 pm+Modified By: Christian Nonis <[email protected]>-----"""@@ -31,6 +31,7 @@ from src.constants.prompts.scout_agent import (SCOUT_AGENT_EXTRACT_ENTITIES_PROMPT,SCOUT_AGENT_SYSTEM_PROMPT,)+from src.utils.tokens import token_detail_from_token_countsclass _ScoutEntity(BaseModel):@@ -90,6 +91,11 @@ class ScoutAgent:self.vector_store = vector_storeself.embeddings = embeddingsself.agent = None+ self.token_detail = None+ self.input_tokens = 0+ self.output_tokens = 0+ self.cached_tokens = 0+ self.reasoning_tokens = 0def _get_tools(self, brain_id: str = "default") -> List[BaseTool]:return []@@ -164,6 +170,15 @@ class ScoutAgent:with ThreadPoolExecutor(max_workers=1) as executor:future = executor.submit(_invoke_agent)response = future.result(timeout=timeout)+ 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,+ )return responseexcept FutureTimeoutError:raise TimeoutError(@@ -182,29 +197,25 @@ class ScoutAgent:except TimeoutError:raise- def _extract_tokens(r):- response_metadata = r.get("response_metadata", {})- token_usage = response_metadata.get("token_usage", {})- if token_usage:- return token_usage.get("prompt_tokens", 0), token_usage.get(- "completion_tokens", 0- )- usage_metadata = r.get("usage_metadata", {})- if usage_metadata:- return usage_metadata.get("input_tokens", 0), usage_metadata.get(- "output_tokens", 0- )- input_tokens = r.get("input_tokens", 0)- output_tokens = r.get("output_tokens", 0)- return input_tokens, output_tokens-- input_tokens, output_tokens = _extract_tokens(response)-return ScoutAgentResponse(entities=[ScoutEntity(**entity.model_dump(mode="json"))for entity in response.get("structured_response", []).entities],- input_tokens=input_tokens,- output_tokens=output_tokens,+ input_tokens=self.input_tokens,+ output_tokens=self.output_tokens,)++ def _update_token_counts(self, usage_metadata: dict):+ """Extract all token counts from usage metadata"""+ # Base counts+ self.input_tokens += usage_metadata.get("input_tokens", 0)+ self.output_tokens += usage_metadata.get("output_tokens", 0)++ # Input details (caching)+ input_details = usage_metadata.get("input_token_details", {})+ self.cached_tokens += input_details.get("cache_read", 0)++ # Output details (reasoning)+ output_details = usage_metadata.get("output_token_details", {})+ 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.pynew file mode 100644index 0000000..f221690--- /dev/null+++ b/src/core/agents/tools/architect_agent/ArchitectAgentCheckUsedEntitiesTool.py@@ -0,0 +1,38 @@+"""+File: /ArchitectAgentCheckUsedEntitiesTool.py+Project: architect_agent+Created Date: Saturday January 17th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Saturday January 17th 2026 12:37:32 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++import json+from langchain.tools import BaseTool+++class ArchitectAgentCheckUsedEntitiesTool(BaseTool):+ name: str = "architect_agent_check_used_entities"+ architect_agent: object++ def __init__(+ self,+ architect_agent: object,+ ):+ description: str = (+ "Tool for checking used entities. "+ "Returns a list of entities that have been used."+ )+ super().__init__(+ architect_agent=architect_agent,+ description=description,+ )++ def _run(self, *args, **kwargs) -> str:+ entities_list = [+ entity.model_dump() if hasattr(entity, "model_dump") else entity.dict()+ for entity in self.architect_agent.used_entities_set+ ]+ return json.dumps(entities_list)diff --git a/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py b/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.pynew file mode 100644index 0000000..5e0110c--- /dev/null+++ b/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py@@ -0,0 +1,246 @@+"""+File: /ArchitectAgentCreateRelationshipTool.py+Created Date: Wednesday January 14th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Wednesday January 14th 2026 10:22:53 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++from dataclasses import dataclass+import json+from typing import Dict, List, Optional+import uuid+from langchain.tools import BaseTool++from src.adapters.graph import GraphAdapter+from src.constants.agents import (+ ArchitectAgentRelationship,+ ArchitectAgentEntity,+ AtomicJanitorAgentInputOutput,+)+from src.constants.kg import Node+from src.core.agents.scout_agent import ScoutEntity+from src.services.input.agents import (+ embeddings_adapter,+ graph_adapter,+ llm_small_adapter,+ vector_store_adapter,+)+from src.lib.neo4j.client import _neo4j_client+from src.utils.tokens import merge_token_details, token_detail_from_token_counts+++class ArchitectAgentCreateRelationshipTool(BaseTool):+ name: str = "architect_agent_create_relationship"+ args_schema: dict = {+ "type": "object",+ "properties": {+ "relationships": {+ "type": "array",+ "description": "A list of relationships to create",+ "items": {+ "type": "object",+ "properties": {+ "subject": {+ "type": "string",+ "description": "The uuid of the subject",+ },+ "predicate": {+ "type": "string",+ "description": "The name of the relationship",+ },+ "object": {+ "type": "string",+ "description": "The uuid of the object",+ },+ "description": {+ "type": "string",+ "description": "The description of the relationship",+ },+ },+ "required": ["subject", "predicate", "object", "description"],+ },+ },+ },+ "required": ["relationships"],+ }+ architect_agent: object+ kg: GraphAdapter+ entities: Dict[str, ScoutEntity]+ brain_id: str = "default"+ targeting: Optional[Node] = None++ def __init__(+ self,+ architect_agent: object,+ entities: Optional[Dict[str, ScoutEntity]],+ kg: GraphAdapter,+ brain_id: str = "default",+ targeting: Optional[Node] = None,+ ):+ description: str = (+ "Tool for creating a set of relationships between entities. "+ "Use this tool to create a set of relationships between entities that together compose a single phrase. "+ "Input must be a list of relationships with a subject entity uuid, an object entity uuid, a predicate name between them and a description of the relationship."+ "The list of relationships must only be for a single phrase."+ "Returns a summary of the created relationships to review them before creating them."+ )+ entities_dict = entities if entities is not None else {}+ super().__init__(+ architect_agent=architect_agent,+ description=description,+ kg=kg,+ entities=entities_dict,+ brain_id=brain_id,+ targeting=targeting,+ )++ @dataclass+ class _ArchitectAgentInputRelationship:+ subject: str+ predicate: str+ object: str+ description: str++ def _run(self, *args, **kwargs) -> str:+ rel_key = str(uuid.uuid4())++ input_rels = []+ output_rels: List[ArchitectAgentRelationship] = []++ if args and isinstance(args[0], dict) and "relationships" in args[0]:+ relationships = args[0]["relationships"]+ elif kwargs and "relationships" in kwargs:+ relationships = kwargs["relationships"]+ elif args and isinstance(args[0], list):+ relationships = args[0]+ else:+ return "Error: relationships parameter is required"++ for rel in relationships:+ subject = rel.get("subject")+ predicate = rel.get("predicate")+ object = rel.get("object")+ description = rel.get("description")++ if subject is None or object is None:+ return f"Subject or object is None: subject={subject}, object={object}"++ if isinstance(subject, str):+ subject = subject.strip()+ if isinstance(object, str):+ object = object.strip()++ if subject not in self.entities:+ return f"Subject not found in entities: {subject}. Available entities: {list(self.entities.keys())}"++ if object not in self.entities:+ return f"Object not found in entities: {object}. Available entities: {list(self.entities.keys())}"++ input_rels.append(+ self._ArchitectAgentInputRelationship(+ subject, predicate, object, description+ )+ )++ subj_entity = self.entities.get(subject)+ obj_entity = self.entities.get(object)++ subj = ArchitectAgentEntity(+ uuid=subj_entity.uuid,+ name=subj_entity.name,+ type=subj_entity.type,+ flow_key=rel_key,+ **(+ {"happened_at": subj_entity.properties.get("happened_at")}+ if subj_entity.properties.get("happened_at")+ else {}+ ),+ )+ obj = ArchitectAgentEntity(+ uuid=obj_entity.uuid,+ name=obj_entity.name,+ type=obj_entity.type,+ flow_key=rel_key,+ **(+ {"happened_at": obj_entity.properties.get("happened_at")}+ if obj_entity.properties.get("happened_at")+ else {}+ ),+ )++ output_rels.append(+ ArchitectAgentRelationship(+ flow_key=rel_key,+ tip=obj,+ tail=subj,+ name=predicate,+ description=description,+ )+ )++ natural_lang = ", ".join(+ [+ f"""({rel.tail.name})-[:{rel.name} {{description: "{rel.description}"}}]->({rel.tip.name})"""+ for rel in output_rels+ ]+ )++ 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_response = janitor_agent.run_atomic_janitor(+ input_relationships=output_rels,+ text=natural_lang,+ targeting=self.targeting,+ brain_id=self.brain_id,+ timeout=300,+ max_retries=3,+ )++ 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,+ )+ self.architect_agent.token_detail = merge_token_details(+ [self.architect_agent.token_detail, janitor_token_detail]+ )++ if fixed_relationships := getattr(janitor_response, "fixed_relationships", []):+ output_rels.extend(+ [+ ArchitectAgentRelationship(+ flow_key=rel_key,+ tip=rel.tip,+ name=rel.name,+ description=rel.description,+ tail=rel.tail,+ )+ for rel in fixed_relationships+ ]+ )++ self.architect_agent.relationships_set.extend(output_rels)+ from pprint import pprint++ pprint(self.architect_agent.relationships_set)+ if len(getattr(janitor_response, "wrong_relationships", [])) > 0:+ return janitor_response++ # for entity_uuid in used_entity_uuids:+ # if entity_uuid in self.architect_agent.entities:+ # del self.architect_agent.entities[entity_uuid]++ # return natural_lang+ return json.dumps({"status": "success", "insert_count": len(output_rels)})diff --git a/src/core/agents/tools/architect_agent/ArchitectAgentGetRemainingEntitiesToProcessTool.py b/src/core/agents/tools/architect_agent/ArchitectAgentGetRemainingEntitiesToProcessTool.pynew file mode 100644index 0000000..ab550c4--- /dev/null+++ b/src/core/agents/tools/architect_agent/ArchitectAgentGetRemainingEntitiesToProcessTool.py@@ -0,0 +1,41 @@+"""+File: /ArchitectAgentGetRemainingEntitiesToProcessTool.py+Project: architect_agent+Created Date: Friday January 16th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Friday January 16th 2026 10:55:16 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++import json+from langchain.tools import BaseTool+++class ArchitectAgentGetRemainingEntitiesToProcessTool(BaseTool):+ name: str = "architect_agent_get_remaining_entities_to_process"+ architect_agent: object++ def __init__(+ self,+ architect_agent: object,+ ):+ description: str = (+ "Tool for getting the remaining entities to process. "+ "Use this tool to get the remaining entities to process. "+ "Returns a list of entities that are not yet processed"+ "or the initial list of entities for the first call."+ )+ super().__init__(+ architect_agent=architect_agent,+ description=description,+ )++ def _run(self, *args, **kwargs) -> str:+ return json.dumps(+ [+ entity.model_dump(mode="json")+ for entity in self.architect_agent.entities.values()+ ]+ )diff --git a/src/core/agents/tools/architect_agent/ArchitectAgentMarkEntitiesAsUsedTool.py b/src/core/agents/tools/architect_agent/ArchitectAgentMarkEntitiesAsUsedTool.pynew file mode 100644index 0000000..c86a4f7--- /dev/null+++ b/src/core/agents/tools/architect_agent/ArchitectAgentMarkEntitiesAsUsedTool.py@@ -0,0 +1,79 @@+"""+File: /ArchitectAgentMarkEntitiesAsUsedTool.py+Project: architect_agent+Created Date: Saturday January 17th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Saturday January 17th 2026 12:37:22 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++import json+from langchain.tools import BaseTool+++class ArchitectAgentMarkEntitiesAsUsedTool(BaseTool):+ name: str = "architect_agent_mark_entities_as_used"+ architect_agent: object+ args_schema: dict = {+ "type": "object",+ "properties": {+ "entity_uuids": {+ "type": "array",+ "description": "A list of entity uuids to mark as used",+ "items": {+ "type": "string",+ "description": "The uuid of the entity to mark as used.",+ },+ },+ },+ "required": ["entity_uuids"],+ }++ def __init__(+ self,+ architect_agent: object,+ ):+ description: str = (+ "Tool for marking entities as used. "+ "Use this tool to mark entities as used. "+ "Input must be a list of entity uuids."+ )+ super().__init__(+ architect_agent=architect_agent,+ description=description,+ )++ def _run(self, *args, **kwargs) -> str:+ entities_to_mark = []++ if args and isinstance(args[0], dict) and "entity_uuids" in args[0]:+ entities_to_mark = args[0]["entity_uuids"]+ elif kwargs and "entity_uuids" in kwargs:+ entities_to_mark = kwargs["entity_uuids"]+ elif args and len(args) > 0 and isinstance(args[0], list):+ entities_to_mark = args[0]+ elif "entities" in kwargs:+ entities_to_mark = kwargs["entities"]+ elif "uuids" in kwargs:+ entities_to_mark = kwargs["uuids"]+ else:+ if len(kwargs) == 1:+ entities_to_mark = list(kwargs.values())[0]+ else:+ entities_to_mark = []++ if isinstance(entities_to_mark, str):+ entities_to_mark = [entities_to_mark]++ if entities_to_mark is None:+ entities_to_mark = []++ for entity_uuid in entities_to_mark:+ 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)++ return "OK"diff --git a/src/core/agents/tools/architect_agent/__init__.py b/src/core/agents/tools/architect_agent/__init__.pynew file mode 100644index 0000000..c178467--- /dev/null+++ b/src/core/agents/tools/architect_agent/__init__.py@@ -0,0 +1,9 @@+"""+File: /__init__.py+Created Date: Wednesday January 14th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Wednesday January 14th 2026 10:22:02 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/core/agents/tools/chat_agent/__init__.py b/src/core/agents/tools/chat_agent/__init__.pynew file mode 100644index 0000000..1c8d205--- /dev/null+++ b/src/core/agents/tools/chat_agent/__init__.py@@ -0,0 +1,9 @@+"""+File: /__init__.py+Created Date: Monday January 12th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Monday January 12th 2026 9:33:39 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/core/agents/tools/janitor_agent/JanitorAgentSearchEntitiesTool.py b/src/core/agents/tools/janitor_agent/JanitorAgentSearchEntitiesTool.pyindex 0446978..097544a 100644--- a/src/core/agents/tools/janitor_agent/JanitorAgentSearchEntitiesTool.py+++ b/src/core/agents/tools/janitor_agent/JanitorAgentSearchEntitiesTool.py@@ -4,12 +4,12 @@ Created Date: Tuesday December 23rd 2025Author: Christian Nonis <[email protected]>-----Last Modified: Tuesday December 23rd 2025 11:21:54 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Modified By: Christian Nonis <[email protected]>-----"""import json-from typing import List+from typing import Dict, List, Unionfrom langchain.tools import BaseToolfrom src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter@@ -32,12 +32,16 @@ class JanitorAgentSearchEntitiesTool(BaseTool):args_schema: dict = {"type": "object","properties": {- "query": {- "type": "string",- "description": "The plain text query to search for entities in the knowledge graph within their names.",+ "queries": {+ "type": "array",+ "items": {+ "type": "string",+ "description": "The plain text query to search for entities in the knowledge graph within their names.",+ },+ "description": "The list of things to search for in the knowledge graph.",},},- "required": ["query"],+ "required": ["queries"],}def __init__(@@ -49,9 +53,11 @@ class JanitorAgentSearchEntitiesTool(BaseTool):brain_id: str = "default",):description: str = (- "Tool for searching the entities of the knowledge graph by plain text name. "- "This tool will return the entities that were found in the knowledge graph."- "Example input: { 'query': 'John Doe' }"+ "Tool to search for entities in the knowledge graph by plain text names. "+ "Call this tool once to search for a list of entities with different names, "+ "don't recall the tool with different queries for same entities, be exaustive on the first call."+ "This tool will return the a map of entities that were found in the knowledge graph where the key is the query and the value is the list of entities that were found."+ 'Example input: { "queries": ["John Doe", "John", "John D.", "Mary", "John\'s Wife"] }')super().__init__(janitor_agent=janitor_agent,@@ -67,43 +73,56 @@ class JanitorAgentSearchEntitiesTool(BaseTool):if len(args) > 0:_query = args[0]else:- _query = kwargs.get("query", "")+ _queries = kwargs.get("queries", [])- if len(_query) == 0:- return "No query provided in the arguments or kwargs"+ if len(_queries) == 0:+ return "No queries provided in the arguments or kwargs"- kg_results = self.kg.search_entities(brain_id=self.brain_id, query_text=_query)+ found_entities: Dict[str, Union[str, List[Node]]] = {}- found_entities: List[Node] = []+ def _clean_query(query: str) -> str:+ chars_to_remove = "'.\"()[]{}\\|*/+=<>,!?:;"+ chars_to_underscore = " -"+ translation_table = str.maketrans(+ chars_to_underscore, "_" * len(chars_to_underscore), chars_to_remove+ )+ return query.strip().lower().translate(translation_table).replace(" ", "_")- for kg_result in kg_results.results:- found_entities.append(kg_result)-- try:- query_vector = self.embeddings.embed_text(_query)- if query_vector.embeddings and len(query_vector.embeddings) > 0:- v_results = self.vector_store.search_vectors(- query_vector.embeddings,- store="nodes",- brain_id=self.brain_id,- )- if len(v_results) > 0:- found_entities.extend(- self.kg.get_nodes_by_uuid(- [- v_result.metadata.get("uuid")- for v_result in v_results- if v_result.metadata.get("uuid") is not None- ],- brain_id=self.brain_id,- )+ for _query in _queries:+ founds = []+ kg_results = self.kg.search_entities(+ brain_id=self.brain_id, query_text=_query+ )+ founds.extend(kg_results.results)+ try:+ query_vector = self.embeddings.embed_text(_query)+ if query_vector.embeddings and len(query_vector.embeddings) > 0:+ v_results = self.vector_store.search_vectors(+ query_vector.embeddings,+ store="nodes",+ brain_id=self.brain_id,)- except Exception as e:- print(f"Vector search failed, using KG results only: {e}")+ if len(v_results) > 0:+ founds.extend(+ self.kg.get_nodes_by_uuid(+ [+ v_result.metadata.get("uuid")+ for v_result in v_results+ if v_result.metadata.get("uuid") is not None+ ],+ brain_id=self.brain_id,+ )+ )+ except Exception as e:+ print(f"Vector search failed, using KG results only: {e}")- if len(found_entities) == 0:- return "Knowledge graph does not contain any entities that match the query"+ if len(found_entities) == 0:+ found_entities[_clean_query(_query)] = (+ "Knowledge graph does not contain any entities that match the query"+ )+ else:+ found_entities[_clean_query(_query)] = [+ f.model_dump(mode="json") for f in founds+ ]- return json.dumps(- [entity.model_dump(mode="json") for entity in found_entities], indent=4- )+ return json.dumps(found_entities, indent=4)diff --git a/src/core/layers/outputs/__init__.py b/src/core/layers/outputs/__init__.pynew file mode 100644index 0000000..245a386--- /dev/null+++ b/src/core/layers/outputs/__init__.py@@ -0,0 +1,9 @@+"""+File: /__init__.py+Created Date: Tuesday January 13th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Tuesday January 13th 2026 8:48:57 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/core/plugins/__init__.py b/src/core/plugins/__init__.pynew file mode 100644index 0000000..91ef518--- /dev/null+++ b/src/core/plugins/__init__.py@@ -0,0 +1,9 @@+"""+File: /__init__.py+Created Date: Monday January 12th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Monday January 12th 2026 9:22:09 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/core/saving/auto_kg.py b/src/core/saving/auto_kg.pyindex 844af19..948cf04 100644--- a/src/core/saving/auto_kg.py+++ b/src/core/saving/auto_kg.py@@ -3,28 +3,34 @@ File: /auto_kg.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Sunday December 21st 2025 2:29:01 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Last Modified: Tuesday December 23rd 2025 9:24:20 pm+Modified By: Christian Nonis <[email protected]>-----"""-from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError-from typing import Optional+from concurrent.futures import (+ Future,+ ThreadPoolExecutor,+ TimeoutError as FutureTimeoutError,+)+from typing import List, Optional, Tuplefrom src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapterfrom src.adapters.graph import GraphAdapter+from src.config import configfrom src.constants.kg import Node, Predicate-from src.core.agents.janitor_agent import JanitorAgentInputOutput-from src.core.agents.scout_agent import ScoutEntity-from src.core.agents.architect_agent import ArchitectAgentRelationship+from src.core.agents.janitor_agent import JanitorAgent+from src.core.agents.scout_agent import ScoutAgent, ScoutEntity+from src.core.agents.architect_agent import ArchitectAgent, ArchitectAgentRelationshipfrom src.services.input.agents import (+ cache_adapter,embeddings_adapter,graph_adapter,- janitor_agent,- scout_agent,- architect_agent,+ llm_small_adapter,vector_store_adapter,)+from src.lib.neo4j.client import _neo4j_client+from src.utils.tokens import merge_token_details, token_detail_from_token_countsclass IngestionManager:@@ -38,6 +44,7 @@ class IngestionManager:self.vector_store = vector_store_adapterself.kg = graph_adapterself.resolved_cache = {}+ self.metadata = {}def process_node_vectors(self, node_data: ScoutEntity, brain_id):if node_data.name in self.resolved_cache:@@ -64,6 +71,10 @@ class IngestionManager:return node_data.uuiddef process_rel_vectors(self, rel_data: ArchitectAgentRelationship, brain_id):+ if not isinstance(rel_data, ArchitectAgentRelationship):+ raise TypeError(+ f"Expected ArchitectAgentRelationship, got {type(rel_data)}"+ )if hasattr(rel_data, "description") and rel_data.description:v_rel = self.embeddings.embed_text(rel_data.description)v_rel.metadata = {@@ -82,7 +93,9 @@ class IngestionManager:}else:print("[ ! ]Relationship not embedded:", rel_data)- return rel_data.uuid+ return rel_data.uuid, (+ rel_data.properties.get("v_id") if rel_data.properties else None+ )def enrich_kg_from_input(@@ -92,127 +105,56 @@ def enrich_kg_from_input(Enrich the knowledge graph from the input."""- input_tokens = 0- output_tokens = 0+ scout_agent = ScoutAgent(+ llm_small_adapter,+ cache_adapter,+ kg=graph_adapter,+ vector_store=vector_store_adapter,+ embeddings=embeddings_adapter,+ )+ architect_agent = ArchitectAgent(+ llm_small_adapter,+ cache_adapter,+ kg=graph_adapter,+ vector_store=vector_store_adapter,+ embeddings=embeddings_adapter,+ )++ token_details = []manager = IngestionManager(embeddings_adapter, vector_store_adapter, graph_adapter)entities = scout_agent.run(input, targeting=targeting, brain_id=brain_id)- input_tokens += entities.input_tokens- output_tokens += entities.output_tokens- # logtable(- # [entity.model_dump(mode="json") for entity in entities.entities],- # title="Entities",- # )+ token_details.append(+ token_detail_from_token_counts(+ scout_agent.input_tokens,+ scout_agent.output_tokens,+ scout_agent.cached_tokens,+ scout_agent.reasoning_tokens,+ )+ )- architect_response = architect_agent.run(+ architect_response = architect_agent.run_tooler(input, entities.entities, targeting=targeting, brain_id=brain_id)- input_tokens += architect_response.input_tokens- output_tokens += architect_response.output_tokens- # logtable(- # [new_node.model_dump(mode="json") for new_node in architect_response.new_nodes],- # title="New Nodes",- # )- # logtable(- # [- # relationship.model_dump(mode="json")- # for relationship in architect_response.relationships- # ],- # title="Relationships",- # )-- normalized_entities = []- normalized_virtual_nodes = []- normalized_relationships = []-- with ThreadPoolExecutor(max_workers=10) as executor:- entity_futures = [- executor.submit(- janitor_agent.run,- JanitorAgentInputOutput(entity=entity),- text=input,- targeting=targeting,- brain_id=brain_id,- )- for entity in entities.entities- ]-- virtual_node_futures = [- executor.submit(- janitor_agent.run,- JanitorAgentInputOutput(virtual_node=new_node),- text=input,- targeting=targeting,- brain_id=brain_id,- )- for new_node in architect_response.new_nodes- ]-- all_futures = list(entity_futures) + list(virtual_node_futures)-- for future in all_futures:- try:- normalized_result = future.result(timeout=180)- input_tokens += normalized_result.input_tokens or 0- output_tokens += normalized_result.output_tokens or 0- if normalized_result.entity:- normalized_entities.append(normalized_result.entity)- elif normalized_result.virtual_node:- normalized_virtual_nodes.append(normalized_result.virtual_node)- else:- print("Entity/Virtual node not normalized:", normalized_result)- except FutureTimeoutError:- print(- "[!] Janitor agent entity/virtual_node future timed out, skipping"- )- continue- except Exception as e:- print(f"[!] Janitor agent entity/virtual_node future failed: {e}")- continue-- relationship_futures = [- executor.submit(- janitor_agent.run,- JanitorAgentInputOutput(relationship=relationship),- text=input,- targeting=targeting,- brain_id=brain_id,- )- for relationship in architect_response.relationships- ]-- for future in relationship_futures:- try:- normalized_result = future.result(timeout=180)- input_tokens += normalized_result.input_tokens or 0- output_tokens += normalized_result.output_tokens or 0- if normalized_result.relationship:- normalized_relationships.append(normalized_result.relationship)- else:- print("Relationship not normalized:", normalized_result)- except FutureTimeoutError:- print("[!] Janitor agent relationship future timed out, skipping")- continue- except Exception as e:- print(f"[!] Janitor agent relationship future failed: {e}")- continue+ token_details.append(+ token_detail_from_token_counts(+ architect_agent.input_tokens,+ architect_agent.output_tokens,+ architect_agent.cached_tokens,+ architect_agent.reasoning_tokens,+ )+ )graph_nodes = []with ThreadPoolExecutor(max_workers=10) as io_executor:node_embedding_futures = []- for entity in normalized_entities:+ for entity in entities.entities:future = io_executor.submit(manager.process_node_vectors, entity, brain_id)node_embedding_futures.append((future, entity))- for virtual_node in normalized_virtual_nodes:- future = io_executor.submit(- manager.process_node_vectors, virtual_node, brain_id- )- node_embedding_futures.append((future, virtual_node))-for future, node_data in node_embedding_futures:try:future.result(timeout=180)@@ -236,29 +178,88 @@ def enrich_kg_from_input(graph_adapter.add_nodes(graph_nodes, brain_id=brain_id)- for relationship in normalized_relationships:- io_executor.submit(manager.process_rel_vectors, relationship, brain_id)- graph_adapter.add_relationship(- Node(- uuid=relationship.tail.uuid,- labels=[relationship.tail.type],- name=relationship.tail.name,- ),- Predicate(- uuid=relationship.uuid,- name=relationship.name,- description=relationship.description,- properties=relationship.properties,- ),- Node(- uuid=relationship.tip.uuid,- labels=[relationship.tip.type],- name=relationship.tip.name,- ),- brain_id=brain_id,+ relationships_list = architect_response+ flattened_relationships = []+ for item in relationships_list:+ if isinstance(item, list):+ flattened_relationships.extend(item)+ else:+ flattened_relationships.append(item)++ rel_embedding_futures: List[Tuple[Future, ArchitectAgentRelationship]] = []+ for relationship in flattened_relationships:+ if not isinstance(relationship, ArchitectAgentRelationship):+ print(f"[!] Skipping invalid relationship type: {type(relationship)}")+ continue+ future = io_executor.submit(+ manager.process_rel_vectors, relationship, brain_id)+ rel_embedding_futures.append((future, relationship))++ for future, relationship in rel_embedding_futures:+ try:+ v_id, v_rel_id = future.result(timeout=180)+ graph_adapter.add_relationship(+ Node(+ uuid=relationship.tail.uuid,+ flow_key=relationship.tail.flow_key,+ labels=[relationship.tail.type],+ name=relationship.tail.name,+ **(+ {"happened_at": relationship.tail.happened_at}+ if relationship.tail.happened_at+ else {}+ ),+ ),+ Predicate(+ uuid=relationship.uuid,+ flow_key=relationship.flow_key,+ name=relationship.name,+ description=relationship.description,+ properties={+ **(relationship.properties or {}),+ "v_id": v_rel_id,+ },+ ),+ Node(+ uuid=relationship.tip.uuid,+ flow_key=relationship.tip.flow_key,+ labels=[relationship.tip.type],+ name=relationship.tip.name,+ **(+ {"happened_at": relationship.tip.happened_at}+ if relationship.tip.happened_at+ else {}+ ),+ ),+ brain_id=brain_id,+ )+ except FutureTimeoutError:+ rel_name = getattr(relationship, "name", "unknown")+ print(+ f"[!] Relationship embedding future timed out for {rel_name}, skipping"+ )+ continue+ except Exception as e:+ rel_name = getattr(relationship, "name", "unknown")+ print(f"[!] Relationship embedding future failed for {rel_name}: {e}")+ continue++ token_details = merge_token_details(+ [scout_agent.token_detail, architect_agent.token_detail]+ )print("-----------------------------------")- print("> Input tokens: ", input_tokens)- print("> Output tokens: ", output_tokens)+ print(+ f"> Input tokens: {token_details.input.total} -> ${token_details.input.total * config.pricing.input_token_price}"+ )+ print(+ f"> Output tokens: {token_details.output.total} -> ${token_details.output.total * config.pricing.output_token_price}"+ )+ print(+ f"> Cost -> ${token_details.input.total * config.pricing.input_token_price + token_details.output.total * config.pricing.output_token_price} for {len(input)} characters"+ )+ 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("-----------------------------------")diff --git a/src/core/search/context.py b/src/core/search/context.pynew file mode 100644index 0000000..f7a0a3c--- /dev/null+++ b/src/core/search/context.py@@ -0,0 +1,9 @@+"""+File: /context.py+Created Date: Sunday January 11th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Sunday January 11th 2026 9:52:52 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/core/search/entity_context.py b/src/core/search/entity_context.pynew file mode 100644index 0000000..b04fae4--- /dev/null+++ b/src/core/search/entity_context.py@@ -0,0 +1,9 @@+"""+File: /entity_context.py+Created Date: Sunday January 11th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Sunday January 11th 2026 9:53:12 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/core/search/entity_info.py b/src/core/search/entity_info.pynew file mode 100644index 0000000..1dde2a5--- /dev/null+++ b/src/core/search/entity_info.py@@ -0,0 +1,113 @@+"""+File: /entity_info.py+Created Date: Sunday January 11th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Sunday January 11th 2026 9:52:59 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""++from typing import List, Set+from datetime import datetime+import numpy as np++from services.kg_agent.main import (+ embeddings_adapter,+ graph_adapter,+ vector_store_adapter,+)+from src.constants.kg import EntityInfo+from src.utils.similarity.vectors import cosine_similarity+++# ================================================================+# NOTE Currently not directly supported by the Event-Centric v2 kg+# Need to figure out how to handle this.+# ================================================================+++class EventSynergyRetriever:+ def __init__(self, memory_id: str):+ self.memory_id = memory_id+ self.graph_adapter = graph_adapter++ def _recursive_explorer(+ self,+ current_node_id: str,+ query_embedding: List[float],+ depth: int,+ visited_ids: Set[str],+ ):+ # -> List[SynergyPath]:+ """+ Recursively crawls the graph to find high-similarity paths+ beyond the initial Triangle.+ """+ if depth <= 0:+ return []++ neighbors = self.graph_adapter.fetch_entity_with_relevant_nodes(+ current_node_id, list(visited_ids)+ )++ found_paths = []++ neighbor_v_ids = [n.node.properties["v_id"] for n in neighbors.relationships]+ if not neighbor_v_ids:+ return []++ similarities = self._batch_measure_similarity(neighbor_v_ids, query_embedding)++ for i, rel in enumerate(neighbors.relationships):+ sim = similarities[i]+ target_node = rel.to_node++ # if sim > 0.4:+ # new_visited = visited_ids | {current_node_id}++ # child_paths = self._recursive_explorer(+ # target_node.id, query_embedding, depth - 1, new_visited+ # )++ # found_paths.append(+ # SynergyPath(+ # node=target_node,+ # relationship=Relationship(+ # **rel.model_dump(),+ # similarity=sim,+ # # Incorporate Recency and Amount into the relationship+ # # if it's an Event or Transaction link+ # ),+ # similarity=sim,+ # depth=depth,+ # children=child_paths,+ # )+ # )++ return sorted(found_paths, key=lambda x: x.similarity, reverse=True)++ def retrieve_matches(self, member_uuid: str, query: str, max_depth: int = 3):+ """+ Starts from a Member and recursively finds the most relevant+ synergy paths in the graph.+ """++ query_embedding = embeddings_adapter.embed_text(query)++ synergy_paths = self._recursive_explorer(+ member_uuid, query_embedding, depth=max_depth, visited_ids=set()+ )++ scored_results = []+ for path in synergy_paths:+ child_bonus = sum([c.similarity for c in path.children]) * 0.1++ days_ago = (datetime.now() - path.relationship.happened_at).days+ recency = 1 / (1 + np.log1p(days_ago))++ total_score = (path.similarity * 0.6) + (recency * 0.2) + child_bonus++ scored_results.append({"path": path, "score": total_score})++ return sorted(scored_results, key=lambda x: x["score"], reverse=True)diff --git a/src/core/search/entity_sibilings.py b/src/core/search/entity_sibilings.pynew file mode 100644index 0000000..d078a7c--- /dev/null+++ b/src/core/search/entity_sibilings.py@@ -0,0 +1,9 @@+"""+File: /entity_sibilings.py+Created Date: Monday January 12th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Monday January 12th 2026 9:48:46 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/lib/milvus/readme.txt b/src/lib/milvus/readme.txtnew file mode 100644index 0000000..bb2c821--- /dev/null+++ b/src/lib/milvus/readme.txt@@ -0,0 +1,5 @@+Attu Official:++```+docker run -p 8000:3000 -e MILVUS_URL={your-milvus-ip}:19530 zilliz/attu:latest+```\ No newline at end of filediff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.pyindex c938e27..4d24988 100644--- a/src/lib/neo4j/client.py+++ b/src/lib/neo4j/client.py@@ -239,7 +239,6 @@ class Neo4jClient(GraphClient):try:result = self._execute_query_with_retry(cypher_query, brain_id)results.append(result)- log("Nodes added: ", results)except Exception as e:print(f"Error adding node: {e} - {cypher_query}")raise@@ -1251,7 +1250,7 @@ class Neo4jClient(GraphClient):{set_clause}{remove_clause}{labels_clause}- RETURN n.uuid as uuid, n.name as name, labels(n) as labels,+ RETURN n.uuid as uuid, n.name as name, labels(n) as labels,n.description as description, properties(n) as properties"""diff --git a/src/services/input/agents.py b/src/services/input/agents.pyindex a603ea4..da0f767 100644--- a/src/services/input/agents.py+++ b/src/services/input/agents.py@@ -3,8 +3,8 @@ File: /agents.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Sunday December 21st 2025 4:17:39 pm-Modified By: the developer formerly known as Christian Nonis at <[email protected]>+Last Modified: Tuesday December 23rd 2025 9:24:20 pm+Modified By: Christian Nonis <[email protected]>-----"""@@ -14,9 +14,6 @@ from src.adapters.graph import GraphAdapterfrom src.adapters.llm import LLMAdapterfrom src.adapters.embeddings import VectorStoreAdapter-from src.core.agents.architect_agent import ArchitectAgent-from src.core.agents.janitor_agent import JanitorAgent-from src.core.agents.scout_agent import ScoutAgentfrom src.lib.llm.client_small import _llm_small_clientfrom src.lib.redis.client import _redis_client@@ -40,29 +37,3 @@ embeddings_adapter.add_client(_embeddings_client)vector_store_adapter = VectorStoreAdapter()vector_store_adapter.add_client(_milvus_client)---# Initialize the agents ================================-scout_agent = ScoutAgent(- llm_small_adapter,- cache_adapter,- kg=graph_adapter,- vector_store=vector_store_adapter,- embeddings=embeddings_adapter,- # database_desc=_neo4j_client.graphdb_description,-)-architect_agent = ArchitectAgent(- llm_small_adapter,- cache_adapter,- kg=graph_adapter,- vector_store=vector_store_adapter,- embeddings=embeddings_adapter,- # database_desc=_neo4j_client.graphdb_description,-)-janitor_agent = JanitorAgent(- llm_small_adapter,- kg=graph_adapter,- vector_store=vector_store_adapter,- embeddings=embeddings_adapter,- database_desc=_neo4j_client.graphdb_description,-)diff --git a/src/services/triggers/__init__.py b/src/services/triggers/__init__.pynew file mode 100644index 0000000..741cf90--- /dev/null+++ b/src/services/triggers/__init__.py@@ -0,0 +1,9 @@+"""+File: /__init__.py+Created Date: Monday January 12th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Monday January 12th 2026 8:56:20 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/services/triggers/neighbourhood.py b/src/services/triggers/neighbourhood.pynew file mode 100644index 0000000..1143405--- /dev/null+++ b/src/services/triggers/neighbourhood.py@@ -0,0 +1,9 @@+"""+File: /neighbourhood.py+Created Date: Monday January 12th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Monday January 12th 2026 9:00:21 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/services/triggers/synthetic_kg.py b/src/services/triggers/synthetic_kg.pynew file mode 100644index 0000000..10ce36a--- /dev/null+++ b/src/services/triggers/synthetic_kg.py@@ -0,0 +1,9 @@+"""+File: /synthetic_kg.py+Created Date: Monday January 12th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Monday January 12th 2026 9:00:59 pm+Modified By: the developer formerly known as Christian Nonis at <[email protected]>+-----+"""diff --git a/src/utils/tokens.py b/src/utils/tokens.pynew file mode 100644index 0000000..76b9cd6--- /dev/null+++ b/src/utils/tokens.py@@ -0,0 +1,92 @@+"""+File: /tokens.py+Project: utils+Created Date: Saturday January 17th 2026+Author: Christian Nonis <[email protected]>+-----+Last Modified: Saturday January 17th 2026 11:22:10 pm+Modified By: Christian Nonis <[email protected]>+-----+"""++from src.constants.agents import TokenDetail, TokenInputDetail, TokenOutputDetail+++def merge_token_details(token_details: list[TokenDetail]) -> TokenDetail:+ 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,+ )++ 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,+ )++ total_input = sum(detail.input.total for detail in token_details)+ total_uncached = sum(detail.input.uncached for detail in token_details)+ total_cached = sum(detail.input.cached for detail in token_details)+ cache_percentage = (total_cached / total_input * 100) if total_input > 0 else 0.0++ total_output = sum(detail.output.total for detail in token_details)+ total_regular = sum(detail.output.regular for detail in token_details)+ total_reasoning = sum(detail.output.reasoning for detail in token_details)+ reasoning_percentage = (+ (total_reasoning / total_output * 100) if total_output > 0 else 0.0+ )++ grand_total = sum(detail.grand_total for detail in token_details)+ effective_total = sum(detail.effective_total for detail in token_details)++ return TokenDetail(+ input=TokenInputDetail(+ total=total_input,+ uncached=total_uncached,+ cached=total_cached,+ cache_percentage=cache_percentage,+ ),+ output=TokenOutputDetail(+ total=total_output,+ regular=total_regular,+ reasoning=total_reasoning,+ reasoning_percentage=reasoning_percentage,+ ),+ grand_total=grand_total,+ effective_total=effective_total,+ )+++def token_detail_from_token_counts(+ input_tokens: int, output_tokens: int, cached_tokens: int, reasoning_tokens: int+) -> TokenDetail:+ 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,+ )