feat: support dynacmic graph via neo4j (#1254)

Co-authored-by: LastWhisper <pkuwkl@gmail.com>
Co-authored-by: whuwkl <whuwkl@gmail.com>

Author: NeilJohnson0930

README.md

@@ -335,6 +335,7 @@ Practical guides and tutorials for implementing specific functionalities in CAME
 |:---|:---|
 | **[Role-Playing Scraper for Report & Knowledge Graph Generation](https://docs.camel-ai.org/cookbooks/applications/roleplaying_scraper.html)** | Create role-playing agents for data scraping and reporting. |
 | **[Create A Hackathon Judge Committee with Workforce](https://docs.camel-ai.org/cookbooks/multi_agent_society/workforce_judge_committee.html)** | Building a team of agents for collaborative judging. |
+| **[Dynamic Knowledge Graph Role-Playing: Multi-Agent System with dynamic, temporally-aware knowledge graphs](https://docs.camel-ai.org/cookbooks/applications/dyamic_knowledge_graph.html)** |  Builds dynamic, temporally-aware knowledge graphs for financial applications using a multi-agent system. It processes financial reports, news articles, and research papers to help traders analyze data, identify relationships, and uncover market insights. The system also utilizes diverse and optional element node deduplication techniques to ensure data integrity and optimize graph structure for financial decision-making. |
 | **[Customer Service Discord Bot with Agentic RAG](https://docs.camel-ai.org/cookbooks/applications/customer_service_Discord_bot_using_SambaNova_with_agentic_RAG.html)** | Learn how to build a robust customer service bot for Discord using Agentic RAG. |
 | **[Customer Service Discord Bot with Local Model](https://docs.camel-ai.org/cookbooks/applications/customer_service_Discord_bot_using_local_model_with_agentic_RAG.html)** | Learn how to build a robust customer service bot for Discord using Agentic RAG which supports local deployment. |
 

camel/agents/knowledge_graph_agent.py

@@ -226,7 +226,8 @@ def _parse_graph_elements(self, input_string: str) -> GraphElement:
         node_pattern = r"Node\(id='(.*?)', type='(.*?)'\)"
         rel_pattern = (
             r"Relationship\(subj=Node\(id='(.*?)', type='(.*?)'\), "
-            r"obj=Node\(id='(.*?)', type='(.*?)'\), type='(.*?)'\)"
+            r"obj=Node\(id='(.*?)', type='(.*?)'\), "
+            r"type='(.*?)'(?:, timestamp='(.*?)')?\)"
         )
 
         nodes = {}
@@ -243,13 +244,24 @@ def _parse_graph_elements(self, input_string: str) -> GraphElement:
 
         # Extract relationships
         for match in re.finditer(rel_pattern, input_string):
-            subj_id, subj_type, obj_id, obj_type, rel_type = match.groups()
+            groups = match.groups()
+            if len(groups) == 6:
+                subj_id, subj_type, obj_id, obj_type, rel_type, timestamp = (
+                    groups
+                )
+            else:
+                subj_id, subj_type, obj_id, obj_type, rel_type = groups
+                timestamp = None
             properties = {'source': 'agent_created'}
             if subj_id in nodes and obj_id in nodes:
                 subj = nodes[subj_id]
                 obj = nodes[obj_id]
                 relationship = Relationship(
-                    subj=subj, obj=obj, type=rel_type, properties=properties
+                    subj=subj,
+                    obj=obj,
+                    type=rel_type,
+                    timestamp=timestamp,
+                    properties=properties,
                 )
                 if self._validate_relationship(relationship):
                     relationships.append(relationship)

camel/storages/graph_storages/graph_element.py

@@ -13,7 +13,7 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 from __future__ import annotations
 
-from typing import List, Union
+from typing import List, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -45,13 +45,15 @@ class Relationship(BaseModel):
         subj (Node): The subject/source node of the relationship.
         obj (Node): The object/target node of the relationship.
         type (str):  The type of the relationship.
+        timestamp (str, optional): The timestamp of the relationship.
         properties (dict): Additional properties associated with the
             relationship.
     """
 
     subj: Node
     obj: Node
     type: str = "Relationship"
+    timestamp: Optional[str] = None
     properties: dict = Field(default_factory=dict)
 
 

camel/storages/graph_storages/neo4j_graph.py

@@ -339,18 +339,24 @@ def refresh_schema(self) -> None:
             ]
         )
 
-    def add_triplet(self, subj: str, obj: str, rel: str) -> None:
-        r"""Adds a relationship (triplet) between two entities in the database.
+    def add_triplet(
+        self, subj: str, obj: str, rel: str, timestamp: Optional[str] = None
+    ) -> None:
+        r"""Adds a relationship (triplet) between two entities
+            in the database with a timestamp.
 
         Args:
             subj (str): The identifier for the subject entity.
             obj (str): The identifier for the object entity.
             rel (str): The relationship between the subject and object.
+            timestamp (Optional[str]): The timestamp of the relationship.
+                                Defaults to None.
         """
         query = """
             MERGE (n1:`%s` {id:$subj})
             MERGE (n2:`%s` {id:$obj})
-            MERGE (n1)-[:`%s`]->(n2)
+            MERGE (n1)-[r:`%s`]->(n2)
+            SET r.timestamp = $timestamp
         """
 
         prepared_statement = query % (
@@ -361,7 +367,10 @@ def add_triplet(self, subj: str, obj: str, rel: str) -> None:
 
         # Execute the query within a database session
         with self.driver.session(database=self.database) as session:
-            session.run(prepared_statement, {"subj": subj, "obj": obj})
+            session.run(
+                prepared_statement,
+                {"subj": subj, "obj": obj, "timestamp": timestamp},
+            )
 
     def _delete_rel(self, subj: str, obj: str, rel: str) -> None:
         r"""Deletes a specific relationship between two nodes in the Neo4j
@@ -721,3 +730,68 @@ def common_neighbour_aware_random_walk(
             return result[0] if result else {}
         except CypherSyntaxError as e:
             raise ValueError(f"Generated Cypher Statement is not valid\n{e}")
+
+    def get_triplet(
+        self,
+        subj: Optional[str] = None,
+        obj: Optional[str] = None,
+        rel: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        r"""
+        Query triplet information. If subj, obj, or rel is
+        not specified, returns all matching triplets.
+
+        Args:
+            subj (Optional[str]): The ID of the subject node.
+                        If None, matches any subject node.
+            obj (Optional[str]): The ID of the object node.
+                        If None, matches any object node.
+            rel (Optional[str]): The type of relationship.
+                        If None, matches any relationship type.
+
+        Returns:
+            List[Dict[str, Any]]: A list of matching triplets,
+                    each containing subj, obj, rel, and timestamp.
+        """
+        import logging
+
+        logging.basicConfig(level=logging.DEBUG)
+        logger = logging.getLogger(__name__)
+
+        # Construct the query
+        query = """
+                MATCH (n1:Entity)-[r]->(n2:Entity)
+                WHERE ($subj IS NULL OR n1.id = $subj)
+                AND ($obj IS NULL OR n2.id = $obj)
+                AND ($rel IS NULL OR type(r) = $rel)
+                RETURN n1.id AS subj, n2.id AS obj, 
+                type(r) AS rel, r.timestamp AS timestamp
+            """
+
+        # Construct the query parameters
+        params = {
+            "subj": subj
+            if subj is not None
+            else None,  # If subj is None, match any subject node
+            "obj": obj
+            if obj is not None
+            else None,  # If obj is None, match any object node
+            "rel": rel
+            if rel is not None
+            else None,  # If rel is None, match any relationship type
+        }
+
+        logger.debug(f"Executing query: {query}")
+        logger.debug(f"Query parameters: {params}")
+
+        with self.driver.session(database=self.database) as session:
+            try:
+                result = session.run(query, params)
+                records = [record.data() for record in result]
+                logger.debug(
+                    f"Query returned {len(records)} records: {records}"
+                )
+                return records
+            except Exception as e:
+                logger.error(f"Error executing query: {e}")
+                return []