graphiti-core 0.19.0rc1__tar.gz → 0.19.0rc3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphiti-core
-Version: 0.19.0rc1
+Version: 0.19.0rc3
 Summary: A temporal graph building library
 Project-URL: Homepage, https://help.getzep.com/graphiti/graphiti/overview
 Project-URL: Repository, https://github.com/getzep/graphiti
@@ -487,25 +487,27 @@ The Gemini reranker uses the `gemini-2.5-flash-lite-preview-06-17` model by defa
 Graphiti supports Ollama for running local LLMs and embedding models via Ollama's OpenAI-compatible API. This is ideal for privacy-focused applications or when you want to avoid API costs.
 
 Install the models:
+```bash
 ollama pull deepseek-r1:7b # LLM
 ollama pull nomic-embed-text # embeddings
+```
 
 ```python
 from graphiti_core import Graphiti
 from graphiti_core.llm_client.config import LLMConfig
-from graphiti_core.llm_client.openai_client import OpenAIClient
+from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
 from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
 from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
 
 # Configure Ollama LLM client
 llm_config = LLMConfig(
-    api_key="abc",  # Ollama doesn't require a real API key
+    api_key="ollama",  # Ollama doesn't require a real API key, but some placeholder is needed
     model="deepseek-r1:7b",
     small_model="deepseek-r1:7b",
-    base_url="http://localhost:11434/v1", # Ollama provides this port
+    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible endpoint
 )
 
-llm_client = OpenAIClient(config=llm_config)
+llm_client = OpenAIGenericClient(config=llm_config)
 
 # Initialize Graphiti with Ollama clients
 graphiti = Graphiti(
@@ -515,7 +517,7 @@ graphiti = Graphiti(
     llm_client=llm_client,
     embedder=OpenAIEmbedder(
         config=OpenAIEmbedderConfig(
-            api_key="abc",
+            api_key="ollama",  # Placeholder API key
             embedding_model="nomic-embed-text",
             embedding_dim=768,
             base_url="http://localhost:11434/v1",

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

@@ -431,25 +431,27 @@ The Gemini reranker uses the `gemini-2.5-flash-lite-preview-06-17` model by defa
 Graphiti supports Ollama for running local LLMs and embedding models via Ollama's OpenAI-compatible API. This is ideal for privacy-focused applications or when you want to avoid API costs.
 
 Install the models:
+```bash
 ollama pull deepseek-r1:7b # LLM
 ollama pull nomic-embed-text # embeddings
+```
 
 ```python
 from graphiti_core import Graphiti
 from graphiti_core.llm_client.config import LLMConfig
-from graphiti_core.llm_client.openai_client import OpenAIClient
+from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
 from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
 from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
 
 # Configure Ollama LLM client
 llm_config = LLMConfig(
-    api_key="abc",  # Ollama doesn't require a real API key
+    api_key="ollama",  # Ollama doesn't require a real API key, but some placeholder is needed
     model="deepseek-r1:7b",
     small_model="deepseek-r1:7b",
-    base_url="http://localhost:11434/v1", # Ollama provides this port
+    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible endpoint
 )
 
