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.

8.9 KB
Raw Blame
import os
import sys
import unittest
from datetime import datetime, timedelta
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.kg import Node, Predicate
from src.core.search.recommend import (
    DEFAULT_BEHAVIOR_WEIGHTS,
    EntityRecommendRetriever,
    behavior_weight,
    degree_dampen,
    recency_decay,
    attr_idf,
)


def _node(uuid: str, name: str, labels: list[str], happened_at=None) -> Node:
    return Node.model_construct(
        uuid=uuid,
        name=name,
        labels=labels,
        happened_at=happened_at,
        properties={},
    )


def _pred(name: str = "MADE", weight=None) -> Predicate:
    props = {"weight": weight} if weight is not None else {}
    return Predicate.model_construct(
        uuid=f"pred-{name}-{weight}",
        name=name,
        description=name,
        properties=props,
        deprecated=False,
    )


class BehaviorWeightTests(unittest.TestCase):
    def test_purchase_higher_than_view(self):
        self.assertEqual(behavior_weight("Purchase"), 1.0)
        self.assertEqual(behavior_weight("View"), 0.2)
        self.assertEqual(behavior_weight("AddToCart"), 0.5)

    def test_unknown_defaults_to_view_weight(self):
        self.assertEqual(behavior_weight("WeirdEvent"), 0.2)

    def test_favorite_between_cart_and_purchase(self):
        self.assertEqual(behavior_weight("Favorite"), 0.7)
        self.assertEqual(behavior_weight("wishlist"), 0.7)
        self.assertEqual(behavior_weight("add_to_favorite"), 0.7)
        self.assertGreater(behavior_weight("Favorite"), behavior_weight("AddToCart"))
        self.assertLess(behavior_weight("Favorite"), behavior_weight("Purchase"))

    def test_follow_is_half(self):
        self.assertEqual(behavior_weight("Follow"), 0.5)
        self.assertEqual(behavior_weight("FLW"), 0.5)
        self.assertEqual(behavior_weight("follow"), 0.5)
        self.assertGreater(behavior_weight("Follow"), behavior_weight("WeirdEvent"))
        self.assertLess(behavior_weight("Follow"), behavior_weight("Favorite"))

    def test_custom_table(self):
        self.assertEqual(behavior_weight("View", {"view": 0.9}), 0.9)


class RecencyDecayTests(unittest.TestCase):
    def test_off_when_half_life_none(self):
        self.assertEqual(recency_decay("01/01/2020", None), 1.0)

    def test_older_decays_more(self):
        now = datetime(2026, 8, 6)
        older = recency_decay("01/01/2020", 30.0, now=now)
        newer = recency_decay("01/08/2026", 30.0, now=now)
        self.assertLess(older, newer)
        self.assertLessEqual(newer, 1.0)

    def test_half_life_halves(self):
        now = datetime(2026, 8, 6)
        past = (now - timedelta(days=30)).strftime("%d/%m/%Y")
        score = recency_decay(past, 30.0, now=now)
        self.assertAlmostEqual(score, 0.5, places=2)


class DegreeDampenTests(unittest.TestCase):
    def test_disabled(self):
        self.assertEqual(degree_dampen(100, False), 1.0)

    def test_hub_lower_than_rare(self):
        self.assertLess(degree_dampen(100, True), degree_dampen(1, True))

    def test_attr_idf_monotonic(self):
        self.assertLess(attr_idf(50), attr_idf(2))


