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.5 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",
    "PIPELINE_MODE": "accurate",
}
for key, value in ENV_DEFAULTS.items():
    os.environ.setdefault(key, value)


def _immediate_chain_factory(persist_calls):
    class ImmediateChain:
        def __init__(self, *steps):
            self.steps = steps

        def apply_async(self, *args, **kwargs):
            for step in self.steps:
                task_name = getattr(step, "task", None) or getattr(step, "name", "")
                args_ = getattr(step, "args", ()) or ()
                if "process_architect_relationships" in str(task_name) and args_:
                    persist_calls.append(args_[0])
            return MagicMock(id="chain")

    return ImmediateChain



def _full_triple():
    return {
        "subject": {"name": "Alice", "type": "PERSON", "uuid": "sub-1"},
        "subj_event": {"name": "MADE", "uuid": "rel-1"},
        "event": {
            "name": "Purchase",
            "type": "EVENT",
            "uuid": "evt-1",
            "happened_at": "01/01/2024",
        },
        "event_obj": {"name": "TARGETED", "uuid": "rel-2", "amount": 3},
        "object": {"name": "Widget", "type": "PRODUCT", "uuid": "obj-1"},
    }


class TripleConversionTests(unittest.TestCase):
    def test_full_triple_produces_subject_event_and_event_object_edges(self):
        from src.core.agents.architect_agent import ingestion_triples_to_relationships
        from src.services.api.constants.requests import IngestionTripleSet

        triple = IngestionTripleSet(**_full_triple())
        relationships, entities = ingestion_triples_to_relationships([triple], [])

        self.assertEqual(len(relationships), 2)
        self.assertEqual(relationships[0].tail.uuid, "sub-1")
        self.assertEqual(relationships[0].name, "MADE")
        self.assertEqual(relationships[0].tip.uuid, "evt-1")
        self.assertEqual(relationships[0].tip.happened_at, "01/01/2024")
        self.assertEqual(relationships[1].tail.uuid, "evt-1")
        self.assertEqual(relationships[1].name, "TARGETED")
        self.assertEqual(relationships[1].tip.uuid, "obj-1")
        self.assertEqual(relationships[1].amount, 3)
        self.assertIn(("alice", "person"), entities)
        self.assertIn(("purchase", "event", "01/01/2024"), entities)

    def test_direct_has_is_one_edge_not_event(self):
        from src.core.agents.architect_agent import ingestion_triples_to_relationships
        from src.services.api.constants.requests import IngestionTripleSet

        triple = IngestionTripleSet(
            subject={"name": "bed", "type": "ENTITY", "uuid": "0"},
            subj_event={"name": "HAS", "uuid": "rel-has-1"},
            object={"name": "rubberwood", "type": "ATTR", "uuid": "hub-attr-rubberwood"},
        )
        relationships, entities = ingestion_triples_to_relationships([triple], [])
        self.assertEqual(len(relationships), 1)
        self.assertEqual(relationships[0].tail.uuid, "0")
        self.assertEqual(relationships[0].name, "HAS")
        self.assertEqual(relationships[0].tip.uuid, "hub-attr-rubberwood")
        self.assertEqual(relationships[0].tip.type, "ATTR")
        self.assertNotIn(("has", "event", ""), entities)
        self.assertNotIn(("has", "event"), entities)

    def test_has_wrapper_without_happened_at_collapses(self):
        from src.core.agents.architect_agent import ingestion_triples_to_relationships
        from src.services.api.constants.requests import IngestionTripleSet

        triple = IngestionTripleSet(
            subject={"name": "bed", "type": "ENTITY", "uuid": "0"},
            subj_event={"name": "HAS", "uuid": "rel-1"},
            event={"name": "HAS", "type": "EVENT", "uuid": "evt-has"},
            event_obj={"name": "HAS", "uuid": "rel-2"},
            object={"name": "modern", "type": "ATTR", "uuid": "hub-modern"},
        )
        relationships, entities = ingestion_triples_to_relationships([triple], [])
        self.assertEqual(len(relationships), 1)
        self.assertEqual(relationships[0].tail.uuid, "0")
        self.assertEqual(relationships[0].tip.uuid, "hub-modern")
        self.assertEqual(relationships[0].name, "HAS")
        self.assertTrue(
            all(getattr(rel.tail, "type", "").upper() != "EVENT" for rel in relationships)
        )
        self.assertTrue(
            all(getattr(rel.tip, "type", "").upper() != "EVENT" for rel in relationships)
        )

    def test_has_event_with_happened_at_stays_two_edges(self):
        from src.core.agents.architect_agent import ingestion_triples_to_relationships
        from src.services.api.constants.requests import IngestionTripleSet

        triple = IngestionTripleSet(
            subject={"name": "u1", "type": "USER", "uuid": "user-1"},
            subj_event={"name": "HAS", "uuid": "rel-1"},
            event={
                "name": "HAS",
                "type": "EVENT",
                "uuid": "evt-dated",
                "happened_at": "01/02/2024",
            },
            event_obj={"name": "HAS", "uuid": "rel-2"},
            object={"name": "sku-1", "type": "ENTITY", "uuid": "sku-1"},
        )
        relationships, _ = ingestion_triples_to_relationships([triple], [])
        self.assertEqual(len(relationships), 2)
        self.assertEqual(relationships[0].tip.uuid, "evt-dated")
        self.assertEqual(relationships[1].tail.uuid, "evt-dated")

    def test_direct_prefers_is_one_edge(self):
        from src.core.agents.architect_agent import ingestion_triples_to_relationships
        from src.services.api.constants.requests import IngestionTripleSet

        triple = IngestionTripleSet(
            subject={"name": "u01", "type": "USER", "uuid": "user:u01"},
            subj_event={
                "name": "PREFERS",
                "uuid": "rel-pref-1",
                "amount": 0.2,
                "properties": {"facet": "style", "value": "70s"},
            },
            object={"name": "70s", "type": "ATTR", "uuid": "hub:attr:70s"},
        )
        relationships, entities = ingestion_triples_to_relationships([triple], [])
        self.assertEqual(len(relationships), 1)
        self.assertEqual(relationships[0].tail.uuid, "user:u01")
        self.assertEqual(relationships[0].name, "PREFERS")
        self.assertEqual(relationships[0].tip.uuid, "hub:attr:70s")
        self.assertEqual(relationships[0].amount, 0.2)
        self.assertNotIn(("prefers", "event", ""), entities)
        self.assertNotIn(("prefers", "event"), entities)


