Strategy Reference

GraphRAG SDK uses the Strategy pattern for every algorithmic concern. Each concern has an abstract base class (ABC) with one or more built-in implementations. You can swap any implementation or write your own.

Overview

#	Concern	ABC	Built-in Implementations
1	Loading	`LoaderStrategy`	`TextLoader`, `PdfLoader`, `MarkdownLoader`
2	Chunking	`ChunkingStrategy`	`FixedSizeChunking`, `SentenceTokenCapChunking`, `ContextualChunking`, `CallableChunking`, `StructuralChunking`
3	Extraction	`ExtractionStrategy`	`GraphExtraction`
4	Resolution	`ResolutionStrategy`	`ExactMatchResolution`, `LLMVerifiedResolution`
5	Retrieval	`RetrievalStrategy`	`LocalRetrieval`, `MultiPathRetrieval`
6	Reranking	`RerankingStrategy`	`CosineReranker`

1. LoaderStrategy

Reads raw text from a data source.

ABC

from graphrag_sdk import LoaderStrategy

class LoaderStrategy(ABC):
    @abstractmethod
    async def load(self, source: str, ctx: Context) -> DocumentOutput:
        """Load text from the given source identifier."""
        ...

Built-in: TextLoader

Reads plain text and markdown files.

from graphrag_sdk.ingestion.loaders.text_loader import TextLoader

loader = TextLoader(encoding="utf-8")  # default encoding

Built-in: PdfLoader

Extracts text from PDF files. Requires pip install graphrag-sdk[pdf].

from graphrag_sdk.ingestion.loaders.pdf_loader import PdfLoader

loader = PdfLoader()

Built-in: MarkdownLoader

Extracts text from Markdown files. Requires pip install graphrag-sdk[markdown].

from graphrag_sdk.ingestion.loaders.markdown_loader import MarkdownLoader

loader = MarkdownLoader()

Design Note: Markup Preservation For complex elements like tables, lists, and code blocks, MarkdownLoader intentionally outputs the raw markdown source (including pipes |, list dashes -, and code fences) rather than stripping the syntax. While this introduces minor syntax “noise”, it preserves critical structural cues (such as spatial column alignment and nested indentation) that the LLM requires during the Extraction phase to accurately parse relational data.

Default Behavior

If no loader is specified in ingest():

.pdf files use PdfLoader
.md files use MarkdownLoader
Everything else uses TextLoader
If text= is passed directly, the loader is skipped

Writing Your Own

class HtmlLoader(LoaderStrategy):
    async def load(self, source: str, ctx: Context) -> DocumentOutput:
        from bs4 import BeautifulSoup
        with open(source) as f:
            soup = BeautifulSoup(f.read(), "html.parser")
        return DocumentOutput(text=soup.get_text())

await rag.ingest("page.html", loader=HtmlLoader())

2. ChunkingStrategy

Splits document text into overlapping chunks for processing.

ABC

from graphrag_sdk import ChunkingStrategy

class ChunkingStrategy(ABC):
    @abstractmethod
    async def chunk(self, text: str, ctx: Context) -> TextChunks:
        """Split text into chunks."""
        ...

Built-in: FixedSizeChunking

Fixed-size character windows with configurable overlap.

from graphrag_sdk.ingestion.chunking_strategies.fixed_size import FixedSizeChunking

chunker = FixedSizeChunking(
    chunk_size=1000,    # characters per chunk (default: 1000)
    chunk_overlap=100,  # overlap between chunks (default: 100)
)

Tuning guidance:

Default (1000/100) works well for general use
Benchmark-winning config uses 1500/200 for richer extraction context
Smaller chunks (500) for fine-grained retrieval, larger (2000) for broader context

Built-in: SentenceTokenCapChunking

Splits at sentence boundaries (never mid-sentence) and enforces a hard token cap per chunk using tiktoken. No LLM or embedder required.

from graphrag_sdk.ingestion.chunking_strategies.sentence_token_cap import SentenceTokenCapChunking