class RecommendExcludeSeenTests(unittest.TestCase):
    @patch("src.core.search.recommend.graph_adapter")
    @patch("src.core.search.recommend.EntitySinergyRetriever")
    def test_exclude_seen_keeps_collaborative_unseen(self, mock_syn_cls, mock_graph):
        user = _node("user:u1", "u1", ["USER"])
        peer = _node("user:u2", "u2", ["USER"])
        shared = _node("item:a", "a", ["PRODUCT"])
        fresh = _node("item:b", "b", ["PRODUCT"])
        evt_u1 = _node("evt:1", "Purchase", ["EVENT"], happened_at="01/08/2026")
        evt_u2_shared = _node("evt:2", "Purchase", ["EVENT"], happened_at="01/08/2026")
        evt_u2_fresh = _node("evt:3", "Purchase", ["EVENT"], happened_at="01/08/2026")

        mock_syn = MagicMock()
        mock_syn.retrieve_sibilings.return_value = (user, [], [], [])
        mock_syn_cls.return_value = mock_syn

        def get_neighbors(uuids, of_types=None, brain_id="default"):
            uid = uuids[0]
            if uid == user.uuid:
                return {user.uuid: [(_pred("MADE"), evt_u1)]}
            if uid == evt_u1.uuid:
                return {
                    evt_u1.uuid: [
                        (_pred("TARGETED"), shared),
                        (_pred("MADE"), user),
                    ]
                }
            if uid == shared.uuid:
                return {
                    shared.uuid: [
                        (_pred("TARGETED"), evt_u1),
                        (_pred("TARGETED"), evt_u2_shared),
                    ]
                }
            if uid == evt_u2_shared.uuid:
                return {
                    evt_u2_shared.uuid: [
                        (_pred("MADE"), peer),
                        (_pred("TARGETED"), shared),
                    ]
                }
            if uid == peer.uuid:
                return {
                    peer.uuid: [
                        (_pred("MADE"), evt_u2_shared),
                        (_pred("MADE"), evt_u2_fresh),
                    ]
                }
            if uid == evt_u2_fresh.uuid:
                return {
                    evt_u2_fresh.uuid: [
                        (_pred("MADE"), peer),
                        (_pred("TARGETED"), fresh),
                    ]
                }
            return {uid: []}

        mock_graph.get_neighbors.side_effect = get_neighbors

        retriever = EntityRecommendRetriever("demorecsys")
        _, recs = retriever.recommend(
            "u1",
            include_asymmetric=True,
            include_multi_interest=False,
            include_attribute_pref=False,
            exclude_seen=True,
            diversify=False,
            labels=["PRODUCT"],
            top_k=10,
        )
        uuids = {r["node"].uuid for r in recs}
        self.assertNotIn(shared.uuid, uuids)
        self.assertIn(fresh.uuid, uuids)

    @patch("src.core.search.recommend.graph_adapter")
    @patch("src.core.search.recommend.EntitySinergyRetriever")
    def test_behavior_weights_rank_purchase_above_view(
        self, mock_syn_cls, mock_graph
    ):
        user = _node("user:u1", "u1", ["USER"])
        p_view = _node("item:v", "v", ["PRODUCT"])
        p_buy = _node("item:b", "b", ["PRODUCT"])
        evt_view = _node("evt:v", "View", ["EVENT"], happened_at="01/08/2026")
        evt_buy = _node("evt:b", "Purchase", ["EVENT"], happened_at="01/08/2026")

        mock_syn = MagicMock()
        mock_syn.retrieve_sibilings.return_value = (user, [], [], [])
        mock_syn_cls.return_value = mock_syn

        def get_neighbors(uuids, of_types=None, brain_id="default"):
            uid = uuids[0]
            if uid == user.uuid:
                return {
                    user.uuid: [
                        (_pred("MADE"), evt_view),
                        (_pred("MADE"), evt_buy),
                    ]
                }
            if uid == evt_view.uuid:
                return {evt_view.uuid: [(_pred("TARGETED"), p_view)]}
            if uid == evt_buy.uuid:
                return {evt_buy.uuid: [(_pred("TARGETED"), p_buy)]}
            return {uid: []}

        mock_graph.get_neighbors.side_effect = get_neighbors

        retriever = EntityRecommendRetriever("demorecsys")
        _, recs = retriever.recommend(
            "u1",
            include_asymmetric=True,
            include_multi_interest=False,
            include_attribute_pref=False,
            exclude_seen=False,
            diversify=False,
            labels=["PRODUCT"],
            top_k=10,
            behavior_weights=DEFAULT_BEHAVIOR_WEIGHTS,
        )
        self.assertGreaterEqual(len(recs), 2)
        by_uuid = {r["node"].uuid: r["score"] for r in recs}
        self.assertGreater(by_uuid[p_buy.uuid], by_uuid[p_view.uuid])


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