FalkorDB GraphRAG-SDK: a Python framework that keeps the retrieval trail attached to the answer

The retrieval failure GraphRAG-SDK is built around

The README makes a specific claim about why RAG systems produce wrong answers: hallucinations are usually a retrieval failure, not a model failure, because the model is asked to answer from context that never contained the answer. GraphRAG-SDK is aimed at that gap. It is a Python SDK for turning raw documents into a knowledge graph stored in FalkorDB, then answering questions by traversing that graph rather than by matching chunks.

The audience is narrow and identifiable. You are building a GenAI application over documents where the answer requires connecting facts that live in different places: who reports to whom, which component depends on which service, which clause in one contract changes the meaning of a clause in another. Single-chunk vector search retrieves text that looks like the question. It does not walk from one entity to a related one.

The README states the project was built from real deployments and that the retrieval harness matters more than the model. That framing explains the design: the SDK spends its complexity budget on graph construction, ontology constraints, and provenance rather than on prompt engineering.

How the graph gets built and how an answer gets traced

Ingestion takes text or a file and produces nodes and edges in a FalkorDB graph. The ontology constrains what can be extracted, so the graph stores typed, checkable facts rather than free-form model output. That is the central mechanism and also the central constraint: whatever your ontology does not describe will not become a typed edge.

Retrieval then runs over that graph. The README contrasts the two approaches directly: vectors match similar chunks, the graph traverses relationships. Multi-hop facts rarely sit in one chunk that happens to be similar to the question, which is the case the graph is meant to cover. The README also states that text-to-Cypher retrieval is enabled in the benchmark configuration, so query generation can be part of the path.

Provenance is the second mechanism. `MENTIONED_IN` edges trace entity mentions back to their source chunks, and `return_context=True` returns the retrieval trail so the application can inspect it. That is what makes abstention possible: the application can gate generation on retrieval and return an explicit evidence-insufficient response instead of guessing. The repository ships `graphrag_sdk/examples/grounded_answers_with_abstention.py` as the worked example of that pattern. The value here is not that the answer is always right. It is that the application can tell when the evidence was thin.

Installing GraphRAG-SDK and running a first ingestion

The README gives a three-step quick start. First install the SDK with the LiteLLM extra, start FalkorDB in Docker, and set a provider key. The `[litellm]` extra is what pulls in the model provider layer, so a plain `pip install graphrag-sdk` is not the path the README describes.

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

The container exposes 6379 for the graph and 3000 for the browser. If you ingest PDFs, the README says to install the `pdf` extra instead: `pip install graphrag-sdk[litellm,pdf]`. It also notes that ingestion sanitizes unsupported control characters in IDs and string properties before graph upserts, which helps avoid FalkorDB Cypher parse errors on noisy PDFs. That detail matters if your source documents come from a scanner or a scraped corpus.