chunker = SentenceTokenCapChunking(
    max_tokens=384,         # max tokens per chunk (default: 384)
    overlap_sentences=2,    # sentences shared between chunks (default: 2)
    encoding_name="cl100k_base",  # tiktoken encoding (default: cl100k_base)
)

Built-in: ContextualChunking

Sentence-boundary chunking with LLM-generated context prefixes prepended to each chunk (Anthropic’s contextual retrieval approach). Improves retrieval for cross-chunk co-reference questions.

from graphrag_sdk.ingestion.chunking_strategies.contextual_chunking import ContextualChunking

chunker = ContextualChunking(
    llm=my_llm,
    max_tokens=384,              # token cap per chunk (default: 384)
    overlap_sentences=2,         # sentence overlap (default: 2)
    max_document_tokens=16_000,  # truncation limit for the doc reference in prompts (default: 16000)
)

Cost note: generates one LLM call per chunk at ingestion time.

Built-in: CallableChunking (bring your own framework)

Adapts any text -> list[str] function into a chunking strategy. Use this to plug in any chunking library — LlamaIndex, LangChain, Unstructured, spaCy, or your own logic — without the SDK carrying those dependencies. Works with sync functions, async functions, and callable classes.

from graphrag_sdk.ingestion.chunking_strategies.callable_chunking import CallableChunking

# Plain function
chunker = CallableChunking(lambda text: text.split("\n\n"))

Built-in: StructuralChunking

Groups content by heading hierarchy into token-bounded chunks. Each chunk stores a breadcrumbs metadata field that is written as a property on the Chunk node in the knowledge graph, making section paths directly queryable via Cypher.

from graphrag_sdk.ingestion.chunking_strategies.structural_chunking import StructuralChunking

chunker = StructuralChunking(
    max_tokens=384,  # max tokens per chunk (default: 384)
    overlap_sentences=2,  # sentences shared between chunks (default: 2)
)

Design Features:

Strict Fallback Configuration: If you supply a custom fallback_chunker (to handle elements that individually exceed max_tokens), you cannot pass shorthand arguments like overlap_sentences or encoding_name to StructuralChunking. Those must be configured directly on your custom fallback chunker instance. This prevents configuration parameters from being silently dropped.
Deep-Tree Resilience: While loaders like MarkdownLoader produce flat element lists, the internal _flatten algorithm uses a recursive DFS approach. This guarantees future compatibility with highly nested DOM structures (like HTML or DOCX parsers) while preserving full hierarchical breadcrumbs.
Graceful Raw Text Fallback: Designed to compose safely with any loader. If the preceding loader does not extract structural AST elements (e.g., PdfLoader or TextLoader which output elements=None), the chunker gracefully bypasses its structural logic and delegates the entire raw text to the fallback chunker, without crashing or dropping content.

Writing Your Own

class SentenceChunking(ChunkingStrategy):
    async def chunk(self, text: str, ctx: Context) -> TextChunks:
        import nltk
        sentences = nltk.sent_tokenize(text)
        chunks = []
        for i, sent in enumerate(sentences):
            chunks.append(TextChunk(text=sent, index=i))
        return TextChunks(chunks=chunks)

3. ExtractionStrategy

Extracts entities, relationships, and entity mentions from text chunks.

ABC

from graphrag_sdk import ExtractionStrategy

class ExtractionStrategy(ABC):
    @abstractmethod
    async def extract(
        self,
        chunks: TextChunks,
        schema: GraphSchema,
        ctx: Context,
    ) -> GraphData:
        """Extract graph data from text chunks."""
        ...

Built-in: GraphExtraction

Composable 2-step extraction with pluggable entity NER and LLM relationship extraction. Step 1 — Entity NER (pluggable via EntityExtractor ABC):

GLiNERExtractor (default): Local GLiNER transformer model, no API calls. Returns typed entities with confidence scores and character spans.
LLMExtractor: Uses a structured NER prompt. Returns entities with confidence, spans, and descriptions.
Custom: Subclass EntityExtractor and implement extract_entities().

