graphiti-core 0.18.8__tar.gz → 0.19.0rc1__tar.gz

graphiti_core-0.19.0rc1/.github/workflows/ai-moderator.yml

@@ -0,0 +1,30 @@
+name: AI Moderator
+on:
+  issues:
+    types: [opened]
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  spam-detection:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      models: read
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/ai-moderator@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          spam-label: 'spam'
+          ai-label: 'ai-generated'
+          minimize-detected-comments: true
+          # Built-in prompt configuration (all enabled by default)
+          enable-spam-detection: true
+          enable-link-spam-detection: true
+          enable-ai-detection: true
+          # custom-prompt-path: '.github/prompts/my-custom.prompt.yml'  # Optional

{graphiti_core-0.18.8 → graphiti_core-0.19.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphiti-core
-Version: 0.18.8
+Version: 0.19.0rc1
 Summary: A temporal graph building library
 Project-URL: Homepage, https://help.getzep.com/graphiti/graphiti/overview
 Project-URL: Repository, https://github.com/getzep/graphiti
@@ -30,7 +30,7 @@ Requires-Dist: langchain-anthropic>=0.2.4; extra == 'dev'
 Requires-Dist: langchain-openai>=0.2.6; extra == 'dev'
 Requires-Dist: langgraph>=0.2.15; extra == 'dev'
 Requires-Dist: langsmith>=0.1.108; extra == 'dev'
-Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pyright>=1.1.404; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.6.1; extra == 'dev'
 Requires-Dist: pytest>=8.3.3; extra == 'dev'
@@ -44,6 +44,10 @@ Provides-Extra: google-genai
 Requires-Dist: google-genai>=1.8.0; extra == 'google-genai'
 Provides-Extra: groq
 Requires-Dist: groq>=0.2.0; extra == 'groq'
+Provides-Extra: neptune
+Requires-Dist: boto3>=1.39.16; extra == 'neptune'
+Requires-Dist: langchain-aws>=0.2.29; extra == 'neptune'
+Requires-Dist: opensearch-py>=3.0.0; extra == 'neptune'
 Provides-Extra: sentence-transformers
 Requires-Dist: sentence-transformers>=3.2.1; extra == 'sentence-transformers'
 Provides-Extra: voyageai
@@ -157,7 +161,7 @@ Graphiti is specifically designed to address the challenges of dynamic and frequ
 Requirements:
 
 - Python 3.10 or higher
-- Neo4j 5.26 / FalkorDB 1.1.2 or higher (serves as the embeddings storage backend)
+- Neo4j 5.26 / FalkorDB 1.1.2 / Amazon Neptune Database Cluster or Neptune Analytics Graph + Amazon OpenSearch Serverless collection (serves as the full text search backend)
 - OpenAI API key (Graphiti defaults to OpenAI for LLM inference and embedding)
 
 > [!IMPORTANT]
@@ -200,6 +204,17 @@ pip install graphiti-core[falkordb]
 uv add graphiti-core[falkordb]
 ```
 
+### Installing with Amazon Neptune Support
+
+If you plan to use Amazon Neptune as your graph database backend, install with the Amazon Neptune extra:
+
+```bash
+pip install graphiti-core[neptune]
+
+# or with uv
+uv add graphiti-core[neptune]
+```
+
 ### You can also install optional LLM providers as extras:
 
 ```bash
@@ -217,6 +232,9 @@ pip install graphiti-core[anthropic,groq,google-genai]
 
 # Install with FalkorDB and LLM providers
 pip install graphiti-core[falkordb,anthropic,google-genai]
+
+# Install with Amazon Neptune
+pip install graphiti-core[neptune]
 ```
 
 ## Default to Low Concurrency; LLM Provider 429 Rate Limit Errors
@@ -236,7 +254,7 @@ If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT
 
 For a complete working example, see the [Quickstart Example](./examples/quickstart/README.md) in the examples directory. The quickstart demonstrates:
 
-1. Connecting to a Neo4j or FalkorDB database
+1. Connecting to a Neo4j, Amazon Neptune, or FalkorDB database
 2. Initializing Graphiti indices and constraints
 3. Adding episodes to the graph (both text and structured JSON)
 4. Searching for relationships (edges) using hybrid search
@@ -319,6 +337,26 @@ driver = FalkorDriver(
 graphiti = Graphiti(graph_driver=driver)
 ```
 
+#### Amazon Neptune
+
+```python
+from graphiti_core import Graphiti
+from graphiti_core.driver.neptune_driver import NeptuneDriver
+
+# Create a FalkorDB driver with custom database name
+driver = NeptuneDriver(
+    host=<NEPTUNE ENDPOINT>,
+    aoss_host=<Amazon OpenSearch Serverless Host>,
+    port=<PORT> # Optional, defaults to 8182,
+    aoss_port=<PORT> # Optional, defaults to 443
+)
+
+driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)
+
+# Pass the driver to Graphiti
+graphiti = Graphiti(graph_driver=driver)
+```
+
 
 ### Performance Configuration
 
@@ -495,7 +533,7 @@ Ensure Ollama is running (`ollama serve`) and that you have pulled the models yo
 
 - [Guides and API documentation](https://help.getzep.com/graphiti).
 - [Quick Start](https://help.getzep.com/graphiti/graphiti/quick-start)
-- [Building an agent with LangChain's LangGraph and Graphiti](https://help.getzep.com/graphiti/graphiti/lang-graph-agent)
+- [Building an agent with LangChain's LangGraph and Graphiti](https://help.getzep.com/graphiti/integrations/lang-graph-agent)
 
 ## Telemetry
 
@@ -510,7 +548,7 @@ When you initialize a Graphiti instance, we collect:
 - **Graphiti version**: The version you're using
 - **Configuration choices**:
   - LLM provider type (OpenAI, Azure, Anthropic, etc.)
-  - Database backend (Neo4j, FalkorDB)
+  - Database backend (Neo4j, FalkorDB, Amazon Neptune Database or Neptune Analytics)
   - Embedder provider (OpenAI, Azure, Voyage, etc.)
 
 ### What We Don't Collect

{graphiti_core-0.18.8 → graphiti_core-0.19.0rc1}/README.md

@@ -105,7 +105,7 @@ Graphiti is specifically designed to address the challenges of dynamic and frequ
 Requirements:
 
 - Python 3.10 or higher
-- Neo4j 5.26 / FalkorDB 1.1.2 or higher (serves as the embeddings storage backend)
+- Neo4j 5.26 / FalkorDB 1.1.2 / Amazon Neptune Database Cluster or Neptune Analytics Graph + Amazon OpenSearch Serverless collection (serves as the full text search backend)
 - OpenAI API key (Graphiti defaults to OpenAI for LLM inference and embedding)
 
 > [!IMPORTANT]
@@ -148,6 +148,17 @@ pip install graphiti-core[falkordb]
 uv add graphiti-core[falkordb]
 ```
 
+### Installing with Amazon Neptune Support
+
+If you plan to use Amazon Neptune as your graph database backend, install with the Amazon Neptune extra:
+
+```bash
+pip install graphiti-core[neptune]
+
+# or with uv
+uv add graphiti-core[neptune]
+```
+
 ### You can also install optional LLM providers as extras:
 
 ```bash
@@ -165,6 +176,9 @@ pip install graphiti-core[anthropic,groq,google-genai]
 
 # Install with FalkorDB and LLM providers
 pip install graphiti-core[falkordb,anthropic,google-genai]
+
+# Install with Amazon Neptune
+pip install graphiti-core[neptune]
 ```
 
 ## Default to Low Concurrency; LLM Provider 429 Rate Limit Errors
@@ -184,7 +198,7 @@ If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT
 
 For a complete working example, see the [Quickstart Example](./examples/quickstart/README.md) in the examples directory. The quickstart demonstrates:
 
-1. Connecting to a Neo4j or FalkorDB database
+1. Connecting to a Neo4j, Amazon Neptune, or FalkorDB database
 2. Initializing Graphiti indices and constraints
 3. Adding episodes to the graph (both text and structured JSON)
 4. Searching for relationships (edges) using hybrid search
@@ -267,6 +281,26 @@ driver = FalkorDriver(
 graphiti = Graphiti(graph_driver=driver)
 ```
 
+#### Amazon Neptune
+
+```python
+from graphiti_core import Graphiti
+from graphiti_core.driver.neptune_driver import NeptuneDriver
+
+# Create a FalkorDB driver with custom database name
+driver = NeptuneDriver(
+    host=<NEPTUNE ENDPOINT>,
+    aoss_host=<Amazon OpenSearch Serverless Host>,
+    port=<PORT> # Optional, defaults to 8182,
+    aoss_port=<PORT> # Optional, defaults to 443
+)
+
+driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)
+
+# Pass the driver to Graphiti
+graphiti = Graphiti(graph_driver=driver)
+```
+
 
 ### Performance Configuration
 
@@ -443,7 +477,7 @@ Ensure Ollama is running (`ollama serve`) and that you have pulled the models yo
 
 - [Guides and API documentation](https://help.getzep.com/graphiti).
 - [Quick Start](https://help.getzep.com/graphiti/graphiti/quick-start)
-- [Building an agent with LangChain's LangGraph and Graphiti](https://help.getzep.com/graphiti/graphiti/lang-graph-agent)
+- [Building an agent with LangChain's LangGraph and Graphiti](https://help.getzep.com/graphiti/integrations/lang-graph-agent)
 
 ## Telemetry
 
@@ -458,7 +492,7 @@ When you initialize a Graphiti instance, we collect:
 - **Graphiti version**: The version you're using
 - **Configuration choices**:
   - LLM provider type (OpenAI, Azure, Anthropic, etc.)
-  - Database backend (Neo4j, FalkorDB)
+  - Database backend (Neo4j, FalkorDB, Amazon Neptune Database or Neptune Analytics)
   - Embedder provider (OpenAI, Azure, Voyage, etc.)
 
 ### What We Don't Collect

{graphiti_core-0.18.8 → graphiti_core-0.19.0rc1}/examples/podcast/podcast_runner.py

@@ -77,7 +77,11 @@ class IsPresidentOf(BaseModel):
 
 async def main(use_bulk: bool = False):
     setup_logging()
-    client = Graphiti(neo4j_uri, neo4j_user, neo4j_password)
+    client = Graphiti(
+        neo4j_uri,
+        neo4j_user,
+        neo4j_password,
+    )
     await clear_data(client.driver)
     await client.build_indices_and_constraints()
     messages = parse_podcast_messages()

{graphiti_core-0.18.8 → graphiti_core-0.19.0rc1}/examples/quickstart/README.md

@@ -18,6 +18,8 @@ This example demonstrates the basic functionality of Graphiti, including:
   - A local DBMS created and started in Neo4j Desktop  
 - **For FalkorDB**:
   - FalkorDB server running (see [FalkorDB documentation](https://falkordb.com/docs/) for setup)
+- **For Amazon Neptune**:
+  - Amazon server running (see [Amazon Neptune documentation](https://aws.amazon.com/neptune/developer-resources/) for setup)
 
 
 ## Setup Instructions
@@ -42,9 +44,19 @@ export NEO4J_PASSWORD=password
 # Optional FalkorDB connection parameters (defaults shown)
 export FALKORDB_URI=falkor://localhost:6379
 
+# Optional Amazon Neptune connection parameters
+NEPTUNE_HOST=your_neptune_host
+NEPTUNE_PORT=your_port_or_8182
+AOSS_HOST=your_aoss_host
+AOSS_PORT=your_port_or_443
+
 # To use a different database, modify the driver constructor in the script
 ```
 
+TIP: For Amazon Neptune host string please use the following formats
+* For Neptune Database: `neptune-db://<cluster endpoint>`
+* For Neptune Analytics: `neptune-graph://<graph identifier>`
+
 3. Run the example:
 
 ```bash
@@ -52,11 +64,14 @@ python quickstart_neo4j.py
 
 # For FalkorDB
 python quickstart_falkordb.py
+
+# For Amazon Neptune
+python quickstart_neptune.py
 ```
 
 ## What This Example Demonstrates
 
-- **Graph Initialization**: Setting up the Graphiti indices and constraints in Neo4j or FalkorDB
+- **Graph Initialization**: Setting up the Graphiti indices and constraints in Neo4j, Amazon Neptune, or FalkorDB
 - **Adding Episodes**: Adding text content that will be analyzed and converted into knowledge graph nodes and edges
 - **Edge Search Functionality**: Performing hybrid searches that combine semantic similarity and BM25 retrieval to find relationships (edges)
 - **Graph-Aware Search**: Using the source node UUID from the top search result to rerank additional search results based on graph distance

{graphiti_core-0.18.8 → graphiti_core-0.19.0rc1}/graphiti_core/driver/driver.py

@@ -27,6 +27,7 @@ logger = logging.getLogger(__name__)
 class GraphProvider(Enum):
     NEO4J = 'neo4j'
     FALKORDB = 'falkordb'
+    NEPTUNE = 'neptune'
 
 
 class GraphDriverSession(ABC):

graphiti_core-0.19.0rc1/graphiti_core/driver/neptune_driver.py

@@ -0,0 +1,299 @@
+"""
+Copyright 2024, Zep Software, Inc.
+
+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.
+"""
+
+import asyncio
+import datetime
+import logging
+from collections.abc import Coroutine
+from typing import Any
+
+import boto3
+from langchain_aws.graphs import NeptuneAnalyticsGraph, NeptuneGraph
+from opensearchpy import OpenSearch, Urllib3AWSV4SignerAuth, Urllib3HttpConnection, helpers
+
+from graphiti_core.driver.driver import GraphDriver, GraphDriverSession, GraphProvider
+
+logger = logging.getLogger(__name__)
+DEFAULT_SIZE = 10
+
+aoss_indices = [
+    {
+        'index_name': 'node_name_and_summary',
+        'body': {
+            'mappings': {
+                'properties': {
+                    'uuid': {'type': 'keyword'},
+                    'name': {'type': 'text'},
+                    'summary': {'type': 'text'},
+                    'group_id': {'type': 'text'},
+                }
+            }
+        },
+        'query': {
+            'query': {'multi_match': {'query': '', 'fields': ['name', 'summary', 'group_id']}},
+            'size': DEFAULT_SIZE,
+        },
+    },
+    {
+        'index_name': 'community_name',
+        'body': {
+            'mappings': {
+                'properties': {
+                    'uuid': {'type': 'keyword'},
+                    'name': {'type': 'text'},
+                    'group_id': {'type': 'text'},
+                }
+            }
+        },
+        'query': {
+            'query': {'multi_match': {'query': '', 'fields': ['name', 'group_id']}},
+            'size': DEFAULT_SIZE,
+        },
+    },
+    {
+        'index_name': 'episode_content',
+        'body': {
+            'mappings': {
+                'properties': {
+                    'uuid': {'type': 'keyword'},
+                    'content': {'type': 'text'},
+                    'source': {'type': 'text'},
+                    'source_description': {'type': 'text'},
+                    'group_id': {'type': 'text'},
+                }
+            }
+        },
+        'query': {
+            'query': {
+                'multi_match': {
+                    'query': '',
+                    'fields': ['content', 'source', 'source_description', 'group_id'],
+                }
+            },
+            'size': DEFAULT_SIZE,
+        },
+    },
+    {
+        'index_name': 'edge_name_and_fact',
+        'body': {
+            'mappings': {
+                'properties': {
+                    'uuid': {'type': 'keyword'},
+                    'name': {'type': 'text'},
+                    'fact': {'type': 'text'},
+                    'group_id': {'type': 'text'},
+                }
+            }
+        },
+        'query': {
+            'query': {'multi_match': {'query': '', 'fields': ['name', 'fact', 'group_id']}},
+            'size': DEFAULT_SIZE,
+        },
+    },
+]
+
+
+class NeptuneDriver(GraphDriver):
+    provider: GraphProvider = GraphProvider.NEPTUNE
+
+    def __init__(self, host: str, aoss_host: str, port: int = 8182, aoss_port: int = 443):
+        """This initializes a NeptuneDriver for use with Neptune as a backend
+
+        Args:
+            host (str): The Neptune Database or Neptune Analytics host
+            aoss_host (str): The OpenSearch host value
+            port (int, optional): The Neptune Database port, ignored for Neptune Analytics. Defaults to 8182.
+            aoss_port (int, optional): The OpenSearch port. Defaults to 443.
+        """
+        if not host:
+            raise ValueError('You must provide an endpoint to create a NeptuneDriver')
+
+        if host.startswith('neptune-db://'):
+            # This is a Neptune Database Cluster
+            endpoint = host.replace('neptune-db://', '')
+            self.client = NeptuneGraph(endpoint, port)
+            logger.debug('Creating Neptune Database session for %s', host)
+        elif host.startswith('neptune-graph://'):
+            # This is a Neptune Analytics Graph
+            graphId = host.replace('neptune-graph://', '')
+            self.client = NeptuneAnalyticsGraph(graphId)
+            logger.debug('Creating Neptune Graph session for %s', host)
+        else:
+            raise ValueError(
+                'You must provide an endpoint to create a NeptuneDriver as either neptune-db://<endpoint> or neptune-graph://<graphid>'
+            )
+
+        if not aoss_host:
+            raise ValueError('You must provide an AOSS endpoint to create an OpenSearch driver.')
+
+        session = boto3.Session()
+        self.aoss_client = OpenSearch(
+            hosts=[{'host': aoss_host, 'port': aoss_port}],
+            http_auth=Urllib3AWSV4SignerAuth(
+                session.get_credentials(), session.region_name, 'aoss'
+            ),
+            use_ssl=True,
+            verify_certs=True,
+            connection_class=Urllib3HttpConnection,
+            pool_maxsize=20,
+        )
+
+    def _sanitize_parameters(self, query, params: dict):
+        if isinstance(query, list):
+            queries = []
+            for q in query:
+                queries.append(self._sanitize_parameters(q, params))
+            return queries
+        else:
+            for k, v in params.items():
+                if isinstance(v, datetime.datetime):
+                    params[k] = v.isoformat()
+                elif isinstance(v, list):
+                    # Handle lists that might contain datetime objects
+                    for i, item in enumerate(v):
+                        if isinstance(item, datetime.datetime):
+                            v[i] = item.isoformat()
+                            query = str(query).replace(f'${k}', f'datetime(${k})')
+                        if isinstance(item, dict):
+                            query = self._sanitize_parameters(query, v[i])
+
+                    # If the list contains datetime objects, we need to wrap each element with datetime()
+                    if any(isinstance(item, str) and 'T' in item for item in v):
+                        # Create a new list expression with datetime() wrapped around each element
+                        datetime_list = (
+                            '['
+                            + ', '.join(
+                                f'datetime("{item}")'
+                                if isinstance(item, str) and 'T' in item
+                                else repr(item)
+                                for item in v
+                            )
+                            + ']'
+                        )
+                        query = str(query).replace(f'${k}', datetime_list)
+                elif isinstance(v, dict):
+                    query = self._sanitize_parameters(query, v)
+            return query
+
+    async def execute_query(
+        self, cypher_query_, **kwargs: Any
+    ) -> tuple[dict[str, Any], None, None]:
+        params = dict(kwargs)
+        if isinstance(cypher_query_, list):
+            for q in cypher_query_:
+                result, _, _ = self._run_query(q[0], q[1])
+            return result, None, None
+        else:
+            return self._run_query(cypher_query_, params)
+
+    def _run_query(self, cypher_query_, params):
+        cypher_query_ = str(self._sanitize_parameters(cypher_query_, params))
+        try:
+            result = self.client.query(cypher_query_, params=params)
+        except Exception as e:
+            logger.error('Query: %s', cypher_query_)
+            logger.error('Parameters: %s', params)
+            logger.error('Error executing query: %s', e)
+            raise e
+
+        return result, None, None
+
+    def session(self, database: str | None = None) -> GraphDriverSession:
+        return NeptuneDriverSession(driver=self)
+
+    async def close(self) -> None:
+        return self.client.client.close()
+
+    async def _delete_all_data(self) -> Any:
+        return await self.execute_query('MATCH (n) DETACH DELETE n')
+
+    def delete_all_indexes(self) -> Coroutine[Any, Any, Any]:
+        return self.delete_all_indexes_impl()
+
+    async def delete_all_indexes_impl(self) -> Coroutine[Any, Any, Any]:
+        # No matter what happens above, always return True
+        return self.delete_aoss_indices()
+
+    async def create_aoss_indices(self):
+        for index in aoss_indices:
+            index_name = index['index_name']
+            client = self.aoss_client
+            if not client.indices.exists(index=index_name):
+                client.indices.create(index=index_name, body=index['body'])
+        # Sleep for 1 minute to let the index creation complete
+        await asyncio.sleep(60)
+
+    async def delete_aoss_indices(self):
+        for index in aoss_indices:
+            index_name = index['index_name']
+            client = self.aoss_client
+            if client.indices.exists(index=index_name):
+                client.indices.delete(index=index_name)
+
+    def run_aoss_query(self, name: str, query_text: str, limit: int = 10) -> dict[str, Any]:
+        for index in aoss_indices:
+            if name.lower() == index['index_name']:
+                index['query']['query']['multi_match']['query'] = query_text
+                query = {'size': limit, 'query': index['query']}
+                resp = self.aoss_client.search(body=query['query'], index=index['index_name'])
+                return resp
+        return {}
+
+    def save_to_aoss(self, name: str, data: list[dict]) -> int:
+        for index in aoss_indices:
+            if name.lower() == index['index_name']:
+                to_index = []
+                for d in data:
+                    item = {'_index': name}
+                    for p in index['body']['mappings']['properties']:
+                        item[p] = d[p]
+                    to_index.append(item)
+                success, failed = helpers.bulk(self.aoss_client, to_index, stats_only=True)
+                if failed > 0:
+                    return success
+                else:
+                    return 0
+
+        return 0
+
+
+class NeptuneDriverSession(GraphDriverSession):
+    def __init__(self, driver: NeptuneDriver):  # type: ignore[reportUnknownArgumentType]
+        self.driver = driver
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        # No cleanup needed for Neptune, but method must exist
+        pass
+
+    async def close(self):
+        # No explicit close needed for Neptune, but method must exist
+        pass
+
+    async def execute_write(self, func, *args, **kwargs):
+        # Directly await the provided async function with `self` as the transaction/session
+        return await func(self, *args, **kwargs)
+
+    async def run(self, query: str | list, **kwargs: Any) -> Any:
+        if isinstance(query, list):
+            res = None
+            for q in query:
+                res = await self.driver.execute_query(q, **kwargs)
+            return res
+        else:
+            return await self.driver.execute_query(str(query), **kwargs)