Neo4j GraphRAG Python Client

1.14.1 · active · verified Wed Apr 15

The neo4j-graphrag library provides Pythonic access and utilities for integrating with Neo4j's GraphRAG (Retrieval Augmented Generation) features. It simplifies building Knowledge Graphs from unstructured text, performing vector embeddings, and executing RAG queries against a Neo4j graph database. The current version is 1.14.1, with a release cadence that is quite active, often seeing minor releases monthly.

Warnings

breaking Python 3.9 support was dropped in version 1.12.0. Additionally, Python 3.15 and newer are not yet supported (requires_python: <3.15,>=3.10.0).
Fix: Ensure your project uses Python versions between 3.10 and 3.14 (inclusive). Downgrade Python if necessary or wait for future `neo4j-graphrag` updates.
gotcha As of version 1.14.1, schema extraction for entity labels explicitly forbids the use of `__` (double underscore) prefixes or suffixes. This may affect existing knowledge graphs or data ingestion pipelines that use such naming conventions.
Fix: Avoid `__` (double underscore) at the beginning or end of entity labels when extracting schema or designing your graph data model.
breaking Version 1.13.0 introduced significant changes for LLM integrations, including support for structured output in `LLMInterfaceV2`, `OpenAILLM`, `VertexAILLM`, and tool calling for `OllamaLLM`. If you were interacting with these LLMs directly or expecting specific unstructured text outputs, your code may need adjustment.
Fix: Review your LLM interaction patterns. If using direct LLM calls or specific output parsing, check the updated API for structured output methods and tool calling. Adapt your code to handle the new capabilities or maintain compatibility if relying on older patterns.
gotcha Version 1.14.0 fixed usage of deprecated APOC procedures. If you are using an older version of `neo4j-graphrag` with a newer Neo4j database version (e.g., Neo4j 5.x) that has removed or changed older APOC procedures, you might encounter errors.
Fix: Upgrade to `neo4j-graphrag` version 1.14.0 or newer to ensure compatibility with modern Neo4j versions and their APOC library.

Install

pip install neo4j-graphrag Base installation
pip install neo4j-graphrag[openai,vertexai,ollama] Installation with common LLM integrations

Imports

GraphRAGPipeline

from neo4j_graphrag.graph_rag_pipeline import GraphRAGPipeline

SimpleKGPipeline

from neo4j_graphrag.knowledge_graph_builder import SimpleKGPipeline

OpenAILLM
```
from neo4j_graphrag.llm import OpenAILLM
```
LLM classes are typically imported directly from `neo4j_graphrag.llm`

VertexAILLM

from neo4j_graphrag.llm import VertexAILLM

Neo4jStore

from neo4j_graphrag.retrievers import Neo4jStore

Quickstart

This quickstart demonstrates how to set up and use the `GraphRAGPipeline` with an OpenAI LLM to query a Neo4j knowledge graph. It requires Neo4j to be running and accessible, and an OpenAI API key. Ensure `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, and `OPENAI_API_KEY` environment variables are set.

import os
from neo4j import GraphDatabase
from neo4j_graphrag.graph_rag_pipeline import GraphRAGPipeline
from neo4j_graphrag.llm import OpenAILLM

# --- Configuration (Set environment variables or replace placeholders) ---
NEO4J_URI = os.environ.get("NEO4J_URI", "bolt://localhost:7687")
NEO4J_USERNAME = os.environ.get("NEO4J_USERNAME", "neo4j")
NEO4J_PASSWORD = os.environ.get("NEO4J_PASSWORD", "password")
NEO4J_DATABASE = os.environ.get("NEO4J_DATABASE", "neo4j")
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "") # Required for OpenAILLM

if not all([NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, OPENAI_API_KEY]):
    print("Warning: Please set NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, and OPENAI_API_KEY environment variables for a runnable example.")
    print("Using default values for Neo4j, which may not connect without a running instance.")
    print("OpenAI API key is missing. The LLM initialization might fail or proceed without API calls.")

try:
    # 1. Initialize Neo4j Driver
    driver = GraphDatabase.driver(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD))
    # Verify connection to ensure Neo4j is reachable and credentials are correct
    driver.verify_connectivity()
    print("Neo4j connection verified successfully.")

    # 2. Initialize your chosen LLM (e.g., OpenAI)
    llm = OpenAILLM(api_key=OPENAI_API_KEY)

    # 3. Initialize the GraphRAG pipeline
    # This pipeline is designed to work with a knowledge graph. For best results,
    # ensure your Neo4j database has relevant data, possibly built using SimpleKGPipeline.
    pipeline = GraphRAGPipeline(
        llm=llm,
        graph_driver=driver,
        database=NEO4J_DATABASE
    )

    # 4. Ask a question to the pipeline
    question = "Who is the CEO of Neo4j?"
    print(f"\nQuestion: {question}")
    response = pipeline.query(question)

    print(f"Answer: {response.answer}")

except Exception as e:
    print(f"An error occurred during quickstart: {e}")
finally:
    if 'driver' in locals():
        driver.close()
        print("Neo4j driver closed.")

view raw JSON →