Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

feat(auto_kg): added architect guardrails, migrated to toollish-relationship-creation

Christian3613696999b0
diff --git a/LICENSE b/LICENSE
index 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 combined
license consisting of:
diff --git a/plugins/readme.txt b/plugins/readme.txt
new file mode 100644
index 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 file
diff --git a/src/config.py b/src/config.py
index 7d47c91..ea834ca 100644
--- a/src/config.py
+++ b/src/config.py
@@ -3,8 +3,8 @@ File: /config.py
Created Date: Sunday October 19th 2025
Author: 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.py
new file mode 100644
index 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: int
diff --git a/src/constants/kg.py b/src/constants/kg.py
index 1b9fb7e..60d2f0d 100644
--- a/src/constants/kg.py
+++ b/src/constants/kg.py
@@ -3,8 +3,8 @@ File: /kg.py
Created Date: Wednesday October 22nd 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Wednesday October 22nd 2025 8:09:09 pm
-Modified By: the developer formerly known as Christian Nonis at <[email protected]>
+Last Modified: Monday January 5th 2026 9:57:30 pm
+Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -26,6 +26,10 @@ class Node(BaseModel):
name: str
description: Optional[str] = None
properties: 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: str
description: 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.py
index acf7006..3cf90f7 100644
--- a/src/constants/prompts/architect_agent.py
+++ b/src/constants/prompts/architect_agent.py
@@ -3,8 +3,8 @@ File: /architect_agent.py
Created Date: Sunday December 21st 2025
Author: 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.py
index 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 2025
Author: 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.py
index 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.py
index 12c2c49..1468730 100644
--- a/src/core/agents/architect_agent.py
+++ b/src/core/agents/architect_agent.py
@@ -3,16 +3,16 @@ File: /architect_agent.py
Created Date: Sunday December 21st 2025
Author: 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, Tuple
from langchain.agents import create_agent
from langchain.tools import BaseTool
-from pydantic import BaseModel, Field
+from langchain_core.messages import RemoveMessage
+from pydantic import BaseModel
import os
from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError
from tenacity import (
@@ -28,92 +28,38 @@ from src.adapters.graph import GraphAdapter
from src.adapters.llm import LLMAdapter
from src.constants.kg import Node
from 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 = 8
class 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_store
self.embeddings = embeddings
self.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 = 0
self.output_tokens = 0
def _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 response
def _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_connected
connected_entity_uuids = set()
all_relationships = []
all_new_nodes = []
+ seen_relationship_keys = set()
max_iterations = 3
iteration = 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 response
except 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 += 1
if 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.py
new file mode 100644
index 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.py
index 3193476..87d8eed 100644
--- a/src/core/agents/janitor_agent.py
+++ b/src/core/agents/janitor_agent.py
@@ -3,15 +3,19 @@ File: /janitor_agent.py
Created Date: Sunday December 21st 2025
Author: 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 json
import os
-from typing import List, Literal, Optional, Tuple
+from functools import reduce
+from typing import List, Literal, Optional, Tuple, Union
from langchain.agents import create_agent
+from langchain.agents.structured_output import ToolStrategy
from langchain.tools import BaseTool
+from langchain_core.messages import RemoveMessage
from pydantic import BaseModel
from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError
from tenacity import (
@@ -25,8 +29,11 @@ from tenacity import (
from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter
from src.adapters.graph import GraphAdapter
from src.adapters.llm import LLMAdapter
+from src.constants.agents import AtomicJanitorAgentInputOutput
from src.constants.kg import Node
from 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 = 8
class JanitorAgentInputOutput(BaseModel):
@@ -54,8 +66,6 @@ class JanitorAgentInputOutput(BaseModel):
relationship: Optional[ArchitectAgentRelationship] = None
virtual_node: Optional[ArchitectAgentNew] = None
entity: Optional[ScoutEntity] = None
- input_tokens: Optional[int] = None
- output_tokens: Optional[int] = None
class JanitorAgent:
@@ -77,6 +87,11 @@ class JanitorAgent:
self.embeddings = embeddings
self.agent = None
self.database_desc = database_desc
+ self.input_tokens = 0
+ self.output_tokens = 0
+ self.cached_tokens = 0
+ self.reasoning_tokens = 0
+ self.token_detail = None
def _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 response
except 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_attempt
raise 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 response
def 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 response
except 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_attempt
raise 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.py
index e8388d4..813f816 100644
--- a/src/core/agents/scout_agent.py
+++ b/src/core/agents/scout_agent.py
@@ -3,8 +3,8 @@ File: /scout_agent.py
Created Date: Sunday December 21st 2025
Author: 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_counts
class _ScoutEntity(BaseModel):
@@ -90,6 +91,11 @@ class ScoutAgent:
self.vector_store = vector_store
self.embeddings = embeddings
self.agent = None
+ self.token_detail = None
+ self.input_tokens = 0
+ self.output_tokens = 0
+ self.cached_tokens = 0
+ self.reasoning_tokens = 0
def _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 response
except 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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__.py
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
index 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 2025
Author: 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, Union
from langchain.tools import BaseTool
from 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__.py
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
index 844af19..948cf04 100644
--- a/src/core/saving/auto_kg.py
+++ b/src/core/saving/auto_kg.py
@@ -3,28 +3,34 @@ File: /auto_kg.py
Created Date: Sunday December 21st 2025
Author: 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, Tuple
from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter
from src.adapters.graph import GraphAdapter
+from src.config import config
from 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, ArchitectAgentRelationship
from 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_counts
class IngestionManager:
@@ -38,6 +44,7 @@ class IngestionManager:
self.vector_store = vector_store_adapter
self.kg = graph_adapter
self.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.uuid
def 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.txt
new file mode 100644
index 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 file
diff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.py
index 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.py
index a603ea4..da0f767 100644
--- a/src/services/input/agents.py
+++ b/src/services/input/agents.py
@@ -3,8 +3,8 @@ File: /agents.py
Created Date: Sunday December 21st 2025
Author: 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 GraphAdapter
from src.adapters.llm import LLMAdapter
from 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 ScoutAgent
from src.lib.llm.client_small import _llm_small_client
from 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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,
+ )