Step 2 — LLM Verify + Relationship Extraction: The LLM receives the pre-extracted entities and original text, verifies entities (removes invalid, adds missed), and extracts relationships with descriptions, keywords, confidence, and evidence spans. Entity Ontology: Every extracted entity is mapped to a known type from the ontology. Entities that don’t match any type are labeled "Unknown". There are three ways to define the ontology: 1. Use the defaults (11 built-in types, good for general use):

from graphrag_sdk import GraphExtraction

# Uses: Person, Organization, Technology, Product, Location, Date,
#       Event, Concept, Law, Dataset, Method
extractor = GraphExtraction(llm=llm)

2. Pass entity_types directly (overrides defaults completely):

# Biomedical domain
extractor = GraphExtraction(
    llm=llm,
    entity_types=["Gene", "Protein", "Disease", "Drug", "Pathway"],
)

# Legal domain
extractor = GraphExtraction(
    llm=llm,
    entity_types=["Person", "Organization", "Law", "Court", "Jurisdiction", "Date"],
)

3. Use GraphSchema entities (schema types override both defaults and entity_types):

from graphrag_sdk import GraphRAG, GraphSchema, EntityType

schema = GraphSchema(entities=[
    EntityType(label="Vehicle", description="Cars, trucks, etc."),
    EntityType(label="Road", description="Streets, highways, etc."),
    EntityType(label="Location", description="Cities, countries, etc."),
])

# Schema entity types are automatically used for extraction
rag = GraphRAG(connection=conn, llm=llm, embedder=embedder, schema=schema)
await rag.ingest("traffic_report.txt")
# Extraction uses: ["Vehicle", "Road", "Location"]

The priority order is: schema.entities > entity_types parameter > defaults. Default entity types: Person, Organization, Technology, Product, Location, Date, Event, Concept, Law, Dataset, Method.

Choosing an Entity Extractor

from graphrag_sdk import GraphExtraction, GLiNERExtractor, LLMExtractor

# Default: GLiNER for step 1, LLM for step 2
extractor = GraphExtraction(llm=llm)

# Use LLM for step 1 instead of GLiNER
extractor = GraphExtraction(
    llm=llm,
    entity_extractor=LLMExtractor(llm),
)

# GLiNER with custom threshold. Spans scoring in the band just below it
# (here 0.45–0.6) are kept as "Unknown" for the step-2 LLM to re-type or
# drop; pass candidate_threshold=None to discard them instead.
extractor = GraphExtraction(
    llm=llm,
    entity_extractor=GLiNERExtractor(threshold=0.6),
)

# With coreference resolution
from graphrag_sdk import FastCorefResolver

extractor = GraphExtraction(
    llm=llm,
    coref_resolver=FastCorefResolver(),  # pip install graphrag-sdk[fastcoref]
)

Entity Extractors:

Class	Description	Parameters
`GLiNERExtractor`	Local GLiNER model (default, no API calls)	`threshold=None` (per-model default, 0.75 for `urchade/gliner_medium-v2.1`), `model_name=None` (`urchade/gliner_medium-v2.1`), `candidate_threshold` (default 25 % below `threshold`), `window_tokens=None`, `window_overlap=48`
`LLMExtractor`	LLM-based NER via structured prompt	`llm` (required), `threshold=0.75`
Custom subclass	Your own `EntityExtractor` subclass	Implement `extract_entities()`

Both extractors use threshold as the confidence cut-off for a typed entity, but they treat spans below it differently. LLMExtractor keeps every span it is given and labels those with confidence below threshold as "Unknown". GLiNERExtractor only keeps spans down to candidate_threshold (by default 25 % under threshold) — those in that band are labeled "Unknown" and handed to step 2, and anything lower is discarded inside the model and never reaches the pipeline; see Extraction for details. Graph output:

All relationships use RELATES edge type. The original type (e.g. WORKS_AT) is in properties["rel_type"].
Entity IDs are type-qualified: compute_entity_id("Paris", "Location") -> "paris__location".
Character spans stored as properties["spans"] = {chunk_id: [{start, end}]} on both entities and relationships.
Entity mentions (MENTIONED_IN edges) link entities to source chunks.

