feat: knowledge graph storage (camel-ai#450)

Author: Wendong-Fan

camel/storages/__init__.py

@@ -12,6 +12,8 @@
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
 
+from .graph_storages.base import BaseGraphStorage
+from .graph_storages.neo4j_graph import Neo4jGraph
 from .key_value_storages.base import BaseKeyValueStorage
 from .key_value_storages.in_memory import InMemoryKeyValueStorage
 from .key_value_storages.json import JsonStorage
@@ -34,4 +36,6 @@
     'VectorDBQueryResult',
     'QdrantStorage',
     'MilvusStorage',
+    'BaseGraphStorage',
+    'Neo4jGraph',
 ]

camel/storages/graph_storages/__init__.py

@@ -0,0 +1,23 @@
+# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+# Licensed under the Apache License, Version 2.0 (the “License”);
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an “AS IS” BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+
+from .base import BaseGraphStorage
+from .graph_element import GraphElement
+from .neo4j_graph import Neo4jGraph
+
+__all__ = [
+    'BaseGraphStorage',
+    'GraphElement',
+    'Neo4jGraph',
+]

camel/storages/graph_storages/base.py

@@ -0,0 +1,82 @@
+# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+# Licensed under the Apache License, Version 2.0 (the “License”);
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an “AS IS” BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+
+class BaseGraphStorage(ABC):
+    r"""An abstract base class for graph storage systems."""
+
+    @property
+    @abstractmethod
+    def get_client(self) -> Any:
+        r"""Get the underlying graph storage client."""
+        pass
+
+    @property
+    @abstractmethod
+    def get_schema(self) -> str:
+        r"""Get the schema of the graph storage"""
+        pass
+
+    @property
+    @abstractmethod
+    def get_structured_schema(self) -> Dict[str, Any]:
+        r"""Get the structured schema of the graph storage"""
+        pass
+
+    @abstractmethod
+    def refresh_schema(self) -> None:
+        r"""Refreshes the graph schema information."""
+        pass
+
+    @abstractmethod
+    def add_triplet(self, subj: str, obj: str, rel: str) -> None:
+        r"""Adds a relationship (triplet) between two entities in the database.
+
+        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.
+        """
+        pass
+
+    @abstractmethod
+    def delete_triplet(self, subj: str, obj: str, rel: str) -> None:
+        r"""Deletes a specific triplet from the graph, comprising a subject,
+        object and relationship.
+
+        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.
+        """
+        pass
+
+    @abstractmethod
+    def query(
+        self, query: str, params: Optional[Dict[str, Any]] = None
+    ) -> List[Dict[str, Any]]:
+        r"""Query the graph store with statement and parameters.
+        Args:
+            query (str): The query to be executed.
+            params (Optional[Dict[str, Any]]): A dictionary of parameters to
+                be used in the query. Defaults to `None`.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries, each
+                dictionary represents a row of results from the query.
+        """
+        pass

camel/storages/graph_storages/graph_element.py

@@ -0,0 +1,74 @@
+# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+# Licensed under the Apache License, Version 2.0 (the “License”);
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an “AS IS” BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Union
+
+from unstructured.documents.elements import Element
+
+
+@dataclass
+class Node:
+    r"""Represents a node in a graph with associated properties.
+
+    Attributes:
+        id (Union[str, int]): A unique identifier for the node.
+        type (str):  The type of the relationship.
+        properties (dict): Additional properties and metadata associated with
+            the node.
+    """
+
+    id: Union[str, int]
+    type: str = "Node"
+    properties: dict = field(default_factory=dict)
+
+
+@dataclass
+class Relationship:
+    r"""Represents a directed relationship between two nodes in a graph.
+
+    Attributes:
+        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.
+        properties (dict): Additional properties associated with the
+            relationship.
+    """
+
+    subj: Node
+    obj: Node
+    type: str = "Relationship"
+    properties: dict = field(default_factory=dict)
+
+
+@dataclass
+class GraphElement:
+    r"""A graph element with lists of nodes and relationships.
+
+    Attributes:
+        nodes (List[Node]): A list of nodes in the graph.
+        relationships (List[Relationship]): A list of relationships in the
+        graph.
+        source (Element): The element from which the graph information is
+        derived.
+    """
+
+    # Allow arbitrary types for Element
+    class Config:
+        arbitrary_types_allowed = True
+
+    nodes: List[Node]
+    relationships: List[Relationship]
+    source: Element