FalkorDB/GraphRAG-SDK

GraphRAG‑SDK – a Graph‑based Retrieval‑Augmented Generation framework

What it is – A Python SDK that lets you turn a collection of documents (text, PDFs, markdown, CSV, …) into a knowledge graph stored in FalkorDB, then answer natural‑language questions by retrieving and traversing that graph. The library is built around the idea that the retrieval step matters more than the LLM; by grounding answers in graph nodes and edges you can dramatically cut down on hallucinations.

Why it matters – Traditional RAG pipelines rely on flat vector similarity search, which often misses multi‑hop facts and provides no traceability. GraphRAG‑SDK adds:

• Relationship traversal – facts that are linked through entities are discovered even when they are not text‑ually similar.
• Provenance edges (MENTIONED_IN) – every answer can be traced back to the exact source chunk(s) that supported it.
• Abstention support – the SDK can detect when the graph lacks sufficient evidence and return an explicit “insufficient evidence” response instead of fabricating an answer.
• Benchmark‑leading accuracy – the README cites a 71.48 % overall accuracy on the GraphRAG‑Bench, outperforming standard vector‑RAG baselines.

Core concepts

Concept	Role
Graph schema	Optional GraphSchema lets you declare entity types (e.g., Person, Organization) and relation types (e.g., WORKS_AT). The schema guides extraction and ensures typed, checkable facts.
Ingestion	rag.ingest(text, document_id) extracts entities/relations with an LLM, deduplicates, creates embeddings, and upserts nodes/edges into FalkorDB.
Finalize	rag.finalize() runs cross‑document deduplication and back‑fills missing embeddings; it is O(graph size) and should be called once after a batch of changes.
Retrieval + generation	rag.completion(question, return_context=True) performs graph‑based retrieval (vector, full‑text, optional text‑to‑Cypher) then passes the retrieved context to the LLM for answer generation.
Incremental updates	update(), delete_document(), and apply_changes() let you keep the graph in sync with a source repository (e.g., CI pipelines) without rebuilding from scratch.

Typical workflow (5‑minute demo)

1. Install – pip install graphrag-sdk[litellm] (add [pdf] extra for PDF support). Run a FalkorDB container (docker run … falkordb/falkordb:latest).
2. Create a GraphRAG instance – supply a ConnectionConfig (host + graph name for tenant isolation) and LLM/embedding providers (the SDK ships a thin wrapper around LiteLLM so any OpenAI‑compatible model works).
3. Ingest documents – call ingest() for each source. The LLM extracts entities, the embedder creates vectors, and the SDK writes Cypher upserts.
4. Finalize – run finalize() once per batch to deduplicate and index.
5. Query – await rag.completion("Where does Alice work?") returns an Answer object containing answer.answer and, if requested, the full retrieval trail.

Installation & quick start snippet

pip install graphrag-sdk[litellm]
# start FalkorDB (Docker) and set your OpenAI key
export OPENAI_API_KEY=sk-…

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

async def main():
    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="demo"),
        llm=LiteLLM(model="openai/gpt-4o-mini"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-large", dimensions=256),
    ) as rag:
        await rag.ingest(text="Alice Johnson works at Acme Corp in London.", document_id="doc1")
        await rag.finalize()
        ans = await rag.completion("Where does Alice work?", return_context=True)
        print(ans.answer)
        print(ans.context)   # provenance edges, source chunks, etc.

asyncio.run(main())

Key features (as listed in the README)

• Benchmark‑leading accuracy (rank 1 on GraphRAG‑Bench at the time of writing).
• Hallucination reduction via graph‑grounded retrieval and provenance edges.
• Fast, multi‑tenant – each graph is isolated by name; FalkorDB provides sub‑millisecond Cypher queries.
• Modular pipeline – you can plug custom ingestion strategies, LLM providers, or embedder back‑ends.
• Incremental updates – safe, idempotent update() with crash‑recovery semantics; batch processing for CI.
• Extensible schema – declare or evolve ontologies; the SDK can discover new types from incoming docs.
• Observability hooks – upcoming releases (Q2 2026) add production‑grade metrics.

Who should use it

• Enterprises that need reliable, auditable RAG answers (e.g., legal, medical, finance) where hallucinations are unacceptable.
• Developers building chat‑bots, Q&A assistants, or internal knowledge bases who want graph‑level reasoning (multi‑hop facts, entity‑centric queries).
• Researchers interested in comparing graph‑based RAG vs. pure vector RAG; the SDK ships with benchmark scripts and reproducibility docs.

Where to learn more

• Full docs: https://docs.falkordb.com/graphrag
• Getting‑started guide, architecture overview, and reliability/grounding docs (all linked from the README).
• Example gallery (graphrag_sdk/examples/…) covers quick start, PDF ingestion, custom strategies, ontology evolution, and the “grounded answers with abstention” pattern.

Community & contribution

• Open‑source under Apache 2.0.
• Active Discord, GitHub Discussions, and issue tracker for support and feature requests.
• Contribution guide and code‑of‑conduct provided.

---

Bottom line – GraphRAG‑SDK is a production‑ready, Python‑first framework that couples FalkorDB’s graph engine with LLM‑driven entity extraction to give you a RAG system that is more accurate, traceable, and controllable than plain vector‑search pipelines.