Writing Your Own Entity Extractor

Subclass EntityExtractor and implement extract_entities():

from graphrag_sdk import EntityExtractor, GraphExtraction
from graphrag_sdk.core.models import ExtractedEntity

class SpaCyExtractor(EntityExtractor):
    def __init__(self, model_name="en_core_web_sm"):
        import spacy
        self._nlp = spacy.load(model_name)

    async def extract_entities(self, text, entity_types, source_chunk_id):
        import asyncio
        doc = await asyncio.to_thread(self._nlp, text)
        return [
            ExtractedEntity(
                name=ent.text,
                type=ent.label_,
                description="",
                source_chunk_ids=[source_chunk_id],
                spans={source_chunk_id: [{"start": ent.start_char, "end": ent.end_char}]},
            )
            for ent in doc.ents
        ]

# Use it
extractor = GraphExtraction(llm=llm, entity_extractor=SpaCyExtractor())
await rag.ingest("doc.txt", extractor=extractor)

Writing Your Own Extraction Strategy

Replace the entire 2-step pipeline by subclassing ExtractionStrategy:

class MyExtraction(ExtractionStrategy):
    async def extract(self, chunks, schema, ctx):
        nodes, rels = [], []
        for chunk in chunks.chunks:
            # Your extraction logic
            ...
        return GraphData(nodes=nodes, relationships=rels)

await rag.ingest("doc.txt", extractor=MyExtraction())

4. ResolutionStrategy

Deduplicates entities that refer to the same real-world thing.

ABC

from graphrag_sdk import ResolutionStrategy

class ResolutionStrategy(ABC):
    @abstractmethod
    async def resolve(
        self,
        graph_data: GraphData,
        ctx: Context,
    ) -> ResolutionResult:
        """Deduplicate entities in the graph data."""
        ...

Returns ResolutionResult with deduplicated nodes, remapped relationships, and merged_count.

Built-in: ExactMatchResolution (ingest default)

Deduplicates by (normalized name, label) only. Fast, no embeddings, no LLM calls. Same-name entities with different labels (Person “Paris” vs Location “Paris”) stay separate; the survivor keeps every member’s description as a list (descriptions) and joined with " | " (description), and every relationship endpoint is re-pointed to it.

from graphrag_sdk.ingestion.resolution_strategies.exact_match import ExactMatchResolution

resolver = ExactMatchResolution(
    resolve_property="name",  # property to match on (default: "name")
)

When to use: Default. Extraction is consistent, or ingest cost matters more than duplicate recall. Ingest is per document, so cross-document duplicates with different surface forms (Airbus / Airbus SE) are left for finalize(), where the resolver pass and the LLM-judged phase see the whole graph (see Storage).

Built-in: LLMVerifiedResolution (opt-in at ingest, default at `finalize()`)

Three tiers that catch the near-duplicates exact match misses (e.g. Acme Corp vs Acme Corporation):

(normalized name, label) exact-match merge — the same first pass ExactMatchResolution performs.
Embed the surviving nodes as "name: description" and compare pairs in one unified same/cross-label candidate stage:
- similarity >= hard_threshold: merged immediately, no LLM call
- soft_threshold <= similarity < hard_threshold: sent to the LLM for a YES/NO verdict, several pairs per call
- similarity < soft_threshold: skipped A label-family gate keeps pairs that cannot be one thing (Person vs Place) away from the LLM, and a cross-label merge needs a second, A/B-swapped vote to agree.
Merge the confirmed clusters, then remap and deduplicate relationships.

Merged descriptions are kept as a list and joined with " | " (concatenated below force_summary_threshold, LLM-summarized at or above it); labels absorbed from cross-label merges are kept in merged_labels and promoted to real Cypher labels on write.

from graphrag_sdk import LLMVerifiedResolution

