Architecture

GraphRAG SDK v2 follows a strategy-based pipeline architecture. Every algorithmic concern is an abstract base class (ABC) with swappable implementations. The system has two main flows: ingestion (document to knowledge graph) and retrieval (question to answer).

Design Principles

• Strategy Modularity -- Every pipeline step is an ABC. Swap any implementation without touching other code.
• Zero-Loss Data -- Full provenance chain from raw text to graph nodes (Document -> Chunk -> Entity).
• Production Latency -- Async-first, connection pooling, batched writes, parallel pipeline steps.
• Simplicity -- Single entry point (GraphRAG), flat package structure, no meta-programming.

Ingestion Pipeline

The ingestion pipeline transforms documents into a knowledge graph in 9 steps. Steps 1-7 run sequentially (each depends on the previous), steps 8-9 run in parallel.

                    Sequential                              Parallel
  ┌──────────────────────────────────────────┐    ┌──────────────────────┐
  │ 1.Load  2.Chunk  3.Lexical  4.Extract    │    │ 8. Mentions          │
  │ 5.Prune  6.Resolve  7.Write             │──>│ 9. Index Chunks      │
  └──────────────────────────────────────────┘    └──────────────────────┘

Step-by-Step

Step	Name	What it does	Strategy ABC
1	Load	Reads raw text from a source (file, URL, raw string)	LoaderStrategy
2	Chunk	Splits text into overlapping windows	ChunkingStrategy
3	Lexical Graph	Creates Document and Chunk nodes with PART_OF and NEXT_CHUNK edges (provenance chain)	Built-in
4	Extract	LLM extracts entities, relationships, and mentions from each chunk	ExtractionStrategy
5	Prune	Filters extracted data against the schema (removes off-schema entities/relationships)	Built-in
6	Resolve	Deduplicates entities (exact match or LLM-assisted description merge)	ResolutionStrategy
7	Write	Batched MERGE of nodes and relationships into FalkorDB	Built-in
8	Mentions	Writes MENTIONED_IN edges linking entities to their source chunks	Built-in (parallel)
9	Index Chunks	Embeds chunk text and stores vector embeddings on Chunk nodes	Built-in (parallel)

Data Flow

str (raw text)
  -> DocumentOutput (text + metadata)
    -> TextChunks (list of TextChunk with uid, text, index)
      -> GraphData (nodes + relationships extracted by LLM)
        -> ResolutionResult (deduplicated nodes + remapped relationships)
          -> FalkorDB (MERGE via GraphStore + vector index via VectorStore)

Graph Schema

The knowledge graph contains these node types and edge types:

Node Labels

Label	Purpose	Has Embedding
Document	Source document metadata	No
Chunk	Text chunk (fragment of a document)	Yes
__Entity__	Secondary label on all extracted entities	Yes (after backfill)
Person, Organization, etc.	Primary entity labels — 11 defaults: Person, Organization, Technology, Product, Location, Date, Event, Concept, Law, Dataset, Method	Via __Entity__

Edge Types

Type	Source -> Target	Purpose
PART_OF	Document -> Chunk	Provenance: which document a chunk came from
NEXT_CHUNK	Chunk -> Chunk	Sequential ordering of chunks
MENTIONED_IN	Entity -> Chunk	Which chunks mention an entity
RELATES	Entity -> Entity	All extracted relationships (single edge type)

All LLM-extracted relationships use the single RELATES edge type. The original relationship type (e.g. WORKS_AT, LOCATED_IN) is preserved as the rel_type property on the edge. A fact property stores a human-readable fact string for embedding.

Post-ingestion: Entity Deduplication

Entity deduplication is handled post-ingestion via deduplicate_entities() rather than during the pipeline. This allows ingesting multiple documents independently, then deduplicating globally. The method groups entities by (normalized name, label) to prevent cross-type merging (e.g. Person "Paris" and Location "Paris" remain separate).

Retrieval Flow

The retrieval system answers questions by searching the knowledge graph through multiple paths, then generating an answer with the LLM.

Question
  |
  v
Keyword Extraction (LLM)
  |
  v
Embed Question (single API call)
  |
  ├── RELATES Edge Vector Search ────────────────────────────┐
  │   -> fact strings + entity entry points                  │
  │                                                          │
  ├── 2-Path Entity Discovery ──────────────────────────────┤
  │   1. Cypher CONTAINS substring match                     │
  │   2. Fulltext search on entity index                     │
  │   + merge entities from RELATES vector search            │
  │                                                          v
  │                                              Top entities (scored + deduped)
  │                                                         |
  │                                              2-Hop Relationship Expansion
  │                                              (1-hop + 2-hop from top entities)
  │                                                         |
  ├── 4-Path Chunk Retrieval ───────────────────────────────┤
  │   1. Fulltext search in chunks                           │
  │   2. Vector search in chunks                             │
  │   3. MENTIONED_IN traversal (entity -> chunk)            │
  │   4. 2-hop: entity -> neighbor -> chunk                  │
  │                                                          v
  │                                              Candidate chunks (cosine reranked)
  │                                                         |
  └──────────────────────────────> Context Assembly
                                    (hint, entities, relationships, facts, passages)
                                          |
                                          v
                                    LLM Generation (RAG prompt)
                                          |
                                          v
                                       Answer

MultiPathRetrieval Parameters

Parameter	Default	Purpose
chunk_top_k	15	Final chunks after reranking
max_entities	30	Total entity cap across all paths
max_relationships	20	Max relationships in context
rel_top_k	15	RELATES edge vector search results
keyword_limit	10	Max keywords extracted from question

Storage Layer

GraphStore

All graph writes go through GraphStore, which provides:

• Batched UNWIND upserts -- 500 nodes/relationships per batch
• Label hints -- relationship MATCH queries use label hints (e.g., MENTIONED_IN matches __Entity__ -> Chunk) for faster lookups
• Per-item fallback -- if a batch fails, retries individual items
• None-id guard -- filters out entities with None/empty IDs (bad LLM extraction)

VectorStore

Vector operations go through VectorStore:

• Index creation -- CREATE VECTOR INDEX for Chunk and Entity embeddings, plus RELATES edge embeddings
• Fulltext index -- for keyword search on chunk text and entity names
• Batched embedding -- embeds texts in bulk, stores via UNWIND
• Search -- db.idx.vector.queryNodes for similarity search

Extending the SDK

To add a custom strategy, subclass the relevant ABC:

from graphrag_sdk import ChunkingStrategy, TextChunks
from graphrag_sdk.core.context import Context

class SemanticChunking(ChunkingStrategy):
    async def chunk(self, text: str, ctx: Context) -> TextChunks:
        # Your implementation here
        ...

Then pass it to ingest():

await rag.ingest("doc.txt", chunker=SemanticChunking())

The same pattern applies to all 6 strategy ABCs: LoaderStrategy, ChunkingStrategy, ExtractionStrategy, ResolutionStrategy, RetrievalStrategy, RerankingStrategy.

Deep Dives

Each subsystem has a dedicated document with step-by-step explanations:

• Ingestion Pipeline — the 9-step pipeline from document to knowledge graph
• Extraction — the 2-step hybrid extraction process (NER + LLM)
• Graph Schema — how the knowledge graph is structured in FalkorDB
• Storage — GraphStore, VectorStore, and EntityDeduplicator internals
• Retrieval — the multi-path retrieval system that answers questions