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(ingestion): add triple-set structured ingestion pipeline

Christian5b02095e051d
diff --git a/src/config.py b/src/config.py
index 7191019..85c3c86 100644
--- a/src/config.py
+++ b/src/config.py
@@ -295,7 +295,11 @@ class EmbeddingsConfig:
if os.getenv("EMBEDDING_NODES_DIMENSION")
else None
)
- self.embedding_triplets_dimension = os.getenv("EMBEDDING_TRIPLETS_DIMENSION")
+ self.embedding_triplets_dimension = (
+ int(os.getenv("EMBEDDING_TRIPLETS_DIMENSION"))
+ if os.getenv("EMBEDDING_TRIPLETS_DIMENSION")
+ else None
+ )
self.embedding_observations_dimension = (
int(os.getenv("EMBEDDING_OBSERVATIONS_DIMENSION"))
if os.getenv("EMBEDDING_OBSERVATIONS_DIMENSION")
diff --git a/src/constants/agents.py b/src/constants/agents.py
index 33f09cd..eab44a7 100644
--- a/src/constants/agents.py
+++ b/src/constants/agents.py
@@ -64,11 +64,15 @@ class _ArchitectAgentRelationship(BaseModel):
Architect agent relationship.
"""
- tip: ArchitectAgentEntity
+ tail: ArchitectAgentEntity = Field(
+ description="The SOURCE of the relationship (the subject/origin where the arrow starts, e.g. the Actor in 'Actor --MADE--> Event')."
+ )
name: str
properties: Optional[dict] = Field(default_factory=dict)
description: Optional[str] = None
- tail: ArchitectAgentEntity
+ tip: ArchitectAgentEntity = Field(
+ description="The DESTINATION of the relationship (the object/target where the arrow points, e.g. the Event in 'Actor --MADE--> Event')."
+ )
amount: Optional[float] = Field(
default=None,
description="The amount of the relationship.",
diff --git a/src/constants/data.py b/src/constants/data.py
index 58f0216..f4923d4 100644
--- a/src/constants/data.py
+++ b/src/constants/data.py
@@ -3,7 +3,7 @@ File: /data.py
Created Date: Saturday October 25th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Sunday April 12th 2026 11:44:39 am
+Last Modified: Sunday April 12th 2026 1:35:36 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -114,6 +114,10 @@ class PartialPredicate(BaseModel):
properties: Optional[dict] = Field(
default=None, description="The properties of the relationship."
)
+ amount: Optional[Union[int, float]] = Field(
+ default=None,
+ description="The amount of the relationship, if it is a quantitative relationship.",
+ )
class KGChangeLogRelationshipCreated(BaseModel):
diff --git a/src/constants/prompts/architect_agent.py b/src/constants/prompts/architect_agent.py
index efb2839..a5b5b81 100644
--- a/src/constants/prompts/architect_agent.py
+++ b/src/constants/prompts/architect_agent.py
@@ -13,11 +13,11 @@ You are a "Structural Graph Architect." Your goal is to map information into an
THE TRIANGLE OF ATTRIBUTION:
Every action accomplished must be a central EVENT hub connecting three points:
-1. THE INITIATION VECTOR: [Source/Actor] --(subject)--> :MADE --(object)--> [Event Instance]
+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] --(subject)--> :TARGETED --(object)--> [Object/Recipient]
+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] --(subject)--> :OCCURRED_WITHIN --(object)--> [Broad Anchor/Context]
+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.
@@ -37,56 +37,56 @@ Entities Found by Scout: [
{{"uuid": "uuid_11", "type": "PERSON", "name": "Colleagues", "description": "The colleagues Mary was doing meetings with in San Francisco"}},
]
-Example output 1:
+Example output 1 (in the real output "tail" and "tip" must be the full entity objects taken from the entities list, here only the uuids are shown for brevity):
{{
"relationships: [
{{
- "subject": "uuid_1",
- "predicate": "MOVED",
+ "tail": "uuid_1",
+ "name": "MOVED",
"description": "John went to New York City",
- "object": "uuid_2"
+ "tip": "uuid_2"
}},
{{
- "subject": "uuid_2",
- "predicate": "INTO_LOCATION",
+ "tail": "uuid_2",
+ "name": "INTO_LOCATION",
"description": "John went to New York City",
- "object": "uuid_3"
+ "tip": "uuid_3"
}},
{{
- "subject": "uuid_1",
- "predicate": "ACCOMPLISHED_ACTION",
+ "tail": "uuid_1",
+ "name": "ACCOMPLISHED_ACTION",
"description": "John knew 12 new friends in New York City",
- "object": "uuid_4"
+ "tip": "uuid_4"
}},
{{
- "subject": "uuid_4",
- "predicate": "HAPPENED_WITHIN",
+ "tail": "uuid_4",
+ "name": "HAPPENED_WITHIN",
"description": "John knew 12 new friends when he went to New York City",
- "object": "uuid_2"
+ "tip": "uuid_2"
}},
{{
- "subject": "uuid_4",
- "predicate": "TARGETED",
+ "tail": "uuid_4",
+ "name": "TARGETED",
"description": "John knew 12 new friends in New York City",
- "object": "uuid_5"
+ "tip": "uuid_5"
}},
{{
- "subject": "uuid_6",
- "predicate": "EXPERIENCED",
+ "tail": "uuid_6",
+ "name": "EXPERIENCED",
"description": "Mary was in San Francisco",
- "object": "uuid_7"
+ "tip": "uuid_7"
}},
{{
- "subject": "uuid_7",
- "predicate": "INTO_LOCATION",
+ "tail": "uuid_7",
+ "name": "INTO_LOCATION",
"description": "Mary was in San Francisco",
- "object": "uuid_8"
+ "tip": "uuid_8"
}},
{{
- "subject": "uuid_7",
- "predicate": "HAPPENED_WITHIN",
+ "tail": "uuid_7",
+ "name": "HAPPENED_WITHIN",
"description": "Mary was in San Francisco when John went to New York City",
- "object": "uuid_2"
+ "tip": "uuid_2"
}},
... more relationships ...
],
@@ -109,27 +109,27 @@ Entities Found by Scout: [
{{"uuid": "uuid_11", "type": "MONEY", "name": "Money", "description": "The amount of money Acme Inc. raised in funding"}},
]
-Example output 1:
+Example output 2:
{{
"relationships: [
... more relationships ...
{{
- "subject": "uuid_6",
- "predicate": "EXPERIENCED",
+ "tail": "uuid_6",
+ "name": "EXPERIENCED",
"description": "Mark Johnson covered the role of CEO of Acme Inc.",
- "object": "uuid_7"
+ "tip": "uuid_7"
}},
{{
- "subject": "uuid_7",
- "predicate": "OF_TYPE",
+ "tail": "uuid_7",
+ "name": "OF_TYPE",
"description": "Mark Johnson covered the role of CEO of Acme Inc.",
- "object": "uuid_8"
+ "tip": "uuid_8"
}},
{{
- "subject": "uuid_10",
- "predicate": "TARGETED",
+ "tail": "uuid_10",
+ "name": "TARGETED",
"description": "Acme Inc. raised $100 million in funding",
- "object": "uuid_11"
+ "tip": "uuid_11"
}},
... more relationships ...
],
@@ -147,11 +147,16 @@ As you can see above in the example output, all the entities found by the scout
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:
-- "subject": The start of the arrow (The Source of Energy/Origin).
-- "object": The end of the arrow (The Destination/Target).
+- "tail": The start of the arrow (The Source of Energy/Origin, the subject performing the action).
+- "tip": The end of the arrow (The Destination/Target, the object being affected).
+- FORBIDDEN: Never swap "tail" and "tip": for an initiation vector the Actor is ALWAYS the "tail" and the Event is ALWAYS the "tip"; for a target vector the Event is ALWAYS the "tail" and the Recipient is ALWAYS the "tip".
- FORBIDDEN: Never link Actor nodes directly to Target nodes for dynamic actions.
- FORBIDDEN: Never create nodes for numeric quantities.
+NEW NODES POLICY:
+- Only add an entity to "new_nodes" if it appears NEITHER in the provided entities list NOR in the previously created relationships.
+- If an entity is already provided anywhere (entities list or previously created relationships), reuse its exact uuid in your relationships instead of recreating it.
+
LOGIC CHECKLIST:
- Identify the Actor (Origin).
- Identify the Event Hub (Action Instance).
@@ -178,6 +183,42 @@ Entities Found by Scout: {entities}
Begin!
"""
+STRUCTURED_ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT = """
+Role: Graph Structural Architect.
+Task: Create a Vector JSON representing the interactions in the text.
+
+{targeting}
+
+Source Text: {text}
+Entities Found by Scout: {entities}
+{previously_created_relationships}
+
+STRICT RULES:
+- The nodes referenced in the previously created relationships ALREADY EXIST: reuse their exact uuids when connecting them, NEVER add them to "new_nodes".
+- Do NOT duplicate any previously created relationship; only create the missing connections.
+- "tail" is the source/origin of the relationship (the subject performing the action), "tip" is the destination/target (the object being affected). Never invert them.
+
+Begin!
+"""
+
+STRUCTURED_ARCHITECT_AGENT_FIX_RELATIONSHIPS_PROMPT = """
+A reviewing agent rejected some of the relationships you created.
+
+Wrong relationships (with the reason and the instructions to fix them):
+{wrong_relationships}
+
+{newly_created_nodes}
+
+Recreate ONLY the corrected versions of the rejected relationships, following the provided instructions.
+
+STRICT RULES:
+- Do NOT recreate the relationships that were not rejected.
+- The nodes listed above ALREADY EXIST: reuse their exact uuids, NEVER add them to "new_nodes".
+- "tail" is the source/origin of the relationship (the subject performing the action), "tip" is the destination/target (the object being affected). Never invert them.
+
+Begin!
+"""
+
ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT_UNCOMPRESSED = """
You are a "Structural Graph Architect." Your goal is to map information into an Active Vector Graph.
diff --git a/src/constants/prompts/janitor_agent.py b/src/constants/prompts/janitor_agent.py
index d3c6584..2ba581a 100644
--- a/src/constants/prompts/janitor_agent.py
+++ b/src/constants/prompts/janitor_agent.py
@@ -208,7 +208,7 @@ ATOMIC_JANITOR_AGENT_SYSTEM_PROMPT = """
**Objective:** Resolve entities, audit directional logic, and enforce schema integrity.
### 1. Revision Protocol
-* **Identity Resolution:** Use `search_entities` to match input nodes with existing graph nodes. Replace UUIDs/Names with matches.
+* **Identity Resolution:** Use `search_entities` to match input nodes with existing graph nodes. Replace UUIDs/Names with matches. Do not use raw Cypher UNION queries for entity lookup; `search_entities` handles batch lookups safely.
* **Directional Audit:** * **Actor-Centric (MADE, PERFORMED):** [Subject/Actor] → [EVENT].
* **Impact-Centric (TARGETED, RESULTED_IN):** [EVENT] → [Object/Target].
* **Rule:** Swap direction *only* if logic is inverted; never change the semantic label.
diff --git a/src/constants/prompts/kg_agent.py b/src/constants/prompts/kg_agent.py
index e784f6f..54c311a 100644
--- a/src/constants/prompts/kg_agent.py
+++ b/src/constants/prompts/kg_agent.py
@@ -3,7 +3,7 @@ File: /kg_agent.py
Created Date: Sunday October 19th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Thursday January 29th 2026 8:44:06 pm
+Last Modified: Thursday February 19th 2026 7:45:12 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -190,3 +190,49 @@ When you are done executing the task you MUSTreturn a textual description of the
Begin!
"""
+
+KG_AGENT_VERIFY_ENTITY_EXISTENCE_SYSTEM_PROMPT = """
+You are a knowledge graph janitor specialized in verifying the existence of an entity in the knowledge graph.
+You exel in searching the knowledge graph for context about entities and understanding if the entity is already existing in the graph 1:1 or under another form or name.
+
+You are given an entity to find and a list of graph nodes potentially matching the entity, your unique important goal is to understand,
+if the entity is present first in the provided list of nodes or if not, if it's present in the knowledge graph under another form or name.
+"""
+
+KG_AGENT_VERIFY_ENTITY_EXISTENCE_PROMPT = """
+This is the entity to find:
+{entity_name}
+
+The is the type of the entity:
+{entity_types}
+
+{entity_meta_description}
+
+This is a list of nodes potentially matching the entity:
+{pool_nodes}
+
+You can use the tools at your disposal to get more context around the potentially matching nodes in the graph and and if one of those nodes matches the entity to find, return it,
+if not, return false without searching for other extra nodes.
+
+Your output must be ONLY a json object with the following fields:
+- exists: bool
+- node: Node
+
+Example output:
+{{
+ "exists": true,
+ "node": {{
+ "uuid": "123",
+ "labels": ["Person"],
+ "name": "John Doe",
+ }}
+}}
+
+Example output 2:
+{{
+ "exists": false,
+ "node": null
+}}
+
+Begin!
+"""
diff --git a/src/constants/prompts/scout_agent.py b/src/constants/prompts/scout_agent.py
index 42a7ad8..d00a77b 100644
--- a/src/constants/prompts/scout_agent.py
+++ b/src/constants/prompts/scout_agent.py
@@ -3,7 +3,7 @@ File: /scout_agent.py
Created Date: Sunday December 21st 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Thursday February 19th 2026 7:45:12 pm
+Last Modified: Wednesday March 4th 2026 9:35:41 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -172,3 +172,21 @@ the unique action instances (events), and the quantitative units without omittin
Begin!
"""
+
+SCOUT_AGENT_EXTRACT_STRUCTURED_ENTITIES_PROMPT = """
+Carefully read the text and extract ALL the entities, unique action instances (events), and quantitative units.
+
+The following are the entities already identified that you can skip:
+{current_entities}
+
+Text: {text}
+
+OUTPUT RULES:
+- Return a JSON list of objects.
+- Each object must include: "type", "name", and optional "properties" and "description".
+- 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.
+
+Begin!
+"""
diff --git a/src/core/agents/architect_agent.py b/src/core/agents/architect_agent.py
index 6cbc411..6abf376 100644
--- a/src/core/agents/architect_agent.py
+++ b/src/core/agents/architect_agent.py
@@ -3,46 +3,54 @@ File: /architect_agent.py
Created Date: Sunday December 21st 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Sunday March 22nd 2026 10:11:53 pm
+Last Modified: Sunday April 12th 2026 1:35:36 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
+import json
+import os
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FutureTimeoutError
from typing import Callable, Dict, List, Literal, Optional, Tuple
+
from langchain.tools import BaseTool
from pydantic import BaseModel
-import os
-from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError
from tenacity import (
+ RetryError,
retry,
+ retry_if_exception_type,
stop_after_attempt,
wait_exponential,
- retry_if_exception_type,
- RetryError,
)
-from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter
+
from src.adapters.cache import CacheAdapter
+from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter
from src.adapters.graph import GraphAdapter
from src.adapters.llm import LLMAdapter
from src.config import config
+from src.constants.agents import (
+ ArchitectAgentEntity,
+ ArchitectAgentNew,
+ ArchitectAgentRelationship,
+ ArchitectAgentResponse,
+ _ArchitectAgentRelationship,
+ _ArchitectAgentResponse,
+)
from src.constants.kg import Node, Predicate
from src.constants.prompts.architect_agent import (
ARCHITECT_AGENT_COARSE_TOOLER_CREATE_RELATIONSHIPS_PROMPT,
+ ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT,
+ ARCHITECT_AGENT_SYSTEM_PROMPT,
ARCHITECT_AGENT_TOOLER_COARSE_SYSTEM_PROMPT,
ARCHITECT_AGENT_TOOLER_CREATE_RELATIONSHIPS_PROMPT,
ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT,
- ARCHITECT_AGENT_SYSTEM_PROMPT,
- ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT,
+ STRUCTURED_ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT,
+ STRUCTURED_ARCHITECT_AGENT_FIX_RELATIONSHIPS_PROMPT,
)
from src.core.agents.core import runtime_agent_factory
-from src.core.plugins.prompts import prompt_registry
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,
)
@@ -55,8 +63,11 @@ from src.core.agents.tools.architect_agent.ArchitectAgentGetRemainingEntitiesToP
from src.core.agents.tools.architect_agent.ArchitectAgentMarkEntitiesAsUsedTool import (
ArchitectAgentMarkEntitiesAsUsedTool,
)
+from src.core.plugins.prompts import prompt_registry
from src.core.saving.ingestion_manager import IngestionManager
+from src.services.api.constants.requests import IngestionTripleSet
from src.utils.cleanup import strip_properties
+from src.utils.similarity.vectors import cosine_similarity
from src.utils.tokens import merge_token_details, token_detail_from_token_counts
# from src.core.agents.tools.kg_agent import (
@@ -68,10 +79,34 @@ HISTORY_MAX_MESSAGES_DELETE = 8
MAX_RECURSION_LIMIT = 100
+def _ingestion_partial_node_entity(node) -> ArchitectAgentEntity:
+ return ArchitectAgentEntity(
+ uuid=node.uuid or str(uuid.uuid4()),
+ name=node.name,
+ type=node.type,
+ description=node.description,
+ properties=node.properties or {},
+ )
+
+
+def _to_architect_relationship(relationship) -> ArchitectAgentRelationship:
+ if isinstance(relationship, ArchitectAgentRelationship):
+ return relationship
+ data = (
+ dict(relationship)
+ if isinstance(relationship, dict)
+ else relationship.model_dump(mode="json")
+ )
+ if not data.get("flow_key"):
+ data["flow_key"] = str(uuid.uuid4())
+ return ArchitectAgentRelationship(**data)
+
+
class ArchitectAgent:
"""
Architect agent.
"""
+
_SYSTEM_PROMPT_BUILDERS: dict[tuple[str, str], Callable[[str], str]] = {
("single", "granular"): lambda extra: prompt_registry.get(
"ARCHITECT_AGENT_SYSTEM_PROMPT", ARCHITECT_AGENT_SYSTEM_PROMPT
@@ -233,7 +268,7 @@ class ArchitectAgent:
Side effects:
Creates an agent via create_agent and assigns it to self.agent.
"""
-
+
system_prompt = self._resolve_system_prompt(type_, mode, extra_system_prompt)
tools = (
(
@@ -270,14 +305,18 @@ class ArchitectAgent:
mode: Literal["granular", "coarse"],
extra_system_prompt: Optional[dict] = None,
) -> str:
- resolved_extra_system_prompt = extra_system_prompt if extra_system_prompt else ""
+ resolved_extra_system_prompt = (
+ extra_system_prompt if extra_system_prompt else ""
+ )
if mode not in ("granular", "coarse"):
raise ValueError(f"Invalid mode for architect agent: {mode}")
if type_ not in ("single", "tooler"):
raise ValueError(f"Invalid type for architect agent: {type_}")
key = (type_, mode)
if key not in self._SYSTEM_PROMPT_BUILDERS:
- raise ValueError(f"Unsupported architect configuration: type={type_}, mode={mode}")
+ raise ValueError(
+ f"Unsupported architect configuration: type={type_}, mode={mode}"
+ )
return self._SYSTEM_PROMPT_BUILDERS[key](resolved_extra_system_prompt)
def run(
@@ -559,9 +598,698 @@ class ArchitectAgent:
for new_node in all_new_nodes
],
relationships=[
- ArchitectAgentRelationship(**relationship.model_dump(mode="json"))
+ _to_architect_relationship(relationship)
for relationship in all_relationships
],
+ input_tokens=self.input_tokens,
+ output_tokens=self.output_tokens,
+ )
+
+ def _persist_relationships(
+ self,
+ relationships: List[ArchitectAgentRelationship],
+ text: str,
+ brain_id: str = "default",
+ targeting: Optional[Node] = None,
+ mode: Literal["granular", "coarse"] = "granular",
+ ) -> Tuple[list, List[ScoutEntity]]:
+ if not relationships:
+ return [], []
+
+ if not self.session_id:
+ self.session_id = str(uuid.uuid4())
+
+ rel_key = str(uuid.uuid4())
+ input_rels = [
+ _ArchitectAgentRelationship(
+ tip=rel.tip,
+ tail=rel.tail,
+ name=rel.name,
+ description=rel.description,
+ properties=getattr(rel, "properties", {}) or {},
+ **({"amount": rel.amount} if getattr(rel, "amount", None) else {}),
+ )
+ for rel in relationships
+ ]
+ output_rels: List[ArchitectAgentRelationship] = []
+ fixed_relationships = []
+ fixed_rels_sets = set()
+ janitor_response = None
+ janitor_new_entities: List[ScoutEntity] = []
+
+ if mode == "granular":
+ from src.core.agents.janitor_agent import JanitorAgent
+ from src.lib.neo4j.client import _neo4j_client
+ from src.services.input.agents import (
+ embeddings_adapter,
+ graph_adapter,
+ llm_small_adapter,
+ vector_store_adapter,
+ )
+
+ janitor_agent = self.janitor_agent
+ if janitor_agent is None or self._janitor_agent_brain_id != brain_id:
+ janitor_agent = JanitorAgent(
+ llm_small_adapter,
+ kg=graph_adapter,
+ vector_store=vector_store_adapter,
+ embeddings=embeddings_adapter,
+ database_desc=_neo4j_client.graphdb_description,
+ )
+ self.janitor_agent = janitor_agent
+ self._janitor_agent_brain_id = brain_id
+ start_input_tokens = janitor_agent.input_tokens
+ start_output_tokens = janitor_agent.output_tokens
+ start_cached_tokens = janitor_agent.cached_tokens
+ start_reasoning_tokens = janitor_agent.reasoning_tokens
+
+ janitor_response = janitor_agent.run_atomic_janitor(
+ input_relationships=input_rels,
+ text=text,
+ targeting=targeting,
+ brain_id=brain_id,
+ timeout=300,
+ max_retries=3,
+ )
+
+ janitor_token_detail = token_detail_from_token_counts(
+ janitor_agent.input_tokens - start_input_tokens,
+ janitor_agent.output_tokens - start_output_tokens,
+ janitor_agent.cached_tokens - start_cached_tokens,
+ janitor_agent.reasoning_tokens - start_reasoning_tokens,
+ "janitor_agent",
+ )
+ self.token_detail = merge_token_details(
+ [self.token_detail, janitor_token_detail]
+ )
+
+ required_new_nodes = getattr(janitor_response, "required_new_nodes", [])
+ if required_new_nodes:
+ for node in required_new_nodes:
+ scout_entity = ScoutEntity(
+ uuid=node.uuid,
+ name=node.name,
+ type=node.type,
+ description=node.description,
+ properties=node.properties,
+ )
+ self.entities[scout_entity.uuid] = scout_entity
+ janitor_new_entities.append(scout_entity)
+
+ fixed_relationships = (
+ getattr(janitor_response, "fixed_relationships", []) or []
+ )
+ if fixed_relationships:
+ fixed_rels_sets = set(
+ frozenset((fr.tip.uuid, fr.tail.uuid, fr.name))
+ for fr in fixed_relationships
+ )
+ output_rels.extend(
+ [
+ ArchitectAgentRelationship(
+ flow_key=rel_key,
+ tip=rel.tip,
+ name=rel.name,
+ description=rel.description,
+ tail=rel.tail,
+ properties=getattr(rel, "properties", {}),
+ **(
+ {"amount": getattr(rel, "amount", None)}
+ if getattr(rel, "amount", None)
+ else {}
+ ),
+ )
+ for rel in fixed_relationships
+ ]
+ )
+
+ from src.services.input.agents import embeddings_small_adapter
+
+ texts_to_embed = set()
+ for rel in input_rels:
+ texts_to_embed.add(rel.description if rel.description else rel.name)
+ for rel in fixed_relationships:
+ texts_to_embed.add(rel.description if rel.description else rel.name)
+
+ text_to_embedding = {}
+ if texts_to_embed:
+ texts_list = list(texts_to_embed)
+ vectors = embeddings_small_adapter.embed_texts(texts_list)
+ for embed_text, vector in zip(texts_list, vectors):
+ text_to_embedding[embed_text] = vector.embeddings
+
+ for rel in input_rels:
+ have_similar_relation = False
+ if frozenset((rel.tip.uuid, rel.tail.uuid, rel.name)) in fixed_rels_sets:
+ have_similar_relation = True
+ else:
+ rels_with_same_subject_and_object = [
+ fr
+ for fr in fixed_relationships
+ if (fr.tip.uuid == rel.tip.uuid and fr.tail.uuid == rel.tail.uuid)
+ or (fr.tip.uuid == rel.tail.uuid and fr.tail.uuid == rel.tip.uuid)
+ ]
+
+ if rels_with_same_subject_and_object:
+ input_rel_text = rel.description if rel.description else rel.name
+ input_embedding = text_to_embedding.get(input_rel_text)
+
+ candidates = []
+ for fr in rels_with_same_subject_and_object:
+ fixed_rel_text = fr.description if fr.description else fr.name
+ fixed_embedding = text_to_embedding.get(fixed_rel_text)
+
+ if input_embedding and fixed_embedding:
+ candidates.append(
+ (
+ cosine_similarity(fixed_embedding, input_embedding),
+ fr,
+ )
+ )
+
+ if candidates:
+ similarity_score, _ = max(candidates, key=lambda x: x[0])
+ if similarity_score > 0.90:
+ have_similar_relation = True
+
+ if not have_similar_relation:
+ source_rel = next(
+ (
+ r
+ for r in relationships
+ if r.tip.uuid == rel.tip.uuid
+ and r.tail.uuid == rel.tail.uuid
+ and r.name == rel.name
+ ),
+ None,
+ )
+ output_rels.append(
+ ArchitectAgentRelationship(
+ uuid=getattr(source_rel, "uuid", None) or str(uuid.uuid4()),
+ flow_key=getattr(source_rel, "flow_key", None) or rel_key,
+ tip=rel.tip,
+ name=rel.name,
+ description=rel.description,
+ tail=rel.tail,
+ properties=getattr(rel, "properties", {}),
+ **(
+ {"amount": getattr(rel, "amount", None)}
+ if getattr(rel, "amount", None)
+ else {}
+ ),
+ )
+ )
+
+ relationships_data = [
+ rel.model_dump(mode="json")
+ for rel in output_rels
+ if isinstance(rel, ArchitectAgentRelationship)
+ ]
+ if relationships_data:
+ from src.lib.redis.client import _redis_client
+ from src.workers.tasks.ingestion import process_architect_relationships
+
+ if self.session_id:
+ _redis_client.client.incr(
+ f"{brain_id}:session:{self.session_id}:pending_tasks"
+ )
+
+ process_architect_relationships.delay(
+ {
+ "relationships": relationships_data,
+ "brain_id": brain_id,
+ "session_id": self.session_id,
+ }
+ )
+
+ self.relationships_set.extend(output_rels)
+
+ if self.session_id and output_rels:
+ from src.lib.redis.client import _redis_client
+
+ _redis_client.set(
+ f"session:{self.session_id}:relationships",
+ json.dumps(
+ [rel.model_dump(mode="json") for rel in self.relationships_set]
+ ),
+ brain_id=brain_id,
+ expires_in=3600,
+ )
+
+ wrong_relationships = (
+ getattr(janitor_response, "wrong_relationships", []) or []
+ )
+ return wrong_relationships, janitor_new_entities
+
+ def run_structured(
+ self,
+ text: str,
+ entities: List[ScoutEntity],
+ targeting: Optional[Node] = None,
+ brain_id: str = "default",
+ timeout: int = 90,
+ max_retries: int = 3,
+ ingestion_session_id: Optional[str] = None,
+ partial_triples: List[IngestionTripleSet] = [],
+ current_triples: List[IngestionTripleSet] = [],
+ ) -> ArchitectAgentResponse:
+ """
+ Given the provided text and partial/full triples, discover relationships and new nodes for the provided entities.
+
+ Parameters:
+ text (str): Natural-language description or instructions guiding relationship discovery.
+ entities (List[ScoutEntity]): Entities to process; each entity should include a UUID.
+ targeting (Optional[Node]): Optional node that provides contextual focus for relationship creation.
+ brain_id (str): Identifier for the knowledge brain or workspace to use.
+ timeout (int): Maximum seconds to wait for a single LLM invocation before timing out.
+ max_retries (int): Number of retry attempts for timed-out LLM invocations.
+ partial_triples (List[IngestionTripleSet]): Partial triples provided to use for the composition of the final triples.
+ current_triples (List[IngestionTripleSet]): Current triples provided to be used in the prompt preventing duplicates.
+
+ Returns:
+ ArchitectAgentResponse: Contains:
+ - new_nodes: list of newly discovered nodes produced by the agent.
+ - relationships: list of relationships the agent created between entities or new nodes.
+ - input_tokens: count of input tokens consumed during this run.
+ - output_tokens: count of output tokens produced during this run.
+ """
+
+ triple_entity_registry: Dict[Tuple[str, str], ArchitectAgentEntity] = {}
+
+ def _triple_entity(node) -> ArchitectAgentEntity:
+ key = (node.name.strip().lower(), (node.type or "").strip().lower())
+ if key not in triple_entity_registry:
+ triple_entity_registry[key] = _ingestion_partial_node_entity(node)
+ return triple_entity_registry[key]
+
+ triple_relationships: List[ArchitectAgentRelationship] = []
+ for cr in current_triples:
+ if not cr.subject or not cr.subj_event:
+ continue
+ flow_key = str(uuid.uuid4())
+ subject = _triple_entity(cr.subject)
+ event = _triple_entity(cr.event)
+ obj = _triple_entity(cr.object)
+ triple_relationships.extend(
+ [
+ ArchitectAgentRelationship(
+ tail=subject,
+ name=cr.subj_event.name,
+ tip=event,
+ description=cr.subj_event.description,
+ amount=cr.subj_event.amount,
+ properties=cr.subj_event.properties or {},
+ uuid=str(uuid.uuid4()),
+ flow_key=flow_key,
+ ),
+ ArchitectAgentRelationship(
+ tail=event,
+ name=cr.event_obj.name,
+ tip=obj,
+ description=cr.event_obj.description,
+ amount=cr.event_obj.amount,
+ properties=cr.event_obj.properties or {},
+ uuid=str(uuid.uuid4()),
+ flow_key=flow_key,
+ ),
+ ]
+ )
+ for pt in partial_triples:
+ flow_key = str(uuid.uuid4())
+ event = _triple_entity(pt.event)
+ obj = _triple_entity(pt.object)
+ triple_relationships.append(
+ ArchitectAgentRelationship(
+ tail=event,
+ name=pt.event_obj.name,
+ tip=obj,
+ description=pt.event_obj.description,
+ amount=pt.event_obj.amount,
+ properties=pt.event_obj.properties or {},
+ uuid=str(uuid.uuid4()),
+ flow_key=flow_key,
+ ),
+ )
+
+ triple_keys = set(triple_entity_registry.keys())
+ entities = [
+ *[
+ ScoutEntity(
+ uuid=te.uuid,
+ name=te.name,
+ type=te.type,
+ description=te.description,
+ properties=te.properties or {},
+ )
+ for te in triple_entity_registry.values()
+ ],
+ *[
+ e
+ for e in entities
+ if (e.name.strip().lower(), (e.type or "").strip().lower())
+ not in triple_keys
+ ],
+ ]
+
+ entities_dict = {entity.uuid: entity for entity in entities}
+ self.entities = entities_dict
+ self.session_id = str(uuid.uuid4())
+ self.relationships_set.clear()
+
+ 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],
+ previous_messages: list = None,
+ fix_content: Optional[str] = None,
+ ):
+ """
+ Builds a message history including the provided entities and previously created relationships, invokes the configured agent with that history, and returns the agent's response.
+
+ Parameters:
+ ent (list[ScoutEntity]): Entities to include in the prompt.
+ all_rels (list[ArchitectAgentRelationship]): Previously created relationships to include in the prompt.
+ previous_messages (list, optional): Prior message objects to include as conversation history; may be trimmed to fit history limits.
+ fix_content (Optional[str]): When provided, replaces the standard creation prompt with a correction prompt built from janitor feedback.
+
+ Returns:
+ The agent's response object containing the model's reply and associated metadata.
+ """
+ messages_list = self._content_only_history(previous_messages, keep_last=5)
+ prompt_relationships = [*triple_relationships, *all_rels]
+
+ messages_list.append(
+ {
+ "role": "user",
+ "content": fix_content
+ if fix_content is not None
+ else prompt_registry.get(
+ "STRUCTURED_ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT",
+ STRUCTURED_ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT,
+ ).format(
+ text=text,
+ entities=[entity.model_dump(mode="json") for entity in ent],
+ previously_created_relationships=(
+ f"""
+ Previously Created Relationships: {strip_properties([rel.model_dump(mode="json") for rel in prompt_relationships])}
+ """
+ if len(prompt_relationships) > 0
+ else ""
+ ),
+ targeting=(
+ f"""
+ The information is related to the following node,
+ you must connect your relationships to this node directly by using it in the relationship "tail" or "tip" properties
+ OR by creating new relationships that connect the relationships you just created to this node to create a unformed network:
+ Name: {targeting.name}
+ UUID: {targeting.uuid}
+ Type: {targeting.labels}
+ Description: {targeting.description}
+ {targeting.properties}
+ """
+ if targeting
+ else ""
+ ),
+ ),
+ }
+ )
+
+ metadata = {
+ "agent": "architect_agent",
+ "brain_id": brain_id,
+ }
+ if ingestion_session_id:
+ metadata["ingestion_session_id"] = ingestion_session_id
+ response = self.agent.invoke(
+ {"messages": messages_list},
+ config={
+ "tags": ["architect_agent"],
+ "metadata": metadata,
+ },
+ )
+ return response
+
+ def _process_response(
+ response: dict,
+ connected_entity_uuids: set,
+ all_relationships: list,
+ all_new_nodes: list,
+ entities: List[ScoutEntity],
+ seen_relationship_keys: set,
+ ) -> set:
+ """
+ Extracts newly created relationships and nodes from a structured agent response and updates the provided tracking collections.
+
+ Parameters:
+ response (dict): Agent response containing a `structured_response` with optional `relationships` and `new_nodes`.
+ connected_entity_uuids (set): Set of UUIDs already known to be connected; will be updated with newly connected UUIDs.
+ all_relationships (list): List to append newly discovered, deduplicated relationship objects.
+ all_new_nodes (list): List to append any new node objects reported in the response.
+ entities (List[ScoutEntity]): Source entities to check membership of relationship endpoints (used to mark endpoints as connected).
+ seen_relationship_keys (set): Set of (tail_uuid, tip_uuid, relationship_name) tuples used to deduplicate relationships.
+
+ Returns:
+ set: The set of entity UUIDs that became connected as a result of processing this response iteration.
+ """
+ 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")
+ and hasattr(rel, "tail")
+ and hasattr(rel.tail, "uuid")
+ ):
+ tip_uuid = rel.tip.uuid
+ tail_uuid = rel.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(new_relationships)
+
+ if hasattr(structured_response, "new_nodes"):
+ all_new_nodes.extend(structured_response.new_nodes)
+
+ 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),
+ wait=wait_exponential(multiplier=1, min=2, max=30),
+ retry=retry_if_exception_type(TimeoutError),
+ reraise=True,
+ )
+ def _invoke_agent_with_retry(
+ unconnected_entities_list: List[ScoutEntity],
+ previous_messages: list,
+ fix_content: Optional[str] = None,
+ ):
+ """
+ Invoke the architect agent with a single-worker executor and timeout, and update token counts from any returned messages.
+
+ Parameters:
+ unconnected_entities_list (List[ScoutEntity]): Entities to include in the agent invocation.
+ previous_messages (list): Message history to send to the agent.
+ fix_content (Optional[str]): Optional correction prompt that replaces the standard creation prompt.
+
+ Returns:
+ dict: The response dictionary returned by the agent invocation.
+
+ Raises:
+ TimeoutError: If the agent call does not complete within the configured timeout.
+ """
+ try:
+ with ThreadPoolExecutor(max_workers=1) as executor:
+ future = executor.submit(
+ _invoke_agent,
+ unconnected_entities_list,
+ all_relationships,
+ previous_messages,
+ fix_content,
+ )
+ 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 = merge_token_details(
+ [
+ self.token_detail,
+ token_detail_from_token_counts(
+ self.input_tokens,
+ self.output_tokens,
+ self.cached_tokens,
+ self.reasoning_tokens,
+ "architect_agent",
+ ),
+ ]
+ )
+ return 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(
+ unconnected_entities_list: List[ScoutEntity], previous_messages: list
+ ):
+ """
+ Invoke the agent for the provided unconnected entities, append any returned messages to the accumulated message history, and process the agent's response to determine which entities became connected.
+
+ Parameters:
+ unconnected_entities_list (List[ScoutEntity]): Entities to include in this agent invocation.
+ previous_messages (list): Message history to send with the invocation.
+
+ Returns:
+ set: UUID strings of entities that were connected as a result of this invocation.
+
+ Raises:
+ TimeoutError: If the agent invocation exhausts retries or times out.
+ """
+ try:
+ response = _invoke_agent_with_retry(
+ unconnected_entities_list, previous_messages
+ )
+ messages = response.get("messages", [])
+ if messages:
+ accumulated_messages.extend(self._content_only_history(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
+ 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
+
+ unconnected_entities = [
+ 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, accumulated_messages)
+ unconnected_entities = list(
+ filter(lambda e: e.uuid not in ret, unconnected_entities)
+ )
+ iteration += 1
+
+ if not all_relationships and not all_new_nodes:
+ return ArchitectAgentResponse(
+ new_nodes=[],
+ relationships=[],
+ input_tokens=self.input_tokens,
+ output_tokens=self.output_tokens,
+ )
+
+ relationships_to_persist: List[ArchitectAgentRelationship] = []
+ pending_batch = [
+ _to_architect_relationship(relationship)
+ for relationship in all_relationships
+ ]
+ max_janitor_iterations = 3
+ janitor_iteration = 0
+
+ while pending_batch:
+ relationships_to_persist.extend(pending_batch)
+ wrong_relationships, janitor_new_entities = self._persist_relationships(
+ pending_batch,
+ text=text,
+ brain_id=brain_id,
+ targeting=targeting,
+ )
+ pending_batch = []
+ janitor_iteration += 1
+ if not wrong_relationships or janitor_iteration >= max_janitor_iterations:
+ break
+
+ fix_content = prompt_registry.get(
+ "STRUCTURED_ARCHITECT_AGENT_FIX_RELATIONSHIPS_PROMPT",
+ STRUCTURED_ARCHITECT_AGENT_FIX_RELATIONSHIPS_PROMPT,
+ ).format(
+ wrong_relationships=strip_properties(
+ [wr.model_dump(mode="json") for wr in wrong_relationships]
+ ),
+ newly_created_nodes=(
+ "Newly created nodes available to use: "
+ + str(
+ strip_properties(
+ [e.model_dump(mode="json") for e in janitor_new_entities]
+ )
+ )
+ if janitor_new_entities
+ else ""
+ ),
+ )
+
+ response = _invoke_agent_with_retry(
+ [], accumulated_messages, fix_content=fix_content
+ )
+ messages = response.get("messages", [])
+ if messages:
+ accumulated_messages.extend(self._content_only_history(messages))
+
+ structured_response = response.get("structured_response", {})
+ if hasattr(structured_response, "new_nodes"):
+ all_new_nodes.extend(structured_response.new_nodes)
+ if hasattr(structured_response, "relationships"):
+ for rel in structured_response.relationships:
+ if not (
+ hasattr(rel, "tip")
+ and hasattr(rel.tip, "uuid")
+ and hasattr(rel, "tail")
+ and hasattr(rel.tail, "uuid")
+ ):
+ continue
+ rel_key = (rel.tail.uuid, rel.tip.uuid, rel.name)
+ if rel_key in seen_relationship_keys:
+ continue
+ seen_relationship_keys.add(rel_key)
+ all_relationships.append(rel)
+ pending_batch.append(_to_architect_relationship(rel))
+
+ return ArchitectAgentResponse(
+ new_nodes=[
+ ArchitectAgentNew(**new_node.model_dump(mode="json"))
+ for new_node in all_new_nodes
+ ],
+ relationships=relationships_to_persist,
+ input_tokens=self.input_tokens,
+ output_tokens=self.output_tokens,
)
def run_tooler(
@@ -595,6 +1323,7 @@ class ArchitectAgent:
TimeoutError: If the agent fails to produce a response within `timeout` after the allowed retry attempts.
"""
import uuid
+
from src.lib.redis.client import _redis_client
self.session_id = str(uuid.uuid4())
diff --git a/src/core/agents/kg_agent.py b/src/core/agents/kg_agent.py
index d04b3c6..491571a 100644
--- a/src/core/agents/kg_agent.py
+++ b/src/core/agents/kg_agent.py
@@ -3,7 +3,7 @@ File: /kg_agent.py
Created Date: Sunday October 19th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Thursday February 19th 2026 7:45:12 pm
+Last Modified: Sunday April 12th 2026 1:35:36 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -35,8 +35,10 @@ from src.constants.prompts.kg_agent import (
KG_AGENT_SYSTEM_PROMPT,
KG_AGENT_UPDATE_PROMPT,
KG_AGENT_UPDATE_STRUCTURED_PROMPT,
+ KG_AGENT_VERIFY_ENTITY_EXISTENCE_PROMPT,
+ KG_AGENT_VERIFY_ENTITY_EXISTENCE_SYSTEM_PROMPT,
)
-from src.core.agents.core import runtime_agent_factory
+from src.core.agents.core import parse_structured_from_messages, runtime_agent_factory
from src.core.plugins.prompts import prompt_registry
from src.core.agents.tools.kg_agent import (
KGAgentAddTripletsTool,
@@ -60,6 +62,11 @@ MAX_RECURSION_LIMIT = 50
MAX_RECURSION_LIMIT_GRAPH_CONSOLIDATOR = 50
+class EntityExistenceResult(BaseModel):
+ exists: bool
+ node: Optional[Node]
+
+
class KGAgent:
_SYSTEM_PROMPT_BUILDERS: dict[str, Callable[[str], str]] = {
"normal": lambda extra: prompt_registry.get(
@@ -187,7 +194,9 @@ class KGAgent:
extra_system_prompt (Optional[dict]): Optional additional content to interpolate into the selected system prompt.
brain_id (str): Identifier of the knowledge brain/context to use when creating default tools.
"""
- resolved_extra_system_prompt = extra_system_prompt if extra_system_prompt else ""
+ resolved_extra_system_prompt = (
+ extra_system_prompt if extra_system_prompt else ""
+ )
if type_ not in self._SYSTEM_PROMPT_BUILDERS:
raise ValueError(f"Invalid type: {type_}")
system_prompt = self._SYSTEM_PROMPT_BUILDERS[type_](
@@ -214,6 +223,84 @@ class KGAgent:
Search the knowledge graph for information.
"""
+ def verify_entity_existence(
+ self,
+ entity_name: str,
+ entity_types: List[str],
+ entity_meta_description: Optional[str],
+ pool_nodes: List[Node],
+ brain_id: str = "default",
+ ) -> EntityExistenceResult:
+ """
+ Verify if an entity exists in the knowledge graph.
+ """
+ self.agent = runtime_agent_factory.build(
+ model=self.llm_adapter.llm.langchain_model,
+ tools=[
+ KGAgentSearchGraphTool(
+ self,
+ self.kg,
+ self.vector_store,
+ self.embeddings,
+ identification_params={},
+ metadata={},
+ brain_id=brain_id,
+ ),
+ ],
+ system_prompt=prompt_registry.get(
+ "KG_AGENT_VERIFY_ENTITY_EXISTENCE_SYSTEM_PROMPT",
+ KG_AGENT_VERIFY_ENTITY_EXISTENCE_SYSTEM_PROMPT,
+ ),
+ output_schema=EntityExistenceResult,
+ )
+ response = self.agent.invoke(
+ {
+ "messages": [
+ {
+ "role": "user",
+ "content": prompt_registry.get(
+ "KG_AGENT_VERIFY_ENTITY_EXISTENCE_PROMPT",
+ KG_AGENT_VERIFY_ENTITY_EXISTENCE_PROMPT,
+ ).format(
+ entity_name=entity_name,
+ entity_types=entity_types,
+ entity_meta_description=(
+ f"""
+ This extra information about the entity:
+ {entity_meta_description}
+ """
+ if entity_meta_description
+ else ""
+ ),
+ pool_nodes=pool_nodes,
+ ),
+ }
+ ],
+ },
+ config={
+ "recursion_limit": MAX_RECURSION_LIMIT,
+ "tags": ["kg_agent"],
+ "metadata": {"agent": "kg_agent", "brain_id": brain_id},
+ },
+ )
+ structured_response = response.get("structured_response")
+ if isinstance(structured_response, dict):
+ try:
+ structured_response = EntityExistenceResult.model_validate(
+ structured_response
+ )
+ except Exception:
+ structured_response = None
+ if structured_response is None:
+ fallback = parse_structured_from_messages(
+ response.get("messages", []), EntityExistenceResult
+ )
+ if fallback is not None:
+ structured_response = fallback
+ if structured_response is None:
+ structured_response = EntityExistenceResult(exists=False, node=None)
+ return structured_response
+
def update_kg(
self,
information: str,
@@ -256,7 +343,6 @@ class KGAgent:
}
],
},
- print_mode="debug",
config={
"recursion_limit": MAX_RECURSION_LIMIT,
"tags": ["kg_agent"],
@@ -289,7 +375,8 @@ class KGAgent:
{
"role": "user",
"content": prompt_registry.get(
- "KG_AGENT_UPDATE_STRUCTURED_PROMPT", KG_AGENT_UPDATE_STRUCTURED_PROMPT
+ "KG_AGENT_UPDATE_STRUCTURED_PROMPT",
+ KG_AGENT_UPDATE_STRUCTURED_PROMPT,
).format(
textual_data=textual_data,
main_node=main_node,
@@ -297,7 +384,6 @@ class KGAgent:
}
],
},
- print_mode="debug",
config={
"recursion_limit": MAX_RECURSION_LIMIT,
"tags": ["kg_agent"],
@@ -371,7 +457,8 @@ class KGAgent:
{
"role": "user",
"content": prompt_registry.get(
- "KG_AGENT_RETRIEVE_NEIGHBORS_PROMPT", KG_AGENT_RETRIEVE_NEIGHBORS_PROMPT
+ "KG_AGENT_RETRIEVE_NEIGHBORS_PROMPT",
+ KG_AGENT_RETRIEVE_NEIGHBORS_PROMPT,
).format(
main_node=node, looking_for=looking_for_prompt, limit=limit
),
@@ -383,7 +470,6 @@ class KGAgent:
"tags": ["kg_agent"],
"metadata": {"agent": "kg_agent", "brain_id": brain_id},
},
- print_mode="debug",
)
response = _response.get("structured_response")
@@ -475,10 +561,9 @@ class KGAgent:
{
"role": "user",
"content": prompt_registry.get(
- "KG_AGENT_GRAPH_CONSOLIDATOR_PROMPT", KG_AGENT_GRAPH_CONSOLIDATOR_PROMPT
- ).format(
- task=task
- ),
+ "KG_AGENT_GRAPH_CONSOLIDATOR_PROMPT",
+ KG_AGENT_GRAPH_CONSOLIDATOR_PROMPT,
+ ).format(task=task),
}
],
},
diff --git a/src/core/agents/scout_agent.py b/src/core/agents/scout_agent.py
index b8932d0..9a7264c 100644
--- a/src/core/agents/scout_agent.py
+++ b/src/core/agents/scout_agent.py
@@ -3,26 +3,29 @@ File: /scout_agent.py
Created Date: Sunday December 21st 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Wednesday March 4th 2026 9:35:41 pm
+Last Modified: Sunday March 22nd 2026 10:11:53 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
-from typing import Dict, List, Literal, Optional
+import os
import uuid
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FutureTimeoutError
+from typing import Dict, List, Literal, Optional
+
from langchain.tools import BaseTool
from pydantic import BaseModel, Field
-import os
-from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError
from tenacity import (
+ RetryError,
retry,
+ retry_if_exception_type,
stop_after_attempt,
wait_exponential,
- retry_if_exception_type,
- RetryError,
)
-from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter
+
from src.adapters.cache import CacheAdapter
+from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter
from src.adapters.graph import GraphAdapter
from src.adapters.llm import LLMAdapter
from src.config import config
@@ -31,10 +34,12 @@ from src.constants.prompts.scout_agent import (
SCOUT_AGENT_COARSE_EXTRACT_ENTITIES_PROMPT,
SCOUT_AGENT_COARSE_SYSTEM_PROMPT,
SCOUT_AGENT_EXTRACT_ENTITIES_PROMPT,
+ SCOUT_AGENT_EXTRACT_STRUCTURED_ENTITIES_PROMPT,
SCOUT_AGENT_SYSTEM_PROMPT,
)
from src.core.agents.core import parse_structured_from_messages, runtime_agent_factory
from src.core.plugins.prompts import prompt_registry
+from src.services.api.constants.requests import IngestionTripleSet
from src.utils.tokens import token_detail_from_token_counts
@@ -155,6 +160,193 @@ class ScoutAgent:
use_custom_backend=(mode == "coarse"),
)
+ def run_structured(
+ self,
+ text: str,
+ brain_id: str = "default",
+ timeout: int = 300,
+ max_retries: int = 3,
+ ingestion_session_id: Optional[str] = None,
+ partial_triples: List[IngestionTripleSet] = [],
+ current_triples: List[IngestionTripleSet] = [],
+ ) -> ScoutAgentResponse:
+ """
+ Given the provided text and partial/full triples, extract all the (missing) entities from the text.
+
+ Performs an LLM invocation (with optional targeting context), applies retries with exponential backoff on timeouts, enforces a per-invocation timeout, and accumulates token usage from the agent responses.
+
+ Parameters:
+ text: The input text to extract entities from.
+ targeting: Optional Node providing contextual targeting information (name, description, properties) to bias extraction.
+ brain_id: Identifier for the agent/brain configuration to use.
+ timeout: Maximum seconds to wait for a single agent invocation before treating it as a timeout.
+ max_retries: Maximum number of retry attempts for timed-out invocations using exponential backoff.
+ ingestion_session_id: Identifier for the ingestion session to use.
+ mode: Mode to use for the scout agent. "granular" for a more granular extraction, "coarse" to extract the most important entities only.
+ partial_triples: List of partial triples to use for the extraction.
+ current_triples: List of current triples to use for the extraction.
+ Returns:
+ A ScoutAgentResponse containing:
+ - entities: list of extracted ScoutEntity objects.
+ - input_tokens: accumulated input token count observed during the run.
+ - output_tokens: accumulated output token count observed during the run.
+
+ Raises:
+ TimeoutError: If a single invocation exceeds `timeout`, or if all retry attempts fail due to timeouts.
+ """
+ self._get_agent(
+ output_schema=_ScoutAgentResponse,
+ brain_id=brain_id,
+ mode="granular",
+ )
+ current_entities = []
+ for triple in current_triples:
+ if not triple.subject or not triple.object or not triple.event:
+ continue
+ current_entities.extend(
+ [
+ ScoutEntity(
+ type=triple.subject.type,
+ name=triple.subject.name,
+ description=triple.subject.description,
+ properties=triple.subject.properties or {},
+ happened_at=triple.subject.happened_at,
+ ),
+ ScoutEntity(
+ type=triple.object.type,
+ name=triple.object.name,
+ description=triple.object.description,
+ properties=triple.object.properties or {},
+ happened_at=triple.object.happened_at,
+ ),
+ ScoutEntity(
+ type=triple.event.type,
+ name=triple.event.name,
+ description=triple.event.description,
+ properties=triple.event.properties or {},
+ happened_at=triple.event.happened_at,
+ ),
+ ]
+ )
+ for triple in partial_triples:
+ current_entities.extend(
+ [
+ ScoutEntity(
+ type=triple.object.type,
+ name=triple.object.name,
+ description=triple.object.description,
+ properties=triple.object.properties or {},
+ ),
+ ScoutEntity(
+ type=triple.event.type,
+ name=triple.event.name,
+ description=triple.event.description,
+ ),
+ ]
+ )
+ prompt = prompt_registry.get(
+ "SCOUT_AGENT_EXTRACT_STRUCTURED_ENTITIES_PROMPT",
+ SCOUT_AGENT_EXTRACT_STRUCTURED_ENTITIES_PROMPT,
+ ).format(
+ text=text,
+ current_entities=current_entities,
+ )
+
+ def _invoke_agent():
+ return self.agent.invoke(
+ {
+ "messages": [
+ {
+ "role": "user",
+ "content": prompt,
+ }
+ ],
+ },
+ config={
+ "tags": ["scout_agent"],
+ "metadata": {
+ "agent": "scout_agent",
+ "brain_id": brain_id,
+ **(
+ {"ingestion_session_id": ingestion_session_id}
+ if ingestion_session_id
+ else {}
+ ),
+ },
+ },
+ )
+
+ @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():
+ """
+ Invoke the agent in a separate thread, enforce the configured timeout, and update token accounting from the agent's response.
+
+ Returns:
+ dict: The agent response dictionary.
+
+ Raises:
+ TimeoutError: If the agent invocation exceeds the specified timeout.
+ """
+ try:
+ 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,
+ "scout_agent",
+ )
+ return response
+ except FutureTimeoutError:
+ raise TimeoutError(
+ f"Scout agent invoke timed out after {timeout} seconds. "
+ "This may indicate a network issue or the LLM service is unresponsive."
+ )
+
+ try:
+ response = _invoke_agent_with_retry()
+ except RetryError as e:
+ last_attempt = e.last_attempt
+ raise TimeoutError(
+ f"Scout agent invoke failed after {last_attempt.attempt_number} attempts. "
+ f"Last error: {last_attempt.exception()}"
+ ) from last_attempt.exception()
+ except TimeoutError:
+ raise
+
+ structured = response.get("structured_response")
+ if isinstance(structured, dict):
+ try:
+ structured = _ScoutAgentResponse.model_validate(structured)
+ except Exception:
+ structured = None
+ if structured is None or not getattr(structured, "entities", None):
+ fallback = parse_structured_from_messages(
+ response.get("messages", []), _ScoutAgentResponse
+ )
+ if fallback is not None and getattr(fallback, "entities", None):
+ structured = fallback
+ if structured is None:
+ structured = _ScoutAgentResponse(entities=[])
+ return ScoutAgentResponse(
+ entities=[
+ ScoutEntity(**entity.model_dump(mode="json"))
+ for entity in structured.entities
+ ],
+ input_tokens=self.input_tokens,
+ output_tokens=self.output_tokens,
+ )
+
def run(
self,
text: str,
@@ -204,14 +396,16 @@ class ScoutAgent:
)
if mode == "granular":
prompt = prompt_registry.get(
- "SCOUT_AGENT_EXTRACT_ENTITIES_PROMPT", SCOUT_AGENT_EXTRACT_ENTITIES_PROMPT
+ "SCOUT_AGENT_EXTRACT_ENTITIES_PROMPT",
+ SCOUT_AGENT_EXTRACT_ENTITIES_PROMPT,
).format(
text=text,
targeting=targeting_str,
)
elif mode == "coarse":
prompt = prompt_registry.get(
- "SCOUT_AGENT_COARSE_EXTRACT_ENTITIES_PROMPT", SCOUT_AGENT_COARSE_EXTRACT_ENTITIES_PROMPT
+ "SCOUT_AGENT_COARSE_EXTRACT_ENTITIES_PROMPT",
+ SCOUT_AGENT_COARSE_EXTRACT_ENTITIES_PROMPT,
).format(
text=text,
targeting=targeting_str,
diff --git a/src/core/agents/tools/janitor_agent/JanitorAgentExecuteGraphReadOperationTool.py b/src/core/agents/tools/janitor_agent/JanitorAgentExecuteGraphReadOperationTool.py
index 181c7cd..5d41bc4 100644
--- a/src/core/agents/tools/janitor_agent/JanitorAgentExecuteGraphReadOperationTool.py
+++ b/src/core/agents/tools/janitor_agent/JanitorAgentExecuteGraphReadOperationTool.py
@@ -8,10 +8,55 @@ Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@
-----
"""
+import json
+import re
+
from langchain.tools import BaseTool
from src.adapters.graph import GraphAdapter
+_UNION_SPLIT_PATTERN = re.compile(r"\bUNION\s+ALL\b|\bUNION\b", re.IGNORECASE)
+
+
+def _split_union_query(query: str) -> list[str]:
+ parts = _UNION_SPLIT_PATTERN.split(query)
+ return [part.strip() for part in parts if part.strip()]
+
+
+def _merge_graph_read_results(results: list[str]) -> str:
+ merged_records = []
+ keys = None
+ errors = []
+
+ for result in results:
+ if result.startswith("Error executing graph operation"):
+ errors.append(result)
+ continue
+ try:
+ payload = json.loads(result)
+ except (json.JSONDecodeError, TypeError):
+ merged_records.append({"raw": result})
+ continue
+ if isinstance(payload, dict) and "records" in payload:
+ merged_records.extend(payload.get("records", []))
+ if keys is None and payload.get("keys"):
+ keys = payload.get("keys")
+ else:
+ merged_records.append(payload)
+
+ if not merged_records and errors:
+ return errors[0]
+
+ payload = {
+ "records": merged_records[:20],
+ "truncated": len(merged_records) > 20,
+ }
+ if keys is not None:
+ payload["keys"] = keys
+ if errors:
+ payload["partial_errors"] = errors
+ return json.dumps(payload, default=str)
+
class JanitorAgentExecuteGraphReadOperationTool(BaseTool):
"""
@@ -44,10 +89,12 @@ class JanitorAgentExecuteGraphReadOperationTool(BaseTool):
):
description: str = (
"Tool for executing read only operations on the knowledge graph. "
- "Use this tool to read information from the knowledge graph. "
- "The query should be a valid graph read only operation depending on the graph database type."
- "The query should be a valid JSON object with a 'query' key. "
- "{database_desc}."
+ "Prefer `search_entities` for entity lookup. "
+ "Use this tool for ad-hoc graph reads when search_entities is not enough. "
+ "The query should be a valid graph read only operation depending on the graph database type. "
+ "{database_desc}. "
+ "For UNION queries, every branch must RETURN the same column aliases "
+ "(e.g. RETURN n.uuid AS uuid, n.name AS name). "
"If you get an error, try again after fixing your query and don't give up. "
"If you get a result, return the result as a JSON object."
)
@@ -62,13 +109,24 @@ class JanitorAgentExecuteGraphReadOperationTool(BaseTool):
def _run(self, *args, **kwargs) -> str:
_query = ""
if len(args) > 0:
- _query = args[0]
+ arg_val = args[0]
+ if isinstance(arg_val, dict):
+ _query = arg_val.get("query", "")
+ else:
+ _query = arg_val
else:
_query = kwargs.get("query", "")
if len(_query) == 0:
return "No query provided in the arguments or kwargs"
- response = self.kg.execute_operation(_query, brain_id=self.brain_id)
+ if _UNION_SPLIT_PATTERN.search(_query):
+ subqueries = _split_union_query(_query)
+ if len(subqueries) > 1:
+ results = [
+ self.kg.execute_operation(subquery, brain_id=self.brain_id)
+ for subquery in subqueries
+ ]
+ return _merge_graph_read_results(results)
- return response
+ return self.kg.execute_operation(_query, brain_id=self.brain_id)
diff --git a/src/core/saving/ingestion_manager.py b/src/core/saving/ingestion_manager.py
index fd82377..44835a2 100644
--- a/src/core/saving/ingestion_manager.py
+++ b/src/core/saving/ingestion_manager.py
@@ -102,8 +102,9 @@ class IngestionManager:
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)
+ text_to_embed = (rel_data.description or "").strip() or rel_data.name
+ if text_to_embed:
+ v_rel = self.embeddings.embed_text(text_to_embed)
v_rel.metadata = {
**(self.metadata or {}),
"uuid": rel_data.uuid,
diff --git a/src/services/api/constants/requests.py b/src/services/api/constants/requests.py
index 960dfef..51aafce 100644
--- a/src/services/api/constants/requests.py
+++ b/src/services/api/constants/requests.py
@@ -3,14 +3,16 @@ File: /requests.py
Created Date: Monday October 20th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Monday February 2nd 2026 10:04:06 pm
+Last Modified: Sunday April 12th 2026 1:35:36 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
-from typing import List, Any, Optional, Tuple
+from typing import Any, List, Optional, Tuple, Union
+
from pydantic import BaseModel, Field, field_serializer
-from src.constants.data import Observation, TextChunk
+
+from src.constants.data import Observation, PartialNode, PartialPredicate, TextChunk
from src.constants.kg import (
EntitySynergy,
IdentificationParams,
@@ -55,16 +57,76 @@ class IngestionStructuredDataElement(BaseModel):
)
+class RequestPartialNode(PartialNode):
+ uuid: Optional[str] = Field(None, description="The id of the node.")
+ type: str = Field(description="The type of the node.")
+ happened_at: Optional[str] = Field(
+ None,
+ description="The date and time the node happened at if known otherwise None. Mostly used for event nodes.",
+ )
+
+
+class RequestPartialPredicate(PartialPredicate):
+ uuid: Optional[str] = Field(None, description="The id of the relationship.")
+ amount: Optional[Union[int, float]] = Field(
+ None,
+ description="The amount of the relationship, if it is a quantitative relationship.",
+ )
+
+
+class IngestionTripleSet(BaseModel):
+ subject: Optional[RequestPartialNode] = Field(
+ None,
+ description="The optional actor of the triple.",
+ )
+ subj_event: Optional[RequestPartialPredicate] = Field(
+ None,
+ description="The optional event predicate of the triple.",
+ )
+ event: RequestPartialNode
+ event_obj: RequestPartialPredicate
+ object: RequestPartialNode
+
+
+class PartialNodeFilter(BaseModel):
+ """
+ Partial node filter model.
+ """
+
+ name: Optional[str] = Field(
+ None,
+ description="The name of the node to filter by.",
+ )
+ type: Optional[str] = Field(
+ None,
+ description="The type of the node to filter by.",
+ )
+ uuid: Optional[str] = Field(
+ None,
+ description="The uuid of the node to filter by.",
+ )
+ meta_description: Optional[str] = Field(
+ None,
+ description="An extra description that explains what this node is about, helpful for entity resolution.",
+ )
+
+
class IngestionStructuredRequestBody(BaseModel):
"""
Request body for the structured ingestion endpoint.
"""
- data: List[IngestionStructuredDataElement]
- observate_for: Optional[List[str]] = Field(
- default=[],
- description="What to look for and describe in the data during observation. "
- "If not provided, the observations will be generic",
+ data: List[IngestionTripleSet] = Field(
+ ...,
+ description="The list of event-centric information triples to ingest.",
+ )
+ anchor: Optional[Union[str, PartialNodeFilter]] = Field(
+ None,
+ description="The related information to connect the structured data to.",
+ )
+ text: Optional[str] = Field(
+ ...,
+ description="Additional text context for the structured data.",
)
brain_id: str = Field(
default="default", description="The brain identifier to store the data in."
@@ -85,9 +147,13 @@ class RetrieveRequestResponse(BaseModel):
try:
from neo4j.graph import (
Node as NeoNode,
- Relationship as NeoRel,
+ )
+ from neo4j.graph import (
Path as NeoPath,
)
+ from neo4j.graph import (
+ Relationship as NeoRel,
+ )
except Exception:
NeoNode = NeoRel = NeoPath = tuple()
from src.constants.kg import Node as KGNode
diff --git a/src/services/api/pyproject.toml b/src/services/api/pyproject.toml
index aaff007..b1fb659 100644
--- a/src/services/api/pyproject.toml
+++ b/src/services/api/pyproject.toml
@@ -7,7 +7,7 @@ name = "common"
version = "0.1.0"
description = "API for the BrainAPI memory layer"
authors = [{ name = "Lumen Platforms Inc." }]
-license = { text = "Business Source License 1.1" }
+license = { text = "PolyForm Small Business License 1.0.0" }
readme = "README.md"
requires-python = ">=3.10"
diff --git a/src/utils/dates.py b/src/utils/dates.py
new file mode 100644
index 0000000..87cc3e0
--- /dev/null
+++ b/src/utils/dates.py
@@ -0,0 +1,27 @@
+from datetime import datetime
+from typing import Optional
+
+_DATE_INPUT_FORMATS = (
+ "%d/%m/%Y",
+ "%Y-%m-%d",
+ "%Y/%m/%d",
+ "%d-%m-%Y",
+ "%B %d, %Y",
+ "%b %d, %Y",
+ "%B %d %Y",
+ "%b %d %Y",
+ "%d %B %Y",
+ "%d %b %Y",
+)
+
+
+def normalize_date_string(value: Optional[str]) -> Optional[str]:
+ if not value or not isinstance(value, str):
+ return value
+ cleaned = value.strip()
+ for fmt in _DATE_INPUT_FORMATS:
+ try:
+ return datetime.strptime(cleaned, fmt).strftime("%d/%m/%Y")
+ except ValueError:
+ continue
+ return value
diff --git a/src/workers/tasks/ingestion.py b/src/workers/tasks/ingestion.py
index df4128a..81d2879 100644
--- a/src/workers/tasks/ingestion.py
+++ b/src/workers/tasks/ingestion.py
@@ -3,7 +3,7 @@ File: /ingestion.py
Created Date: Sunday October 19th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Thursday February 19th 2026 7:45:12 pm
+Last Modified: Wednesday March 4th 2026 9:35:41 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -15,16 +15,23 @@ import os
import tempfile
import time
import tomllib
-from pathlib import Path
-from uuid import uuid4
-from typing import List, Optional, Tuple
from concurrent.futures import (
Future,
ThreadPoolExecutor,
+)
+from concurrent.futures import (
TimeoutError as FutureTimeoutError,
)
+from pathlib import Path
+from typing import List, Optional, Tuple, TypedDict
+from uuid import uuid4
+
+from pydantic import BaseModel
+
from src.config import config
+from src.constants.agents import ArchitectAgentRelationship
from src.constants.data import (
+ KGChangeLogNodePropertiesUpdated,
KGChangeLogPredicateUpdatedProperty,
KGChanges,
KGChangesType,
@@ -32,35 +39,219 @@ from src.constants.data import (
PartialNode,
StructuredData,
TextChunk,
- KGChangeLogNodePropertiesUpdated,
)
-from src.constants.kg import Node, Predicate
-from src.constants.agents import ArchitectAgentRelationship
+from src.constants.kg import IdentificationParams, Node, Predicate
from src.constants.prompts.misc import NODE_DESCRIPTION_PROMPT
+from src.constants.tasks.ingestion import (
+ IngestionTaskArgs,
+ IngestionTaskDataType,
+ IngestionTaskTextArgs,
+)
+from src.core.agents.architect_agent import ArchitectAgent
+from src.core.agents.kg_agent import KGAgent
+from src.core.agents.scout_agent import ScoutAgent, ScoutEntity
from src.core.plugins.prompts import prompt_registry
from src.core.saving.auto_kg import enrich_kg_from_input
from src.core.saving.ingestion_manager import IngestionManager
-from src.services.api.constants.requests import IngestionStructuredRequestBody
+from src.services.api.constants.requests import (
+ IngestionStructuredRequestBody,
+ IngestionTripleSet,
+ PartialNodeFilter,
+)
from src.services.data.main import data_adapter
from src.services.input.agents import llm_small_adapter
from src.services.kg_agent.main import (
+ cache_adapter,
embeddings_adapter,
graph_adapter,
vector_store_adapter,
)
from src.services.observations.main import observations_agent
+from src.utils.dates import normalize_date_string
+from src.utils.similarity.vectors import cosine_similarity
from src.workers.app import ingestion_app
-from src.constants.tasks.ingestion import (
- IngestionTaskArgs,
- IngestionTaskDataType,
- IngestionTaskTextArgs,
-)
-from src.services.kg_agent.main import cache_adapter
PYPROJECT_PATH = Path(__file__).parent.parent.parent.parent / "pyproject.toml"
with open(PYPROJECT_PATH, "rb") as f:
BRAIN_VERSION = tomllib.load(f)["project"]["version"]
+NODE_RESOLUTION_SIMILARITY = 0.9
+EVENT_RESOLUTION_NAME_SIMILARITY = 0.7
+
+
+def _entity_key(entity) -> Tuple[str, str]:
+ return (
+ (entity.name or "").strip().lower(),
+ (entity.type or "").strip().lower(),
+ )
+
+
+def _is_same_graph_node(graph_node: Node, entity) -> bool:
+ if graph_node.uuid and graph_node.uuid == entity.uuid:
+ return True
+ same_name = (graph_node.name or "").strip().lower() == (
+ entity.name or ""
+ ).strip().lower()
+ labels = [str(label).strip().lower() for label in (graph_node.labels or [])]
+ return same_name and (entity.type or "").strip().lower() in labels
+
+
+def _normalize_relationship_dates(
+ relationships: List[ArchitectAgentRelationship],
+) -> None:
+ for relationship in relationships:
+ for entity in (relationship.tail, relationship.tip):
+ if (entity.type or "").strip().upper() == "DATE":
+ entity.name = normalize_date_string(entity.name)
+ if getattr(entity, "happened_at", None):
+ entity.happened_at = normalize_date_string(entity.happened_at)
+
+
+def _resolve_relationship_entities(
+ relationships: List[ArchitectAgentRelationship], brain_id: str
+) -> None:
+ unique_entities = {}
+ for relationship in relationships:
+ for entity in (relationship.tail, relationship.tip):
+ unique_entities.setdefault(_entity_key(entity), entity)
+
+ embeddings_cache: dict = {}
+
+ def _name_embedding(name: str):
+ key = (name or "").strip().lower()
+ if key not in embeddings_cache:
+ try:
+ vector = embeddings_adapter.embed_text(name)
+ embeddings_cache[key] = vector.embeddings if vector else None
+ except Exception:
+ embeddings_cache[key] = None
+ return embeddings_cache[key]
+
+ def _exact_match(entity) -> Optional[Node]:
+ try:
+ return graph_adapter.get_by_identification_params(
+ IdentificationParams(name=entity.name, entity_types=[entity.type]),
+ brain_id=brain_id,
+ entity_types=[entity.type],
+ )
+ except Exception:
+ return None
+
+ def _vector_match(entity) -> Optional[Node]:
+ embedding = _name_embedding(entity.name)
+ if not embedding:
+ return None
+ try:
+ candidates = vector_store_adapter.search_vectors(
+ embedding, brain_id=brain_id, store="nodes", k=5
+ )
+ except Exception:
+ return None
+ entity_type = (entity.type or "").strip().lower()
+ for candidate in candidates:
+ metadata = candidate.metadata or {}
+ candidate_uuid = metadata.get("uuid")
+ labels = [
+ str(label).strip().lower() for label in metadata.get("labels") or []
+ ]
+ if not candidate_uuid or entity_type not in labels:
+ continue
+ candidate_vectors = vector_store_adapter.get_by_ids(
+ [candidate.id], store="nodes", brain_id=brain_id
+ )
+ if not candidate_vectors or not candidate_vectors[0].embeddings:
+ continue
+ similarity = cosine_similarity(embedding, candidate_vectors[0].embeddings)
+ if similarity < NODE_RESOLUTION_SIMILARITY:
+ continue
+ node = graph_adapter.get_by_uuid(candidate_uuid, brain_id=brain_id)
+ if node:
+ return node
+ return None
+
+ resolutions: dict = {}
+ for key, entity in unique_entities.items():
+ if key[1] == "event":
+ continue
+ node = _exact_match(entity) or _vector_match(entity)
+ if node:
+ resolutions[key] = node
+
+ def _apply_resolutions():
+ for relationship in relationships:
+ for entity in (relationship.tail, relationship.tip):
+ node = resolutions.get(_entity_key(entity))
+ if node:
+ entity.uuid = node.uuid
+ entity.name = node.name
+
+ _apply_resolutions()
+ resolved_uuids = {node.uuid for node in resolutions.values()}
+
+ for key, event in unique_entities.items():
+ if key[1] != "event" or key in resolutions:
+ continue
+ anchor_uuids = set()
+ for relationship in relationships:
+ if (
+ _entity_key(relationship.tip) == key
+ and relationship.tail.uuid in resolved_uuids
+ ):
+ anchor_uuids.add(relationship.tail.uuid)
+ if (
+ _entity_key(relationship.tail) == key
+ and relationship.tip.uuid in resolved_uuids
+ ):
+ anchor_uuids.add(relationship.tip.uuid)
+ if not anchor_uuids:
+ continue
+ try:
+ neighbor_map = graph_adapter.get_neighbors(
+ list(anchor_uuids), of_types=["EVENT"], brain_id=brain_id
+ )
+ except Exception:
+ continue
+ candidate_counts: dict = {}
+ candidate_nodes: dict = {}
+ for pairs in (neighbor_map or {}).values():
+ seen = set()
+ for _, neighbor in pairs:
+ if not neighbor or not neighbor.uuid or neighbor.uuid in seen:
+ continue
+ seen.add(neighbor.uuid)
+ candidate_nodes[neighbor.uuid] = neighbor
+ candidate_counts[neighbor.uuid] = (
+ candidate_counts.get(neighbor.uuid, 0) + 1
+ )
+ event_embedding = _name_embedding(event.name)
+ if not event_embedding:
+ continue
+ event_date = normalize_date_string(getattr(event, "happened_at", None))
+ required_anchors = max(1, (len(anchor_uuids) + 1) // 2)
+ best = None
+ for candidate_uuid, count in candidate_counts.items():
+ if count < required_anchors:
+ continue
+ candidate = candidate_nodes[candidate_uuid]
+ candidate_date = normalize_date_string(
+ getattr(candidate, "happened_at", None)
+ or (candidate.properties or {}).get("happened_at")
+ )
+ if event_date and candidate_date and event_date != candidate_date:
+ continue
+ candidate_embedding = _name_embedding(candidate.name)
+ if not candidate_embedding:
+ continue
+ similarity = cosine_similarity(event_embedding, candidate_embedding)
+ if similarity < EVENT_RESOLUTION_NAME_SIMILARITY:
+ continue
+ if best is None or similarity > best[0]:
+ best = (similarity, candidate)
+ if best:
+ resolutions[key] = best[1]
+
+ _apply_resolutions()
+
def format_textual_data(data: dict, include_keys: bool = True) -> str:
def format_value(v):
@@ -256,6 +447,8 @@ def process_architect_relationships(self, args: dict):
relationships = [
ArchitectAgentRelationship(**rel_data) for rel_data in relationships_data
]
+ _normalize_relationship_dates(relationships)
+ _resolve_relationship_entities(relationships, brain_id)
with ThreadPoolExecutor(max_workers=10) as io_executor:
rel_embedding_futures: List[Tuple[Future, ArchitectAgentRelationship]] = []
@@ -265,6 +458,11 @@ def process_architect_relationships(self, args: dict):
f"[!] Skipping invalid relationship type: {type(relationship)}"
)
continue
+ if relationship.tail.uuid == relationship.tip.uuid:
+ print(
+ f"[!] Skipping self-relationship {relationship.name} on {relationship.tail.name}"
+ )
+ continue
future = io_executor.submit(
ingestion_manager.process_rel_vectors,
relationship,
@@ -311,11 +509,11 @@ def process_architect_relationships(self, args: dict):
if similar_rel:
similar_tail, _, similar_tip = similar_rel[0]
if (
- similar_tail.uuid == relationship.tail.uuid
- and similar_tip.uuid == relationship.tip.uuid
+ _is_same_graph_node(similar_tail, relationship.tail)
+ and _is_same_graph_node(similar_tip, relationship.tip)
) or (
- similar_tail.uuid == relationship.tip.uuid
- and similar_tip.uuid == relationship.tail.uuid
+ _is_same_graph_node(similar_tail, relationship.tip)
+ and _is_same_graph_node(similar_tip, relationship.tail)
):
vector_store_adapter.remove_vectors(
[v_rel_id],
@@ -354,7 +552,13 @@ def process_architect_relationships(self, args: dict):
labels=[node_data.type],
name=node_data.name,
description=node_data.description,
- properties=node_data.properties,
+ properties={
+ k: v
+ for k, v in (
+ node_data.properties or {}
+ ).items()
+ if v is not None
+ },
polarity=(
node_data.polarity
if node_data.polarity
@@ -398,10 +602,18 @@ def process_architect_relationships(self, args: dict):
uuid=relationship.uuid,
flow_key=relationship.flow_key,
name=relationship.name,
- description=relationship.description,
+ description=relationship.description or "",
properties={
- **(relationship.properties or {}),
- "v_id": v_rel_id,
+ **{
+ k: v
+ for k, v in (relationship.properties or {}).items()
+ if v is not None
+ },
+ **(
+ {"v_id": v_rel_id}
+ if v_rel_id is not None
+ else {}
+ ),
},
last_updated=datetime.datetime.now(),
amount=relationship.amount,
@@ -484,19 +696,13 @@ def process_architect_relationships(self, args: dict):
@ingestion_app.task(bind=True)
def ingest_structured_data(self, args: dict):
"""
- Ingest structured elements into the knowledge graph by creating nodes, embedding and storing vectors, generating observations, and saving structured-data records.
+ Ingest event-centric information triples into the knowledge graph enriching subgraphs and registering the information in the memory.
Parses `args` into an IngestionStructuredRequestBody and for each element:
- - creates a graph node with properties and metadata,
- - records node property change logs (KG changes),
- - embeds and stores node and element vectors in the vector store,
- - generates and stores observations (vectors and Observation records),
- - merges and saves structured-data records,
- - calls knowledge-graph enrichment for the element,
- and updates a task status cache with "started" and "completed" entries.
+ -
Parameters:
- args (dict): The raw task payload parsed into IngestionStructuredRequestBody (must include brain_id and data elements).
+ args (dict): The raw task payload parsed into IngestionStructuredRequestBody.
Returns:
str: The task id for this ingestion (self.request.id).
@@ -521,192 +727,141 @@ def ingest_structured_data(self, args: dict):
expires_in=3600 * 24 * 7,
)
- for element in payload.data:
- uuid = str(uuid4())
- _element = element.model_dump(mode="json")
- description = llm_small_adapter.generate_text(
- prompt=prompt_registry.get(
- "NODE_DESCRIPTION_PROMPT", NODE_DESCRIPTION_PROMPT
- ).format(
- element=json.dumps(
+ anchor = None
+ ingestion_manager = IngestionManager(
+ embeddings_adapter, vector_store_adapter, graph_adapter
+ )
+
+ if isinstance(payload.anchor, PartialNodeFilter) and payload.anchor.uuid:
+ anchor = graph_adapter.get_by_uuid(
+ payload.anchor.uuid, brain_id=payload.brain_id
+ )
+ if not anchor:
+ cache_adapter.set(
+ key=f"task:{self.request.id}",
+ value=json.dumps(
{
- **_element.get("json_data", {}),
- **_element.get("textual_data", {}),
- },
- indent=2,
- ),
- element_type=", ".join(element.types) if element.types else "thing",
- element_name=(
- element.identification_params.name
- if element.identification_params
- else "the thing"
+ "status": "failed",
+ "task_id": self.request.id,
+ "error": f"Anchor node with uuid {payload.anchor.uuid} not found",
+ }
),
+ brain_id=payload.brain_id,
+ expires_in=3600 * 24 * 7,
)
- )
- node = graph_adapter.add_nodes(
- [
- Node(
- uuid=uuid,
- labels=element.types,
- name=element.identification_params.name,
- description=description,
- properties={
- **(element.json_data if element.json_data else {}),
- **(
- element.identification_params.model_dump(mode="json")
- if element.identification_params
- else {}
- ),
- **(element.textual_data if element.textual_data else {}),
- },
- )
- ],
- brain_id=payload.brain_id,
- identification_params=element.identification_params.model_dump(
- mode="json"
- ),
- metadata={
- **(element.metadata if element.metadata else {}),
- },
- )[0]
-
- # Saving the node properties updated change
- kg_changes = KGChanges(
- type=KGChangesType.NODE_PROPERTIES_UPDATED,
- change=KGChangeLogNodePropertiesUpdated(
- node=PartialNode(
- **node.model_dump(mode="json"),
- ),
- properties=[
- KGChangeLogPredicateUpdatedProperty(
- property=property,
- previous_value=None,
- new_value=node.properties[property],
- )
- for property in node.properties
- ],
- ),
- )
- data_adapter.save_kg_changes(kg_changes, brain_id=payload.brain_id)
+ return
- existing_structured_data = data_adapter.get_structured_data_by_id(
- id=uuid, brain_id=payload.brain_id
+ else:
+ anchor = graph_adapter.get_by_identification_params(
+ IdentificationParams(
+ name=payload.anchor.name, entity_types=[payload.anchor.type]
+ )
)
-
- new_structured_data = None
-
- if existing_structured_data:
- new_structured_data = existing_structured_data.model_copy(
- update={
- "data": {
- **(
- existing_structured_data.data
- if existing_structured_data.data
- else {}
- ),
- **(element.json_data if element.json_data else {}),
- },
- "types": [
- *existing_structured_data.types,
- *element.types,
- ],
- "metadata": {
- **(
- existing_structured_data.metadata
- if existing_structured_data.metadata
- else {}
- ),
- **(element.metadata if element.metadata else {}),
- },
- "brain_version": BRAIN_VERSION,
- },
+ if not anchor:
+ txt = (
+ payload.anchor.name + "; " + (payload.anchor.meta_description or "")
)
- # TODO: update the changelogs here
- else:
- vector = embeddings_adapter.embed_text(node.name)
- vector.id = node.uuid
- vector.metadata = {
- "labels": node.labels,
- "name": node.name,
- "uuid": node.uuid,
- }
- vector_store_adapter.add_vectors(vectors=[vector], store="nodes")
- new_structured_data = StructuredData(
- id=uuid,
- data={
- **(element.json_data if element.json_data else {}),
- **(element.textual_data if element.textual_data else {}),
- },
- types=element.types,
- metadata=element.metadata,
- brain_version=BRAIN_VERSION,
+ embedded_anchor = embeddings_adapter.embed_text(txt)
+ matching_vector_nodes = vector_store_adapter.search_vectors(
+ embedded_anchor.embeddings,
+ store="nodes",
+ brain_id=payload.brain_id,
+ k=10,
)
-
- data_adapter.save_structured_data(
- structured_data=new_structured_data,
- brain_id=payload.brain_id,
- )
- vector = embeddings_adapter.embed_text(
- format_textual_data(element.textual_data, include_keys=False)
- + "\n"
- + (
- ", ".join(node.labels)
- if isinstance(node.labels, list)
- else node.labels
+ matching_nodes = graph_adapter.get_by_uuids(
+ [v.metadata.get("uuid") for v in matching_vector_nodes],
+ brain_id=payload.brain_id,
)
- + "\n"
- + node.name,
- )
- vector.id = node.uuid
- vector.metadata = {
- "labels": node.labels,
- "name": node.name,
- "uuid": node.uuid,
- }
- vector_store_adapter.add_vectors(vectors=[vector], store="data")
-
- text_content = format_textual_data(element.textual_data)
- observations = observations_agent.observe(
- text=text_content,
- observate_for=payload.observate_for,
- )
- for obs in observations:
- obs_vector = embeddings_adapter.embed_text(obs)
- obs_vector.id = str(uuid4())
- obs_vector.metadata = {
- "resource_id": node.uuid,
- "labels": node.labels,
- "name": node.name,
- }
- vector_store_adapter.add_vectors(
- vectors=[obs_vector], store="observations"
+ kg_agent = KGAgent(
+ llm_adapter=llm_small_adapter,
+ cache_adapter=cache_adapter,
+ kg=graph_adapter,
+ vector_store=vector_store_adapter,
+ embeddings=embeddings_adapter,
+ database_desc=graph_adapter.graphdb_description,
)
- if len(observations) > 0:
- data_adapter.save_observations(
- [
- Observation(
- id=node.uuid,
- text=obs,
- metadata={
- "labels": node.labels,
- "name": node.name,
- },
- resource_id=node.uuid,
- )
- for obs in observations
- ],
+ kg_agent_anchor_result = kg_agent.verify_entity_existence(
+ entity_name=payload.anchor.name,
+ entity_types=[payload.anchor.type],
+ entity_meta_description=payload.anchor.meta_description,
+ pool_nodes=matching_nodes,
brain_id=payload.brain_id,
)
-
- enrich_kg_from_input(
- (
- json.dumps(element.textual_data, indent=2)
- if len(element.textual_data.keys()) > 0
- else description
- ),
- targeting=node,
+ if kg_agent_anchor_result.exists:
+ anchor = kg_agent_anchor_result.node
+ elif payload.anchor:
+ anchor_entity = ScoutEntity(
+ name=payload.anchor.name,
+ type=payload.anchor.type,
+ description=payload.anchor.meta_description,
+ )
+ ingestion_manager.process_node_vectors(
+ anchor_entity, payload.brain_id
+ )
+ added_nodes = graph_adapter.add_nodes(
+ [
+ Node(
+ uuid=anchor_entity.uuid,
+ labels=[payload.anchor.type],
+ name=anchor_entity.name,
+ description=anchor_entity.description,
+ properties=anchor_entity.properties,
+ )
+ ],
+ brain_id=payload.brain_id,
+ )
+ anchor = added_nodes[0]
+
+ if payload.text:
+ current_triples: List[IngestionTripleSet] = []
+ partial_triples: List[IngestionTripleSet] = []
+ for triple in payload.data:
+ if triple.subject and triple.subj_event:
+ current_triples.append(triple)
+ else:
+ partial_triples.append(triple)
+
+ scout_agent = ScoutAgent(
+ llm_adapter=llm_small_adapter,
+ cache_adapter=cache_adapter,
+ kg=graph_adapter,
+ vector_store=vector_store_adapter,
+ embeddings=embeddings_adapter,
+ )
+ architect_agent = ArchitectAgent(
+ llm_adapter=llm_small_adapter,
+ cache_adapter=cache_adapter,
+ kg=graph_adapter,
+ vector_store=vector_store_adapter,
+ embeddings=embeddings_adapter,
+ ingestion_manager=ingestion_manager,
+ )
+ scout_agent_response = scout_agent.run_structured(
+ text=payload.text if payload.text else None,
brain_id=payload.brain_id,
+ timeout=180,
+ max_retries=3,
+ ingestion_session_id=self.request.id,
+ partial_triples=partial_triples,
+ current_triples=current_triples,
)
+ architect_agent.run_structured(
+ text=payload.text if payload.text else None,
+ entities=scout_agent_response.entities,
+ targeting=anchor,
+ brain_id=payload.brain_id,
+ timeout=180,
+ max_retries=3,
+ ingestion_session_id=self.request.id,
+ partial_triples=partial_triples,
+ current_triples=current_triples,
+ )
+
+ # TODO [SIR]: Add the triples to the knowledge graph + save the data + create the embeddings and save them -- save the text if present and find a way to save the rels (maybe isn't necessary?)
+
+ # TODO [SIR]: Create the observations ??
+ # NOTE [SIR]: structured is by definition ment to save precise information so the pipeline will only be granular/accurate
+ # NOTE [SIR]: for the text ingestion the lightweight can be converted into ingestion of only observations instead whole text
cache_adapter.set(
key=f"task:{self.request.id}",
@@ -747,12 +902,14 @@ def consolidate_graph_async(
Consolidate graph after all processing tasks complete.
"""
import os
+
import langsmith
+
+ from src.config import config
from src.core.layers.graph_consolidation.graph_consolidation import (
consolidate_graph,
)
from src.lib.redis.client import _redis_client
- from src.config import config
print(
f"[DEBUG (consolidate_graph_async)]: Starting consolidation for session {session_id}"
@@ -829,6 +986,7 @@ def ingest_file(self, content_b64: str, filename: str, brain_id: str):
ingest_data task per page.
"""
from celery.exceptions import OperationalError
+
try:
from docling.document_converter import DocumentConverter
except ImportError as exc:
diff --git a/tui/package-lock.json b/tui/package-lock.json
index 574fcc5..5b83b7c 100644
--- a/tui/package-lock.json
+++ b/tui/package-lock.json
@@ -1,12 +1,12 @@
{
- "name": "brainapi",
- "version": "0.1.0",
+ "name": "brainapi-tui",
+ "version": "0.2.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
- "name": "brainapi",
- "version": "0.1.0",
+ "name": "brainapi-tui",
+ "version": "0.2.0",
"license": "MIT",
"dependencies": {
"@clack/prompts": "^0.7.0",
diff --git a/tui/package.json b/tui/package.json
index 201b1cf..7b8fc38 100644
--- a/tui/package.json
+++ b/tui/package.json
@@ -1,6 +1,6 @@
{
"name": "brainapi-tui",
- "version": "0.1.1",
+ "version": "0.2.0",
"description": "Interactive installer and runtime CLI for BrainAPI.",
"license": "MIT",
"type": "module",