📦 Still on the v0.x API? Pin the legacy release: pip install graphrag-sdk==0.8.2.

GraphRAG-SDK

The simplest, most accurate GraphRAG framework built on FalkorDB

Most GraphRAG systems work in demos and break under production constraints. GraphRAG SDK was built from real deployments around a simple idea: the retrieval harness matters more than the model. The result is a modular, benchmark-leading framework with predictable cost and sensible defaults that gets you from raw documents to cited answers quickly.

---

Benchmarks

Rank	System	Novel (Multi-Doc)	Medical (Single-Doc)	Overall
1	FalkorDB GraphRAG SDK ◄	63.73	75.73	69.73
2	G-Reasoner	58.94	73.30	66.12
3	AutoPrunedRetriever	63.72	67.00	65.36
4	HippoRAG2	56.48	64.85	60.67
5	Fast-GraphRAG	52.02	64.12	58.07
6	RAG (w rerank) (Vector RAG)	48.35	62.43	55.39
7	LightRAG	45.09	62.59	53.84
8	HippoRAG	44.75	59.08	51.92
9	MS-GraphRAG (local)	50.93	45.16	48.05

Overall ACC on GraphRAG-Bench Novel (20 novels, 2,010 questions) and Medical (1 corpus, 2,062 questions) datasets. FalkorDB scored with gpt-4o-mini (Azure OpenAI); competitor numbers are from the published leaderboard. Overall = mean of Novel and Medical ACC. See docs/benchmark.md for per-category breakdowns, methodology, and reproduction instructions.

---

Quick Start

1. Install and start FalkorDB

pip install graphrag-sdk[litellm]
docker run -d -p 6379:6379 -p 3000:3000 --name falkordb falkordb/falkordb:latest
export OPENAI_API_KEY="sk-..."

For PDF ingestion, install the pdf extra instead: pip install graphrag-sdk[litellm,pdf]. Ingestion sanitizes unsupported control characters in IDs and string properties before graph upserts, which helps avoid FalkorDB Cypher parse errors on noisy PDFs.

2. Ingest a document

import asyncio
from graphrag_sdk import GraphRAG, ConnectionConfig, LiteLLM, LiteLLMEmbedder

async def main():
    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="my_graph"),
        llm=LiteLLM(model="openai/gpt-5.4"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-large", dimensions=1536),
    ) as rag:
        # Ingest raw text (pass a file path with the `pdf` extra installed for PDFs)
        result = await rag.ingest(
            "my_doc",
            text="Alice Johnson is a software engineer at Acme Corp in London.",
        )
        print(f"Nodes: {result.nodes_created}, Edges: {result.relationships_created}")

        # Finalize: deduplicate entities, backfill embeddings, create indexes
        await rag.finalize()

        # Full RAG: retrieve + generate
        answer = await rag.completion("Where does Alice work?")
        print(answer.answer)

asyncio.run(main())

3. Define a schema (optional)

from graphrag_sdk import GraphSchema, EntityType, RelationType

schema = GraphSchema(
    entities=[
        EntityType(label="Person", description="A human being"),
        EntityType(label="Organization", description="A company or institution"),
        EntityType(label="Location", description="A geographic location"),
    ],
    relations=[
        RelationType(label="WORKS_AT", description="Is employed by", patterns=[("Person", "Organization")]),
        RelationType(label="LOCATED_IN", description="Is situated in", patterns=[("Organization", "Location")]),
    ],
)

async with GraphRAG(
    connection=ConnectionConfig(host="localhost", graph_name="my_graph"),
    llm=LiteLLM(model="openai/gpt-5.4"),
    embedder=LiteLLMEmbedder(model="openai/text-embedding-3-large", dimensions=1536),
    schema=schema,
) as rag:
    ...  # ingest / completion as above

---

Ingestion & Retrieval Pipeline

Area	Item	Execution	Description
Ingestion	1. Load	Sequential	Read raw text from files (PDF, TXT) or strings.
Ingestion	2. Chunk	Sequential	Split content into overlapping text chunks.
Ingestion	3. Lexical Graph	Sequential	Create Document and Chunk nodes with provenance edges.
Ingestion	4. Extract	Sequential	Run GLiNER2 local NER and LLM-based relationship extraction.
Ingestion	5. Quality Filter	Sequential	Remove invalid extracted nodes (empty IDs, malformed shape).
Ingestion	6. Prune	Sequential	Filter nodes/relations against the schema; drop orphan relations.
Ingestion	7. Resolve	Sequential	Deduplicate entities (exact match, semantic, LLM-verified).
Ingestion	8. Write	Sequential	Persist graph updates with batched MERGE operations in FalkorDB.
Ingestion	9a. Mentions	Parallel	Link entities back to source chunks.
Ingestion	9b. Index	Parallel	Embed and index chunks for retrieval.
Retrieval	Vector search	Runtime	Finds semantically similar chunks.
Retrieval	Full-text search	Runtime	Matches exact terms and keywords.
Retrieval	Cypher queries	Runtime	Executes structured graph lookups.
Retrieval	Relationship expansion	Runtime	Traverses connected entities and context.
Retrieval	Cosine reranking	Runtime	Reorders candidates by relevance.

💡 Every answer is traceable to its source chunks via MENTIONS edges. Pass return_context=True to completion() to get the retrieval trail alongside the answer.

---

Examples

#	Example	What it demonstrates
1	Quick Start	Minimal ingest + query
2	PDF with Schema	PDF ingestion with custom entity types
3	Custom Strategies	Benchmark-winning pipeline configuration
4	Custom Provider	Implement your own LLM/Embedder
5	Notebook Demo	Interactive walkthrough with provenance inspection

---

Documentation

Guide	Description
Getting Started	Step-by-step tutorial from install to first query
Architecture	Pipeline design, graph schema, retrieval strategy
Configuration	Connection, providers, and tuning reference
Strategies	All ABCs and built-in implementations
Providers	LLM and embedder configuration guide
Benchmark	Methodology, results, and reproduction instructions
API Reference	Full API documentation

---

Development Milestones

• 2024-06: First public release
• 2024-Q4: PDF ingestion and multi-provider LLMs
• 2025-Q1–Q2: Pluggable providers and pipeline tuning
• 2025-Q3: Sharper retrieval, deeper test coverage
• 🎉 2026-04: Version 1.0 is released
• 2026-Q2: Increase production capabilities — timeouts, logs; expand ingestion support — tables, structured data
• 2026-Q3: Introduce Agentic GraphRAG; complete PDF ingestion
• 2026-Q4: Smarter retrieval — dynamic traversal, temporal graph

---

Contributing

We welcome contributions! See CONTRIBUTING.md for development setup, testing, and code style guidelines.

Please read our Code of Conduct before participating.

Community

• Discord -- Ask questions, share what you build
• GitHub Discussions -- Feature ideas, Q&A
• Issues -- Bug reports and feature requests

---

Citation

If you use GraphRAG SDK in your research, please cite:

@software{graphrag_sdk,
  title  = {GraphRAG SDK: A Modular Graph RAG Framework},
  author = {FalkorDB},
  year   = {2026},
  url    = {https://github.com/FalkorDB/GraphRAG-SDK},
}

---

License

Apache License 2.0