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.

21.0 KB
Raw Blame
import asyncio
import os
import sys
import types
import unittest
from types import SimpleNamespace
from unittest.mock import MagicMock, 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",
    "POSTGRES_HOST": "localhost",
    "POSTGRES_PORT": "5432",
    "POSTGRES_USERNAME": "postgres",
    "POSTGRES_PASSWORD": "postgres",
}
for key, value in ENV_DEFAULTS.items():
    os.environ.setdefault(key, value)

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from src.constants.embeddings import Vector
from src.constants.data import TextChunk
from src.constants.kg import Node, Predicate
from src.core.search.entity_info import EventSynergyRetriever
from src.services.api.constants.requests import GetContextRequestBody
from src.utils.nlp.ner import ExtractElementsResponse


def _node(uuid: str, name: str, *, happened_at: str | None = None, labels=None):
    return Node(
        uuid=uuid,
        name=name,
        labels=labels or ["PERSON"],
        description=f"desc-{name}",
        happened_at=happened_at,
    )


def _pred(uuid: str, name: str):
    return Predicate(uuid=uuid, name=name, description=f"desc-{name}")


class CollectQueryVariantsTests(unittest.TestCase):
    def test_includes_noun_chunks_deduped_and_capped(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        elements = ExtractElementsResponse(
            tokens=[{"text": "Alice", "lemma": "Alice", "pos": "PROPN"}],
            noun_chunks=[
                "closest friend",
                "Alice",
                "charity event",
                "weekend trip",
                "old school",
                "extra chunk",
                "another one",
            ],
        )
        variants = retrieve_mod._collect_query_variants(
            "What did Alice do with her closest friend?", elements
        )
        self.assertEqual(variants[0], "What did Alice do with her closest friend?")
        self.assertIn("Alice", variants)
        self.assertIn("closest friend", variants)
        self.assertIn("charity event", variants)
        noun_chunks_included = [
            chunk
            for chunk in elements.noun_chunks
            if chunk in variants and chunk != "Alice"
        ]
        self.assertLessEqual(
            len(noun_chunks_included), retrieve_mod._MAX_NOUN_CHUNKS
        )
        self.assertTrue(
            any("friend" in v.lower() for v in variants[1:]),
            "enumeration decomposition should add relation-focused subqueries",
        )


class FormatHelpersTests(unittest.TestCase):
    def test_format_includes_happened_at(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        n = _node("a", "Alice")
        r = _pred("r1", "ATTENDED")
        m = _node("e", "Wedding", happened_at="2024-05-01", labels=["EVENT"])
        r2 = _pred("r2", "INVOLVED")
        b = _node("b", "Bob")
        line = retrieve_mod._format_event_fact(n, r, m, r2, b)
        self.assertIn("@2024-05-01", line)
        self.assertIn("Wedding", line)


class GetContextRetrievalTests(unittest.IsolatedAsyncioTestCase):
    async def test_retains_all_event_facts_not_just_first(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        facts = [
            (
                _node("a", "Alice"),
                _pred("r1", "ATTENDED"),
                _node("e1", "Event1", happened_at="2024-01-01", labels=["EVENT"]),
                _pred("r2", "WITH"),
                _node("b", "Bob"),
            ),
            (
                _node("a", "Alice"),
                _pred("r3", "VISITED"),
                _node("e2", "Event2", happened_at="2024-02-01", labels=["EVENT"]),
                _pred("r4", "IN"),
                _node("c", "Paris", labels=["LOCATION"]),
            ),
            (
                _node("a", "Alice"),
                _pred("r5", "BOUGHT"),
                _node("e3", "Event3", labels=["EVENT"]),
                _pred("r6", "ITEM"),
                _node("d", "Book", labels=["OBJECT"]),
            ),
            (
                _node("a", "Alice"),
                _pred("r7", "MET"),
                _node("e4", "Event4", labels=["EVENT"]),
                _pred("r8", "WITH"),
                _node("f", "Carol"),
            ),
            (
                _node("a", "Alice"),
                _pred("r9", "MOVED"),
                _node("e5", "Event5", labels=["EVENT"]),
                _pred("r10", "TO"),
                _node("g", "London", labels=["LOCATION"]),
            ),
        ]

        mock_embeddings = MagicMock()
        mock_embeddings.embed_text.return_value = Vector(
            id="q", embeddings=[0.1, 0.2, 0.3], metadata={}
        )

        mock_vs = MagicMock()
        mock_vs.search_nodes.return_value = [
            Vector(
                id="n1",
                embeddings=[0.1, 0.2, 0.3],
                metadata={"uuid": "a", "name": "Alice"},
                distance=0.1,
            )
        ]
        mock_vs.search_relationships.return_value = []

        mock_graph = MagicMock()
        mock_graph.get_event_centric_neighbors.return_value = facts

        mock_data = MagicMock()
        mock_data.get_last_text_chunks.return_value = []
        mock_data.get_last_structured_data.return_value = []

        elements = ExtractElementsResponse(tokens=[], noun_chunks=[])

        with (
            patch.object(retrieve_mod, "embeddings_adapter", mock_embeddings),
            patch.object(retrieve_mod, "vector_search", mock_vs),
            patch.object(retrieve_mod, "graph_adapter", mock_graph),
            patch.object(retrieve_mod, "data_adapter", mock_data),
            patch.object(
                retrieve_mod._entity_extractor,
                "extract_elements",
                return_value=elements,
            ),
        ):
            response = await retrieve_mod.get_context(
                GetContextRequestBody(text="Alice", brain_id="brain-a", max_facts=40)
            )

        self.assertEqual(len(response.triples), 5)
        self.assertIn("@2024-01-01", response.text_context)
        self.assertIn("Paris", response.text_context)

    async def test_relationship_vector_search_seeds_facts(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        fact = (
            _node("tail", "Alice"),
            _pred("r1", "ORGANIZED"),
            _node("mid", "Fundraiser", happened_at="2023-11-11", labels=["EVENT"]),
            _pred("r2", "FOR"),
            _node("tip", "Charity", labels=["ORG"]),
        )

        mock_embeddings = MagicMock()
        mock_embeddings.embed_text.return_value = Vector(
            id="q", embeddings=[0.1, 0.2, 0.3], metadata={}
        )

        mock_vs = MagicMock()
        mock_vs.search_nodes.return_value = []
        mock_vs.search_relationships.return_value = [
            Vector(
                id="rel1",
                embeddings=[0.1, 0.2, 0.3],
                metadata={"uuid": "r1", "node_ids": ["tail", "mid"]},
                distance=0.05,
            )
        ]

        mock_graph = MagicMock()
        mock_graph.get_event_centric_neighbors.return_value = [fact]

        mock_data = MagicMock()
        mock_data.get_last_text_chunks.return_value = []
        mock_data.get_last_structured_data.return_value = []

        elements = ExtractElementsResponse(tokens=[], noun_chunks=[])

        with (
            patch.object(retrieve_mod, "embeddings_adapter", mock_embeddings),
            patch.object(retrieve_mod, "vector_search", mock_vs),
            patch.object(retrieve_mod, "graph_adapter", mock_graph),
            patch.object(retrieve_mod, "data_adapter", mock_data),
            patch.object(
                retrieve_mod._entity_extractor,
                "extract_elements",
                return_value=elements,
            ),
        ):
            response = await retrieve_mod.get_context(
                GetContextRequestBody(
                    text="who organized the fundraiser",
                    brain_id="brain-a",
                )
            )

        mock_graph.get_event_centric_neighbors.assert_called()
        seed_uuids = mock_graph.get_event_centric_neighbors.call_args[0][0]
        self.assertIn("tail", seed_uuids)
        self.assertIn("mid", seed_uuids)
        self.assertEqual(len(response.triples), 1)
        self.assertIn("Fundraiser", response.text_context)

    async def test_max_facts_cap_and_dedup(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        shared = (
            _node("a", "Alice"),
            _pred("r1", "ATTENDED"),
            _node("e1", "Event1", labels=["EVENT"]),
            _pred("r2", "WITH"),
            _node("b", "Bob"),
        )
        other = (
            _node("a", "Alice"),
            _pred("r3", "VISITED"),
            _node("e2", "Event2", labels=["EVENT"]),
            _pred("r4", "IN"),
            _node("c", "Paris", labels=["LOCATION"]),
        )

        mock_embeddings = MagicMock()
        mock_embeddings.embed_text.return_value = Vector(
            id="q", embeddings=[0.1, 0.2, 0.3], metadata={}
        )
        mock_vs = MagicMock()
        mock_vs.search_nodes.return_value = [
            Vector(
                id="n1",
                embeddings=[0.1, 0.2, 0.3],
                metadata={"uuid": "a", "name": "Alice"},
                distance=0.2,
            )
        ]
        mock_vs.search_relationships.return_value = []
        mock_graph = MagicMock()
        mock_graph.get_event_centric_neighbors.return_value = [shared, shared, other]
        mock_data = MagicMock()
        mock_data.get_last_text_chunks.return_value = []
        mock_data.get_last_structured_data.return_value = []
        elements = ExtractElementsResponse(tokens=[], noun_chunks=[])

        with (
            patch.object(retrieve_mod, "embeddings_adapter", mock_embeddings),
            patch.object(retrieve_mod, "vector_search", mock_vs),
            patch.object(retrieve_mod, "graph_adapter", mock_graph),
            patch.object(retrieve_mod, "data_adapter", mock_data),
            patch.object(
                retrieve_mod._entity_extractor,
                "extract_elements",
                return_value=elements,
            ),
        ):
            response = await retrieve_mod.get_context(
                GetContextRequestBody(text="Alice", brain_id="brain-a", max_facts=1)
            )

        self.assertEqual(len(response.triples), 1)

    async def test_context_path_does_not_emit_dossier_lines(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        fact = (
            _node("a", "Alice"),
            _pred("r1", "KNOWS"),
            _node("e1", "Meeting", labels=["EVENT"]),
            _pred("r2", "WITH"),
            _node("b", "Bob"),
        )

        mock_embeddings = MagicMock()
        mock_embeddings.embed_text.return_value = Vector(
            id="q", embeddings=[0.1, 0.2, 0.3], metadata={}
        )
        mock_vs = MagicMock()
        mock_vs.search_nodes.return_value = [
            Vector(
                id="n1",
                embeddings=[0.1, 0.2, 0.3],
                metadata={"uuid": "a", "name": "Alice"},
                distance=0.1,
            )
        ]
        mock_vs.search_relationships.return_value = []
        mock_graph = MagicMock()
        mock_graph.get_event_centric_neighbors.return_value = [fact]
        mock_data = MagicMock()
        mock_data.get_last_text_chunks.return_value = []
        mock_data.get_last_structured_data.return_value = []
        elements = ExtractElementsResponse(
            tokens=[{"text": "Alice", "lemma": "Alice", "pos": "PROPN"}],
            noun_chunks=[],
        )

        with (
            patch.object(retrieve_mod, "embeddings_adapter", mock_embeddings),
            patch.object(retrieve_mod, "vector_search", mock_vs),
            patch.object(retrieve_mod, "graph_adapter", mock_graph),
            patch.object(retrieve_mod, "data_adapter", mock_data),
            patch.object(
                retrieve_mod._entity_extractor,
                "extract_elements",
                return_value=elements,
            ),
            patch(
                "src.core.search.entity_info.EventSynergyRetriever"
            ) as synergy_cls,
        ):
            response = await retrieve_mod.get_context(
                GetContextRequestBody(
                    text="Where does Alice's friend live?",
                    brain_id="brain-a",
                )
            )

        synergy_cls.assert_not_called()
        self.assertFalse(
            any(line.startswith("[dossier:") for line in response.text_context.splitlines())
        )
        self.assertEqual(len(response.triples), 1)


class EventSynergyHardeningTests(unittest.TestCase):
    def test_explores_top_k_branches_not_only_greedy_best(self):
        alice = _node("a", "Alice")
        wrong = _node("w", "Wrong")
        mid = _node("m", "Bridge")
        goal = _node("g", "Goal")
        rel_wrong = _pred("rw", "DISTRACTOR")
        rel_wrong.properties = {"v_id": "v_wrong"}
        rel_bridge = _pred("rb", "VIA")
        rel_bridge.properties = {"v_id": "v_bridge"}
        rel_goal = _pred("rg", "REACHES")
        rel_goal.properties = {"v_id": "v_goal"}

        neighbors = {
            "a": [(rel_wrong, wrong), (rel_bridge, mid)],
            "m": [(rel_goal, goal)],
            "w": [],
            "g": [],
        }

        embeddings = {
            "v_wrong": [1.0, 0.0, 0.0],
            "v_bridge": [0.8, 0.2, 0.0],
            "v_goal": [0.0, 1.0, 0.0],
        }
        query_embedding = [0.0, 1.0, 0.0]

        def fake_get_by_ids(ids, store="relationships", brain_id="default"):
            vid = ids[0]
            return [
                Vector(id=vid, embeddings=embeddings[vid], metadata={})
            ]

        with (
            patch(
                "src.core.search.entity_info.graph_adapter.get_neighbors",
                side_effect=lambda nodes, brain_id="default", **kwargs: {
                    nodes[0]: neighbors.get(nodes[0], [])
                },
            ),
            patch(
                "src.core.search.entity_info.vector_store_adapter.get_by_ids",
                side_effect=fake_get_by_ids,
            ),
            patch(
                "src.core.search.entity_info.cosine_similarity",
                side_effect=lambda a, b: sum(x * y for x, y in zip(a, b)),
            ),
        ):
            retriever = EventSynergyRetriever("brain-a")
            path = retriever._recursive_explorer(
                "a",
                query_embedding,
                depth=3,
                visited_ids=set(),
                work_counter=[0],
                branch_factor=3,
            )

        self.assertGreaterEqual(len(path), 2)
        hop_names = [hop[0][0].name for hop in path]
        self.assertIn("VIA", hop_names)
        self.assertIn("REACHES", hop_names)

    def test_work_cap_stops_exploration(self):
        nodes = {f"n{i}": _node(f"n{i}", f"N{i}") for i in range(20)}
        rels = {}
        for i in range(19):
            pred = _pred(f"r{i}", f"REL{i}")
            pred.properties = {"v_id": f"v{i}"}
            rels[f"n{i}"] = [(pred, nodes[f"n{i+1}"])]
        rels["n19"] = []

        with (
            patch(
                "src.core.search.entity_info.graph_adapter.get_neighbors",
                side_effect=lambda nodes_arg, brain_id="default", **kwargs: {
                    nodes_arg[0]: rels.get(nodes_arg[0], [])
                },
            ),
            patch(
                "src.core.search.entity_info.vector_store_adapter.get_by_ids",
                side_effect=lambda ids, store="relationships", brain_id="default": [
                    Vector(id=ids[0], embeddings=[1.0, 0.0], metadata={})
                ],
            ),
            patch(
                "src.core.search.entity_info.cosine_similarity",
                return_value=0.5,
            ),
            patch("src.core.search.entity_info._MAX_EXPLORATION_WORK", 3),
        ):
            retriever = EventSynergyRetriever("brain-a")
            work = [0]
            retriever._recursive_explorer(
                "n0",
                [1.0, 0.0],
                depth=20,
                visited_ids=set(),
                work_counter=work,
                branch_factor=1,
            )
            self.assertLessEqual(work[0], 3)


class ContextPassageModeTests(unittest.TestCase):
    def test_search_off_keeps_ilike_lexical_leg(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        mock_embeddings = MagicMock()
        mock_embeddings.embed_text.return_value = Vector(
            id="q", embeddings=[0.1], metadata={}
        )
        mock_vs = MagicMock()
        mock_vs.search_data.return_value = [
            Vector(id="d", metadata={"resource_id": "dense-1"}, distance=0.2)
        ]
        ilike_chunk = TextChunk(id="ilike-1", text="ilike hit about license")
        mock_data = MagicMock()
        mock_data.search.return_value = SimpleNamespace(text_chunks=[ilike_chunk])
        mock_data.get_text_chunks_by_ids.return_value = (
            [TextChunk(id="dense-1", text="dense body")],
            [],
        )

        with (
            patch.object(retrieve_mod, "embeddings_adapter", mock_embeddings),
            patch.object(retrieve_mod, "vector_search", mock_vs),
            patch.object(retrieve_mod, "data_adapter", mock_data),
            patch.object(retrieve_mod.config, "search_enabled", False),
            patch.object(retrieve_mod.config, "context_passage_mode", "hybrid"),
        ):
            hits = retrieve_mod._retrieve_passages("license", "brain-a", limit=8)

        mock_data.search.assert_called()
        mock_data.search_bm25.assert_not_called()
        self.assertTrue(any(item[0] == "ilike-1" for item in hits))

    def test_search_on_hybrid_uses_bm25(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        mock_embeddings = MagicMock()
        mock_embeddings.embed_text.return_value = Vector(
            id="q", embeddings=[0.1], metadata={}
        )
        mock_vs = MagicMock()
        mock_vs.search_data.return_value = [
            Vector(id="d", metadata={"resource_id": "dense-1"}, distance=0.2)
        ]
        bm25_chunk = TextChunk(id="bm25-1", text="bm25 hit about license")
        mock_data = MagicMock()
        mock_data.search_bm25.return_value = [(bm25_chunk, 5.0)]
        mock_data.get_text_chunks_by_ids.return_value = (
            [TextChunk(id="dense-1", text="dense body")],
            [],
        )

        with (
            patch.object(retrieve_mod, "embeddings_adapter", mock_embeddings),
            patch.object(retrieve_mod, "vector_search", mock_vs),
            patch.object(retrieve_mod, "data_adapter", mock_data),
            patch.object(retrieve_mod.config, "search_enabled", True),
            patch.object(retrieve_mod.config, "context_passage_mode", "hybrid"),
        ):
            hits = retrieve_mod._retrieve_passages("license", "brain-a", limit=8)

        mock_data.search_bm25.assert_called()
        mock_data.search.assert_not_called()
        ids = [item[0] for item in hits]
        self.assertIn("bm25-1", ids)
        self.assertIn("dense-1", ids)

    def test_search_on_ilike_freezes_old_lexical_leg(self):
        from src.services.api.controllers import retrieve as retrieve_mod

        mock_embeddings = MagicMock()
        mock_embeddings.embed_text.return_value = Vector(
            id="q", embeddings=[0.1], metadata={}
        )
        mock_vs = MagicMock()
        mock_vs.search_data.return_value = []
        ilike_chunk = TextChunk(id="ilike-2", text="legacy ilike")
        mock_data = MagicMock()
        mock_data.search.return_value = SimpleNamespace(text_chunks=[ilike_chunk])

        with (
            patch.object(retrieve_mod, "embeddings_adapter", mock_embeddings),
            patch.object(retrieve_mod, "vector_search", mock_vs),
            patch.object(retrieve_mod, "data_adapter", mock_data),
            patch.object(retrieve_mod.config, "search_enabled", True),
            patch.object(retrieve_mod.config, "context_passage_mode", "ilike"),
        ):
            hits = retrieve_mod._retrieve_passages("license", "brain-a", limit=8)

        mock_data.search.assert_called()
        mock_data.search_bm25.assert_not_called()
        self.assertEqual(hits[0][0], "ilike-2")


if __name__ == "__main__":
    unittest.main()