BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.
Python ai-agentsai-memoryknowledge-graphknowledge-managementknowledge-representationreccomendation-system
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.pngnew file mode 100644index 0000000..3f1fc37Binary files /dev/null and b/.github/assets/screen-video.png differdiff --git a/Dockerfile b/Dockerfileindex 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/.cacheRUN 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.mdindex 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&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.pyindex 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 loggingimport osfrom typing import Literalimport 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_pathself.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.pyindex 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.pyindex 0b09fe2..4d36e1e 100644--- a/src/core/agents/architect_agent.py+++ b/src/core/agents/architect_agent.py@@ -3,7 +3,7 @@ File: /architect_agent.pyCreated Date: Sunday December 21st 2025Author: Christian Nonis <[email protected]>------Last Modified: Thursday February 19th 2026 7:45:12 pm+Last Modified: Sunday March 22nd 2026 10:11:53 pmModified 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.pyindex 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: BaseChatModelsystem_prompt: strtools: list[BaseTool]output_schema: BaseModel | None@@ -36,7 +37,7 @@ class AgentBase:debug: bool = False,thinking: bool = False,):- self.model = model+ self._base_model = modelself.system_prompt = system_promptself.tools = toolsself.output_schema = output_schema@@ -45,18 +46,33 @@ class AgentBase:self.thinking = thinkingif 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 modelelse (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 namedef _get_effective_output_schema(self):diff --git a/src/core/agents/core/invoke_loop.py b/src/core/agents/core/invoke_loop.pyindex 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_promptfrom .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 = 3for _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",+ ):+ breakif raw_tc:passelif content_breaks_ollama_tool_parse(n_message):@@ -230,7 +294,10 @@ def run_invoke_loop(agent, messages, config):tool_call_id_counter += 1n_message = Nonecontinue- 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_inputif 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_namewhile True:_next_attempts = 3for _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:+ raisenext_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):] = existingbreakbreak+ _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 ""+ breakif next_raw_tc:passelif content_breaks_ollama_tool_parse(next_content):@@ -454,7 +599,10 @@ def run_invoke_loop(agent, messages, config):)tool_call_id_counter += 1continue- 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_nameelse:agent.messages.append({diff --git a/src/core/agents/core/prompts.py b/src/core/agents/core/prompts.pyindex 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 BaseToolfrom .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 basedef 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.pyindex 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.pyCreated Date: Wednesday January 14th 2026Author: Christian Nonis <[email protected]>------Last Modified: Thursday February 19th 2026 7:45:12 pm+Last Modified: Wednesday March 4th 2026 9:35:41 pmModified 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.pyindex 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- ]+ ] = serializedreturn 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.pyindex 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_adapterfrom src.lib.neo4j.client import _neo4j_clientfrom src.utils.tokens import merge_token_details, token_detail_from_token_countsdiff --git a/src/lib/embeddings/client_small.py b/src/lib/embeddings/client_small.pyindex 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_CHECKINGfrom src.adapters.interfaces.embeddings import EmbeddingsClientfrom 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.pyindex 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_CHECKINGfrom src.adapters.interfaces.embeddings import EmbeddingsClientfrom 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 _modelclass 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 ediff --git a/src/services/api/controllers/system.py b/src/services/api/controllers/system.pyindex 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 2025Author: 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 resultdiff --git a/src/services/mcp/main.py b/src/services/mcp/main.pyindex 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 asynciofrom contextvars import ContextVarfrom 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_adapterfrom src.services.mcp.utils import guard_brainpatauth_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 tripletsexcept 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 patif type(brain_key) == str:return [brain_key]-- # Gets all the brainsbrains = 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.pyindex 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 Truediff --git a/src/services/observations/main.py b/src/services/observations/main.pyindex 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 LLMAdapterfrom 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)