The second step is ingestion. The README example opens a `GraphRAG` context with a `ConnectionConfig` and a `graph_name`, which the README describes as per-tenant isolation, then calls `rag.ingest` with text and a `document_id`. The result object carries `nodes_created` and relationship counts, so the first thing you should look at after a run is whether the graph is as large as your document implies.

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.5"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-large", dimensions=256),
    ) as rag:
        result = await rag.ingest(
            text="Alice Johnson is a software engineer at Acme Corp in London.",
            document_id="my_doc",
        )
        print(f"Nodes: {result.nodes_created}, Edges: {result.relati"

Note that the README snippet is truncated at this point in the repository, so the print statement is cut off mid-call. Treat the surrounding API shape as documented and the exact output line as something to read from the file itself. The repository also ships a `docker-compose.yml` pinning `falkordb/falkordb:v4.18.0` with a named volume and a `redis-cli ping` healthcheck, which is the more reproducible way to run the server than the floating `latest` tag in the quick start.

Where the ontology and the benchmark configuration bite

The strongest limitation is stated by the project itself. The ontology constrains what can be extracted. If a relationship is not in your ontology, the graph will not carry it as a typed edge, and traversal cannot reach it later. That means schema design happens before ingestion and is expensive to change afterward, because the fix is re-ingestion, not a query tweak.

The benchmark table deserves the same scrutiny. The README reports FalkorDB GraphRAG SDK at 66.09 Novel, 76.87 Medical, 71.48 overall, ahead of G-reasoner at 66.12 and vector RAG with reranking at 55.39. The README is unusually explicit about how those numbers were produced: `gpt-4o-mini` on Azure OpenAI at temperature 0.7 for both graph construction and generation, `text-embedding-3-large` at 1024 dimensions, text-to-Cypher retrieval enabled, and the benchmark's own `generation_eval.py` unmodified as judge. It also states that competitor numbers come from the published leaderboard unchanged, and that the overall score is the project's own summary while the leaderboard ranks each dataset separately. Two datasets, one model, one embedding configuration. If your model or dimensions differ, those numbers do not transfer.

The third limitation is operational. GraphRAG-SDK is a front end to FalkorDB. You run a FalkorDB server, you keep it available, and your ingestion pipeline depends on it. The README does not document rollback of an ingestion, so a bad extraction pass is not obviously reversible from the SDK surface. The README also does not describe a managed hosting option.

GraphRAG-SDK against a Neo4j-based GraphRAG stack

The realistic alternative is building the same pipeline on Neo4j, either with a general GraphRAG framework or with your own extraction and Cypher. The difference is not the retrieval idea, which is the same, but the store underneath it.

FalkorDB is a Redis-module graph database. The quick start is one `docker run` and a Python client, and the repository's compose file pins a version with a healthcheck. Neo4j is a standalone server with its own drivers, its own query language dialect, and a larger operational footprint. If your organization already runs Neo4j and has people who know it, adding FalkorDB means a second graph store to back up, monitor and upgrade.

The SDK's differentiator is what comes bundled: ontology-driven extraction, `MENTIONED_IN` provenance edges, `return_context=True` on retrieval, and the abstention example. A Neo4j-based GraphRAG stack typically gives you the graph and leaves those layers to you. That is a real trade-off in both directions. Bundled layers are faster to start and harder to replace; hand-built layers fit your data model exactly and cost engineering time up front. The README's benchmark table is the project's argument that the bundled layers are worth it, and the configuration note above is the reason to read that table carefully rather than take the headline number.

Maintenance, releases and the Apache-2.0 terms

The repository is not archived and the last push was on 2026-09-09, which is recent. Releases are frequent enough to plan around: v1.4.0 on 2026-08-10, v1.3.0 on 2026-06-04, and v1.2.0 on 2026-06-01. The gap between v1.2.0 and v1.3.0 is three days, which suggests the version numbers track feature batches rather than a fixed schedule. The repository carries a CHANGELOG.md, so the upgrade path is documented in the tree rather than only in release notes.

Upgrade cost has two parts. The SDK side is a Python package, so pinning a version is a line in your dependency file. The server side is FalkorDB itself, and the quick start pulls `falkordb/falkordb:latest` while `docker-compose.yml` pins `falkordb/falkordb:v4.18.0`. Running `latest` in production means the graph server can change under you on a container restart. Pin the image tag.

Licensing is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. It also requires that you preserve copyright and licence notices and state significant changes. That applies to the SDK. It does not automatically cover the FalkorDB server image you run alongside it, and the README does not describe the server's licensing in this repository. Check the server's own terms separately; this is not legal advice.

Editorial conclusion

Adopt GraphRAG-SDK if your questions need multi-hop facts, per-tenant graph isolation, and an answer path that can return the retrieval trail or abstain. Skip it if your corpus answers well from single-chunk vector similarity, or if you already run Neo4j and do not want a second graph store. Before committing, verify three things: that the benchmark configuration in the docs matches your model and embedding dimensions, that you can run `docker run -d -p 6379:6379 -p 3000:3000 --name falkordb falkordb/falkordb:latest` in your environment, and that your ontology can express the relationships your questions actually need, because the README states the ontology constrains what can be extracted.

Frequently asked questions

Official sources

1. FalkorDB/GraphRAG-SDK on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases