graphiti-core 0.19.0rc3__tar.gz → 0.20.0__tar.gz

{graphiti_core-0.19.0rc3 → graphiti_core-0.20.0}/.github/workflows/cla.yml

@@ -28,7 +28,7 @@ jobs:
           path-to-document: "https://github.com/getzep/graphiti/blob/main/Zep-CLA.md" # e.g. a CLA or a DCO document
           # branch should not be protected unless a personal PAT is used
           branch: "main"
-          allowlist: paul-paliychuk,prasmussen15,danielchalef,dependabot[bot],ellipsis-dev,Claude[bot]
+          allowlist: paul-paliychuk,prasmussen15,danielchalef,dependabot[bot],ellipsis-dev,Claude[bot],claude[bot]
 
           # the followings are the optional inputs - If the optional inputs are not given, then default values will be taken
           #remote-organization-name: enter the remote organization name where the signatures should be stored (Default is storing the signatures in the same repository)

graphiti_core-0.20.0/.github/workflows/claude-code-review.yml

@@ -0,0 +1,50 @@
+name: Claude PR Auto Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  auto-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Automatic PR Review
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          use_sticky_comment: true
+          allowed_bots: "dependabot"
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request.
+
+            Note: The PR branch is already checked out in the current working directory.
+
+            Focus on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security implications
+            - Test coverage
+            - Documentation updates if needed
+            - Verify that README.md and docs are updated for any new features or config changes
+
+            Provide constructive feedback with specific suggestions for improvement.
+            Use `gh pr comment:*` for top-level comments.
+            Use `mcp__github_inline_comment__create_inline_comment` to highlight specific areas of concern.
+            Only your GitHub comments that you post will be seen, so don't submit your review as a normal message, just as comments.
+            If the PR has already been reviewed, or there are no noteworthy changes, don't post anything.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*)"

{graphiti_core-0.19.0rc3 → graphiti_core-0.20.0}/.github/workflows/claude.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@beta
+        uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 

{graphiti_core-0.19.0rc3 → graphiti_core-0.20.0}/.github/workflows/unit_tests.yml

@@ -49,6 +49,7 @@ jobs:
           NEO4J_URI: bolt://localhost:7687
           NEO4J_USER: neo4j
           NEO4J_PASSWORD: testpass
+          DISABLE_NEPTUNE: 1
         run: |
           uv run pytest -m "not integration"
       - name: Wait for FalkorDB

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphiti-core
-Version: 0.19.0rc3
+Version: 0.20.0
 Summary: A temporal graph building library
 Project-URL: Homepage, https://help.getzep.com/graphiti/graphiti/overview
 Project-URL: Repository, https://github.com/getzep/graphiti
@@ -26,6 +26,7 @@ Requires-Dist: google-genai>=1.8.0; extra == 'dev'
 Requires-Dist: groq>=0.2.0; extra == 'dev'
 Requires-Dist: ipykernel>=6.29.5; extra == 'dev'
 Requires-Dist: jupyterlab>=4.2.4; extra == 'dev'
+Requires-Dist: kuzu>=0.11.2; extra == 'dev'
 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'
@@ -44,6 +45,8 @@ 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: kuzu
+Requires-Dist: kuzu>=0.11.2; extra == 'kuzu'
 Provides-Extra: neptune
 Requires-Dist: boto3>=1.39.16; extra == 'neptune'
 Requires-Dist: langchain-aws>=0.2.29; extra == 'neptune'
@@ -87,9 +90,15 @@ Graphiti
 <br />
 
 > [!TIP]
-> Check out the new [MCP server for Graphiti](mcp_server/README.md)! Give Claude, Cursor, and other MCP clients powerful Knowledge Graph-based memory.
+> Check out the new [MCP server for Graphiti](mcp_server/README.md)! Give Claude, Cursor, and other MCP clients powerful
+> Knowledge Graph-based memory.
 
-Graphiti is a framework for building and querying temporally-aware knowledge graphs, specifically tailored for AI agents operating in dynamic environments. Unlike traditional retrieval-augmented generation (RAG) methods, Graphiti continuously integrates user interactions, structured and unstructured enterprise data, and external information into a coherent, queryable graph. The framework supports incremental data updates, efficient retrieval, and precise historical queries without requiring complete graph recomputation, making it suitable for developing interactive, context-aware AI applications.
+Graphiti is a framework for building and querying temporally-aware knowledge graphs, specifically tailored for AI agents
+operating in dynamic environments. Unlike traditional retrieval-augmented generation (RAG) methods, Graphiti
+continuously integrates user interactions, structured and unstructured enterprise data, and external information into a
+coherent, queryable graph. The framework supports incremental data updates, efficient retrieval, and precise historical
+queries without requiring complete graph recomputation, making it suitable for developing interactive, context-aware AI
+applications.
 
 Use Graphiti to:
 
@@ -100,19 +109,21 @@ Use Graphiti to:
 <br />
 
 <p align="center">
-    <img src="images/graphiti-graph-intro.gif" alt="Graphiti temporal walkthrough" width="700px">   
+    <img src="images/graphiti-graph-intro.gif" alt="Graphiti temporal walkthrough" width="700px">
 </p>
 
 <br />
 
-A knowledge graph is a network of interconnected facts, such as _"Kendra loves Adidas shoes."_ Each fact is a "triplet" represented by two entities, or
+A knowledge graph is a network of interconnected facts, such as _"Kendra loves Adidas shoes."_ Each fact is a "triplet"
+represented by two entities, or
 nodes ("Kendra", "Adidas shoes"), and their relationship, or edge ("loves"). Knowledge Graphs have been explored
 extensively for information retrieval. What makes Graphiti unique is its ability to autonomously build a knowledge graph
 while handling changing relationships and maintaining historical context.
 
 ## Graphiti and Zep's Context Engineering Platform.
 
