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.

fix(misc): - fixed base agent infinite final loop - added new brain's api format check alphanum + starting with a character - video on readme - updated dockerfile with transformer cache folder - fixed imports of instances

Christiancb15c8617489
diff --git a/.github/assets/screen-video.png b/.github/assets/screen-video.png
new file mode 100644
index 0000000..3f1fc37
Binary files /dev/null and b/.github/assets/screen-video.png differ
diff --git a/Dockerfile b/Dockerfile
index bd58b6a..ff3fe4c 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -12,7 +12,6 @@ ENV PYTHONUNBUFFERED=1 \
POETRY_NO_INTERACTION=1 \
POETRY_VIRTUALENVS_IN_PROJECT=true \
HF_HOME=/app/.cache \
- TRANSFORMERS_CACHE=/app/.cache \
SENTENCE_TRANSFORMERS_HOME=/app/.cache
RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -56,7 +55,6 @@ ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
PATH="/app/.venv/bin:$PATH" \
HF_HOME=/app/.cache \
- TRANSFORMERS_CACHE=/app/.cache \
SENTENCE_TRANSFORMERS_HOME=/app/.cache \
PIP_NO_CACHE_DIR=1 \
PIP_RETRIES=8 \
diff --git a/README.md b/README.md
index 1183a68..1afa45d 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,10 @@
<a href="https://brainapi.lumen-labs.ai/docs/v2">API Docs ↗</a>
</p>
+<a href="https://youtu.be/ECOleTRjl64?si=fBUALoYvsiUl-BPC">
+ <img src=".github/assets/screen-video.png" width="100%" alt="Watch the video" />
+</a>
+
<p align="center">
<img src="https://pbs.twimg.com/media/G6jXa2HXsAAJhDO?format=jpg&amp;name=4096x4096" alt="BrainAPI Concept Art" width="1000" style="border-radius:4px;box-shadow:0 2px 12px rgba(0,0,0,0.09);margin-bottom:16px;"/>
</p>
diff --git a/src/config.py b/src/config.py
index 912ca53..4473283 100644
--- a/src/config.py
+++ b/src/config.py
@@ -10,6 +10,7 @@ Modified By: Christian Nonis <[email protected]>
# pylint: disable=too-few-public-methods
+import logging
import os
from typing import Literal
import dotenv
@@ -20,6 +21,8 @@ _env_name = os.getenv("ENV")
_env_path = _project_root / f".env{'.' + _env_name if _env_name else ''}"
dotenv.load_dotenv(dotenv_path=_env_path)
+logger = logging.getLogger(__name__)
+
class AzureConfig:
"""
@@ -66,7 +69,7 @@ class GCPConfig:
f"Credentials file not found at: {credentials_path}. "
"Please set GCP_CREDENTIALS_PATH environment variable or place gcp_credentials.json in the project root."
)
- print("[GCPConfig] credentials_path: ", credentials_path)
+ logger.debug("GCP credentials_path: %s", credentials_path)
self.credentials_path = credentials_path
self.project_id = os.getenv("GCP_PROJECT_ID")
self.small_llm_model = os.getenv("GCP_SMALL_LLM_MODEL")
diff --git a/src/constants/prompts/architect_agent.py b/src/constants/prompts/architect_agent.py
index 6a36c49..036299b 100644
--- a/src/constants/prompts/architect_agent.py
+++ b/src/constants/prompts/architect_agent.py
@@ -213,7 +213,7 @@ Entities Found by Scout: [
]
Example architect_agent_create_relationship tool input 1:
-[
+{{"relationships": [
{{
"subject": "uuid_1",
"predicate": "MOVED",
@@ -230,7 +230,7 @@ Example architect_agent_create_relationship tool input 1:
"subject": "uuid_1",
"predicate": "ACCOMPLISHED_ACTION",
"description": "John knew 12 new friends in New York City",
- "amount": 12, // You must add the amount TO THE RELATIONSHIP PROPERTIES if there is any quantity specified in the text.
+ "amount": 12,
"object": "uuid_4"
}},
{{
@@ -243,16 +243,14 @@ Example architect_agent_create_relationship tool input 1:
"subject": "uuid_4",
"predicate": "TARGETED",
"description": "John knew 12 new friends in New York City",
- "object": "uuid_5"
- "amount": 12, // You must add the amount TO THE RELATIONSHIP PROPERTIES if there is any quantity specified in the text.
- }},
- ... more relationships (remember that you must map all the entities found by the scout) ...
- }}
-]
+ "object": "uuid_5",
+ "amount": 12
+ }}
+]}}
Example architect_agent_create_relationship tool output:
"OK"
Example architect_agent_create_relationship tool input 2:
-[
+{{"relationships": [
{{
"subject": "uuid_6",
"predicate": "EXPERIENCED",
@@ -270,9 +268,8 @@ Example architect_agent_create_relationship tool input 2:
"predicate": "HAPPENED_WITHIN",
"description": "Mary was in San Francisco when John went to New York City",
"object": "uuid_2"
- }},
- ... more relationships ...
-]
+ }}
+]}}
Example architect_agent_create_relationship tool output 2:
"OK"
@@ -418,7 +415,7 @@ Entities Found by Scout: [
]
Example architect_agent_create_relationship tool input 1:
-[
+{{"relationships": [
{{
"subject": "uuid_1",
"predicate": "MOVED",
@@ -435,7 +432,7 @@ Example architect_agent_create_relationship tool input 1:
"subject": "uuid_1",
"predicate": "ACCOMPLISHED_ACTION",
"description": "John knew 12 new friends in New York City",
- "amount": 12, // You must add the amount TO THE RELATIONSHIP PROPERTIES if there is any quantity specified in the text.
+ "amount": 12,
"object": "uuid_4"
}},
{{
@@ -448,14 +445,14 @@ Example architect_agent_create_relationship tool input 1:
"subject": "uuid_4",
"predicate": "TARGETED",
"description": "John knew 12 new friends in New York City",
- "object": "uuid_5"
- "amount": 12, // You must add the amount TO THE RELATIONSHIP PROPERTIES if there is any quantity specified in the text.
- }},
- ... more relationships (remember that you must map all the entities found by the scout) ...
- }}
-]
+ "object": "uuid_5",
+ "amount": 12
+ }}
+]}}
+Example architect_agent_create_relationship tool output:
+"OK"
Example architect_agent_create_relationship tool input 2:
-[
+{{"relationships": [
{{
"subject": "uuid_6",
"predicate": "EXPERIENCED",
@@ -473,9 +470,8 @@ Example architect_agent_create_relationship tool input 2:
"predicate": "HAPPENED_WITHIN",
"description": "Mary was in San Francisco when John went to New York City",
"object": "uuid_2"
- }},
- ... more relationships ...
-]
+ }}
+]}}
Your workflow must be:
1. First of all call the architect_agent_get_remaining_entities_to_process tool to get the entities found by the scout.
diff --git a/src/core/agents/architect_agent.py b/src/core/agents/architect_agent.py
index 0b09fe2..4d36e1e 100644
--- a/src/core/agents/architect_agent.py
+++ b/src/core/agents/architect_agent.py
@@ -3,7 +3,7 @@ File: /architect_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: Sunday March 22nd 2026 10:11:53 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -230,7 +230,8 @@ class ArchitectAgent:
elif type_ == "tooler":
if mode == "granular":
system_prompt = prompt_registry.get(
- "ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT", ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT
+ "ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT",
+ ARCHITECT_AGENT_TOOLER_SYSTEM_PROMPT,
).format(
extra_system_prompt=(
extra_system_prompt if extra_system_prompt else ""
@@ -238,7 +239,8 @@ class ArchitectAgent:
)
elif mode == "coarse":
system_prompt = prompt_registry.get(
- "ARCHITECT_AGENT_TOOLER_COARSE_SYSTEM_PROMPT", ARCHITECT_AGENT_TOOLER_COARSE_SYSTEM_PROMPT
+ "ARCHITECT_AGENT_TOOLER_COARSE_SYSTEM_PROMPT",
+ ARCHITECT_AGENT_TOOLER_COARSE_SYSTEM_PROMPT,
).format(
extra_system_prompt=(
extra_system_prompt if extra_system_prompt else ""
@@ -337,7 +339,8 @@ class ArchitectAgent:
{
"role": "user",
"content": prompt_registry.get(
- "ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT", ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT
+ "ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT",
+ ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT,
).format(
text=text,
entities=[entity.model_dump(mode="json") for entity in ent],
diff --git a/src/core/agents/core/agent_base.py b/src/core/agents/core/agent_base.py
index 8e35a64..a4619cb 100644
--- a/src/core/agents/core/agent_base.py
+++ b/src/core/agents/core/agent_base.py
@@ -20,6 +20,7 @@ warnings.filterwarnings(
class AgentBase:
model: BaseChatModel
+ _base_model: BaseChatModel
system_prompt: str
tools: list[BaseTool]
output_schema: BaseModel | None
@@ -36,7 +37,7 @@ class AgentBase:
debug: bool = False,
thinking: bool = False,
):
- self.model = model
+ self._base_model = model
self.system_prompt = system_prompt
self.tools = tools
self.output_schema = output_schema
@@ -45,18 +46,33 @@ class AgentBase:
self.thinking = thinking
if self.thinking:
- self.model.extra_body = {
- **self.model.extra_body,
+ model.extra_body = {
+ **model.extra_body,
"think": (
("high" if self.thinking else "low")
- if "gpt" in self.model and "oss" in self.model
+ if "gpt" in model and "oss" in model
else (True if self.thinking else False)
),
}
+ self._tools_bound = False
+ if tools:
+ try:
+ self.model = model.bind_tools(tools)
+ self._tools_bound = True
+ except Exception:
+ self.model = model
+ else:
+ self.model = model
+
+ def _unbind_tools(self) -> None:
+ if self._tools_bound:
+ self.model = self._base_model
+ self._tools_bound = False
+
def _model_requires_thought_signatures(self) -> bool:
- mod = getattr(type(self.model), "__module__", "") or ""
- name = getattr(type(self.model), "__name__", "") or ""
+ mod = getattr(type(self._base_model), "__module__", "") or ""
+ name = getattr(type(self._base_model), "__name__", "") or ""
return "vertex" in mod.lower() or "Vertex" in name
def _get_effective_output_schema(self):
diff --git a/src/core/agents/core/invoke_loop.py b/src/core/agents/core/invoke_loop.py
index c41aafc..406ed2c 100644
--- a/src/core/agents/core/invoke_loop.py
+++ b/src/core/agents/core/invoke_loop.py
@@ -17,6 +17,48 @@ from .prompts import build_system_internal_prompt
from .structured_output import finalize_structured_response, parse_structured_output
+def _infer_tool_from_parsed(parsed: dict, tools: list):
+ if not parsed or not tools:
+ return None, None
+ if (
+ len(parsed) == 1
+ and "entities" in parsed
+ and isinstance(parsed["entities"], list)
+ ):
+ for t in tools:
+ t_schema = getattr(t, "args_schema", None)
+ if not isinstance(t_schema, dict):
+ continue
+ required = t_schema.get("required", [])
+ if len(required) == 1:
+ prop = t_schema.get("properties", {}).get(required[0], {})
+ if prop.get("type") == "array":
+ return t.name, {required[0]: parsed["entities"]}
+ return None, None
+ for t in tools:
+ t_schema = getattr(t, "args_schema", None)
+ if not isinstance(t_schema, dict):
+ continue
+ required = t_schema.get("required", [])
+ if required and all(k in parsed for k in required):
+ return t.name, parsed
+ return None, None
+
+
+def _log_token_usage(response) -> None:
+ usage = getattr(response, "usage_metadata", None)
+ if usage is None and isinstance(response, dict):
+ usage = response.get("usage_metadata")
+ if usage:
+ details = usage.get("input_token_details") or {}
+ cached = details.get("cache_read", 0)
+ print(
+ f"[TOKENS] in={usage.get('input_tokens', 0)} "
+ f"out={usage.get('output_tokens', 0)}"
+ + (f" cached={cached}" if cached else "")
+ )
+
+
def run_invoke_loop(agent, messages, config):
model_responses = []
agent.messages = []
@@ -28,6 +70,7 @@ def run_invoke_loop(agent, messages, config):
agent.output_schema,
agent.model,
agent.thinking,
+ tools_bound=agent._tools_bound,
)
+ "\n"
+ agent.system_prompt,
@@ -56,6 +99,7 @@ def run_invoke_loop(agent, messages, config):
_n_message = agent.model.invoke(agent.messages, config)
_n_message = normalize_invoke_response(_n_message)
model_responses.append(_n_message)
+ _log_token_usage(_n_message)
raw_content = normalize_message_content(
_n_message.get("content")
if isinstance(_n_message, dict)
@@ -76,9 +120,22 @@ def run_invoke_loop(agent, messages, config):
else:
_invoke_attempts = 3
for _invoke_attempt in range(_invoke_attempts):
- _n_message = agent.model.invoke(agent.messages, config)
+ try:
+ _n_message = agent.model.invoke(agent.messages, config)
+ except Exception as _invoke_exc:
+ _exc_str = str(_invoke_exc).lower()
+ if agent._tools_bound and (
+ "invalid message format" in _exc_str
+ or "invalid_request_error" in _exc_str
+ or "tool" in _exc_str
+ ):
+ agent._unbind_tools()
+ _n_message = agent.model.invoke(agent.messages, config)
+ else:
+ raise
_n_message = normalize_invoke_response(_n_message)
model_responses.append(_n_message)
+ _log_token_usage(_n_message)
raw_content = normalize_message_content(
_n_message.get("content")
if isinstance(_n_message, dict)
@@ -158,6 +215,13 @@ def run_invoke_loop(agent, messages, config):
existing
)
break
+ _outer_finish = get_finish_reason_from_response(_n_message)
+ if _outer_finish and str(_outer_finish).upper() in (
+ "MAX_TOKENS",
+ "LENGTH",
+ "MAX_LENGTH",
+ ):
+ break
if raw_tc:
pass
elif content_breaks_ollama_tool_parse(n_message):
@@ -230,7 +294,10 @@ def run_invoke_loop(agent, messages, config):
tool_call_id_counter += 1
n_message = None
continue
- agent.messages.append(assistant_msg)
+ if raw_tc and not agent._model_requires_thought_signatures():
+ agent.messages.append(_n_message)
+ else:
+ agent.messages.append(assistant_msg)
tool_name, tool_input = _recovered_name, _recovered_input
if tool_name is None:
tool_name, tool_input = get_tool_call_from_response(_n_message)
@@ -238,6 +305,10 @@ def run_invoke_loop(agent, messages, config):
parsed = strip_json(n_message)
tool_name = parsed.get("tool_name")
tool_input = parsed.get("tool_input")
+ if tool_name is None and agent.tools:
+ tool_name, tool_input = _infer_tool_from_parsed(
+ parsed, agent.tools
+ )
if tool_name is None:
tool_name, tool_input = get_tool_call_from_malformed_response(
_n_message
@@ -248,21 +319,87 @@ def run_invoke_loop(agent, messages, config):
None,
)
if tool is not None:
- n_message = agent._call_tool(tool, tool_input)
- agent.messages.append(
- {
- "role": "tool",
- "content": n_message,
- "tool_call_id": tool_call_id,
- }
- )
- tool_call_id_counter += 1
+ serialized_tcs = assistant_msg.get("tool_calls") or []
+ if raw_tc and len(serialized_tcs) > 1:
+ for _tc in serialized_tcs:
+ _tc_name = _tc.get("name")
+ _tc_args = _tc.get("args") or {}
+ _tc_id = _tc.get("id") or f"call_{tool_call_id_counter}"
+ _tc_tool = next(
+ (t for t in agent.tools if t.name == _tc_name), None
+ )
+ _tc_result = (
+ agent._call_tool(_tc_tool, _tc_args)
+ if _tc_tool
+ else f"Tool {_tc_name} not found."
+ )
+ agent.messages.append(
+ {
+ "role": "tool",
+ "content": _tc_result,
+ "tool_call_id": _tc_id,
+ }
+ )
+ n_message = _tc_result
+ tool_call_id_counter += 1
+ else:
+ n_message = agent._call_tool(tool, tool_input)
+ agent.messages.append(
+ {
+ "role": "tool",
+ "content": n_message,
+ "tool_call_id": tool_call_id,
+ }
+ )
+ tool_call_id_counter += 1
_did_retry_recovered_next_tool_call = False
+ _last_called_tool_name = tool_name
while True:
_next_attempts = 3
for _next_attempt in range(_next_attempts):
- next_response = agent.model.invoke(agent.messages, config)
+ if (
+ not agent._model_requires_thought_signatures()
+ and agent.messages
+ and isinstance(agent.messages[-1], dict)
+ and agent.messages[-1].get("role") == "tool"
+ ):
+ _last_tool = agent.messages[-1]
+ _last_content = _last_tool.get("content") or ""
+ if (
+ "\nContinue with the next steps." not in _last_content
+ and "\nDo NOT call" not in _last_content
+ ):
+ if _last_called_tool_name:
+ _hint = (
+ f"\n\nYou already called"
+ f" '{_last_called_tool_name}'."
+ " Do NOT call this same tool again."
+ " Proceed to the next step of the"
+ " workflow."
+ )
+ else:
+ _hint = "\n\nContinue with the next steps."
+ agent.messages[-1] = {
+ **_last_tool,
+ "content": _last_content + _hint,
+ }
+ try:
+ next_response = agent.model.invoke(agent.messages, config)
+ except Exception as _next_exc:
+ _next_exc_str = str(_next_exc).lower()
+ if agent._tools_bound and (
+ "invalid message format" in _next_exc_str
+ or "invalid_request_error" in _next_exc_str
+ or "tool" in _next_exc_str
+ ):
+ agent._unbind_tools()
+ next_response = agent.model.invoke(
+ agent.messages, config
+ )
+ else:
+ raise
next_response = normalize_invoke_response(next_response)
+ _log_token_usage(next_response)
if agent.debug:
print(
"[DEBUG (agent_base)]: Next response: ",
@@ -365,6 +502,14 @@ def run_invoke_loop(agent, messages, config):
] = existing
break
break
+ _next_finish = get_finish_reason_from_response(next_response)
+ if _next_finish and str(_next_finish).upper() in (
+ "MAX_TOKENS",
+ "LENGTH",
+ "MAX_LENGTH",
+ ):
+ n_message = next_content or ""
+ break
if next_raw_tc:
pass
elif content_breaks_ollama_tool_parse(next_content):
@@ -454,7 +599,10 @@ def run_invoke_loop(agent, messages, config):
)
tool_call_id_counter += 1
continue
- agent.messages.append(next_assistant_msg)
+ if next_raw_tc and not agent._model_requires_thought_signatures():
+ agent.messages.append(next_response)
+ else:
+ agent.messages.append(next_assistant_msg)
next_tool_name, next_tool_input = (
_next_recovered_name,
_next_recovered_input,
@@ -469,6 +617,10 @@ def run_invoke_loop(agent, messages, config):
)
next_tool_name = next_parsed.get("tool_name")
next_tool_input = next_parsed.get("tool_input")
+ if next_tool_name is None and agent.tools:
+ next_tool_name, next_tool_input = (
+ _infer_tool_from_parsed(next_parsed, agent.tools)
+ )
if next_tool_name is None:
next_tool_name, next_tool_input = (
get_tool_call_from_malformed_response(next_response)
@@ -479,20 +631,60 @@ def run_invoke_loop(agent, messages, config):
None,
)
if tool is not None:
- n_message = agent._call_tool(tool, next_tool_input)
- if agent.debug:
- print(
- "[DEBUG (agent_base)]: Tool result: ",
- n_message,
- )
- agent.messages.append(
- {
- "role": "tool",
- "content": n_message,
- "tool_call_id": next_tool_call_id,
- }
+ next_serialized_tcs = (
+ next_assistant_msg.get("tool_calls") or []
)
- tool_call_id_counter += 1
+ if next_raw_tc and len(next_serialized_tcs) > 1:
+ for _tc in next_serialized_tcs:
+ _tc_name = _tc.get("name")
+ _tc_args = _tc.get("args") or {}
+ _tc_id = (
+ _tc.get("id") or f"call_{tool_call_id_counter}"
+ )
+ _tc_tool = next(
+ (
+ t
+ for t in agent.tools
+ if t.name == _tc_name
+ ),
+ None,
+ )
+ _tc_result = (
+ agent._call_tool(_tc_tool, _tc_args)
+ if _tc_tool
+ else f"Tool {_tc_name} not found."
+ )
+ if agent.debug:
+ print(
+ "[DEBUG (agent_base)]: Tool result: ",
+ _tc_result,
+ )
+ agent.messages.append(
+ {
+ "role": "tool",
+ "content": _tc_result,
+ "tool_call_id": _tc_id,
+ }
+ )
+ n_message = _tc_result
+ tool_call_id_counter += 1
+ _last_called_tool_name = next_tool_name
+ else:
+ n_message = agent._call_tool(tool, next_tool_input)
+ if agent.debug:
+ print(
+ "[DEBUG (agent_base)]: Tool result: ",
+ n_message,
+ )
+ agent.messages.append(
+ {
+ "role": "tool",
+ "content": n_message,
+ "tool_call_id": next_tool_call_id,
+ }
+ )
+ tool_call_id_counter += 1
+ _last_called_tool_name = next_tool_name
else:
agent.messages.append(
{
diff --git a/src/core/agents/core/prompts.py b/src/core/agents/core/prompts.py
index 151f529..8ad50c0 100644
--- a/src/core/agents/core/prompts.py
+++ b/src/core/agents/core/prompts.py
@@ -6,18 +6,22 @@ from langchain.tools import BaseTool
from .schema_utils import flatten_json_schema_for_llm, get_output_schema_json_schema
-def format_tool_description(tool: BaseTool) -> str:
+def _tool_schema_str(tool: BaseTool) -> str:
args = getattr(tool, "args_schema", None)
if hasattr(args, "model_json_schema"):
- input_str = json.dumps(args.model_json_schema(), indent=2)
- elif isinstance(args, dict):
- input_str = json.dumps(args, indent=2)
- else:
- input_str = str(args) if args is not None else "N/A"
- return f"""
- {tool.name}: {tool.description}
- Input schema: {input_str}
- """
+ return json.dumps(args.model_json_schema())
+ if isinstance(args, dict):
+ return json.dumps(args)
+ return str(args) if args is not None else ""
+
+
+def format_tool_description(tool: BaseTool, include_schema: bool = False) -> str:
+ base = f"- {tool.name}: {tool.description}"
+ if include_schema:
+ schema = _tool_schema_str(tool)
+ if schema:
+ return f"{base} Schema: {schema}"
+ return base
def build_system_internal_prompt(
@@ -25,28 +29,20 @@ def build_system_internal_prompt(
output_schema: Any,
model: Any,
thinking: bool,
+ tools_bound: bool = True,
) -> str:
tools_block = ""
if tools:
- tools_list = "\n".join(format_tool_description(t) for t in tools)
- tools_block = f"""
- You are able to use the following tools:
- {tools_list}
-
- The input to those tools if required must be ONLY the input specified in the tool's info.
-
- To call a tool you can use your tool calling caapability or output a JSON object with the following structure:
- ```json
- {{
- "tool_name": "tool_name",
- "tool_input": "tool_input"
- }}
- ```
- {"You MUST NOT use your internal function calling capability, if you want to use a tool just output the json above and nothing else, the system will recall you back to continue the workflow with the output of the tool." if 'gpt' in model and 'oss' in model else ''}
-
- Proceed ONLY one tool at a time, when requesting a tool you must not use more than one tool in the same output, after requesting a tool
- you will be recalled back by the system to continue the workflow.
- """
+ tools_list = "\n".join(
+ format_tool_description(t, include_schema=not tools_bound) for t in tools
+ )
+ _oss = "gpt" in str(model) and "oss" in str(model)
+ _json_fallback = (
+ 'If you cannot use native tool calling, output ONLY: {"tool_name": "...", "tool_input": {...}} and nothing else.'
+ if _oss
+ else ""
+ )
+ tools_block = f"""Tools:\n{tools_list}\n\nCall one tool at a time. {_json_fallback}"""
output_schema_block = ""
if output_schema:
schema_dict = get_output_schema_json_schema(output_schema)
diff --git a/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py b/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py
index a4bbe20..463c92d 100644
--- a/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py
+++ b/src/core/agents/tools/architect_agent/ArchitectAgentCreateRelationshipTool.py
@@ -3,7 +3,7 @@ File: /ArchitectAgentCreateRelationshipTool.py
Created Date: Wednesday January 14th 2026
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]>
-----
"""
@@ -77,7 +77,7 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):
"Returns a summary of the created relationships to review them before creating them."
)
entities_dict = entities if entities is not None else {}
-
+
args_schema: dict = {
"type": "object",
"properties": {
@@ -92,9 +92,12 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):
"properties": {
"subject": {
"type": "string",
- "description": "The uuid of the subject"
- + """ OR a TYPE:NAME that you want to use if the element is missing in the entities list, it must only be a valid uuid or a TYPE:NAME string"""
- if mode == "coarse" else "",
+ "description": (
+ "The uuid of the subject, it must be a valid uuid format (4-8-4-4-12 hexadecimal character strings) that is present in the entities list"
+ + """ OR a TYPE:NAME that you want to use if the element is missing in the entities list, it must only be a valid uuid or a TYPE:NAME string"""
+ if mode == "coarse"
+ else ""
+ ),
},
"predicate": {
"type": "string",
@@ -102,9 +105,12 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):
},
"object": {
"type": "string",
- "description": "The uuid of the object"
- + """ OR a TYPE:NAME that you want to use if the element is missing in the entities list, it must only be a valid uuid or a TYPE:NAME string"""
- if mode == "coarse" else "",
+ "description": (
+ "The uuid of the object, it must be a valid uuid format (4-8-4-4-12 hexadecimal character strings) that is present in the entities list"
+ + """ OR a TYPE:NAME that you want to use if the element is missing in the entities list, it must only be a valid uuid or a TYPE:NAME string"""
+ if mode == "coarse"
+ else ""
+ ),
},
"description": {
"type": "string",
@@ -121,7 +127,7 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):
},
"required": ["relationships"],
}
-
+
super().__init__(
architect_agent=architect_agent,
description=description,
@@ -426,7 +432,7 @@ class ArchitectAgentCreateRelationshipTool(BaseTool):
)
required_new_nodes = getattr(janitor_response, "required_new_nodes", [])
-
+
if required_new_nodes:
for node in required_new_nodes:
scout_entity = ScoutEntity(
diff --git a/src/core/agents/tools/janitor_agent/JanitorAgentSearchRelationshipTool.py b/src/core/agents/tools/janitor_agent/JanitorAgentSearchRelationshipTool.py
index 00ba1dc..fce3c3c 100644
--- a/src/core/agents/tools/janitor_agent/JanitorAgentSearchRelationshipTool.py
+++ b/src/core/agents/tools/janitor_agent/JanitorAgentSearchRelationshipTool.py
@@ -138,14 +138,32 @@ class JanitorAgentSearchRelationshipsTool(BaseTool):
_query.get("subject") + " -> " + _query.get("object")
] = "Graph does not contain any relationships between the subject and object"
else:
+ serialized = []
+ for f in founds:
+ if isinstance(f, tuple):
+ subject_node, predicate, object_node = f
+ entry = {
+ "subject": strip_properties(
+ [subject_node.model_dump(mode="json")],
+ pop_also=["last_updated", "v_id", "properties"],
+ )[0],
+ "predicate": strip_properties(
+ [predicate.model_dump(mode="json")],
+ pop_also=["last_updated", "v_id", "properties"],
+ )[0],
+ "object": strip_properties(
+ [object_node.model_dump(mode="json")],
+ pop_also=["last_updated", "v_id", "properties"],
+ )[0],
+ }
+ else:
+ entry = strip_properties(
+ [f.model_dump(mode="json")],
+ pop_also=["last_updated", "v_id", "properties"],
+ )[0]
+ serialized.append(entry)
found_relationships[
_query.get("subject") + " -> " + _query.get("object")
- ] = [
- strip_properties(
- [f.model_dump(mode="json")],
- pop_also=["last_updated", "v_id", "properties"],
- )[0]
- for f in founds
- ]
+ ] = serialized
return json.dumps(found_relationships, indent=4)
diff --git a/src/core/layers/graph_consolidation/graph_consolidation.py b/src/core/layers/graph_consolidation/graph_consolidation.py
index bc95e68..3f4d721 100644
--- a/src/core/layers/graph_consolidation/graph_consolidation.py
+++ b/src/core/layers/graph_consolidation/graph_consolidation.py
@@ -46,7 +46,7 @@ from src.services.input.agents import (
llm_small_adapter,
vector_store_adapter,
)
-from src.services.observations.main import llm_adapter
+from src.core.instances import llm_small_adapter as llm_adapter
from src.lib.neo4j.client import _neo4j_client
from src.utils.tokens import merge_token_details, token_detail_from_token_counts
diff --git a/src/lib/embeddings/client_small.py b/src/lib/embeddings/client_small.py
index 3904c4c..2f916b9 100644
--- a/src/lib/embeddings/client_small.py
+++ b/src/lib/embeddings/client_small.py
@@ -8,18 +8,28 @@ Modified By: Christian Nonis <[email protected]>
-----
"""
-from sentence_transformers import SentenceTransformer
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
from src.adapters.interfaces.embeddings import EmbeddingsClient
from src.config import config
-_model = SentenceTransformer(config.embeddings.small_model)
+if TYPE_CHECKING:
+ from sentence_transformers import SentenceTransformer
+_model: SentenceTransformer | None = None
-class EmbeddingsClientSmall(EmbeddingsClient):
- def __init__(self):
- self.model = _model
+def _get_model() -> SentenceTransformer:
+ global _model
+ if _model is None:
+ from sentence_transformers import SentenceTransformer
+ _model = SentenceTransformer(config.embeddings.small_model)
+ return _model
+
+
+class EmbeddingsClientSmall(EmbeddingsClient):
def embed_text(self, text: str) -> list[float]:
"""
Return the embedding vector for the given text using the configured model.
@@ -30,7 +40,7 @@ class EmbeddingsClientSmall(EmbeddingsClient):
Returns:
list[float]: Dense embedding vector representing the input text.
"""
- embedding = self.model.encode(text, convert_to_numpy=True)
+ embedding = _get_model().encode(text, convert_to_numpy=True)
return embedding.tolist()
def embed_texts(self, texts: list[str]) -> list[list[float]]:
@@ -43,7 +53,7 @@ class EmbeddingsClientSmall(EmbeddingsClient):
Returns:
list[list[float]]: Dense embedding vectors representing the input texts.
"""
- embeddings = self.model.encode(texts, convert_to_numpy=True)
+ embeddings = _get_model().encode(texts, convert_to_numpy=True)
return embeddings.tolist()
diff --git a/src/lib/embeddings/local.py b/src/lib/embeddings/local.py
index 702b780..9a0976f 100644
--- a/src/lib/embeddings/local.py
+++ b/src/lib/embeddings/local.py
@@ -9,14 +9,27 @@ Modified By: Christian Nonis <[email protected]>
-----
"""
-from sentence_transformers import SentenceTransformer
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
from src.adapters.interfaces.embeddings import EmbeddingsClient
from src.config import config
+if TYPE_CHECKING:
+ from sentence_transformers import SentenceTransformer
+
E5_PREFIX = "passage: "
-_model = SentenceTransformer(config.embeddings.local_model)
+_model: SentenceTransformer | None = None
+
+
+def _get_model() -> SentenceTransformer:
+ global _model
+ if _model is None:
+ from sentence_transformers import SentenceTransformer
+ _model = SentenceTransformer(config.embeddings.local_model)
+ return _model
class EmbeddingError(Exception):
@@ -24,9 +37,6 @@ class EmbeddingError(Exception):
class LocalEmbeddingsClient(EmbeddingsClient):
- def __init__(self):
- self.model = _model
-
def _prefix(self, text: str) -> str:
if text.strip().lower().startswith(E5_PREFIX.strip().lower()):
return text
@@ -35,7 +45,7 @@ class LocalEmbeddingsClient(EmbeddingsClient):
def embed_text(self, text: str) -> list[float]:
try:
prefixed = self._prefix(text)
- embedding = self.model.encode(prefixed, convert_to_numpy=True)
+ embedding = _get_model().encode(prefixed, convert_to_numpy=True)
return embedding.tolist()
except Exception as e:
raise EmbeddingError(f"Embedding failed: {e}") from e
@@ -43,7 +53,7 @@ class LocalEmbeddingsClient(EmbeddingsClient):
def embed_texts(self, texts: list[str]) -> list[list[float]]:
try:
prefixed = [self._prefix(t) for t in texts]
- embeddings = self.model.encode(prefixed, convert_to_numpy=True)
+ embeddings = _get_model().encode(prefixed, convert_to_numpy=True)
return embeddings.tolist()
except Exception as e:
raise EmbeddingError(f"Embedding failed: {e}") from e
diff --git a/src/services/api/controllers/system.py b/src/services/api/controllers/system.py
index ea2eb93..25ba1a0 100644
--- a/src/services/api/controllers/system.py
+++ b/src/services/api/controllers/system.py
@@ -4,7 +4,7 @@ Created Date: Monday December 1st 2025
Author: Christian Nonis <[email protected]>
-----
Last Modified: Monday December 1st 2025 10:13:27 pm
-Modified By: the developer formerly known as Christian Nonis at <[email protected]>
+Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -27,5 +27,7 @@ async def create_new_brain(request: CreateBrainRequest):
"""
Create a new brain
"""
+ if not (request.brain_id.isalnum() and request.brain_id[0].isalpha()):
+ raise ValueError("brain_id must be alphanumeric and start with a letter")
result = await asyncio.to_thread(data_adapter.create_brain, request.brain_id)
return result
diff --git a/src/services/mcp/main.py b/src/services/mcp/main.py
index f020c57..6c28c88 100644
--- a/src/services/mcp/main.py
+++ b/src/services/mcp/main.py
@@ -9,14 +9,19 @@ Modified By: Christian Nonis <[email protected]>
-----
"""
+import asyncio
from contextvars import ContextVar
from typing import Any
+
from mcp.server import FastMCP
-from pydantic import BaseModel
-from src.core.instances import embeddings_adapter, vector_store_adapter
+
+from src.core.instances import (
+ data_adapter,
+ embeddings_adapter,
+ graph_adapter,
+ vector_store_adapter,
+)
from src.lib.neo4j.client import _neo4j_client
-from src.services.data.main import data_adapter
-from src.services.kg_agent.main import graph_adapter
from src.services.mcp.utils import guard_brainpat
auth_token_var: ContextVar[str | None] = ContextVar("auth_token", default=None)
@@ -39,13 +44,17 @@ def get_search_operation_instructions(message: str) -> str:
"""
-class SearchMemoryInput(BaseModel):
- db_query: str
- brain_id: str
+def _search_memory_sync(db_query: str, brain_id: str) -> Any:
+ try:
+ if not guard_brainpat(auth_token_var.get(), brain_id):
+ return "Unauthorized"
+ return graph_adapter.execute_operation(db_query, brain_id)
+ except Exception as e:
+ return f"Error executing graph operation: {e}"
@mcp.tool()
-def search_memory(db_query: str, brain_id: str) -> Any:
+async def search_memory(db_query: str, brain_id: str) -> Any:
"""
Search the brain for memories and information.
This tool will search into the knowledge graph.
@@ -54,52 +63,53 @@ def search_memory(db_query: str, brain_id: str) -> Any:
- db_query: str: the operation to execute on the graph.
- brain_id: str: the brain to search in.
"""
+ return await asyncio.to_thread(_search_memory_sync, db_query, brain_id)
+
+
+def _search_semantically_sync(query: str, brain_id: str) -> Any:
try:
if not guard_brainpat(auth_token_var.get(), brain_id):
return "Unauthorized"
- return graph_adapter.execute_operation(db_query, brain_id)
+ query_embedding = embeddings_adapter.embed_text(query)
+ data_vectors = vector_store_adapter.search_vectors(
+ query_embedding.embeddings, store="nodes", brain_id=brain_id, k=5
+ )
+ triplets = graph_adapter.get_event_centric_neighbors(
+ [v.metadata.get("uuid") for v in data_vectors], brain_id=brain_id
+ )
+ return triplets
except Exception as e:
return f"Error executing graph operation: {e}"
-
-
+
+
@mcp.tool()
-def search_semantically(query: str, brain_id: str) -> Any:
+async def search_semantically(query: str, brain_id: str) -> Any:
"""
Search information semantically, given a query and a brain to search in,
this tool will return a list of graph nodes that are semantically related to the query.
-
+
This tool is useful to search into the graph for information without knowing names or labels.
-
+
Input must be a JSON object with the following fields:
- query: str: the query to search for.
- brain_id: str: the brain to search in.
"""
- try:
- if not guard_brainpat(auth_token_var.get(), brain_id):
- return "Unauthorized"
- query_embedding = embeddings_adapter.embed_text(query)
- data_vectors = vector_store_adapter.search_vectors(
- query_embedding.embeddings, store="nodes", brain_id=brain_id, k=5
- )
- triplets = graph_adapter.get_event_centric_neighbors([v.metadata.get("uuid") for v in data_vectors], brain_id=brain_id)
- return triplets
- except Exception as e:
- return f"Error executing graph operation: {e}"
+ return await asyncio.to_thread(_search_semantically_sync, query, brain_id)
-def list_brains() -> list[str]:
- """
- This tool lists all the brains/memory stores available
- """
+def _list_brains_sync() -> list[str] | str:
brain_key = guard_brainpat(auth_token_var.get())
if not brain_key:
return "Unauthorized"
-
- # Returns only the brain which has the pat
if type(brain_key) == str:
return [brain_key]
-
- # Gets all the brains
brains = data_adapter.get_brains_list()
return [brain.name_key for brain in brains]
+
+
+async def list_brains() -> list[str] | str:
+ """
+ This tool lists all the brains/memory stores available
+ """
+ return await asyncio.to_thread(_list_brains_sync)
diff --git a/src/services/mcp/utils.py b/src/services/mcp/utils.py
index f5a6692..2904fa7 100644
--- a/src/services/mcp/utils.py
+++ b/src/services/mcp/utils.py
@@ -20,7 +20,6 @@ def guard_brainpat(pat: str = None, target_brain: str = None) -> bool | str:
If the BrainPAT is not matching any brain, it will try to match with the systempat,
if the systempat is not matching, it will raise an auth error.
"""
- print(pat, config.brainpat_token)
if pat == config.brainpat_token:
return True
diff --git a/src/services/observations/main.py b/src/services/observations/main.py
index 40b914d..6378f3f 100644
--- a/src/services/observations/main.py
+++ b/src/services/observations/main.py
@@ -8,12 +8,8 @@ Modified By: Christian Nonis <[email protected]>
-----
"""
-from src.adapters.llm import LLMAdapter
from src.core.agents.observations_agent import ObservationsAgent
-from src.lib.llm.client_small import _llm_small_client
+from src.core.instances import llm_small_adapter
-llm_adapter = LLMAdapter()
-llm_adapter.add_client(_llm_small_client)
-
-observations_agent = ObservationsAgent(llm_adapter)
+observations_agent = ObservationsAgent(llm_small_adapter)