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
Refactor agent runtime creation and embedding/graph logic
Cursor Agent012135d2ef70
diff --git a/src/adapters/embeddings.py b/src/adapters/embeddings.pyindex 42407b7..41c5966 100644--- a/src/adapters/embeddings.py+++ b/src/adapters/embeddings.py@@ -20,9 +20,36 @@ from src.constants.embeddings import Vectorfrom src.lib.embeddings.client import EmbeddingError+class EmbeddingFailureStrategy:+ def on_single_failure(self, error: EmbeddingError) -> Vector:+ raise NotImplementedError++ def on_batch_failure(self, error: EmbeddingError, count: int) -> list[Vector]:+ raise NotImplementedError+++class ReturnEmptyVectorStrategy(EmbeddingFailureStrategy):+ def on_single_failure(self, error: EmbeddingError) -> Vector:+ print(f"Embedding failed in adapter, returning empty vector: {error}")+ return Vector(id=str(uuid.uuid4()), embeddings=[], metadata={})++ def on_batch_failure(self, error: EmbeddingError, count: int) -> list[Vector]:+ print(f"Embedding failed in adapter, returning empty vectors: {error}")+ return [Vector(id=str(uuid.uuid4()), embeddings=[], metadata={}) for _ in range(count)]+++class RaiseEmbeddingFailureStrategy(EmbeddingFailureStrategy):+ def on_single_failure(self, error: EmbeddingError) -> Vector:+ raise error++ def on_batch_failure(self, error: EmbeddingError, count: int) -> list[Vector]:+ raise error++class EmbeddingsAdapter:- def __init__(self):+ def __init__(self, failure_strategy: EmbeddingFailureStrategy | None = None):self.embeddings = None+ self.failure_strategy = failure_strategy or ReturnEmptyVectorStrategy()def add_client(self, client: EmbeddingsClient) -> None:"""@@ -30,6 +57,9 @@ class EmbeddingsAdapter:"""self.embeddings = client+ def set_failure_strategy(self, strategy: EmbeddingFailureStrategy) -> None:+ self.failure_strategy = strategy+@retry(stop=stop_after_attempt(5),wait=wait_exponential(multiplier=1, min=2, max=30),@@ -54,8 +84,7 @@ class EmbeddingsAdapter:embeddings = self._embed_text_with_retry(text)return Vector(id=str(uuid.uuid4()), embeddings=embeddings, metadata={})except EmbeddingError as e:- print(f"Embedding failed in adapter, returning empty vector: {e}")- return Vector(id=str(uuid.uuid4()), embeddings=[], metadata={})+ return self.failure_strategy.on_single_failure(e)def embed_texts(self, texts: list[str]) -> list[Vector]:"""@@ -68,10 +97,7 @@ class EmbeddingsAdapter:for embeddings in embeddings_list]except EmbeddingError as e:- print(f"Embedding failed in adapter, returning empty vectors: {e}")- return [- Vector(id=str(uuid.uuid4()), embeddings=[], metadata={}) for _ in texts- ]+ return self.failure_strategy.on_batch_failure(e, len(texts))class VectorStoreAdapter:diff --git a/src/adapters/graph.py b/src/adapters/graph.pyindex 4ac2f0f..d8dd3fb 100644--- a/src/adapters/graph.py+++ b/src/adapters/graph.py@@ -389,6 +389,32 @@ class GraphAdapter:"""return self.graph.get_schema(brain_id)+ def _reduce_neighbor_vectors(+ self,+ vectors_with_desc: list[dict],+ averaged_vector: list[float],+ similarity_threshold: float,+ description: Optional[str],+ ) -> set[str]:+ reduced_vectors = vectors_with_desc+ if description:+ reduced_vectors = reduce_list(+ vectors_with_desc,+ access_key="embeddings",+ similarity_threshold=0.8,+ by_vector=averaged_vector,+ rerank={+ "local": "description",+ "with_": description,+ },+ )+ return {+ vector["metadata"]["uuid"]+ for vector in reduced_vectors+ if cosine_similarity(averaged_vector, vector["embeddings"])+ >= similarity_threshold+ }+def get_2nd_degree_hops(self,from_uuids: List[str],@@ -490,34 +516,12 @@ class GraphAdapter:if fd[1].uuid in fd_vs_by_uuid]from_node = nodes_by_uuid[node_uuid]- filtered_uuids = []- if from_node.description:- filtered = reduce_list(- fd_vs_with_desc,- access_key="embeddings",- similarity_threshold=0.8,- by_vector=averaged_vector,- rerank={- "local": "description",- "with_": from_node.description,- },- )- filtered_uuids = {- v["metadata"]["uuid"]- for v in filtered- if cosine_similarity(averaged_vector, v["embeddings"])- >= similarity_threshold- }- else:- filtered_uuids = {- fd[1].uuid- for fd in fd_list- if fd[1].uuid in fd_vs_by_uuid- and cosine_similarity(- averaged_vector, fd_vs_by_uuid[fd[1].uuid].embeddings- )- >= similarity_threshold- }+ filtered_uuids = self._reduce_neighbor_vectors(+ vectors_with_desc=fd_vs_with_desc,+ averaged_vector=averaged_vector,+ similarity_threshold=similarity_threshold,+ description=from_node.description,+ )filtered_fd_by_origin[node_uuid] = [fd for fd in fd_list if fd[1].uuid in filtered_uuids]@@ -565,31 +569,12 @@ class GraphAdapter:if sd[1].uuid in sd_vs_by_uuid]- reduced_uuids = []- if from_node.description:- reduced = reduce_list(- sd_vs_with_desc,- access_key="embeddings",- similarity_threshold=0.8,- by_vector=averaged_vector,- rerank={- "local": "description",- "with_": from_node.description,- },- )- reduced_uuids = {- v["metadata"]["uuid"]- for v in reduced- if cosine_similarity(averaged_vector, v["embeddings"])- >= similarity_threshold- }- else:- reduced_uuids = {- sd["metadata"]["uuid"]- for sd in sd_vs_with_desc- if cosine_similarity(averaged_vector, sd["embeddings"])- >= similarity_threshold- }+ reduced_uuids = self._reduce_neighbor_vectors(+ vectors_with_desc=sd_vs_with_desc,+ averaged_vector=averaged_vector,+ similarity_threshold=similarity_threshold,+ description=from_node.description,+ )second_degree = [(flatten_pred(sd[0]), flatten_node(sd[1]))diff --git a/src/core/agents/architect_agent.py b/src/core/agents/architect_agent.pyindex 562da86..0b09fe2 100644--- a/src/core/agents/architect_agent.py+++ b/src/core/agents/architect_agent.py@@ -9,7 +9,6 @@ Modified By: Christian Nonis <[email protected]>"""from typing import Dict, List, Literal, Optional, Tuple-from langchain.agents import create_agentfrom langchain.tools import BaseToolfrom pydantic import BaseModelimport os@@ -35,7 +34,7 @@ from src.constants.prompts.architect_agent import (ARCHITECT_AGENT_SYSTEM_PROMPT,ARCHITECT_AGENT_CREATE_RELATIONSHIPS_PROMPT,)-from src.core.agents.core.agent_base import AgentBase+from src.core.agents.core import runtime_agent_factoryfrom src.core.plugins.prompts import prompt_registryfrom src.core.agents.scout_agent import ScoutEntityfrom src.constants.agents import (@@ -237,7 +236,7 @@ class ArchitectAgent:extra_system_prompt if extra_system_prompt else ""))- if mode == "coarse":+ elif mode == "coarse":system_prompt = prompt_registry.get("ARCHITECT_AGENT_TOOLER_COARSE_SYSTEM_PROMPT", ARCHITECT_AGENT_TOOLER_COARSE_SYSTEM_PROMPT).format(@@ -245,6 +244,8 @@ class ArchitectAgent:extra_system_prompt if extra_system_prompt else ""))+ else:+ raise ValueError(f"Invalid mode for architect agent: {mode}")tools = ((tools@@ -264,22 +265,15 @@ class ArchitectAgent:(output_schema if output_schema else None) if type_ == "single" else None)- if mode == "granular":- self.agent = create_agent(- model=self.llm_adapter.llm.langchain_model,- tools=tools,- system_prompt=system_prompt,- response_format=response_format,- debug=os.environ.get("DEBUG", "false").lower() == "true",- )- if mode == "coarse" or config.agentic_architecture == "custom":- self.agent = AgentBase(- model=self.llm_adapter.llm.langchain_model,- tools=tools,- system_prompt=system_prompt,- output_schema=response_format,- debug=os.environ.get("DEBUG", "false").lower() == "true",- )+ self.agent = runtime_agent_factory.build(+ model=self.llm_adapter.llm.langchain_model,+ tools=tools,+ system_prompt=system_prompt,+ output_schema=response_format,+ debug=os.environ.get("DEBUG", "false").lower() == "true",+ architecture=config.agentic_architecture,+ use_custom_backend=(mode == "coarse"),+ )def run(self,diff --git a/src/core/agents/core/__init__.py b/src/core/agents/core/__init__.pyindex ac30427..1551e72 100644--- a/src/core/agents/core/__init__.py+++ b/src/core/agents/core/__init__.py@@ -10,5 +10,11 @@ Modified By: Christian Nonis <[email protected]>"""from .agent_base import AgentBase, parse_structured_from_messages+from .runtime_agent_factory import RuntimeAgentFactory, runtime_agent_factory-__all__ = ["AgentBase", "parse_structured_from_messages"]+__all__ = [+ "AgentBase",+ "parse_structured_from_messages",+ "RuntimeAgentFactory",+ "runtime_agent_factory",+]diff --git a/src/core/agents/core/runtime_agent_factory.py b/src/core/agents/core/runtime_agent_factory.pynew file mode 100644index 0000000..f56ad2a--- /dev/null+++ b/src/core/agents/core/runtime_agent_factory.py@@ -0,0 +1,42 @@+from typing import Any++from langchain.agents import create_agent+from langchain_core.language_models import BaseChatModel++from .agent_base import AgentBase+++class RuntimeAgentFactory:+ def __init__(self, create_agent_fn=create_agent, custom_agent_cls=AgentBase):+ self._create_agent_fn = create_agent_fn+ self._custom_agent_cls = custom_agent_cls++ def build(+ self,+ *,+ model: BaseChatModel,+ tools: list[Any],+ system_prompt: str,+ output_schema: Any = None,+ debug: bool = False,+ architecture: str = "custom",+ use_custom_backend: bool = False,+ ):+ if use_custom_backend or architecture == "custom":+ return self._custom_agent_cls(+ model=model,+ tools=tools,+ system_prompt=system_prompt,+ output_schema=output_schema,+ debug=debug,+ )+ return self._create_agent_fn(+ model=model,+ tools=tools,+ system_prompt=system_prompt,+ response_format=output_schema,+ debug=debug,+ )+++runtime_agent_factory = RuntimeAgentFactory()diff --git a/src/core/agents/janitor_agent.py b/src/core/agents/janitor_agent.pyindex f8bd148..1db09dc 100644--- a/src/core/agents/janitor_agent.py+++ b/src/core/agents/janitor_agent.py@@ -12,7 +12,6 @@ import jsonimport osfrom functools import reducefrom typing import List, Literal, Optional, Tuple, Union-from langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategyfrom langchain.tools import BaseToolfrom pydantic import BaseModel@@ -44,7 +43,7 @@ from src.core.agents.architect_agent import (ArchitectAgentRelationship,ArchitectAgentNew,)-from src.core.agents.core.agent_base import AgentBase+from src.core.agents.core import runtime_agent_factoryfrom src.core.agents.scout_agent import ScoutEntityfrom src.core.agents.tools.janitor_agent import (JanitorAgentGetSchemaTool,@@ -216,22 +215,14 @@ class JanitorAgent:else:response_format = output_schema- if config.agentic_architecture == "custom":- self.agent = AgentBase(- model=self.llm_adapter.llm.langchain_model,- tools=(tools if tools else self._get_tools(brain_id)),- system_prompt=system_prompt,- output_schema=response_format,- debug=os.environ.get("DEBUG", "false").lower() == "true",- )- else:- self.agent = create_agent(- model=self.llm_adapter.llm.langchain_model,- tools=(tools if tools else self._get_tools(brain_id)),- system_prompt=system_prompt,- response_format=response_format,- debug=os.environ.get("DEBUG", "false").lower() == "true",- )+ self.agent = runtime_agent_factory.build(+ model=self.llm_adapter.llm.langchain_model,+ tools=(tools if tools else self._get_tools(brain_id)),+ system_prompt=system_prompt,+ output_schema=response_format,+ debug=os.environ.get("DEBUG", "false").lower() == "true",+ architecture=config.agentic_architecture,+ )def _content_only_history(self, messages: Optional[list], keep_last: Optional[int] = Nonediff --git a/src/core/agents/kg_agent.py b/src/core/agents/kg_agent.pyindex db28ff6..67861e9 100644--- a/src/core/agents/kg_agent.py+++ b/src/core/agents/kg_agent.py@@ -10,7 +10,6 @@ Modified By: Christian Nonis <[email protected]>import osfrom typing import Iterable, List, Literal, Optional, Union-from langchain.agents import create_agentfrom langchain.tools import BaseToolfrom pydantic import BaseModelfrom concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError@@ -37,7 +36,7 @@ from src.constants.prompts.kg_agent import (KG_AGENT_UPDATE_PROMPT,KG_AGENT_UPDATE_STRUCTURED_PROMPT,)-from src.core.agents.core.agent_base import AgentBase+from src.core.agents.core import runtime_agent_factoryfrom src.core.plugins.prompts import prompt_registryfrom src.core.agents.tools.kg_agent import (KGAgentAddTripletsTool,@@ -192,26 +191,18 @@ class KGAgent:extra_system_prompt=extra_system_prompt if extra_system_prompt else "")- if config.agentic_architecture == "custom":- self.agent = AgentBase(- model=self.llm_adapter.llm.langchain_model,- tools=(tools if tools else self._get_tools(identification_params, metadata, brain_id)),- system_prompt=system_prompt,- output_schema=output_schema if output_schema else None,- debug=os.environ.get("DEBUG", "false").lower() == "true",- )- else:- self.agent = create_agent(- model=self.llm_adapter.llm.langchain_model,- tools=(- tools- if tools- else self._get_tools(identification_params, metadata, brain_id)- ),- system_prompt=system_prompt,- response_format=output_schema if output_schema else None,- debug=os.environ.get("DEBUG", "false").lower() == "true",- )+ self.agent = runtime_agent_factory.build(+ model=self.llm_adapter.llm.langchain_model,+ tools=(+ tools+ if tools+ else self._get_tools(identification_params, metadata, brain_id)+ ),+ system_prompt=system_prompt,+ output_schema=output_schema if output_schema else None,+ debug=os.environ.get("DEBUG", "false").lower() == "true",+ architecture=config.agentic_architecture,+ )self._agent_type = type_self._agent_brain_id = brain_iddiff --git a/src/core/agents/scout_agent.py b/src/core/agents/scout_agent.pyindex 0733a22..b8932d0 100644--- a/src/core/agents/scout_agent.py+++ b/src/core/agents/scout_agent.py@@ -10,7 +10,6 @@ Modified By: Christian Nonis <[email protected]>from typing import Dict, List, Literal, Optionalimport uuid-from langchain.agents import create_agentfrom langchain.tools import BaseToolfrom pydantic import BaseModel, Fieldimport os@@ -34,7 +33,7 @@ from src.constants.prompts.scout_agent import (SCOUT_AGENT_EXTRACT_ENTITIES_PROMPT,SCOUT_AGENT_SYSTEM_PROMPT,)-from src.core.agents.core.agent_base import AgentBase, parse_structured_from_messages+from src.core.agents.core import parse_structured_from_messages, runtime_agent_factoryfrom src.core.plugins.prompts import prompt_registryfrom src.utils.tokens import token_detail_from_token_counts@@ -137,29 +136,24 @@ class ScoutAgent:).format(extra_system_prompt=extra_system_prompt if extra_system_prompt else "")- if mode == "coarse":+ elif mode == "coarse":system_prompt = prompt_registry.get("SCOUT_AGENT_COARSE_SYSTEM_PROMPT", SCOUT_AGENT_COARSE_SYSTEM_PROMPT).format(extra_system_prompt=extra_system_prompt if extra_system_prompt else "")-- if mode == "granular":- self.agent = create_agent(- model=self.llm_adapter.llm.langchain_model,- tools=(tools if tools else self._get_tools(brain_id)),- system_prompt=system_prompt,- response_format=output_schema if output_schema else None,- debug=os.environ.get("DEBUG", "false").lower() == "true",- )- if mode == "coarse" or config.agentic_architecture == "custom":- self.agent = AgentBase(- model=self.llm_adapter.llm.langchain_model,- tools=(tools if tools else self._get_tools(brain_id)),- system_prompt=system_prompt,- output_schema=output_schema if output_schema else None,- debug=os.environ.get("DEBUG", "false").lower() == "true",- )+ else:+ raise ValueError(f"Invalid mode for scout agent: {mode}")++ self.agent = runtime_agent_factory.build(+ model=self.llm_adapter.llm.langchain_model,+ tools=(tools if tools else self._get_tools(brain_id)),+ system_prompt=system_prompt,+ output_schema=output_schema if output_schema else None,+ debug=os.environ.get("DEBUG", "false").lower() == "true",+ architecture=config.agentic_architecture,+ use_custom_backend=(mode == "coarse"),+ )def run(self,@@ -215,13 +209,15 @@ class ScoutAgent:text=text,targeting=targeting_str,)- if mode == "coarse":+ elif mode == "coarse":prompt = prompt_registry.get("SCOUT_AGENT_COARSE_EXTRACT_ENTITIES_PROMPT", SCOUT_AGENT_COARSE_EXTRACT_ENTITIES_PROMPT).format(text=text,targeting=targeting_str,)+ else:+ raise ValueError(f"Invalid mode for scout agent: {mode}")def _invoke_agent():return self.agent.invoke(diff --git a/tests/test_architecture_refactors.py b/tests/test_architecture_refactors.pynew file mode 100644index 0000000..d651cc3--- /dev/null+++ b/tests/test_architecture_refactors.py@@ -0,0 +1,151 @@+import os+import unittest+from unittest.mock import patch+++ENV_DEFAULTS = {+ "BRAINPAT_TOKEN": "test-token",+ "MODELS_MODE": "local",+ "EMBEDDINGS_LOCAL_MODEL": "local-model",+ "EMBEDDINGS_SMALL_MODEL": "small-model",+ "EMBEDDING_NODES_DIMENSION": "3",+ "EMBEDDING_TRIPLETS_DIMENSION": "3",+ "EMBEDDING_OBSERVATIONS_DIMENSION": "3",+ "EMBEDDING_DATA_DIMENSION": "3",+ "EMBEDDING_RELATIONSHIPS_DIMENSION": "3",+ "REDIS_HOST": "localhost",+ "REDIS_PORT": "6379",+ "NEO4J_HOST": "localhost",+ "NEO4J_PORT": "7687",+ "NEO4J_USERNAME": "neo4j",+ "NEO4J_PASSWORD": "password",+ "MILVUS_HOST": "localhost",+ "MILVUS_PORT": "19530",+ "MONGO_CONNECTION_STRING": "mongodb://localhost:27017",+ "CELERY_WORKER_CONCURRENCY": "1",+ "OLLAMA_HOST": "localhost",+ "OLLAMA_PORT": "11434",+ "OLLAMA_LLM_SMALL_MODEL": "small",+ "OLLAMA_LLM_LARGE_MODEL": "large",+}+for key, value in ENV_DEFAULTS.items():+ os.environ.setdefault(key, value)++from src.adapters.embeddings import EmbeddingsAdapter, RaiseEmbeddingFailureStrategy+from src.adapters.graph import GraphAdapter+from src.core.agents.core.runtime_agent_factory import RuntimeAgentFactory+from src.lib.embeddings.client import EmbeddingError+++class FakeFailingEmbeddingClient:+ def embed_text(self, text: str) -> list[float]:+ raise EmbeddingError("embedding failed")++ def embed_texts(self, texts: list[str]) -> list[list[float]]:+ raise EmbeddingError("embedding failed")+++class RuntimeAgentFactoryTests(unittest.TestCase):+ def test_factory_uses_custom_backend_when_forced(self):+ class FakeCustomAgent:+ def __init__(self, **kwargs):+ self.kwargs = kwargs++ def fake_create_agent(**kwargs):+ return {"kind": "langchain", "kwargs": kwargs}++ factory = RuntimeAgentFactory(+ create_agent_fn=fake_create_agent, custom_agent_cls=FakeCustomAgent+ )+ built = factory.build(+ model=object(),+ tools=[],+ system_prompt="system",+ output_schema=dict,+ architecture="langchain",+ use_custom_backend=True,+ debug=True,+ )+ self.assertIsInstance(built, FakeCustomAgent)+ self.assertEqual(built.kwargs["output_schema"], dict)+ self.assertEqual(built.kwargs["system_prompt"], "system")++ def test_factory_uses_langchain_backend_when_supported(self):+ class FakeCustomAgent:+ def __init__(self, **kwargs):+ self.kwargs = kwargs++ def fake_create_agent(**kwargs):+ return {"kind": "langchain", "kwargs": kwargs}++ factory = RuntimeAgentFactory(+ create_agent_fn=fake_create_agent, custom_agent_cls=FakeCustomAgent+ )+ built = factory.build(+ model=object(),+ tools=["t1"],+ system_prompt="system",+ output_schema=dict,+ architecture="langchain",+ use_custom_backend=False,+ debug=False,+ )+ self.assertEqual(built["kind"], "langchain")+ self.assertEqual(built["kwargs"]["response_format"], dict)+ self.assertEqual(built["kwargs"]["tools"], ["t1"])+++class EmbeddingsStrategyTests(unittest.TestCase):+ def test_embeddings_default_strategy_returns_empty_vectors(self):+ adapter = EmbeddingsAdapter()+ adapter.add_client(FakeFailingEmbeddingClient())+ single = adapter.embed_text("hello")+ many = adapter.embed_texts(["a", "b"])+ self.assertEqual(single.embeddings, [])+ self.assertEqual(len(many), 2)+ self.assertTrue(all(v.embeddings == [] for v in many))++ def test_embeddings_raise_strategy_raises_error(self):+ adapter = EmbeddingsAdapter()+ adapter.add_client(FakeFailingEmbeddingClient())+ adapter.set_failure_strategy(RaiseEmbeddingFailureStrategy())+ with self.assertRaises(EmbeddingError):+ adapter.embed_text("hello")+ with self.assertRaises(EmbeddingError):+ adapter.embed_texts(["a"])+++class GraphAdapterReductionTests(unittest.TestCase):+ def test_reduce_neighbor_vectors_without_description(self):+ adapter = GraphAdapter()+ vectors = [+ {"metadata": {"uuid": "a"}, "embeddings": [1.0, 0.0], "description": None},+ {"metadata": {"uuid": "b"}, "embeddings": [0.0, 1.0], "description": None},+ ]+ reduced = adapter._reduce_neighbor_vectors(+ vectors_with_desc=vectors,+ averaged_vector=[1.0, 0.0],+ similarity_threshold=0.5,+ description=None,+ )+ self.assertEqual(reduced, {"a"})++ def test_reduce_neighbor_vectors_with_description_reranks(self):+ adapter = GraphAdapter()+ vectors = [+ {"metadata": {"uuid": "a"}, "embeddings": [1.0, 0.0], "description": "d1"},+ {"metadata": {"uuid": "b"}, "embeddings": [1.0, 0.0], "description": "d2"},+ ]+ with patch("src.adapters.graph.reduce_list", return_value=[vectors[1]]) as reduced:+ result = adapter._reduce_neighbor_vectors(+ vectors_with_desc=vectors,+ averaged_vector=[1.0, 0.0],+ similarity_threshold=0.0,+ description="focus",+ )+ reduced.assert_called_once()+ self.assertEqual(result, {"b"})+++if __name__ == "__main__":+ unittest.main()