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.

15.3 KB
Raw Blame
import os
import unittest
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",
}
for key, value in ENV_DEFAULTS.items():
    os.environ.setdefault(key, value)

from fastapi import HTTPException

from src.constants.embeddings import Vector
from src.constants.data import TextChunk
from src.services.api.constants.requests import SearchRequestBody


class SearchApiTests(unittest.IsolatedAsyncioTestCase):
    async def test_404_when_search_disabled(self):
        from src.services.api.controllers import search as search_mod

        with patch.object(search_mod.config, "search_enabled", False):
            with self.assertRaises(HTTPException) as ctx:
                await search_mod.search(SearchRequestBody(query="license"))
        self.assertEqual(ctx.exception.status_code, 404)

    async def test_fused_hits_when_both_channels_on(self):
        from src.services.api.controllers import search as search_mod

        dense_vec = Vector(
            id="dense-1",
            metadata={"resource_id": "chunk-dense"},
            distance=0.1,
        )
        bm25_chunk = TextChunk(id="chunk-bm25", text="counseling license renewal")
        mock_embeddings = MagicMock()
        mock_embeddings.embed_text.return_value = Vector(
            id="q", embeddings=[0.1, 0.2], metadata={}
        )
        mock_vs = MagicMock()
        mock_vs.search_data.return_value = [dense_vec]
        mock_data = MagicMock()
        mock_data.search_bm25.return_value = [(bm25_chunk, 4.2)]
        mock_data.get_text_chunks_by_ids.return_value = (
            [TextChunk(id="chunk-dense", text="dense passage about alice")],
            [],
        )

        with (
            patch.object(search_mod.config, "search_enabled", True),
            patch.object(search_mod.config, "search_use_dense", True),
            patch.object(search_mod.config, "search_use_bm25", True),
            patch.object(search_mod.config, "search_fusion", "rrf"),
            patch.object(search_mod, "embeddings_adapter", mock_embeddings),
            patch.object(search_mod, "vector_search", mock_vs),
            patch.object(search_mod, "data_adapter", mock_data),
        ):
            response = await search_mod.search(
                SearchRequestBody(query="license", k=10, profile_stages=True)
            )

        ids = [hit.id for hit in response.hits]
        self.assertIn("chunk-dense", ids)
        self.assertIn("chunk-bm25", ids)
        self.assertTrue(any(hit.scores.rrf for hit in response.hits))
        mock_embeddings.embed_text.assert_called_once_with("license")
        self.assertIsNotNone(response.stage_timings)
        stage_names = [s["stage"] for s in response.stage_timings.get("stages", [])]
        self.assertIn("embed.query", stage_names)
        self.assertTrue(
            any(name.startswith("search.") for name in stage_names),
            stage_names,
        )

    async def test_dense_only_skips_bm25(self):
        from src.services.api.controllers import search as search_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="d1", metadata={"resource_id": "only-dense"}, distance=0.2)
        ]
        mock_data = MagicMock()
        mock_data.get_text_chunks_by_ids.return_value = (
            [TextChunk(id="only-dense", text="vector hit")],
            [],
        )

        with (
            patch.object(search_mod.config, "search_enabled", True),
            patch.object(search_mod.config, "search_use_dense", True),
            patch.object(search_mod.config, "search_use_bm25", False),
            patch.object(search_mod, "embeddings_adapter", mock_embeddings),
            patch.object(search_mod, "vector_search", mock_vs),
            patch.object(search_mod, "data_adapter", mock_data),
        ):
            response = await search_mod.search(SearchRequestBody(query="alice", k=5))

        self.assertEqual([hit.id for hit in response.hits], ["only-dense"])
        mock_data.search_bm25.assert_not_called()
        self.assertIsNotNone(response.hits[0].scores.dense)

    async def test_bm25_only_skips_embed(self):
        from src.services.api.controllers import search as search_mod

        mock_embeddings = MagicMock()
        mock_data = MagicMock()
        mock_data.search_bm25.return_value = [
            (TextChunk(id="lex", text="license board"), 3.1)
        ]
        mock_vs = MagicMock()

        with (
            patch.object(search_mod.config, "search_enabled", True),
            patch.object(search_mod.config, "search_use_dense", False),
            patch.object(search_mod.config, "search_use_bm25", True),
            patch.object(search_mod, "embeddings_adapter", mock_embeddings),
            patch.object(search_mod, "vector_search", mock_vs),
            patch.object(search_mod, "data_adapter", mock_data),
        ):
            response = await search_mod.search(SearchRequestBody(query="license", k=5))

        self.assertEqual([hit.id for hit in response.hits], ["lex"])
        mock_embeddings.embed_text.assert_not_called()
        mock_vs.search_data.assert_not_called()
        self.assertEqual(response.hits[0].scores.bm25, 3.1)
        self.assertIsNone(response.hits[0].node_id)
        self.assertEqual(response.node_ids, [])

    async def test_passage_docid_sets_node_id(self):
        from src.services.api.controllers import search as search_mod

        mock_embeddings = MagicMock()
        mock_data = MagicMock()
        mock_data.search_bm25.return_value = [
            (
                TextChunk(
                    id="chunk-bed",
                    text="DOCID 0.\nTitle: solid wood platform bed\nClass: Beds",
                ),
                5.0,
            )
        ]
        mock_vs = MagicMock()

        with (
            patch.object(search_mod.config, "search_enabled", True),
            patch.object(search_mod.config, "search_use_dense", False),
            patch.object(search_mod.config, "search_use_bm25", True),
            patch.object(search_mod, "embeddings_adapter", mock_embeddings),
            patch.object(search_mod, "vector_search", mock_vs),
            patch.object(search_mod, "data_adapter", mock_data),
        ):
            response = await search_mod.search(
                SearchRequestBody(query="platform bed", k=5)
            )

        self.assertEqual([hit.id for hit in response.hits], ["chunk-bed"])
        self.assertEqual(response.hits[0].channel, "passages")
        self.assertEqual(response.hits[0].node_id, "0")
        self.assertEqual(response.node_ids, ["0"])

    def test_default_search_mode_is_default(self):
        body = SearchRequestBody(query="license")
        self.assertEqual(body.mode, "default")
        self.assertEqual(body.k, 10)
        self.assertIsNone(body.extras)

    async def test_extras_equality_filter_and_facets(self):
        from src.services.api.controllers import search as search_mod
        from src.core.search.hybrid import (
            facet_counts_from_extras,
            hit_matches_extras,
        )

        self.assertTrue(hit_matches_extras({"locale": "it"}, {"locale": "IT"}))
        self.assertFalse(hit_matches_extras({"color": "argento"}, {"color": "nope"}))
        self.assertEqual(
            facet_counts_from_extras(
                [
                    {"locale": "it", "color": "argento", "brand": "CasaLuce"},
                    {"locale": "it", "color": "blu navy", "brand": "AtelierNord"},
                    None,
                ]
            ),
            {
                "locale": {"it": 2},
                "color": {"argento": 1, "blu navy": 1},
                "brand": {"CasaLuce": 1, "AtelierNord": 1},
            },
        )
        self.assertIsNone(facet_counts_from_extras([None, {}]))
        self.assertEqual(
            facet_counts_from_extras(
                [{"locale": "it", "uuid": "skip-me", "resource_id": "chunk"}]
            ),
            {"locale": {"it": 1}},
        )

        mock_data = MagicMock()
        mock_data.search_bm25.return_value = [
            (
                TextChunk(
                    id="it-1",
                    text="bollitore acciaio",
                    metadata={"locale": "it", "color": "argento", "brand": "CasaLuce"},
                ),
                3.0,
            ),
            (
                TextChunk(
                    id="it-2",
                    text="divano velluto",
                    metadata={"locale": "it", "color": "blu navy", "brand": "AtelierNord"},
                ),
                2.0,
            ),
        ]
        mock_data.get_text_chunks_by_ids.return_value = ([], [])
        mock_embeddings = MagicMock()
        mock_vs = MagicMock()

        with (
            patch.object(search_mod.config, "search_enabled", True),
            patch.object(search_mod.config, "search_use_dense", False),
            patch.object(search_mod.config, "search_use_bm25", True),
            patch.object(search_mod, "embeddings_adapter", mock_embeddings),
            patch.object(search_mod, "vector_search", mock_vs),
            patch.object(search_mod, "data_adapter", mock_data),
        ):
            kept = await search_mod.search(
                SearchRequestBody(query="divano", k=10, extras={"locale": "it"})
            )
            missed = await search_mod.search(
                SearchRequestBody(query="divano", k=10, extras={"color": "nope"})
            )
            unfiltered = await search_mod.search(
                SearchRequestBody(query="divano", k=10)
            )

        self.assertEqual({hit.id for hit in kept.hits}, {"it-1", "it-2"})
        self.assertEqual(kept.hits[0].extras["locale"], "it")
        self.assertEqual(kept.facets["locale"]["it"], 2)
        self.assertEqual(kept.facets["brand"]["CasaLuce"], 1)
        self.assertEqual(missed.hits, [])
        self.assertIsNone(missed.facets)
        self.assertEqual({hit.id for hit in unfiltered.hits}, {"it-1", "it-2"})
        self.assertEqual(unfiltered.hits[0].channel, "passages")
        mock_embeddings.embed_text.assert_not_called()

    def test_literal_overlap_and_frozen_head_helpers(self):
        from src.core.search.hybrid import (
            frozen_head_merge,
            fuse_passage_lists,
            literal_overlap_ids,
        )

        ranked = frozen_head_merge(
            [f"h{index}" for index in range(12)],
            [["extra", "h0"]],
            head_k=10,
            k=15,
        )
        self.assertEqual(ranked[:10], [f"h{index}" for index in range(10)])
        self.assertEqual(ranked[10], "extra")
        ids = literal_overlap_ids(
            "navy velvet sofa",
            {
                "hit": "Title: Navy velvet sofa two seats",
                "miss": "plastic kettle lid",
                "partial": "velvet throw pillow",
            },
            k=10,
        )
        self.assertEqual(ids[0], "hit")
        self.assertIn("partial", ids)
        self.assertNotIn("miss", ids)
        fused = fuse_passage_lists(
            ["d1", "d2"],
            ["b1", "d1"],
            fusion="cc",
            alpha=0.7,
            dense_similarities={"d1": 1.0, "d2": 0.2},
            bm25_scores={"b1": 4.0, "d1": 1.0},
        )
        self.assertTrue(fused)
        self.assertEqual(fused[0][0], "d1")

    async def test_fusion_alpha_request_overrides_config(self):
        from src.services.api.controllers import search as search_mod

        mock_data = MagicMock()
        mock_data.search_bm25.return_value = [
            (TextChunk(id="lex", text="license board"), 3.1)
        ]
        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="d1", metadata={"resource_id": "dense-1"}, distance=0.1)
        ]
        mock_data.get_text_chunks_by_ids.return_value = (
            [TextChunk(id="dense-1", text="vector hit")],
            [],
        )

        with (
            patch.object(search_mod.config, "search_enabled", True),
            patch.object(search_mod.config, "search_use_dense", True),
            patch.object(search_mod.config, "search_use_bm25", True),
            patch.object(search_mod.config, "search_fusion", "rrf"),
            patch.object(search_mod.config, "search_fusion_alpha", 0.1),
            patch.object(search_mod.config, "search_literal_fill", False),
            patch.object(search_mod, "embeddings_adapter", mock_embeddings),
            patch.object(search_mod, "vector_search", mock_vs),
            patch.object(search_mod, "data_adapter", mock_data),
        ):
            response = await search_mod.search(
                SearchRequestBody(
                    query="license",
                    k=5,
                    fusion="cc",
                    fusion_alpha=0.9,
                )
            )

        ids = [hit.id for hit in response.hits]
        self.assertIn("dense-1", ids)
        self.assertTrue(any(hit.scores.cc is not None for hit in response.hits))

    async def test_literal_fill_uses_frozen_head(self):
        from src.services.api.controllers import search as search_mod

        mock_data = MagicMock()
        mock_data.search_bm25.return_value = [
            (TextChunk(id=f"h{index}", text=f"t{index}"), float(20 - index))
            for index in range(12)
        ]
        mock_data.get_text_chunks.return_value = (
            [TextChunk(id="title-hit", text="navy velvet sofa")],
            1,
        )
        mock_embeddings = MagicMock()
        mock_vs = MagicMock()

        with (
            patch.object(search_mod.config, "search_enabled", True),
            patch.object(search_mod.config, "search_use_dense", False),
            patch.object(search_mod.config, "search_use_bm25", True),
            patch.object(search_mod.config, "search_literal_fill", True),
            patch.object(search_mod, "embeddings_adapter", mock_embeddings),
            patch.object(search_mod, "vector_search", mock_vs),
            patch.object(search_mod, "data_adapter", mock_data),
        ):
            response = await search_mod.search(
                SearchRequestBody(query="navy velvet sofa", k=15)
            )

        ids = [hit.id for hit in response.hits]
        self.assertEqual(ids[:10], [f"h{index}" for index in range(10)])
        self.assertIn("title-hit", ids[10:])
        self.assertEqual(response.channel_lists["literal"], ["title-hit"])


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