-llm_client = OpenAIClient(config=llm_config)
+llm_client = OpenAIGenericClient(config=llm_config)
 
 # Initialize Graphiti with Ollama clients
 graphiti = Graphiti(
@@ -459,7 +461,7 @@ graphiti = Graphiti(
     llm_client=llm_client,
     embedder=OpenAIEmbedder(
         config=OpenAIEmbedderConfig(
-            api_key="abc",
+            api_key="ollama",  # Placeholder API key
             embedding_model="nomic-embed-text",
             embedding_dim=768,
             base_url="http://localhost:11434/v1",

graphiti_core-0.19.0rc3/examples/quickstart/quickstart_neptune.py

@@ -0,0 +1,252 @@
+"""
+Copyright 2025, 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 json
+import logging
+import os
+from datetime import datetime, timezone
+from logging import INFO
+
+from dotenv import load_dotenv
+
+from graphiti_core import Graphiti
+from graphiti_core.driver.neptune_driver import NeptuneDriver
+from graphiti_core.nodes import EpisodeType
+from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_RRF
+
+#################################################
+# CONFIGURATION
+#################################################
+# Set up logging and environment variables for
+# connecting to Neptune database
+#################################################
+
+# Configure logging
+logging.basicConfig(
+    level=INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    datefmt='%Y-%m-%d %H:%M:%S',
+)
+logger = logging.getLogger(__name__)
+
+load_dotenv()
+
+# Neptune and OpenSearch connection parameters
+neptune_uri = os.environ.get('NEPTUNE_HOST')
+neptune_port = int(os.environ.get('NEPTUNE_PORT', 8182))
+aoss_host = os.environ.get('AOSS_HOST')
+
+if not neptune_uri:
+    raise ValueError('NEPTUNE_HOST must be set')
+
+
+if not aoss_host:
+    raise ValueError('AOSS_HOST must be set')
+
+
+async def main():
+    #################################################
+    # INITIALIZATION
+    #################################################
+    # Connect to Neptune and set up Graphiti indices
+    # This is required before using other Graphiti
+    # functionality
+    #################################################
+
+    # Initialize Graphiti with Neptune connection
+    driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)
+
+    graphiti = Graphiti(graph_driver=driver)
+
+    try:
+        # Initialize the graph database with graphiti's indices. This only needs to be done once.
+        await driver.delete_aoss_indices()
+        await driver._delete_all_data()
+        await graphiti.build_indices_and_constraints()
+
+        #################################################
+        # ADDING EPISODES
+        #################################################
+        # Episodes are the primary units of information
+        # in Graphiti. They can be text or structured JSON
+        # and are automatically processed to extract entities
+        # and relationships.
+        #################################################
+
+        # Example: Add Episodes
+        # Episodes list containing both text and JSON episodes
+        episodes = [
+            {
+                'content': 'Kamala Harris is the Attorney General of California. She was previously '
+                'the district attorney for San Francisco.',
+                'type': EpisodeType.text,
+                'description': 'podcast transcript',
+            },
+            {
+                'content': 'As AG, Harris was in office from January 3, 2011 – January 3, 2017',
+                'type': EpisodeType.text,
+                'description': 'podcast transcript',
+            },
+            {
+                'content': {
+                    'name': 'Gavin Newsom',
+                    'position': 'Governor',
+                    'state': 'California',
+                    'previous_role': 'Lieutenant Governor',
+                    'previous_location': 'San Francisco',
+                },
+                'type': EpisodeType.json,
+                'description': 'podcast metadata',
+            },
+            {
+                'content': {
+                    'name': 'Gavin Newsom',
+                    'position': 'Governor',
+                    'term_start': 'January 7, 2019',
+                    'term_end': 'Present',
+                },
+                'type': EpisodeType.json,
+                'description': 'podcast metadata',
+            },
+        ]
+
+        # Add episodes to the graph
+        for i, episode in enumerate(episodes):
+            await graphiti.add_episode(
+                name=f'Freakonomics Radio {i}',
+                episode_body=episode['content']
+                if isinstance(episode['content'], str)
+                else json.dumps(episode['content']),
+                source=episode['type'],
+                source_description=episode['description'],
+                reference_time=datetime.now(timezone.utc),
+            )
+            print(f'Added episode: Freakonomics Radio {i} ({episode["type"].value})')
+
+        await graphiti.build_communities()
+
+        #################################################
+        # BASIC SEARCH
+        #################################################
+        # The simplest way to retrieve relationships (edges)
+        # from Graphiti is using the search method, which
+        # performs a hybrid search combining semantic
+        # similarity and BM25 text retrieval.
+        #################################################
+
+        # Perform a hybrid search combining semantic similarity and BM25 retrieval
+        print("\nSearching for: 'Who was the California Attorney General?'")
+        results = await graphiti.search('Who was the California Attorney General?')
+
+        # Print search results
+        print('\nSearch Results:')
+        for result in results:
+            print(f'UUID: {result.uuid}')
+            print(f'Fact: {result.fact}')
+            if hasattr(result, 'valid_at') and result.valid_at:
+                print(f'Valid from: {result.valid_at}')
+            if hasattr(result, 'invalid_at') and result.invalid_at:
+                print(f'Valid until: {result.invalid_at}')
+            print('---')
+
+        #################################################
+        # CENTER NODE SEARCH
+        #################################################
+        # For more contextually relevant results, you can
+        # use a center node to rerank search results based
+        # on their graph distance to a specific node
+        #################################################
+
+        # Use the top search result's UUID as the center node for reranking
+        if results and len(results) > 0:
+            # Get the source node UUID from the top result
+            center_node_uuid = results[0].source_node_uuid
+
+            print('\nReranking search results based on graph distance:')
+            print(f'Using center node UUID: {center_node_uuid}')
+
+            reranked_results = await graphiti.search(
+                'Who was the California Attorney General?', center_node_uuid=center_node_uuid
+            )
+
+            # Print reranked search results
+            print('\nReranked Search Results:')
+            for result in reranked_results:
+                print(f'UUID: {result.uuid}')
+                print(f'Fact: {result.fact}')
+                if hasattr(result, 'valid_at') and result.valid_at:
+                    print(f'Valid from: {result.valid_at}')
+                if hasattr(result, 'invalid_at') and result.invalid_at:
+                    print(f'Valid until: {result.invalid_at}')
+                print('---')
+        else:
+            print('No results found in the initial search to use as center node.')
+
+        #################################################
+        # NODE SEARCH USING SEARCH RECIPES
+        #################################################
+        # Graphiti provides predefined search recipes
+        # optimized for different search scenarios.
+        # Here we use NODE_HYBRID_SEARCH_RRF for retrieving
+        # nodes directly instead of edges.
+        #################################################
+
+        # Example: Perform a node search using _search method with standard recipes
+        print(
+            '\nPerforming node search using _search method with standard recipe NODE_HYBRID_SEARCH_RRF:'
+        )
+
+        # Use a predefined search configuration recipe and modify its limit
+        node_search_config = NODE_HYBRID_SEARCH_RRF.model_copy(deep=True)
+        node_search_config.limit = 5  # Limit to 5 results
+
+        # Execute the node search
+        node_search_results = await graphiti._search(
+            query='California Governor',
+            config=node_search_config,
+        )
+
+        # Print node search results
+        print('\nNode Search Results:')
+        for node in node_search_results.nodes:
+            print(f'Node UUID: {node.uuid}')
+            print(f'Node Name: {node.name}')
+            node_summary = node.summary[:100] + '...' if len(node.summary) > 100 else node.summary
+            print(f'Content Summary: {node_summary}')
+            print(f'Node Labels: {", ".join(node.labels)}')
+            print(f'Created At: {node.created_at}')
+            if hasattr(node, 'attributes') and node.attributes:
+                print('Attributes:')
+                for key, value in node.attributes.items():
+                    print(f'  {key}: {value}')
+            print('---')
+
+    finally:
+        #################################################
+        # CLEANUP
+        #################################################
+        # Always close the connection to Neptune when
+        # finished to properly release resources
+        #################################################
+
+        # Close the connection
+        await graphiti.close()
+        print('\nConnection closed')
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

{graphiti_core-0.19.0rc1 → graphiti_core-0.19.0rc3}/graphiti_core/migrations/neo4j_node_group_labels.py

@@ -1,4 +1,8 @@
+import asyncio
+import os
+
 from graphiti_core.driver.driver import GraphDriver
+from graphiti_core.driver.neo4j_driver import Neo4jDriver
 from graphiti_core.helpers import validate_group_id
 from graphiti_core.utils.maintenance.graph_data_operations import build_dynamic_indexes
 
@@ -11,21 +15,21 @@ async def neo4j_node_group_labels(driver: GraphDriver, group_id: str, batch_size
                         MATCH (n:Episodic {group_id: $group_id})
                         CALL {
                             WITH n
-                            SET n:$group_label
+                            SET n:$($group_label)
                         } IN TRANSACTIONS OF $batch_size ROWS"""
 
     entity_query = """
                         MATCH (n:Entity {group_id: $group_id})
                         CALL {
                             WITH n
-                            SET n:$group_label
+                            SET n:$($group_label)
                         } IN TRANSACTIONS OF $batch_size ROWS"""
 
     community_query = """
                         MATCH (n:Community {group_id: $group_id})
                         CALL {
                             WITH n
-                            SET n:$group_label
+                            SET n:$($group_label)
                         } IN TRANSACTIONS OF $batch_size ROWS"""
 
     async with driver.session() as session:
@@ -51,3 +55,31 @@ async def neo4j_node_group_labels(driver: GraphDriver, group_id: str, batch_size
             group_label='Community_' + group_id.replace('-', ''),
             batch_size=batch_size,
         )
+
+
+async def neo4j_node_label_migration(driver: GraphDriver):
+    query = """MATCH (n:Episodic)
+                RETURN DISTINCT n.group_id AS group_id"""
+
+    results, _, _ = await driver.execute_query(query)
+    for result in results:
+        group_id = result['group_id']
+        await neo4j_node_group_labels(driver, group_id)
+
+
+async def main():
+    neo4j_uri = os.environ.get('NEO4J_URI') or 'bolt://localhost:7687'
+    neo4j_user = os.environ.get('NEO4J_USER') or 'neo4j'
+    neo4j_password = os.environ.get('NEO4J_PASSWORD') or 'password'
+
+    driver = Neo4jDriver(
+        uri=neo4j_uri,
+        user=neo4j_user,
+        password=neo4j_password,
+    )
+    await neo4j_node_label_migration(driver)
+    await driver.close()
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

{graphiti_core-0.19.0rc1 → graphiti_core-0.19.0rc3}/graphiti_core/search/search.py

@@ -21,6 +21,7 @@ from time import time
 from graphiti_core.cross_encoder.client import CrossEncoderClient
 from graphiti_core.driver.driver import GraphDriver
 from graphiti_core.edges import EntityEdge
+from graphiti_core.embedder.client import EMBEDDING_DIM
 from graphiti_core.errors import SearchRerankerError
 from graphiti_core.graphiti_types import GraphitiClients
 from graphiti_core.helpers import semaphore_gather
@@ -29,6 +30,7 @@ from graphiti_core.search.search_config import (
     DEFAULT_SEARCH_LIMIT,
     CommunityReranker,
     CommunitySearchConfig,
+    CommunitySearchMethod,
     EdgeReranker,
     EdgeSearchConfig,
     EdgeSearchMethod,
@@ -81,11 +83,29 @@ async def search(
 
     if query.strip() == '':
         return SearchResults()
-    query_vector = (
-        query_vector
-        if query_vector is not None
-        else await embedder.create(input_data=[query.replace('\n', ' ')])
-    )
+
+    if (
+        config.edge_config
+        and EdgeSearchMethod.cosine_similarity in config.edge_config.search_methods
+        or config.edge_config
+        and EdgeReranker.mmr == config.edge_config.reranker
+        or config.node_config
+        and NodeSearchMethod.cosine_similarity in config.node_config.search_methods
+        or config.node_config
+        and NodeReranker.mmr == config.node_config.reranker
+        or (
+            config.community_config
+            and CommunitySearchMethod.cosine_similarity in config.community_config.search_methods
+        )
+        or (config.community_config and CommunityReranker.mmr == config.community_config.reranker)
+    ):
+        search_vector = (
+            query_vector
+            if query_vector is not None
+            else await embedder.create(input_data=[query.replace('\n', ' ')])
+        )
+    else:
+        search_vector = [0.0] * EMBEDDING_DIM
 
     # if group_ids is empty, set it to None
     group_ids = group_ids if group_ids and group_ids != [''] else None
@@ -99,7 +119,7 @@ async def search(
             driver,
             cross_encoder,
             query,
-            query_vector,
+            search_vector,
             group_ids,
             config.edge_config,
             search_filter,
@@ -112,7 +132,7 @@ async def search(
             driver,
             cross_encoder,
             query,
-            query_vector,
+            search_vector,
             group_ids,
             config.node_config,
             search_filter,
@@ -125,7 +145,7 @@ async def search(
             driver,
             cross_encoder,
             query,
-            query_vector,
+            search_vector,
             group_ids,
             config.episode_config,
             search_filter,
@@ -136,7 +156,7 @@ async def search(
             driver,
             cross_encoder,
             query,
-            query_vector,
+            search_vector,
             group_ids,
             config.community_config,
             config.limit,

{graphiti_core-0.19.0rc1 → graphiti_core-0.19.0rc3}/graphiti_core/utils/maintenance/graph_data_operations.py

@@ -35,7 +35,8 @@ logger = logging.getLogger(__name__)
 
 async def build_indices_and_constraints(driver: GraphDriver, delete_existing: bool = False):
     if driver.provider == GraphProvider.NEPTUNE:
-        return  # Neptune does not need indexes built
+        await driver.create_aoss_indices()  # pyright: ignore[reportAttributeAccessIssue]
+        return
     if delete_existing:
         records, _, _ = await driver.execute_query(
             """

{graphiti_core-0.19.0rc1 → graphiti_core-0.19.0rc3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "graphiti-core"
 description = "A temporal graph building library"
-version = "0.19.0pre1"
+version = "0.19.0pre3"
 authors = [
     { name = "Paul Paliychuk", email = "paul@getzep.com" },
     { name = "Preston Rasmussen", email = "preston@getzep.com" },

{graphiti_core-0.19.0rc1 → graphiti_core-0.19.0rc3}/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 2
 requires-python = ">=3.10, <4"
 resolution-markers = [
     "python_full_version >= '3.14'",
@@ -783,7 +783,7 @@ wheels = [
 
 [[package]]
 name = "graphiti-core"
-version = "0.19.0rc1"
+version = "0.19.0rc3"
 source = { editable = "." }
 dependencies = [
     { name = "diskcache" },