Skip to content

v1.0.0rc1 — GraphRAG SDK v1 Release Candidate

Pre-release
Pre-release

Choose a tag to compare

View all tags
@galshubeli galshubeli released this 16 Apr 10:35
· 181 commits to main since this release
v1.0.0rc1
9c9dbdb
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

GraphRAG SDK v1.0.0rc1 — Release Candidate

This is the Release Candidate for v1.0. v1.0 is a full rewrite of the SDK. If you are running v0.x in production, do not auto-upgrade — pip install graphrag-sdk continues to return v0.8.1 by design. This RC is opt-in only.

Install this RC

pip install graphrag-sdk --pre
# or
pip install graphrag-sdk==1.0.0rc1

Stay on v0.x

pip install graphrag-sdk          # still gives you 0.8.1
pip install "graphrag-sdk<1"      # pin explicitly

v0.x code and history are preserved on the legacy-v0 branch and the v0-final tag.

What's new in v1

  • Async-first API. await rag.ingest(...), await rag.completion(...), async with GraphRAG(...) as rag: — everything is coroutine-based.
  • Strategy pattern throughout. Every pipeline concern — loading, chunking, extraction, resolution, retrieval, reranking — is a swappable strategy behind an abstract interface. Subclass and inject; the SDK doesn't care.
  • Multi-path retrieval. 5 parallel retrieval paths (vector, fulltext, cypher, relationship expansion, chunk) combined with cosine reranking. Default strategy.
  • Full provenance. Every entity has MENTIONS edges back to its source chunks; every chunk knows its document. Pass return_context=True to completion() to get the retrieval trail.
  • MkDocs site live at https://falkordb.github.io/GraphRAG-SDK/.

Benchmark

Ranked #1 on GraphRAG-Bench Novel dataset (20 novels, 2,010 questions, automated evaluation):

Rank System Overall
1 FalkorDB GraphRAG SDK 63.73
2 AutoPrunedRetriever 63.72
3 G-Reasoner 58.94
4 HippoRAG2 56.48

Competitor numbers from the GraphRAG-Bench public leaderboard. See docs/benchmark.md for full methodology and reproduction instructions.

Breaking changes from v0.x

This is not a migration — it's a rewrite. The public API, module layout, graph schema, and storage format all changed. If you have a v0.x graph in FalkorDB, you'll need to re-ingest into v1.

  • Package layout moved to graphrag_sdk/src/graphrag_sdk/.
  • Entry point is now GraphRAG (facade); the v0.x KnowledgeGraph class is gone.
  • All I/O is async. Sync wrappers exist (completion_sync, finalize_sync) but the primary API is async.
  • Schema is defined via GraphSchema, EntityType, RelationType, SchemaPattern.

See the README Quick Start for the new shape.

Known limitations

  • Entity resolution still produces duplicates for name variants of the same real-world entity.
  • RediSearch fulltext query escaping has edge cases with reserved words (non-fatal, logged).
  • Ingestion quality is the main retrieval-accuracy ceiling — working on it for 1.1.

Feedback

Please try the RC and tell us what breaks:

Assets 2
Loading