-Graphiti powers the core of [Zep](https://www.getzep.com), a turn-key context engineering platform for AI Agents. Zep offers agent memory, Graph RAG for dynamic data, and context retrieval and assembly.
+Graphiti powers the core of [Zep](https://www.getzep.com), a turn-key context engineering platform for AI Agents. Zep
+offers agent memory, Graph RAG for dynamic data, and context retrieval and assembly.
 
 Using Graphiti, we've demonstrated Zep is
 the [State of the Art in Agent Memory](https://blog.getzep.com/state-of-the-art-agent-memory/).
@@ -127,22 +138,26 @@ We're excited to open-source Graphiti, believing its potential reaches far beyon
 
 ## Why Graphiti?
 
-Traditional RAG approaches often rely on batch processing and static data summarization, making them inefficient for frequently changing data. Graphiti addresses these challenges by providing:
+Traditional RAG approaches often rely on batch processing and static data summarization, making them inefficient for
+frequently changing data. Graphiti addresses these challenges by providing:
 
 - **Real-Time Incremental Updates:** Immediate integration of new data episodes without batch recomputation.
-- **Bi-Temporal Data Model:** Explicit tracking of event occurrence and ingestion times, allowing accurate point-in-time queries.
-- **Efficient Hybrid Retrieval:** Combines semantic embeddings, keyword (BM25), and graph traversal to achieve low-latency queries without reliance on LLM summarization.
-- **Custom Entity Definitions:** Flexible ontology creation and support for developer-defined entities through straightforward Pydantic models.
+- **Bi-Temporal Data Model:** Explicit tracking of event occurrence and ingestion times, allowing accurate point-in-time
+  queries.
+- **Efficient Hybrid Retrieval:** Combines semantic embeddings, keyword (BM25), and graph traversal to achieve
+  low-latency queries without reliance on LLM summarization.
+- **Custom Entity Definitions:** Flexible ontology creation and support for developer-defined entities through
+  straightforward Pydantic models.
 - **Scalability:** Efficiently manages large datasets with parallel processing, suitable for enterprise environments.
 
 <p align="center">
-    <img src="/images/graphiti-intro-slides-stock-2.gif" alt="Graphiti structured + unstructured demo" width="700px">   
+    <img src="/images/graphiti-intro-slides-stock-2.gif" alt="Graphiti structured + unstructured demo" width="700px">
 </p>
 
 ## Graphiti vs. GraphRAG
 
 | Aspect                     | GraphRAG                              | Graphiti                                         |
-| -------------------------- | ------------------------------------- | ------------------------------------------------ |
+|----------------------------|---------------------------------------|--------------------------------------------------|
 | **Primary Use**            | Static document summarization         | Dynamic data management                          |
 | **Data Handling**          | Batch-oriented processing             | Continuous, incremental updates                  |
 | **Knowledge Structure**    | Entity clusters & community summaries | Episodic data, semantic entities, communities    |
@@ -154,14 +169,16 @@ Traditional RAG approaches often rely on batch processing and static data summar
 | **Custom Entity Types**    | No                                    | Yes, customizable                                |
 | **Scalability**            | Moderate                              | High, optimized for large datasets               |
 
-Graphiti is specifically designed to address the challenges of dynamic and frequently updated datasets, making it particularly suitable for applications requiring real-time interaction and precise historical queries.
+Graphiti is specifically designed to address the challenges of dynamic and frequently updated datasets, making it
+particularly suitable for applications requiring real-time interaction and precise historical queries.
 
 ## Installation
 
 Requirements:
 
 - Python 3.10 or higher
-- 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)
+- Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.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]
@@ -204,6 +221,17 @@ pip install graphiti-core[falkordb]
 uv add graphiti-core[falkordb]
 ```
 
+### Installing with Kuzu Support
+
+If you plan to use Kuzu as your graph database backend, install with the Kuzu extra:
+
+```bash
+pip install graphiti-core[kuzu]
+
+# or with uv
+uv add graphiti-core[kuzu]
+```
+
 ### Installing with Amazon Neptune Support
 
 If you plan to use Amazon Neptune as your graph database backend, install with the Amazon Neptune extra:
@@ -239,33 +267,41 @@ pip install graphiti-core[neptune]
 
 ## Default to Low Concurrency; LLM Provider 429 Rate Limit Errors
 
-Graphiti's ingestion pipelines are designed for high concurrency. By default, concurrency is set low to avoid LLM Provider 429 Rate Limit Errors. If you find Graphiti slow, please increase concurrency as described below.
+Graphiti's ingestion pipelines are designed for high concurrency. By default, concurrency is set low to avoid LLM
+Provider 429 Rate Limit Errors. If you find Graphiti slow, please increase concurrency as described below.
 
-Concurrency controlled by the `SEMAPHORE_LIMIT` environment variable. By default, `SEMAPHORE_LIMIT` is set to `10` concurrent operations to help prevent `429` rate limit errors from your LLM provider. If you encounter such errors, try lowering this value.
+Concurrency controlled by the `SEMAPHORE_LIMIT` environment variable. By default, `SEMAPHORE_LIMIT` is set to `10`
+concurrent operations to help prevent `429` rate limit errors from your LLM provider. If you encounter such errors, try
+lowering this value.
 
-If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT` to boost episode ingestion performance.
+If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT` to boost episode ingestion
+performance.
 
 ## Quick Start
 
 > [!IMPORTANT]
-> Graphiti defaults to using OpenAI for LLM inference and embedding. Ensure that an `OPENAI_API_KEY` is set in your environment.
+> Graphiti defaults to using OpenAI for LLM inference and embedding. Ensure that an `OPENAI_API_KEY` is set in your
+> environment.
 > Support for Anthropic and Groq LLM inferences is available, too. Other LLM providers may be supported via OpenAI
 > compatible APIs.
 
-For a complete working example, see the [Quickstart Example](./examples/quickstart/README.md) in the examples directory. The quickstart demonstrates:
+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, Amazon Neptune, or FalkorDB database
+1. Connecting to a Neo4j, Amazon Neptune, FalkorDB, or Kuzu 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
 5. Reranking search results using graph distance
 6. Searching for nodes using predefined search recipes
 
-The example is fully documented with clear explanations of each functionality and includes a comprehensive README with setup instructions and next steps.
+The example is fully documented with clear explanations of each functionality and includes a comprehensive README with
+setup instructions and next steps.
 
 ## MCP Server
 
-The `mcp_server` directory contains a Model Context Protocol (MCP) server implementation for Graphiti. This server allows AI assistants to interact with Graphiti's knowledge graph capabilities through the MCP protocol.
+The `mcp_server` directory contains a Model Context Protocol (MCP) server implementation for Graphiti. This server
+allows AI assistants to interact with Graphiti's knowledge graph capabilities through the MCP protocol.
 
 Key features of the MCP server include:
 
@@ -275,7 +311,8 @@ Key features of the MCP server include:
 - Group management for organizing related data
 - Graph maintenance operations
 
-The MCP server can be deployed using Docker with Neo4j, making it easy to integrate Graphiti into your AI assistant workflows.
+The MCP server can be deployed using Docker with Neo4j, making it easy to integrate Graphiti into your AI assistant
+workflows.
 
 For detailed setup instructions and usage examples, see the [MCP server README](./mcp_server/README.md).
 
@@ -298,7 +335,8 @@ Database names are configured directly in the driver constructors:
 - **Neo4j**: Database name defaults to `neo4j` (hardcoded in Neo4jDriver)
 - **FalkorDB**: Database name defaults to `default_db` (hardcoded in FalkorDriver)
 
-As of v0.17.0, if you need to customize your database configuration, you can instantiate a database driver and pass it to the Graphiti constructor using the `graph_driver` parameter.
+As of v0.17.0, if you need to customize your database configuration, you can instantiate a database driver and pass it
+to the Graphiti constructor using the `graph_driver` parameter.
 
 #### Neo4j with Custom Database Name
 
@@ -337,6 +375,19 @@ driver = FalkorDriver(
 graphiti = Graphiti(graph_driver=driver)
 ```
 
+#### Kuzu
+
+```python
+from graphiti_core import Graphiti
+from graphiti_core.driver.kuzu_driver import KuzuDriver
+
+# Create a Kuzu driver
+driver = KuzuDriver(db="/tmp/graphiti.kuzu")
+
+# Pass the driver to Graphiti
+graphiti = Graphiti(graph_driver=driver)
+```
+
 #### Amazon Neptune
 
 ```python
@@ -345,10 +396,14 @@ 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
+    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)
@@ -357,17 +412,20 @@ driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)
 graphiti = Graphiti(graph_driver=driver)
 ```
 
-
-### Performance Configuration
-
-`USE_PARALLEL_RUNTIME` is an optional boolean variable that can be set to true if you wish
-to enable Neo4j's parallel runtime feature for several of our search queries.
-Note that this feature is not supported for Neo4j Community edition or for smaller AuraDB instances,
-as such this feature is off by default.
-
 ## Using Graphiti with Azure OpenAI
 
-Graphiti supports Azure OpenAI for both LLM inference and embeddings. Azure deployments often require different endpoints for LLM and embedding services, and separate deployments for default and small models.
+Graphiti supports Azure OpenAI for both LLM inference and embeddings. Azure deployments often require different
+endpoints for LLM and embedding services, and separate deployments for default and small models.
+
+> [!IMPORTANT]
+> **Azure OpenAI v1 API Opt-in Required for Structured Outputs**
+>
+> Graphiti uses structured outputs via the `client.beta.chat.completions.parse()` method, which requires Azure OpenAI
+> deployments to opt into the v1 API. Without this opt-in, you'll encounter 404 Resource not found errors during episode
+> ingestion.
+>
+> To enable v1 API support in your Azure OpenAI deployment, follow Microsoft's
+> guide: [Azure OpenAI API version lifecycle](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/api-version-lifecycle?tabs=key#api-evolution).
 
 ```python
 from openai import AsyncAzureOpenAI
@@ -427,11 +485,13 @@ graphiti = Graphiti(
 # Now you can use Graphiti with Azure OpenAI
 ```
 
-Make sure to replace the placeholder values with your actual Azure OpenAI credentials and deployment names that match your Azure OpenAI service configuration.
+Make sure to replace the placeholder values with your actual Azure OpenAI credentials and deployment names that match
+your Azure OpenAI service configuration.
 
 ## Using Graphiti with Google Gemini
 
-Graphiti supports Google's Gemini models for LLM inference, embeddings, and cross-encoding/reranking. To use Gemini, you'll need to configure the LLM client, embedder, and the cross-encoder with your Google API key.
+Graphiti supports Google's Gemini models for LLM inference, embeddings, and cross-encoding/reranking. To use Gemini,
+you'll need to configure the LLM client, embedder, and the cross-encoder with your Google API key.
 
 Install Graphiti:
 
@@ -480,13 +540,17 @@ graphiti = Graphiti(
 # Now you can use Graphiti with Google Gemini for all components
 ```
 
-The Gemini reranker uses the `gemini-2.5-flash-lite-preview-06-17` model by default, which is optimized for cost-effective and low-latency classification tasks. It uses the same boolean classification approach as the OpenAI reranker, leveraging Gemini's log probabilities feature to rank passage relevance.
+The Gemini reranker uses the `gemini-2.5-flash-lite-preview-06-17` model by default, which is optimized for
+cost-effective and low-latency classification tasks. It uses the same boolean classification approach as the OpenAI
+reranker, leveraging Gemini's log probabilities feature to rank passage relevance.
 
 ## Using Graphiti with Ollama (Local LLM)
 
-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.
+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
@@ -539,7 +603,8 @@ Ensure Ollama is running (`ollama serve`) and that you have pulled the models yo
 
 ## Telemetry
 
-Graphiti collects anonymous usage statistics to help us understand how the framework is being used and improve it for everyone. We believe transparency is important, so here's exactly what we collect and why.
+Graphiti collects anonymous usage statistics to help us understand how the framework is being used and improve it for
+everyone. We believe transparency is important, so here's exactly what we collect and why.
 
 ### What We Collect
 
@@ -549,9 +614,9 @@ When you initialize a Graphiti instance, we collect:
 - **System information**: Operating system, Python version, and system architecture
 - **Graphiti version**: The version you're using
 - **Configuration choices**:
-  - LLM provider type (OpenAI, Azure, Anthropic, etc.)
-  - Database backend (Neo4j, FalkorDB, Amazon Neptune Database or Neptune Analytics)
-  - Embedder provider (OpenAI, Azure, Voyage, etc.)
+    - LLM provider type (OpenAI, Azure, Anthropic, etc.)
+    - Database backend (Neo4j, FalkorDB, Kuzu, Amazon Neptune Database or Neptune Analytics)
+    - Embedder provider (OpenAI, Azure, Voyage, etc.)
 
 ### What We Don't Collect
 
@@ -603,10 +668,12 @@ echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc
 
 ```python
 import os
+
 os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'
 
 # Then initialize Graphiti as usual
 from graphiti_core import Graphiti
+
 graphiti = Graphiti(...)
 ```
 
@@ -615,7 +682,8 @@ Telemetry is automatically disabled during test runs (when `pytest` is detected)
 ### Technical Details
 
 - Telemetry uses PostHog for anonymous analytics collection
-- All telemetry operations are designed to fail silently - they will never interrupt your application or affect Graphiti functionality
+- All telemetry operations are designed to fail silently - they will never interrupt your application or affect Graphiti
+  functionality
 - The anonymous ID is stored locally and is not tied to any personal information
 
 ## Status and Roadmap
@@ -623,8 +691,8 @@ Telemetry is automatically disabled during test runs (when `pytest` is detected)
 Graphiti is under active development. We aim to maintain API stability while working on:
 
 - [x] Supporting custom graph schemas:
-  - Allow developers to provide their own defined node and edge classes when ingesting episodes
-  - Enable more flexible knowledge representation tailored to specific use cases
+    - Allow developers to provide their own defined node and edge classes when ingesting episodes
+    - Enable more flexible knowledge representation tailored to specific use cases
 - [x] Enhancing retrieval capabilities with more robust and configurable options
 - [x] Graphiti MCP Server
 - [ ] Expanding test coverage to ensure reliability and catch edge cases