feat: support nebular database

Author: tianxing02

examples/basic_modules/nebular_example.py

@@ -1,7 +1,7 @@
 import json
 import os
 
-from datetime import datetime
+from datetime import datetime, timezone
 
 import numpy as np
 
@@ -191,7 +191,9 @@ def example_shared_db(db_name: str = "shared-traval-group"):
             "user_name": os.getenv("NEBULAR_USER", "root"),
             "password": os.getenv("NEBULAR_PASSWORD", "xxxxxx"),
             "space": db_name,
+            "auto_create": True,
             "embedding_dimension": 3072,
+            "use_multi_db": False,
         },
     )
     graph_alice = GraphStoreFactory.from_config(config_alice)
@@ -200,9 +202,171 @@ def example_shared_db(db_name: str = "shared-traval-group"):
         print(str(graph_alice.get_node(node["id"]))[:1000])
 
 
+def run_user_session(
+    user_name: str,
+    db_name: str,
+    topic_text: str,
+    concept_texts: list[str],
+    fact_texts: list[str],
+):
+    print(f"\n=== {user_name} starts building their memory graph ===")
+
+    # Manually initialize correct GraphDB class
+
+    config = GraphDBConfigFactory(
+        backend="nebular",
+        config={
+            "hosts": json.loads(os.getenv("NEBULAR_HOSTS", "localhost")),
+            "user_name": os.getenv("NEBULAR_USER", "root"),
+            "password": os.getenv("NEBULAR_PASSWORD", "xxxxxx"),
+            "space": db_name,
+            "auto_create": True,
+            "embedding_dimension": 3072,
+            "use_multi_db": False,
+        },
+    )
+    graph = GraphStoreFactory.from_config(config)
+
+    # Start with a clean slate for this user
+    graph.clear()
+
+    now = datetime.now(timezone.utc).isoformat()
+
+    # === Step 1: Create a root topic node (e.g., user's research focus) ===
+    topic = TextualMemoryItem(
+        memory=topic_text,
+        metadata=TreeNodeTextualMemoryMetadata(
+            memory_type="LongTermMemory",
+            key="Research Topic",
+            hierarchy_level="topic",
+            type="fact",
+            memory_time="2024-01-01",
+            status="activated",
+            visibility="public",
+            updated_at=now,
+            embedding=embed_memory_item(topic_text),
+        ),
+    )
+    graph.add_node(topic.id, topic.memory, topic.metadata.model_dump(exclude_none=True))
+
+    # === Step 2: Create two concept nodes linked to the topic ===
+    concept_items = []
+    for i, text in enumerate(concept_texts):
+        concept = TextualMemoryItem(
+            memory=text,
+            metadata=TreeNodeTextualMemoryMetadata(
+                memory_type="LongTermMemory",
+                key=f"Concept {i + 1}",
+                hierarchy_level="concept",
+                type="fact",
+                memory_time="2024-01-01",
+                status="activated",
+                visibility="public",
+                updated_at=now,
+                embedding=embed_memory_item(text),
+                tags=["concept"],
+                confidence=90 + i,
+            ),
+        )
+        graph.add_node(concept.id, concept.memory, concept.metadata.model_dump(exclude_none=True))
+        graph.add_edge(topic.id, concept.id, type="PARENT")
+        concept_items.append(concept)
+
+    # === Step 3: Create supporting facts under each concept ===
+    for i, text in enumerate(fact_texts):
+        fact = TextualMemoryItem(
+            memory=text,
+            metadata=TreeNodeTextualMemoryMetadata(
+                memory_type="WorkingMemory",
+                key=f"Fact {i + 1}",
+                hierarchy_level="fact",
+                type="fact",
+                memory_time="2024-01-01",
+                status="activated",
+                visibility="public",
+                updated_at=now,
+                embedding=embed_memory_item(text),
+                confidence=85.0,
+                tags=["fact"],
+            ),
+        )
+        graph.add_node(fact.id, fact.memory, fact.metadata.model_dump(exclude_none=True))
+        graph.add_edge(concept_items[i % len(concept_items)].id, fact.id, type="PARENT")
+
+    # === Step 4: Retrieve memory using semantic search ===
+    vector = embed_memory_item("How is memory retrieved?")
+    search_result = graph.search_by_embedding(vector, top_k=2)
+    for r in search_result:
+        node = graph.get_node(r["id"])
+        print("🔍 Search result:", node["memory"])
+
+    # === Step 5: Tag-based neighborhood discovery ===
+    neighbors = graph.get_neighbors_by_tag(["concept"], exclude_ids=[], top_k=2)
+    print("📎 Tag-related nodes:", [neighbor["memory"] for neighbor in neighbors])
+
+    # === Step 6: Retrieve children (facts) of first concept ===
+    children = graph.get_children_with_embeddings(concept_items[0].id)
+    print("📍 Children of concept:", [child["memory"] for child in children])
+
+    # === Step 7: Export a local subgraph and grouped statistics ===
+    subgraph = graph.get_subgraph(topic.id, depth=2)
+    print("📌 Subgraph node count:", len(subgraph["neighbors"]))
+
+    stats = graph.get_grouped_counts(["memory_type", "status"])
+    print("📊 Grouped counts:", stats)
+
+    # === Step 8: Demonstrate updates and cleanup ===
+    graph.update_node(
+        concept_items[0].id, {"confidence": 99.0, "created_at": "2025-07-24T20:11:56.375687"}
+    )
+    graph.remove_oldest_memory("WorkingMemory", keep_latest=1)
+    graph.delete_edge(topic.id, concept_items[0].id, type="PARENT")
+    graph.delete_node(concept_items[1].id)
+
+    # === Step 9: Export and re-import the entire graph structure ===
+    exported = graph.export_graph()
+    graph.import_graph(exported)
+    print("📦 Graph exported and re-imported, total nodes:", len(exported["nodes"]))
+
+
+def example_complex_shared_db(db_name: str = "shared-traval-group-complex"):
+    # User 1: Alice explores structured memory for LLMs
+    run_user_session(
+        user_name="alice",
+        db_name=db_name,
+        topic_text="Alice studies structured memory and long-term memory optimization in LLMs.",
+        concept_texts=[
+            "Short-term memory can be simulated using WorkingMemory blocks.",
+            "A structured memory graph improves retrieval precision for agents.",
+        ],
+        fact_texts=[
+            "Embedding search is used to find semantically similar memory items.",
+            "User memories are stored as node-edge structures that support hierarchical reasoning.",
+        ],
+    )
+
+    # User 2: Bob focuses on GNN-based reasoning
+    run_user_session(
+        user_name="bob",
+        db_name=db_name,
+        topic_text="Bob investigates how graph neural networks can support knowledge reasoning.",
+        concept_texts=[
+            "GNNs can learn high-order relations among entities.",
+            "Attention mechanisms in graphs improve inference precision.",
+        ],
+        fact_texts=[
+            "GAT outperforms GCN in graph classification tasks.",
+            "Multi-hop reasoning helps answer complex queries.",
+        ],
+    )
+
+
 if __name__ == "__main__":
     print("\n=== Example: Multi-DB ===")
     example_multi_db(db_name="paper")
 
     print("\n=== Example: Single-DB ===")
     example_shared_db(db_name="shared_traval_group")
+
+    print("\n=== Example: Single-DB-Complex ===")
+    example_complex_shared_db(db_name="shared-traval-group-complex-new")