# neo4j/neo4j-graphrag-python architecture

> Architecture diagram of the GitHub repository neo4j/neo4j-graphrag-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neo4j/neo4j-graphrag-python
- Repository: https://github.com/neo4j/neo4j-graphrag-python

## Overview

##### Project type and purpose
- This is not a web front-end/backend application but a Python SDK/library (“neo4j-graphrag”) that enables developers to build Graph Retrieval-Augmented Generation (GraphRAG) applications.
- It provides two major feature sets:
- Knowledge Graph construction pipelines (SimpleKGPipeline & customizable Pipeline)
- Retrieval and RAG generation (Vector/Hybrid/Text2Cypher retrievers + GraphRAG generator)
- It integrates with Neo4j (graph database), external vector stores (Weaviate, Pinecone, Qdrant), and LLM providers (OpenAI, Anthropic, Cohere, Vertex AI, Mistral, Ollama).

##### File structure
- Top-level “src/neo4j_graphrag” holds the production library code, organized by functionality:
- embeddings/ – pluggable embedder adapters
- llm/ – pluggable LLM adapters
- retrievers/ – Vector, Hybrid, Text2Cypher, External store integrations
- generation/ – GraphRAG orchestration that receives retrieved context + LLM
- experimental/pipeline/ – fully configurable pipeline engine: components, config reader, orchestrator, notifications
- indexes.py – create / upsert Neo4j vector indexes
- schema.py, filters.py, neo4j_queries.py – domain logic for graph operations
- Tests are split into unit (per-module) and e2e (requiring Neo4j + optional vector DBs).
- Examples folder demonstrates usage patterns.

##### README for additional insights
- Confirms core abstractions: SimpleKGPipeline vs. Pipeline, retrievers, GraphRAG class.
- Emphasizes external dependencies: Neo4j driver, LLM providers, optional vector DB clients.
- Shows sample flows:
a) Build KG: text → embedder → pipeline components → Neo4j write
b) Create/populate vector index: Neo4j index APIs
c) Retrieve & answer: query → retriever → GraphRAG → LLM → answer

