# tomasonjo/neo4j-graphrag-python architecture

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

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

## Overview

Neo4j GraphRAG is a Python library for building knowledge graphs and using graph-aware retrieval to ground generated answers. The main user path is query → retrieval → context-augmented generation. A separate construction path turns text or PDFs into graph data; the README identifies both a configurable pipeline and a simpler builder. The package also exposes vector-index management, multiple retrieval strategies, external vector-store retrievers, and provider adapters. Several implementation details are unsampled, so the graph shows documented capabilities but omits uncertain internal wiring.

Main entry points: [`src/neo4j_graphrag/experimental/pipeline/kg_builder.py`](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/kg_builder.py) (Simple KG builder), [`src/neo4j_graphrag/llm`](https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/llm) (LLM adapters), [`src/neo4j_graphrag/retrievers/tools_retriever.py`](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/tools_retriever.py) (Tools retriever), [`src/neo4j_graphrag/generation/graphrag.py`](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/generation/graphrag.py) (GraphRAG search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_construction["Graph construction"]
  node_simple_kg["Simple KG builder<br/>[kg_builder.py]"]
  node_loaders["Text and PDF loaders"]
  node_splitters["Text splitters"]
  node_extractor["Entity extraction"]
  node_resolver["Entity resolution<br/>[resolver.py]"]
  node_kg_writer["Graph writer<br/>[kg_writer.py]"]
end

subgraph group_retrieval["Retrieval"]
  node_index_api["Vector index API<br/>[indexes.py]"]
  node_retrievers["Neo4j retrievers"]
  node_external_retrievers["External vector retrievers"]
  node_tools_retriever["Tools retriever<br/>[tools_retriever.py]"]
end

subgraph group_generation["Answer generation"]
  node_graph_rag["GraphRAG search<br/>[graphrag.py]"]
end

subgraph group_integrations["Model integrations"]
  node_llm_api["LLM adapters"]
  node_embedding_api["Embedding adapters"]
end

subgraph group_pipeline["Pipeline runtime"]
  node_exp_pipeline["Pipeline engine<br/>[pipeline.py]"]
  node_component_tasks["Component tasks<br/>[component.py]"]
end

node_developer(("Application developer"))
node_query_user(("Questioner"))
node_neo4j[("Neo4j database")]
node_llm_provider["LLM provider"]
node_embedding_provider["Embedding provider"]
node_external_vector_store[("External vector store")]

node_developer -->|"configures build"| node_simple_kg
node_developer -->|"creates index"| node_index_api
node_simple_kg -->|"runs pipeline"| node_exp_pipeline
node_exp_pipeline -->|"executes tasks"| node_component_tasks
node_simple_kg -->|"accepts text or PDF"| node_loaders
node_simple_kg -->|"builds graph"| node_neo4j
node_simple_kg -->|"uses model"| node_llm_api
node_simple_kg -->|"uses embedder"| node_embedding_api
node_loaders -->|"splits text"| node_splitters
node_splitters -->|"provides chunks"| node_extractor
node_extractor -->|"extracts entities"| node_resolver
node_resolver -->|"resolves entities"| node_kg_writer
node_kg_writer -->|"writes graph"| node_neo4j
node_query_user -->|"asks question"| node_graph_rag
node_graph_rag -->|"retrieves context"| node_retrievers
node_retrievers -->|"queries graph"| node_neo4j
node_graph_rag -->|"generates answer"| node_llm_api
node_llm_api -.->|"calls model"| node_llm_provider
node_embedding_api -.->|"requests vectors"| node_embedding_provider
node_index_api -->|"creates index"| node_neo4j
node_developer -->|"configures retrieval"| node_external_retrievers
node_external_retrievers -.->|"searches vectors"| node_external_vector_store
node_developer -->|"configures tools"| node_tools_retriever
node_tools_retriever -->|"selects tools"| node_llm_api
node_tools_retriever -->|"runs selected tools"| node_neo4j

click node_simple_kg "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/kg_builder.py"
click node_exp_pipeline "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/pipeline.py"
click node_component_tasks "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/component.py"
click node_loaders "https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/components"
click node_splitters "https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/components/text_splitters"
click node_extractor "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/components/entity_relation_extractor.py"
click node_resolver "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/components/resolver.py"
click node_kg_writer "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/components/kg_writer.py"
click node_index_api "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/indexes.py"
click node_retrievers "https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/retrievers"
click node_external_retrievers "https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/retrievers/external"
click node_tools_retriever "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/tools_retriever.py"
click node_graph_rag "https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/generation/graphrag.py"
click node_llm_api "https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/llm"
click node_embedding_api "https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/embeddings"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_simple_kg,node_loaders,node_splitters,node_extractor,node_resolver,node_kg_writer toneBlue
class node_index_api,node_retrievers,node_external_retrievers,node_tools_retriever,node_neo4j,node_external_vector_store toneAmber
class node_graph_rag toneMint
class node_llm_api,node_embedding_api toneRose
class node_exp_pipeline,node_component_tasks,node_developer,node_query_user,node_llm_provider,node_embedding_provider toneIndigo
```

## Components

### Graph construction

- [Simple KG builder](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/kg_builder.py): `src/neo4j_graphrag/experimental/pipeline/kg_builder.py`
- [Text and PDF loaders](https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/components): `src/neo4j_graphrag/components`
- [Text splitters](https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/components/text_splitters): `src/neo4j_graphrag/components/text_splitters`
- [Entity extraction](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/components/entity_relation_extractor.py): `src/neo4j_graphrag/components/entity_relation_extractor.py`
- [Entity resolution](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/components/resolver.py): `src/neo4j_graphrag/components/resolver.py`
- [Graph writer](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/components/kg_writer.py): `src/neo4j_graphrag/components/kg_writer.py`

### Retrieval

- [Vector index API](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/indexes.py): `src/neo4j_graphrag/indexes.py`
- [Neo4j retrievers](https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/retrievers): `src/neo4j_graphrag/retrievers`
- [External vector retrievers](https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/retrievers/external): `src/neo4j_graphrag/retrievers/external`
- [Tools retriever](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/retrievers/tools_retriever.py): `src/neo4j_graphrag/retrievers/tools_retriever.py`

### Answer generation

- [GraphRAG search](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/generation/graphrag.py): `src/neo4j_graphrag/generation/graphrag.py`

### Model integrations

- [LLM adapters](https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/llm): `src/neo4j_graphrag/llm`
- [Embedding adapters](https://github.com/tomasonjo/neo4j-graphrag-python/tree/main/src/neo4j_graphrag/embeddings): `src/neo4j_graphrag/embeddings`

### Pipeline runtime

- [Pipeline engine](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/pipeline.py): `src/neo4j_graphrag/experimental/pipeline/pipeline.py`
- [Component tasks](https://github.com/tomasonjo/neo4j-graphrag-python/blob/main/src/neo4j_graphrag/experimental/pipeline/component.py): `src/neo4j_graphrag/experimental/pipeline/component.py`

### Other components

- **Application developer**
- **Questioner**
- **Neo4j database**
- **LLM provider**
- **Embedding provider**
- **External vector store**

## Connections

- Application developer → Simple KG builder: configures build
- Application developer → Vector index API: creates index
- Simple KG builder → Pipeline engine: runs pipeline
- Pipeline engine → Component tasks: executes tasks
- Simple KG builder → Text and PDF loaders: accepts text or PDF
- Simple KG builder → Neo4j database: builds graph
- Simple KG builder → LLM adapters: uses model
- Simple KG builder → Embedding adapters: uses embedder
- Text and PDF loaders → Text splitters: splits text
- Text splitters → Entity extraction: provides chunks
- Entity extraction → Entity resolution: extracts entities
- Entity resolution → Graph writer: resolves entities
- Graph writer → Neo4j database: writes graph
- Questioner → GraphRAG search: asks question
- GraphRAG search → Neo4j retrievers: retrieves context
- Neo4j retrievers → Neo4j database: queries graph
- GraphRAG search → LLM adapters: generates answer
- LLM adapters → LLM provider: calls model
- Embedding adapters → Embedding provider: requests vectors
- Vector index API → Neo4j database: creates index
- Application developer → External vector retrievers: configures retrieval
- External vector retrievers → External vector store: searches vectors
- Application developer → Tools retriever: configures tools
- Tools retriever → LLM adapters: selects tools
- Tools retriever → Neo4j database: runs selected tools