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
feat(retrieval): support history-aware retrieve and graph store helpers
Christian35e347996365
diff --git a/src/adapters/graph.py b/src/adapters/graph.pyindex 3ce6f10..cc2cc5c 100644--- a/src/adapters/graph.py+++ b/src/adapters/graph.py@@ -839,6 +839,14 @@ class GraphAdapter:def rebuild_hub_bridge_index(self, brain_id: str = "default") -> int:return self.graph.rebuild_hub_bridge_index(brain_id)+ def refresh_hub_bridges_for_entities(+ self, entity_uuids: list, brain_id: str = "default"+ ) -> int:+ refresh = getattr(self.graph, "refresh_hub_bridges_for_entities", None)+ if refresh is None:+ return self.rebuild_hub_bridge_index(brain_id)+ return int(refresh(brain_id, list(entity_uuids or [])) or 0)+def get_hub_bridges(self,event_uuids: list[str],diff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.pyindex de8affe..9079052 100644--- a/src/lib/neo4j/client.py+++ b/src/lib/neo4j/client.py@@ -2207,6 +2207,81 @@ class Neo4jClient(GraphClient):)return len(bridges)+ def refresh_hub_bridges_for_entities(+ self, brain_id: str, entity_uuids: list[str]+ ) -> int:+ from src.core.saving.hub_bridges import (+ bridges_from_memberships,+ entity_event_memberships,+ )++ touched = sorted({str(u) for u in entity_uuids if u})+ if not touched:+ return self.rebuild_hub_bridge_index(brain_id)++ self.ensure_database(brain_id)+ cypher_rows = """+ MATCH (event)-[r]-(entity)+ WHERE 'EVENT' IN labels(event)+ AND NOT 'EVENT' IN labels(entity)+ AND type(r) <> 'HUB_BRIDGE'+ AND entity['uuid'] IN $entity_uuids+ RETURN event['uuid'] AS event_uuid,+ entity['uuid'] AS entity_uuid,+ entity['name'] AS entity_name,+ type(r) AS rel_name+ """+ result = self.driver.execute_query(+ cypher_rows,+ parameters_={"entity_uuids": touched},+ database_=brain_id,+ )+ rows = [+ (+ str(record.get("event_uuid") or ""),+ str(record.get("entity_uuid") or ""),+ str(record.get("entity_name") or ""),+ str(record.get("rel_name") or ""),+ )+ for record in result.records+ ]+ bridges = bridges_from_memberships(entity_event_memberships(rows))+ self.driver.execute_query(+ """+ MATCH ()-[r:HUB_BRIDGE]->()+ WHERE r.shared_entity IN $entity_uuids+ DELETE r+ """,+ parameters_={"entity_uuids": touched},+ database_=brain_id,+ )+ for bridge in bridges:+ self.driver.execute_query(+ """+ MATCH (a {uuid: $event_a}), (b {uuid: $event_b})+ WHERE 'EVENT' IN labels(a) AND 'EVENT' IN labels(b)+ MERGE (a)-[r:HUB_BRIDGE {+ shared_entity: $shared_entity+ }]->(b)+ SET r.shared_entity_name = $shared_entity_name,+ r.weight = $weight,+ r.uuid = $bridge_uuid+ """,+ parameters_={+ "event_a": bridge.event_a,+ "event_b": bridge.event_b,+ "shared_entity": bridge.shared_entity,+ "shared_entity_name": bridge.shared_entity_name,+ "weight": float(bridge.weight),+ "bridge_uuid": (+ f"hub-bridge:{bridge.event_a}:{bridge.event_b}:"+ f"{bridge.shared_entity}"+ ),+ },+ database_=brain_id,+ )+ return len(bridges)+def get_hub_bridges(self,event_uuids: list[str],diff --git a/src/lib/postgresql/graph_store.py b/src/lib/postgresql/graph_store.pyindex 54b9b49..0e7b88d 100644--- a/src/lib/postgresql/graph_store.py+++ b/src/lib/postgresql/graph_store.py@@ -834,6 +834,51 @@ class PostgreSQLGraphStore:conn.commit()return len(bridges)+ def delete_hub_bridges_for_entities(+ self, brain_id: str, entity_uuids: list[str]+ ) -> int:+ unique = sorted({str(u) for u in entity_uuids if u})+ if not unique:+ return 0+ self._ensure_brain_schema(brain_id)+ with self._connection(brain_id) as conn:+ with conn.cursor() as cur:+ cur.execute(+ "DELETE FROM kg_hub_bridges WHERE shared_entity = ANY(%s)",+ (unique,),+ )+ deleted = cur.rowcount or 0+ conn.commit()+ return int(deleted)++ def upsert_hub_bridges(+ self,+ brain_id: str,+ bridges: list[tuple[str, str, str, str, float]],+ ) -> int:+ if not bridges:+ return 0+ self._ensure_brain_schema(brain_id)+ with self._connection(brain_id) as conn:+ with conn.cursor() as cur:+ for event_a, event_b, shared_entity, shared_name, weight in bridges:+ if not event_a or not event_b or event_a == event_b:+ continue+ a, b = (event_a, event_b) if event_a < event_b else (event_b, event_a)+ cur.execute(+ """+ INSERT INTO kg_hub_bridges+ (event_a, event_b, shared_entity, shared_entity_name, weight)+ VALUES (%s, %s, %s, %s, %s)+ ON CONFLICT (event_a, event_b, shared_entity) DO UPDATE SET+ shared_entity_name = EXCLUDED.shared_entity_name,+ weight = EXCLUDED.weight+ """,+ (a, b, shared_entity, shared_name or "", float(weight)),+ )+ conn.commit()+ return len(bridges)+def get_hub_bridges_for_events(self,brain_id: str,diff --git a/src/lib/postgresql/networkx_client.py b/src/lib/postgresql/networkx_client.pyindex 1272285..2dd14e6 100644--- a/src/lib/postgresql/networkx_client.py+++ b/src/lib/postgresql/networkx_client.py@@ -1378,6 +1378,61 @@ class NetworkXGraphClient(GraphClient):]return self._store.replace_hub_bridges(brain_id, payload)+ def refresh_hub_bridges_for_entities(+ self, brain_id: str, entity_uuids: list[str]+ ) -> int:+ from src.core.saving.hub_bridges import (+ bridges_from_memberships,+ entity_event_memberships,+ is_event_labels,+ )++ touched = sorted({str(u) for u in entity_uuids if u})+ if not touched:+ return self.rebuild_hub_bridge_index(brain_id)++ self._store.ensure_database(brain_id)+ brain = self._store.get_brain(brain_id)+ touched_set = set(touched)+ rows: list[tuple[str, str, str, str]] = []+ for source, target, _key, edge_data in brain.graph.edges(keys=True, data=True):+ rel_name = str(edge_data.get("rel_type") or edge_data.get("name") or "")+ source_labels = brain.labels(source)+ target_labels = brain.labels(target)+ source_is_event = is_event_labels(source_labels)+ target_is_event = is_event_labels(target_labels)+ if source_is_event and not target_is_event and target in touched_set:+ rows.append(+ (+ source,+ target,+ str(brain.node_data(target).get("name") or ""),+ rel_name,+ )+ )+ elif target_is_event and not source_is_event and source in touched_set:+ rows.append(+ (+ target,+ source,+ str(brain.node_data(source).get("name") or ""),+ rel_name,+ )+ )+ bridges = bridges_from_memberships(entity_event_memberships(rows))+ payload = [+ (+ br.event_a,+ br.event_b,+ br.shared_entity,+ br.shared_entity_name,+ br.weight,+ )+ for br in bridges+ ]+ self._store.delete_hub_bridges_for_entities(brain_id, touched)+ return self._store.upsert_hub_bridges(brain_id, payload)+def get_hub_bridges(self,event_uuids: list[str],@@ -1412,13 +1467,19 @@ class NetworkXGraphClient(GraphClient):self._store.ensure_database(brain_id)brain = self._store.get_brain(brain_id)- session_re = re.compile(r"session_(\d+)", re.IGNORECASE)+ session_re = re.compile(+ r"session_(\d+)|(?:\b|_)b(\d+)_t(\d+)\b",+ re.IGNORECASE,+ )def sessions_from_text(text: str) -> list[str]:found: list[str] = []seen: set[str] = set()for match in session_re.finditer(text or ""):- sid = f"session_{match.group(1)}"+ if match.group(1):+ sid = f"session_{match.group(1)}"+ else:+ sid = f"session_b{match.group(2)}_t{match.group(3)}"if sid not in seen:seen.add(sid)found.append(sid)diff --git a/src/services/api/controllers/retrieve.py b/src/services/api/controllers/retrieve.pyindex 4b48d5f..a62434f 100644--- a/src/services/api/controllers/retrieve.py+++ b/src/services/api/controllers/retrieve.py@@ -52,6 +52,26 @@ _PASSAGE_K = 24_PPR_DAMPING = 0.85_PPR_ITERS = 20_SESSION_RE = re.compile(r"session_(\d+)", re.IGNORECASE)+_BATCH_TURN_RE = re.compile(r"\bb(\d+)_t(\d+)\b", re.IGNORECASE)+_HISTORY_MODE_RE = re.compile(+ r"\b("+ r"order(?:ing|ed)?|chronolog|sequence|walk me through|"+ r"contradict|conflict(?:ing)?|inconsisten|"+ r"previously|originally|before (?:the |that )?(?:update|change|extension)|"+ r"first (?:said|stated|mentioned|sprint|deadline)|"+ r"how many (?:weeks|days)|"+ r"between .+ and |"+ r"have i|did i"+ r")\b",+ re.I,+)+_CURRENT_TRUTH_RE = re.compile(+ r"\b("+ r"now|currently|latest|updated (?:to|value)|after the (?:update|change)|"+ r"how many commits|average response time|response time of"+ r")\b",+ re.I,+)_SPINE_ACTOR = ("MADE", "INITIATED", "PERFORMED", "EXPERIENCED", "COVERED")_SPINE_TARGET = ("TARGETED", "AFFECTED", "RESULTED")_CONTEXT_REL = ("OCCURRED", "WITHIN")@@ -204,6 +224,7 @@ def _expand_cross_event_bridges(brain_id: str,*,max_per_hub: int,+ include_history: bool = False,) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:from src.core.saving.hub_bridges import (HubBridge,@@ -347,7 +368,7 @@ def _expand_cross_event_bridges(score = max(0.0, score - min(0.05, 0.02 * len(novel)))reserve_ok = seed in reserve_hubsfor n, r, m, r2, b in facts_by_hub.get(event_uuid, []):- if not _is_currently_valid(r) or not _is_currently_valid(r2):+ if not _fact_predicates_allowed(r, r2, include_history=include_history):continuekey = _fact_key(r, r2)if key in existing_keys:@@ -355,13 +376,18 @@ def _expand_cross_event_bridges(existing_keys.add(key)chunk_ids = _extract_source_chunk_ids(n, r, m, r2, b)session_ids = _sessions_from_chunk_map(chunk_ids, chunk_sessions)+ fact_text = _format_event_fact(n, r, m, r2, b)+ if include_history and not (+ _is_currently_valid(r) and _is_currently_valid(r2)+ ):+ fact_text = f"[superseded] {fact_text}"expanded.append({"identified_entity": f"bridge:{bridge.shared_entity}","triple": (n, r, m, r2, b),"score": score,"key": key,- "text": _format_event_fact(n, r, m, r2, b),+ "text": fact_text,"chunk_ids": chunk_ids,"session_ids": session_ids,"bridge": {@@ -1244,6 +1270,26 @@ def _is_currently_valid(predicate: Predicate) -> bool:return True+def _wants_historical_facts(query: str) -> bool:+ text = (query or "").strip()+ if not text:+ return False+ if _CURRENT_TRUTH_RE.search(text) and not _HISTORY_MODE_RE.search(text):+ return False+ return bool(_HISTORY_MODE_RE.search(text))+++def _fact_predicates_allowed(+ r: Predicate,+ r2: Predicate,+ *,+ include_history: bool,+) -> bool:+ if include_history:+ return True+ return _is_currently_valid(r) and _is_currently_valid(r2)++def _collect_query_variants(text: str, elements) -> list[str]:seen: set[str] = set()variants: list[str] = []@@ -1275,6 +1321,8 @@ def _collect_query_variants(text: str, elements) -> list[str]:added_chunks += 1for extra in _decompose_enumeration_queries(text, elements):_add(extra)+ for extra in _ordering_aspect_queries(text):+ _add(extra)return variants@@ -1283,12 +1331,47 @@ _ENUMERATION_RE = re.compile(r"changes?|traits?|hobbies|activities)\b",re.IGNORECASE,)+_ORDERING_ASPECT_QUERIES_BUDGET = (+ "core functionality authentication expense tracking visualization",+ "transaction CRUD error handling response management",+ "security deployment integration tests gunicorn workers",+)+_ORDERING_ASPECT_QUERIES_TRANSLATION = (+ "translation API integration error handling DeepL",+ "rate limiting request queue caching Redis",+ "language detection libraries franc evaluation",+ "database schema optimization contextual memory store",+)def _is_enumeration_question(text: str) -> bool:return bool(_ENUMERATION_RE.search(text or ""))+def _is_ordering_question(text: str) -> bool:+ return bool(+ re.search(+ r"\b(order|ordered|ordering|chronolog|sequence|walk me through)\b",+ text or "",+ re.I,+ )+ )+++def _ordering_aspect_queries(text: str) -> list[str]:+ if not _is_ordering_question(text):+ return []+ q = text or ""+ if re.search(+ r"\b(translation|language detection|deepl|franc|microservice|"+ r"multi-language|rate limit)\b",+ q,+ re.I,+ ):+ return list(_ORDERING_ASPECT_QUERIES_TRANSLATION)[:2]+ return list(_ORDERING_ASPECT_QUERIES_BUDGET)[:2]++def _decompose_enumeration_queries(text: str, elements) -> list[str]:if not _is_enumeration_question(text):return []@@ -1349,6 +1432,7 @@ def _build_adjacency_from_seeds(*,query: str | None = None,query_embedding: list[float] | None = None,+ include_history: bool = False,) -> dict[str, list[tuple[str, float]]]:weighted: dict[str, dict[str, float]] = {}if not seed_uuids:@@ -1360,7 +1444,7 @@ def _build_adjacency_from_seeds(except Exception:return {}for n, r, m, r2, b in neighbors:- if not _is_currently_valid(r) or not _is_currently_valid(r2):+ if not _fact_predicates_allowed(r, r2, include_history=include_history):continuen_uuid = getattr(n, "uuid", None)m_uuid = getattr(m, "uuid", None)@@ -1538,6 +1622,11 @@ def _session_ids_from_text(text: str) -> list[str]:if sid not in seen:seen.add(sid)found.append(sid)+ for match in _BATCH_TURN_RE.finditer(text or ""):+ sid = f"session_b{match.group(1)}_t{match.group(2)}"+ if sid not in seen:+ seen.add(sid)+ found.append(sid)return found@@ -1694,6 +1783,7 @@ async def _build_context(candidates: list[dict[str, Any]] = []seed_hits: list[tuple[str, float, str]] = []passage_hits: list[tuple[str, float, str]] = []+ include_history = _wants_historical_facts(request.text)def _collect_facts_for_variant(text: str,@@ -1724,7 +1814,9 @@ async def _build_context(local: list[dict[str, Any]] = []with profile_stage("facts.assemble"):for n, r, m, r2, b in neighbors:- if not _is_currently_valid(r) or not _is_currently_valid(r2):+ if not _fact_predicates_allowed(+ r, r2, include_history=include_history+ ):continuedistances = [uuid_to_distance[u]@@ -1736,13 +1828,18 @@ async def _build_context(if u in uuid_to_distance]score = min(distances) if distances else float("inf")+ fact_text = _format_event_fact(n, r, m, r2, b)+ if include_history and not (+ _is_currently_valid(r) and _is_currently_valid(r2)+ ):+ fact_text = f"[superseded] {fact_text}"local.append({"identified_entity": text,"triple": (n, r, m, r2, b),"score": score,"key": _fact_key(r, r2),- "text": _format_event_fact(n, r, m, r2, b),+ "text": fact_text,"chunk_ids": _extract_source_chunk_ids(n, r, m, r2, b),})@@ -1854,6 +1951,7 @@ async def _build_context(candidates,request.brain_id,max_per_hub=request.cross_event_bridges,+ include_history=include_history,)detail["candidates"] = len(candidates)detail["paths"] = len(bridge_paths)@@ -1873,6 +1971,7 @@ async def _build_context(sorted(personalization.keys()),request.brain_id,query=request.text,+ include_history=include_history,)adjacency_detail["nodes"] = len(adjacency)with profile_stage("ppr.iterations", iterations=_PPR_ITERS):@@ -1957,7 +2056,7 @@ async def _build_context(memberships,seed_sessions,k_topics=10,- k_sessions=10,+ k_sessions=20 if include_history else 10,)preferred = set(preferred_sessions)topic_detail["topics"] = len(response_topics)diff --git a/src/utils/dates.py b/src/utils/dates.pyindex 1c00d23..d3ed852 100644--- a/src/utils/dates.py+++ b/src/utils/dates.py@@ -13,6 +13,8 @@ _DATE_INPUT_FORMATS = ("%b %d %Y","%d %B %Y","%d %b %Y",+ "%B-%d-%Y",+ "%b-%d-%Y","%Y-%m-%dT%H:%M:%S","%Y-%m-%dT%H:%M:%S%z","%Y-%m-%dT%H:%M:%S.%f",diff --git a/tests/test_beam_history_mode.py b/tests/test_beam_history_mode.pynew file mode 100644index 0000000..713d86f--- /dev/null+++ b/tests/test_beam_history_mode.py@@ -0,0 +1,114 @@+from __future__ import annotations++import os+import sys+import unittest+from datetime import datetime+from types import SimpleNamespace++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.services.api.controllers import retrieve as retrieve_mod+from src.utils.dates import parse_date_string+++class HistoryModeTests(unittest.TestCase):+ def test_ordering_query_wants_history(self):+ self.assertTrue(+ retrieve_mod._wants_historical_facts(+ "Can you list the order in which I brought up aspects?"+ )+ )++ def test_first_sprint_wants_history(self):+ self.assertTrue(+ retrieve_mod._wants_historical_facts("When does my first sprint end?")+ )++ def test_have_i_contradiction_probe_wants_history(self):+ self.assertTrue(+ retrieve_mod._wants_historical_facts(+ "Have I integrated Flask-Login for session management?"+ )+ )++ def test_knowledge_update_stays_current_only(self):+ self.assertFalse(+ retrieve_mod._wants_historical_facts(+ "What is the average response time of the dashboard API?"+ )+ )+ self.assertFalse(+ retrieve_mod._wants_historical_facts(+ "How many commits have been merged into the main branch?"+ )+ )++ def test_fact_predicates_include_superseded_in_history_mode(self):+ current = SimpleNamespace(properties={}, deprecated=False)+ old = SimpleNamespace(properties={"invalid_at": "2024-03-31"}, deprecated=False)+ self.assertFalse(+ retrieve_mod._fact_predicates_allowed(old, current, include_history=False)+ )+ self.assertTrue(+ retrieve_mod._fact_predicates_allowed(old, current, include_history=True)+ )+++class SessionIdParseTests(unittest.TestCase):+ def test_session_and_batch_turn_ids(self):+ text = "Session id: session_12. Unit id: b3_t2. Also session_4."+ ids = retrieve_mod._session_ids_from_text(text)+ self.assertIn("session_12", ids)+ self.assertIn("session_4", ids)+ self.assertIn("session_b3_t2", ids)+++class BeamDateStampTests(unittest.TestCase):+ def test_hyphenated_beam_anchor_parses(self):+ self.assertEqual(+ parse_date_string("March-15-2024"),+ datetime(2024, 3, 15),+ )++ def test_normalized_beam_anchor_parses(self):+ self.assertEqual(+ parse_date_string("March 15, 2024"),+ datetime(2024, 3, 15),+ )+++if __name__ == "__main__":+ unittest.main()