resolver = LLMVerifiedResolution(
    llm=llm,                       # LLMInterface for YES/NO verification and summaries (optional)
    embedder=embedder,             # Embedder for pairwise cosine similarity (optional)
    hard_threshold=0.95,           # Merge without asking the LLM (default: 0.95)
    soft_threshold=0.65,           # Below this, skip the pair entirely (default: 0.65)
    max_llm_pairs=500,             # Cap on ambiguous pairs per call, highest similarity first (default: 500)
    batch_verification=True,       # Several pairs per LLM call (default: True)
    verification_max_pairs_per_call=5,
    force_summary_threshold=3,     # Trigger LLM summary at this many descriptions (default: 3)
    max_summary_tokens=500,        # Max tokens for LLM summary (default: 500)
    ann_top_k=50,                  # Nearest neighbours retrieved per node (default: 50)
)

Both providers are optional but must be passed explicitly when you construct the strategy yourself; GraphRAG.ingest() wires its own LLM and embedder only into the default instance. With no embedder it degrades to exact match, and with no llm the ambiguous zone is skipped so only the hard_threshold tier merges. When to use: Pass it to ingest(resolver=...) when one document names the same entity inconsistently; recall on real duplicates is roughly 2.5x that of exact match on the benchmark corpus, at the cost of embedding and LLM calls during ingest. Across documents, finalize() already runs it over the whole graph by default (resolve=False turns that off).

5. RetrievalStrategy

Searches the knowledge graph to find context for answering a question. Uses the Template Method pattern: search() handles validation and formatting, you implement _execute().

ABC

from graphrag_sdk import RetrievalStrategy

class RetrievalStrategy(ABC):
    def __init__(self, graph_store=None, vector_store=None):
        self.graph_store = graph_store
        self.vector_store = vector_store

    async def search(self, query: str, ctx: Context = None, **kwargs) -> RetrieverResult:
        """Public API: validate -> execute -> format."""
        ...

    @abstractmethod
    async def _execute(self, query: str, ctx: Context, **kwargs) -> RawSearchResult:
        """Implement your search logic here."""
        ...

Built-in: LocalRetrieval

Simple retrieval: vector search on chunks + 1-hop entity traversal.

from graphrag_sdk.retrieval.strategies.local import LocalRetrieval

retriever = LocalRetrieval(
    graph_store=rag.graph_store,
    vector_store=rag.vector_store,
    embedder=embedder,
    top_k=5,                # chunks to retrieve (default: 5)
    include_entities=True,  # include connected entities (default: True)
)

When to use: Simple use cases, low latency requirements, small graphs.

Built-in: MultiPathRetrieval

Production-grade retrieval with RELATES edge vector search, 2-path entity discovery, 4-path chunk retrieval, and cosine reranking. This is the default, and the strategy used for the GraphRAG-Bench results.

from graphrag_sdk import MultiPathRetrieval

retriever = MultiPathRetrieval(
    graph_store=rag.graph_store,
    vector_store=rag.vector_store,
    embedder=embedder,
    llm=llm,
    chunk_top_k=15,         # final chunks after reranking (default: 15)
    max_entities=30,        # total entity cap (default: 30)
    max_relationships=20,   # max relationships in context (default: 20)
    rel_top_k=15,           # RELATES edge vector search results (default: 15)
    keyword_limit=10,       # max keywords from question (default: 10)
)

rag = GraphRAG(connection=conn, llm=llm, embedder=embedder, retrieval_strategy=retriever)

When to use: Default choice. Best accuracy on benchmark. Handles complex multi-hop questions.

Writing Your Own

class GlobalRetrieval(RetrievalStrategy):
    async def _execute(self, query, ctx, **kwargs):
        # Your custom retrieval logic
        results = await self.vector_store.search(query_vector, top_k=20)
        return RawSearchResult(records=results)

rag = GraphRAG(connection=conn, llm=llm, embedder=embedder, retrieval_strategy=GlobalRetrieval())

6. RerankingStrategy

Reranks retrieval results before they are passed to the LLM for answer generation.

ABC

from graphrag_sdk import RerankingStrategy

class RerankingStrategy(ABC):
    @abstractmethod
    async def rerank(
        self,
        query: str,
        result: RetrieverResult,
        ctx: Context,
    ) -> RetrieverResult:
        """Rerank and filter retrieval results."""
        ...

Built-in: CosineReranker