class StructuredTriplePersistenceTests(unittest.TestCase):
    def test_triple_only_persists_without_llm(self):
        from src.workers.tasks import ingestion as ingestion_mod

        request = MagicMock()
        request.id = "task-struct-1"
        persist_calls = []
        saved_structured = []
        scout_called = []
        architect_called = []

        args = {
            "data": [_full_triple()],
            "brain_id": "tenant-a",
            "text": None,
            "mode": "deterministic",
        }

        with (
            patch.object(ingestion_mod, "cache_adapter"),
            patch.object(ingestion_mod, "graph_adapter"),
            patch.object(ingestion_mod, "IngestionManager"),
            patch.object(ingestion_mod, "data_adapter") as data_adapter,
            patch.object(ingestion_mod, "ScoutAgent") as ScoutAgent,
            patch.object(ingestion_mod, "ArchitectAgent") as ArchitectAgent,
            patch.object(ingestion_mod, "KGAgent") as KGAgent,
            patch("celery.chain", _immediate_chain_factory(persist_calls)),
            patch.object(ingestion_mod, "set_ingestion_task_status"),
            patch.object(ingestion_mod, "finalize_ingestion_task"),
        ):
            data_adapter.save_structured_data.side_effect = (
                lambda data, brain_id="default": saved_structured.append(
                    {"data": data, "brain_id": brain_id}
                )
                or data
            )
            ScoutAgent.side_effect = lambda **kwargs: scout_called.append(True)
            ArchitectAgent.side_effect = lambda **kwargs: architect_called.append(True)
            KGAgent.side_effect = lambda **kwargs: (_ for _ in ()).throw(
                AssertionError("KGAgent must not be constructed in deterministic mode")
            )

            result = ingestion_mod.ingest_structured_data.run.__func__(
                type("Bound", (), {"request": request})(),
                args,
            )

        self.assertEqual(result, "task-struct-1")
        self.assertEqual(len(persist_calls), 1)
        relationships = persist_calls[0]["relationships"]
        self.assertEqual(len(relationships), 2)
        self.assertEqual(relationships[0]["name"], "MADE")
        self.assertEqual(relationships[1]["name"], "TARGETED")
        self.assertEqual(
            relationships[0]["properties"].get("source"), "structured_deterministic"
        )
        self.assertEqual(persist_calls[0]["brain_id"], "tenant-a")
        self.assertEqual(len(saved_structured), 1)
        self.assertEqual(saved_structured[0]["brain_id"], "tenant-a")
        self.assertEqual(saved_structured[0]["data"].id, "task-struct-1")
        self.assertEqual(scout_called, [])
        self.assertEqual(architect_called, [])

    def test_deterministic_ignores_text_for_llm(self):
        from src.workers.tasks import ingestion as ingestion_mod

        request = MagicMock()
        request.id = "task-struct-det-text"
        persist_calls = []
        scout_called = []

        args = {
            "data": [_full_triple()],
            "brain_id": "recsys-demo",
            "text": "should not trigger scout",
            "mode": "deterministic",
        }

        with (
            patch.object(ingestion_mod, "cache_adapter"),
            patch.object(ingestion_mod, "graph_adapter"),
            patch.object(ingestion_mod, "IngestionManager"),
            patch.object(ingestion_mod, "data_adapter"),
            patch.object(ingestion_mod, "ScoutAgent") as ScoutAgent,
            patch.object(ingestion_mod, "ArchitectAgent"),
            patch.object(ingestion_mod, "KGAgent"),
            patch("celery.chain", _immediate_chain_factory(persist_calls)),
            patch.object(ingestion_mod, "set_ingestion_task_status"),
            patch.object(ingestion_mod, "finalize_ingestion_task"),
        ):
            ScoutAgent.side_effect = lambda **kwargs: scout_called.append(True)
            ingestion_mod.ingest_structured_data.run.__func__(
                type("Bound", (), {"request": request})(),
                args,
            )

        self.assertEqual(scout_called, [])
        self.assertEqual(len(persist_calls), 1)

    def test_deterministic_fails_closed_on_unresolved_name_anchor(self):
        from src.workers.tasks import ingestion as ingestion_mod

        request = MagicMock()
        request.id = "task-struct-anchor-fail"
        graph = MagicMock()
        graph.get_by_identification_params.return_value = None

        args = {
            "data": [_full_triple()],
            "brain_id": "recsys-demo",
            "mode": "deterministic",
            "anchor": {"name": "Alice", "type": "PERSON"},
        }

        with (
            patch.object(ingestion_mod, "cache_adapter"),
            patch.object(ingestion_mod, "graph_adapter", graph),
            patch.object(ingestion_mod, "IngestionManager"),
            patch.object(ingestion_mod, "data_adapter"),
            patch.object(ingestion_mod, "KGAgent") as KGAgent,
            patch.object(ingestion_mod, "set_ingestion_task_status"),
        ):
            KGAgent.side_effect = lambda **kwargs: (_ for _ in ()).throw(
                AssertionError("KGAgent must not run in deterministic mode")
            )
            with self.assertRaises(ValueError) as ctx:
                ingestion_mod.ingest_structured_data.run.__func__(
                    type("Bound", (), {"request": request})(),
                    args,
                )
        self.assertIn("deterministic mode", str(ctx.exception))

    def test_text_enrichment_does_not_repersist_submitted_triples(self):
        from src.core.agents.architect_agent import ArchitectAgentResponse
        from src.core.agents.scout_agent import ScoutAgentResponse
        from src.workers.tasks import ingestion as ingestion_mod

        request = MagicMock()
        request.id = "task-struct-2"
        persist_calls = []
        run_structured_kwargs = []

        args = {
            "data": [_full_triple()],
            "brain_id": "tenant-a",
            "text": "Alice bought a widget",
            "mode": "hybrid",
        }

        scout = MagicMock()
        scout.run_structured.return_value = ScoutAgentResponse(entities=[])
        architect = MagicMock()
        architect.session_id = "sess-enrich"
        architect.take_pending_relationships.return_value = []
        architect.run_structured.side_effect = (
            lambda **kwargs: run_structured_kwargs.append(kwargs)
            or ArchitectAgentResponse(new_nodes=[], relationships=[])
        )

        with (
            patch.object(ingestion_mod, "cache_adapter"),
            patch.object(ingestion_mod, "graph_adapter"),
            patch.object(ingestion_mod, "IngestionManager"),
            patch.object(ingestion_mod, "data_adapter"),
            patch.object(ingestion_mod, "ScoutAgent", return_value=scout),
            patch.object(ingestion_mod, "ArchitectAgent", return_value=architect),
            patch("celery.chain", _immediate_chain_factory(persist_calls)),
            patch.object(ingestion_mod, "set_ingestion_task_status"),
            patch.object(ingestion_mod, "finalize_ingestion_task"),
        ):
            ingestion_mod.ingest_structured_data.run.__func__(
                type("Bound", (), {"request": request})(),
                args,
            )

        self.assertEqual(len(persist_calls), 1)
        self.assertEqual(len(run_structured_kwargs), 1)
        self.assertFalse(run_structured_kwargs[0]["persist_submitted"])
        for rel in persist_calls[0]["relationships"]:
            self.assertEqual(rel["properties"].get("source"), "structured_deterministic")

    def test_resolved_mode_inference(self):
        from src.services.api.constants.requests import (
            IngestionStructuredRequestBody,
            IngestionTripleSet,
        )

        triple = IngestionTripleSet(**_full_triple())
        self.assertEqual(
            IngestionStructuredRequestBody(data=[triple]).resolved_mode(),
            "deterministic",
        )
        self.assertEqual(
            IngestionStructuredRequestBody(
                data=[triple], text="x"
            ).resolved_mode(),
            "hybrid",
        )
        self.assertEqual(
            IngestionStructuredRequestBody(
                data=[triple], text="x", mode="deterministic"
            ).resolved_mode(),
            "deterministic",
        )


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