{"id":15159659,"url":"https://github.com/neo4j/neo4j-graphrag-python","last_synced_at":"2026-02-11T00:01:28.959Z","repository":{"id":237922481,"uuid":"764049913","full_name":"neo4j/neo4j-graphrag-python","owner":"neo4j","description":"Neo4j GraphRAG for Python","archived":false,"fork":false,"pushed_at":"2026-01-23T11:02:35.000Z","size":4381,"stargazers_count":996,"open_issues_count":30,"forks_count":176,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-01-23T20:19:11.041Z","etag":null,"topics":["ai","cypher","genai","graph-database","graphrag","neo4j","python","python3","rag"],"latest_commit_sha":null,"homepage":"https://neo4j.com/docs/neo4j-graphrag-python/current/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neo4j.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.APACHE2.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.txt","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-27T11:49:23.000Z","updated_at":"2026-01-22T21:45:23.000Z","dependencies_parsed_at":"2024-05-20T08:28:34.528Z","dependency_job_id":"fcf8bb8a-6c3f-4e3a-87bc-807cfee4f786","html_url":"https://github.com/neo4j/neo4j-graphrag-python","commit_stats":{"total_commits":221,"total_committers":10,"mean_commits":22.1,"dds":0.6832579185520362,"last_synced_commit":"6ac97b736d21ab8751d26c03d20787f417732cf5"},"previous_names":["neo4j/neo4j-genai-python","neo4j/neo4j-graphrag-python"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/neo4j/neo4j-graphrag-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j%2Fneo4j-graphrag-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j%2Fneo4j-graphrag-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j%2Fneo4j-graphrag-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j%2Fneo4j-graphrag-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neo4j","download_url":"https://codeload.github.com/neo4j/neo4j-graphrag-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neo4j%2Fneo4j-graphrag-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29322733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T20:44:44.282Z","status":"ssl_error","status_checked_at":"2026-02-10T20:44:43.393Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cypher","genai","graph-database","graphrag","neo4j","python","python3","rag"],"created_at":"2024-09-26T21:41:12.454Z","updated_at":"2026-02-11T00:01:28.728Z","avatar_url":"https://github.com/neo4j.png","language":"Python","readme":"# Neo4j GraphRAG Package for Python\n\nThe official Neo4j GraphRAG package for Python enables developers to build [graph retrieval augmented generation (GraphRAG)](https://neo4j.com/blog/graphrag-manifesto/) applications using the power of Neo4j and Python.\nAs a first-party library, it offers a robust, feature-rich, and high-performance solution, with the added assurance of long-term support and maintenance directly from Neo4j.\n\n## 📄 Documentation\n\nDocumentation can be found [here](https://neo4j.com/docs/neo4j-graphrag-python/)\n\n### Resources\n\nA series of blog posts demonstrating how to use this package:\n\n- Build a Knowledge Graph and use GenAI to answer questions:\n  - [GraphRAG Python Package: Accelerating GenAI With Knowledge Graphs](https://neo4j.com/blog/graphrag-python-package/)\n- Retrievers: when the Neo4j graph is already populated:\n  - [Getting Started With the Neo4j GraphRAG Python Package](https://neo4j.com/developer-blog/get-started-graphrag-python-package/)\n  - [Enriching Vector Search With Graph Traversal Using the GraphRAG Python Package](https://neo4j.com/developer-blog/graph-traversal-graphrag-python-package/)\n  - [Hybrid Retrieval for GraphRAG Applications Using the GraphRAG Python Package](https://neo4j.com/developer-blog/hybrid-retrieval-graphrag-python-package/)\n  - [Enhancing Hybrid Retrieval With Graph Traversal Using the GraphRAG Python Package](https://neo4j.com/developer-blog/enhancing-hybrid-retrieval-graphrag-python-package/)\n  - [Effortless RAG With Text2CypherRetriever](https://medium.com/neo4j/effortless-rag-with-text2cypherretriever-cb1a781ca53c)\n\nA list of Neo4j GenAI-related features can also be found at [Neo4j GenAI Ecosystem](https://neo4j.com/labs/genai-ecosystem/).\n\n\n## 🐍 Python Version Support\n\n| Version | Supported? |\n|---------|-----------:|\n| 3.14    |    \u0026check; |\n| 3.13    |    \u0026check; |\n| 3.12    |    \u0026check; |\n| 3.11    |    \u0026check; |\n| 3.10    |    \u0026check; |\n\n## 📦 Installation\n\nTo install the latest stable version, run:\n\n```shell\npip install neo4j-graphrag\n```\n\n### Optional Dependencies\n\nThis package has some optional features that can be enabled using\nthe extra dependencies described below:\n\n- LLM providers (at least one is required for RAG and KG Builder Pipeline):\n    - **ollama**: LLMs from Ollama\n    - **openai**: LLMs from OpenAI (including AzureOpenAI)\n    - **google**: LLMs from Vertex AI\n    - **cohere**: LLMs from Cohere\n    - **anthropic**: LLMs from Anthropic\n    - **mistralai**: LLMs from MistralAI\n- **sentence-transformers** : to use embeddings from the `sentence-transformers` Python package\n- Vector database (to use :ref:`External Retrievers`):\n    - **weaviate**: store vectors in Weaviate\n    - **pinecone**: store vectors in Pinecone\n    - **qdrant**: store vectors in Qdrant\n- **experimental**: experimental features mainly related to the Knowledge Graph creation pipelines.\n- **nlp**: installs spaCy for NLP pipelines, used by `SpaCySemanticMatchResolver` in the experimental KG builder components.\n- **fuzzy-matching**: installs RapidFuzz, used by `FuzzyMatchResolver` in the experimental KG builder components.\n\n\u003e Note: The **`nlp`** extra is currently **not supported on Python 3.14** due to an upstream spaCy import-time issue ([spaCy #13895](https://github.com/explosion/spaCy/issues/13895)). Use Python **3.13 or earlier** for spaCy-based features until that is resolved upstream.\n\n\nInstall package with optional dependencies with (for instance):\n\n```shell\npip install \"neo4j-graphrag[openai]\"\n```\n\n## 💻 Example Usage\n\nThe scripts below demonstrate how to get started with the package and make use of its key features.\nTo run these examples, ensure that you have a Neo4j instance up and running and update the `NEO4J_URI`, `NEO4J_USERNAME`, and `NEO4J_PASSWORD` variables in each script with the details of your Neo4j instance.\nFor the examples, make sure to export your OpenAI key as an environment variable named `OPENAI_API_KEY`.\nAdditional examples are available in the `examples` folder.\n\n### Knowledge Graph Construction\n\n**NOTE: The [APOC core library](https://neo4j.com/labs/apoc/) must be installed in your Neo4j instance in order to use this feature**\n\nThis package offers two methods for constructing a knowledge graph.\n\nThe `Pipeline` class provides extensive customization options, making it ideal for advanced use cases.\nSee the `examples/pipeline` folder for examples of how to use this class.\n\nFor a more streamlined approach, the `SimpleKGPipeline` class offers a simplified abstraction layer over the `Pipeline`, making it easier to build knowledge graphs.\nBoth classes support working directly with text and PDFs.\n\n```python\nimport asyncio\n\nfrom neo4j import GraphDatabase\nfrom neo4j_graphrag.embeddings import OpenAIEmbeddings\nfrom neo4j_graphrag.experimental.pipeline.kg_builder import SimpleKGPipeline\nfrom neo4j_graphrag.llm import OpenAILLM\n\nNEO4J_URI = \"neo4j://localhost:7687\"\nNEO4J_USERNAME = \"neo4j\"\nNEO4J_PASSWORD = \"password\"\n\n# Connect to the Neo4j database\ndriver = GraphDatabase.driver(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD))\n\n# List the entities and relations the LLM should look for in the text\nnode_types = [\"Person\", \"House\", \"Planet\"]\nrelationship_types = [\"PARENT_OF\", \"HEIR_OF\", \"RULES\"]\npatterns = [\n    (\"Person\", \"PARENT_OF\", \"Person\"),\n    (\"Person\", \"HEIR_OF\", \"House\"),\n    (\"House\", \"RULES\", \"Planet\"),\n]\n\n# Create an Embedder object\nembedder = OpenAIEmbeddings(model=\"text-embedding-3-large\")\n\n# Instantiate the LLM\nllm = OpenAILLM(\n    model_name=\"gpt-4o\",\n    model_params={\n        \"max_tokens\": 2000,\n        \"response_format\": {\"type\": \"json_object\"},\n        \"temperature\": 0,\n    },\n)\n\n# Instantiate the SimpleKGPipeline\nkg_builder = SimpleKGPipeline(\n    llm=llm,\n    driver=driver,\n    embedder=embedder,\n    schema={\n        \"node_types\": node_types,\n        \"relationship_types\": relationship_types,\n        \"patterns\": patterns,\n    },\n    on_error=\"IGNORE\",\n    from_pdf=False,\n)\n\n# Run the pipeline on a piece of text\ntext = (\n    \"The son of Duke Leto Atreides and the Lady Jessica, Paul is the heir of House \"\n    \"Atreides, an aristocratic family that rules the planet Caladan.\"\n)\nasyncio.run(kg_builder.run_async(text=text))\ndriver.close()\n```\n\n\u003e Warning: In order to run this code, the `openai` Python package needs to be installed: `pip install \"neo4j_graphrag[openai]\"`\n\n\nExample knowledge graph created using the above script:\n\n![Example knowledge graph](https://raw.githubusercontent.com/neo4j/neo4j-graphrag-python/fd276af0069e4dd1769255d358793cc96e299bf3/images/kg_construction.svg)\n\n### Creating a Vector Index\n\nWhen creating a vector index, make sure you match the number of dimensions in the index with the number of dimensions your embeddings have.\n\n```python\nfrom neo4j import GraphDatabase\nfrom neo4j_graphrag.indexes import create_vector_index\n\nNEO4J_URI = \"neo4j://localhost:7687\"\nNEO4J_USERNAME = \"neo4j\"\nNEO4J_PASSWORD = \"password\"\nINDEX_NAME = \"vector-index-name\"\n\n# Connect to the Neo4j database\ndriver = GraphDatabase.driver(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD))\n\n# Create the index\ncreate_vector_index(\n    driver,\n    INDEX_NAME,\n    label=\"Chunk\",\n    embedding_property=\"embedding\",\n    dimensions=3072,\n    similarity_fn=\"euclidean\",\n)\ndriver.close()\n```\n\n### Populating a Vector Index\n\nThis example demonstrates one method for upserting data in your Neo4j database.\nIt's important to note that there are alternative approaches, such as using the [Neo4j Python driver](https://github.com/neo4j/neo4j-python-driver).\n\nEnsure that your vector index is created prior to executing this example.\n\n```python\nfrom neo4j import GraphDatabase\nfrom neo4j_graphrag.embeddings import OpenAIEmbeddings\nfrom neo4j_graphrag.indexes import upsert_vectors\nfrom neo4j_graphrag.types import EntityType\n\nNEO4J_URI = \"neo4j://localhost:7687\"\nNEO4J_USERNAME = \"neo4j\"\nNEO4J_PASSWORD = \"password\"\n\n# Connect to the Neo4j database\ndriver = GraphDatabase.driver(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD))\n\n# Create an Embedder object\nembedder = OpenAIEmbeddings(model=\"text-embedding-3-large\")\n\n# Generate an embedding for some text\ntext = (\n    \"The son of Duke Leto Atreides and the Lady Jessica, Paul is the heir of House \"\n    \"Atreides, an aristocratic family that rules the planet Caladan.\"\n)\nvector = embedder.embed_query(text)\n\n# Upsert the vector\nupsert_vectors(\n    driver,\n    ids=[\"1234\"],\n    embedding_property=\"vectorProperty\",\n    embeddings=[vector],\n    entity_type=EntityType.NODE,\n)\ndriver.close()\n```\n\n### Performing a Similarity Search\n\nPlease note that when querying a Neo4j vector index _approximate_ nearest neighbor search is used, which may not always deliver exact results.\nFor more information, refer to the Neo4j documentation on [limitations and issues of vector indexes](https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/vector-indexes/#limitations-and-issues).\n\nIn the example below, we perform a simple vector search using a retriever that conducts a similarity search over the `vector-index-name` vector index.\n\nThis library provides more retrievers beyond just the `VectorRetriever`.\nSee the `examples` folder for examples of how to use these retrievers.\n\nBefore running this example, make sure your vector index has been created and populated.\n\n```python\nfrom neo4j import GraphDatabase\nfrom neo4j_graphrag.embeddings import OpenAIEmbeddings\nfrom neo4j_graphrag.generation import GraphRAG\nfrom neo4j_graphrag.llm import OpenAILLM\nfrom neo4j_graphrag.retrievers import VectorRetriever\n\nNEO4J_URI = \"neo4j://localhost:7687\"\nNEO4J_USERNAME = \"neo4j\"\nNEO4J_PASSWORD = \"password\"\nINDEX_NAME = \"vector-index-name\"\n\n# Connect to the Neo4j database\ndriver = GraphDatabase.driver(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD))\n\n# Create an Embedder object\nembedder = OpenAIEmbeddings(model=\"text-embedding-3-large\")\n\n# Initialize the retriever\nretriever = VectorRetriever(driver, INDEX_NAME, embedder)\n\n# Instantiate the LLM\nllm = OpenAILLM(model_name=\"gpt-4o\", model_params={\"temperature\": 0})\n\n# Instantiate the RAG pipeline\nrag = GraphRAG(retriever=retriever, llm=llm)\n\n# Query the graph\nquery_text = \"Who is Paul Atreides?\"\nresponse = rag.search(query_text=query_text, retriever_config={\"top_k\": 5})\nprint(response.answer)\ndriver.close()\n```\n\n## 🤝 Contributing\n\nYou must sign the [contributors license agreement](https://neo4j.com/developer/contributing-code/#sign-cla) in order to make contributions to this project.\n\n### Install Dependencies\n\nOur Python dependencies are managed using uv.\nIf uv is not yet installed on your system, you can follow the instructions [here](https://docs.astral.sh/uv/getting-started/installation/) to set it up.\nTo begin development on this project, start by cloning the repository and then install all necessary dependencies, including the development dependencies, with the following command:\n\n```bash\nuv sync --group dev\n```\n\n### Reporting Issues\n\nIf you have a bug to report or feature to request, first\n[search to see if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments).\nIf a related issue doesn't exist, please raise a new issue using the [issue form](https://github.com/neo4j/neo4j-graphrag-python/issues/new/choose).\n\nIf you're a Neo4j Enterprise customer, you can also reach out to [Customer Support](http://support.neo4j.com/).\n\nIf you don't have a bug to report or feature request, but you need a hand with\nthe library; community support is available via [Neo4j Online Community](https://community.neo4j.com/)\nand/or [Discord](https://discord.gg/neo4j).\n\n### Workflow for Contributions\n\n1. Fork the repository.\n2. Install Python and uv.\n3. Create a working branch from `main` and start with your changes!\n\n### Code Formatting and Linting\n\nOur codebase follows strict formatting and linting standards using [Ruff](https://docs.astral.sh/ruff/) for code quality checks and [Mypy](https://github.com/python/mypy) for type checking.\nBefore contributing, ensure that all code is properly formatted, free of linting issues, and includes accurate type annotations.\n\n- To install Ruff, follow the instructions [here](https://docs.astral.sh/ruff/installation/).\n- To set up Mypy, follow the steps outlined [here](https://mypy.readthedocs.io/en/stable/getting_started.html#installing-and-running-mypy).\n\nAdherence to these standards is required for contributions to be accepted.\n\n#### Using Pre-commit\n\nWe recommend setting up [pre-commit](https://pre-commit.com/) to automate code quality checks.\nThis ensures your changes meet our guidelines before committing.\n\n1. Install pre-commit by following the [installation guide](https://pre-commit.com/#install).\n2. Set up the pre-commit hooks by running:\n\n   ```bash\n   pre-commit install\n   ```\n\n3. To manually check if a file meets the quality requirements, run:\n\n   ```bash\n   pre-commit run --file path/to/file\n   ```\n\n### Pull Requests\n\nWhen you're finished with your changes, create a pull request (PR) using the following workflow.\n\n- Ensure you have formatted and linted your code.\n- Ensure that you have [signed the CLA](https://neo4j.com/developer/contributing-code/#sign-cla).\n- Ensure that the base of your PR is set to `main`.\n- Don't forget to [link your PR to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)\n    if you are solving one.\n- Check the checkbox to [allow maintainer edits](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)\n    so that maintainers can make any necessary tweaks and update your branch for merge.\n- Reviewers may ask for changes to be made before a PR can be merged, either using\n    [suggested changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request)\n    or normal pull request comments. You can apply suggested changes directly through\n    the UI. Any other changes can be made in your fork and committed to the PR branch.\n- As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).\n- Update the `CHANGELOG.md` if you have made significant changes to the project, these include:\n  - Major changes:\n    - New features\n    - Bug fixes with high impact\n    - Breaking changes\n  - Minor changes:\n    - Documentation improvements\n    - Code refactoring without functional impact\n    - Minor bug fixes\n- Keep `CHANGELOG.md` changes brief and focus on the most important changes.\n\n### Updating the `CHANGELOG.md`\n\n1. You can automatically generate a changelog suggestion for your PR by commenting on it [using CodiumAI](https://github.com/CodiumAI-Agent):\n\n```\n@CodiumAI-Agent /update_changelog\n```\n\n2. Edit the suggestion if necessary and update the appropriate subsection in the `CHANGELOG.md` file under 'Next'.\n3. Commit the changes.\n\n## 🧪 Tests\n\nTo be able to run all tests, all extra packages needs to be installed.\nThis is achieved by:\n\n```bash\nuv sync --all-extras\n```\n\n### Unit Tests\n\nInstall the project dependencies then run the following command to run the unit tests locally:\n\n```bash\nuv run pytest tests/unit\n```\n\n### E2E tests\n\nTo execute end-to-end (e2e) tests, you need the following services to be running locally:\n\n- neo4j\n- weaviate\n- weaviate-text2vec-transformers\n\nThe simplest way to set these up is by using Docker Compose:\n\n```bash\ndocker compose -f tests/e2e/docker-compose.yml up\n```\n\n_(tip: If you encounter any caching issues within the databases, you can completely remove them by running `docker compose -f tests/e2e/docker-compose.yml down`)_\n\nOnce all the services are running, execute the following command to run the e2e tests:\n\n```bash\nuv run pytest tests/e2e\n```\n\n## ℹ️ Additional Information\n\n- [The official Neo4j Python driver](https://github.com/neo4j/neo4j-python-driver)\n- [Neo4j GenAI integrations](https://neo4j.com/docs/cypher-manual/current/genai-integrations/)\n","funding_links":[],"categories":["LLM Frameworks","Python","Software"],"sub_categories":["RAG"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneo4j%2Fneo4j-graphrag-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneo4j%2Fneo4j-graphrag-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneo4j%2Fneo4j-graphrag-python/lists"}