Reranks by cosine similarity between query embedding and item embeddings.

from graphrag_sdk import CosineReranker

reranker = CosineReranker(
    embedder=embedder,
    top_k=15,          # keep top N results (default: 15)
)

result = await rag.completion("question", reranker=reranker)

Note: MultiPathRetrieval already includes cosine reranking internally. The standalone CosineReranker is useful when using LocalRetrieval or a custom strategy.

Writing Your Own

class LLMReranker(RerankingStrategy):
    async def rerank(self, query, result, ctx):
        # Score each item with the LLM and sort
        scored = []
        for item in result.items:
            score = await self.llm.ainvoke(f"Rate relevance 0-10: {query} vs {item.content}")
            scored.append((float(score.content), item))
        scored.sort(reverse=True)
        return RetrieverResult(items=[item for _, item in scored[:10]])

Home

Pipeline

Ontology

Reference

Overview

1. LoaderStrategy

ABC

Built-in: TextLoader

Built-in: PdfLoader

Built-in: MarkdownLoader

Default Behavior

Writing Your Own

2. ChunkingStrategy

ABC

Built-in: FixedSizeChunking

Built-in: SentenceTokenCapChunking

Built-in: ContextualChunking

Built-in: CallableChunking (bring your own framework)

Built-in: StructuralChunking

Writing Your Own

3. ExtractionStrategy

ABC

Built-in: GraphExtraction

Choosing an Entity Extractor

Writing Your Own Entity Extractor

Writing Your Own Extraction Strategy

4. ResolutionStrategy

ABC

Built-in: ExactMatchResolution (ingest default)

Built-in: LLMVerifiedResolution (opt-in at ingest, default at `finalize()`)

5. RetrievalStrategy

ABC

Built-in: LocalRetrieval

Built-in: MultiPathRetrieval

Writing Your Own

6. RerankingStrategy

ABC

Built-in: CosineReranker

Writing Your Own

​Overview

​1. LoaderStrategy

​ABC

​Built-in: TextLoader

​Built-in: PdfLoader

​Built-in: MarkdownLoader

​Default Behavior

​Writing Your Own

​2. ChunkingStrategy

​ABC

​Built-in: FixedSizeChunking

​Built-in: SentenceTokenCapChunking

​Built-in: ContextualChunking

​Built-in: CallableChunking (bring your own framework)

​Built-in: StructuralChunking

​Writing Your Own

​3. ExtractionStrategy

​ABC

​Built-in: GraphExtraction

​Choosing an Entity Extractor

​Writing Your Own Entity Extractor

​Writing Your Own Extraction Strategy

​4. ResolutionStrategy

​ABC

​Built-in: ExactMatchResolution (ingest default)

​Built-in: LLMVerifiedResolution (opt-in at ingest, default at finalize())

​5. RetrievalStrategy

​ABC

​Built-in: LocalRetrieval

​Built-in: MultiPathRetrieval

​Writing Your Own

​6. RerankingStrategy

​ABC

​Built-in: CosineReranker

​Writing Your Own

Overview

1. LoaderStrategy

ABC

Built-in: TextLoader

Built-in: PdfLoader

Built-in: MarkdownLoader

Default Behavior

Writing Your Own

2. ChunkingStrategy

ABC

Built-in: FixedSizeChunking

Built-in: SentenceTokenCapChunking

Built-in: ContextualChunking

Built-in: CallableChunking (bring your own framework)

Built-in: StructuralChunking

Writing Your Own

3. ExtractionStrategy

ABC

Built-in: GraphExtraction

Choosing an Entity Extractor

Writing Your Own Entity Extractor

Writing Your Own Extraction Strategy

4. ResolutionStrategy

ABC

Built-in: ExactMatchResolution (ingest default)

Built-in: LLMVerifiedResolution (opt-in at ingest, default at `finalize()`)

5. RetrievalStrategy

ABC

Built-in: LocalRetrieval

Built-in: MultiPathRetrieval

Writing Your Own

6. RerankingStrategy

ABC

Built-in: CosineReranker

Writing Your Own