##### Final reminder
Be detailed: include every major module, component family, and external integration. Don’t overthink—separate the library into its logical sub-systems (Pipeline, Embeddings, LLM, Retrievers, Indexing, EG storage, Generation) and map out how they connect to Neo4j, vector DBs, and LLM APIs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Client("Client Script"):::client
        ConfigFile("Pipeline Config (YAML/JSON)"):::client
    end

    %% Library Core
    subgraph "neo4j-graphrag Library" 
        direction TB
        subgraph "Pipeline"
            direction TB
            SimpleKGPipeline["SimpleKGPipeline API"]:::core
            PipelineEngine["Pipeline Engine"]:::core
            ConfigReader["Configuration Reader"]:::core
            PipelineConfig["Pipeline Config Models"]:::core
            Notifications["Notifications"]:::core
        end
        subgraph "Experimental Components"
            direction TB
            Loader["PDF/Text Loader"]:::core
            Splitter["Text Splitter"]:::core
            Extractor["Entity/Relation Extractor"]:::core
            Resolver["Lexical Graph Builder"]:::core
            KGWriter["KG Writer"]:::core
            Neo4jReader["Neo4j Reader"]:::core
        end
        subgraph "Core Modules"
            direction TB
            Embeddings["Embeddings Module"]:::core
            LLM["LLM Module"]:::core
            Retrievers["Retrievers Module"]:::core
            GraphRAG["GraphRAG Generator"]:::core
            IndexUtils["Index Utilities"]:::core
            DomainLogic["Domain Logic"]:::core
            Utils["Utilities"]:::core
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Neo4jDB["Neo4j Database"]:::external
        subgraph "Vector Stores"
            direction TB
            Weaviate["Weaviate"]:::external
            Pinecone["Pinecone"]:::external
            Qdrant["Qdrant"]:::external
        end
        subgraph "LLM APIs"
            direction TB
            OpenAI["OpenAI"]:::external
            Anthropic["Anthropic"]:::external
            Cohere["Cohere"]:::external
            VertexAI["Vertex AI"]:::external
            Mistral["Mistral"]:::external
            Ollama["Ollama"]:::external
        end
    end

    %% Data Flows
    Client -->|calls| SimpleKGPipeline
    Client -->|calls| PipelineEngine
    SimpleKGPipeline -->|uses| PipelineEngine
    PipelineEngine -->|loads| ConfigReader
    PipelineEngine -->|reads| PipelineConfig
    PipelineEngine -->|sends notifications to| Notifications
    PipelineEngine -->|orchestrates| Loader
    PipelineEngine -->|orchestrates| Splitter
    PipelineEngine -->|orchestrates| Extractor
    PipelineEngine -->|orchestrates| Resolver
    PipelineEngine -->|orchestrates| KGWriter
    PipelineEngine -->|orchestrates| Neo4jReader

    Loader -->|outputs text| Splitter
    Splitter -->|chunks| Extractor
    Extractor -->|entities/relations| Resolver
    Resolver -->|graph| KGWriter
    KGWriter -->|writes| Neo4jDB
    Neo4jReader -->|reads| Neo4jDB

    Client -->|calls| IndexUtils
    IndexUtils -->|creates/upserts| Neo4jDB

    Client -->|calls| GraphRAG
    GraphRAG -->|uses retriever| Retrievers
    Retrievers -->|vector/cypher queries| Neo4jDB
    Retrievers -->|vector queries| Weaviate
    Retrievers -->|vector queries| Pinecone
    Retrievers -->|vector queries| Qdrant
    Retrievers -->|delegates embed| Embeddings
    GraphRAG -->|delegates llm| LLM

    Embeddings -->|calls| OpenAI
    Embeddings -->|calls| Anthropic
    Embeddings -->|calls| Cohere
    Embeddings -->|calls| VertexAI
    Embeddings -->|calls| Mistral
    Embeddings -->|calls| Ollama

    LLM -->|calls| OpenAI
    LLM -->|calls| Anthropic
    LLM -->|calls| Cohere
    LLM -->|calls| VertexAI
    LLM -->|calls| Mistral
    LLM -->|calls| Ollama

    %% Click Events
    click PipelineEngine "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/orchestrator.py"
    click PipelineEngine "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/pipeline.py"
    click SimpleKGPipeline "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/config/template_pipeline/simple_kg_builder.py"
    click Embeddings "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/embeddings/base.py"
    click Embeddings "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/embeddings/cohere.py"
    click Embeddings "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/embeddings/mistral.py"
    click Embeddings "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/embeddings/ollama.py"
    click Embeddings "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/embeddings/openai.py"
    click Embeddings "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/embeddings/sentence_transformers.py"
    click Embeddings "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/embeddings/vertexai.py"
    click LLM "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/llm/base.py"
    click LLM "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/llm/anthropic_llm.py"
    click LLM "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/llm/cohere_llm.py"
    click LLM "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/llm/mistralai_llm.py"
    click LLM "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/llm/ollama_llm.py"
    click LLM "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/llm/openai_llm.py"
    click LLM "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/llm/vertexai_llm.py"
    click Retrievers "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/vector.py"
    click Retrievers "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/hybrid.py"
    click Retrievers "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/text2cypher.py"
    click Retrievers "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/external/pinecone/pinecone.py"
    click Retrievers "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/external/qdrant/qdrant.py"
    click Retrievers "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/external/weaviate/weaviate.py"
    click GraphRAG "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/generation/graphrag.py"
    click IndexUtils "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/indexes.py"
    click DomainLogic "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/schema.py"
    click DomainLogic "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/filters.py"
    click DomainLogic "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/neo4j_queries.py"
    click Loader "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/components/pdf_loader.py"
    click Splitter "https://github.com/neo4j/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/experimental/components/text_splitters"
    click Extractor "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/components/entity_relation_extractor.py"
    click Resolver "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/components/lexical_graph.py"
    click KGWriter "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/components/kg_writer.py"
    click Neo4jReader "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/components/neo4j_reader.py"
    click ConfigReader "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/config/config_reader.py"
    click PipelineConfig "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/config/pipeline_config.py"
    click Notifications "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/notification.py"
    click Utils "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/utils/driver_config.py"
    click Utils "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/utils/logging.py"
    click Utils "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/utils/validation.py"
    click Utils "https://github.com/neo4j/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/utils/version_utils.py"

    %% Styles
    classDef core fill:#CFE2F3,stroke:#318CE7,stroke-width:1px
    classDef external fill:#D5E8D4,stroke:#82B366,stroke-width:1px
    classDef client fill:#FFE6CC,stroke:#D99011,stroke-width:1px
```
