graphrag-lite 0.1.1

A minimal GraphRAG implementation in ~600 lines of Python code

GraphRAG-Lite

Minimal GraphRAG implementation in ~600 lines of Python code.

中文文档

GraphRAG-Lite is a lightweight, educational implementation of GraphRAG (Graph-based Retrieval-Augmented Generation). It's designed to help you understand the core principles of GraphRAG in a single afternoon.

Features

• Minimal: ~600 lines of code, easy to read and understand
• Zero Config: Only requires OpenAI API key, no complex setup
• 4 Query Modes: local, global, mix, naive
• Optimized: Batch embeddings, LLM caching, NumPy-accelerated vector search
• Streaming: Real-time response output support

Installation

pip install graphrag-lite

Or install from source:

git clone https://github.com/shibing624/graphrag-lite.git
cd graphrag-lite
pip install -e .

Quick Start

import os
from graphrag_lite import GraphRAGLite

# Initialize
graph = GraphRAGLite(
    storage_path="./my_graph",
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL"),  # Optional
)

# Insert documents
graph.insert("""
Charles Dickens wrote "A Christmas Carol" in 1843.
The story features Ebenezer Scrooge, a miserly old man,
and the ghost of his former business partner Jacob Marley.
""")

# Query
answer = graph.query("What is the relationship between Scrooge and Marley?")
print(answer)

Query Modes

Mode	Description	Use Case
local	Entity → Related relations	Specific entity questions
global	Relation → Related entities	Relationship questions
mix	Entity + Relation + Text chunks	Recommended for most cases
naive	Text chunks only (traditional RAG)	Baseline comparison

# Different query modes
answer = graph.query("Who is Scrooge?", mode="local")
answer = graph.query("Who is Scrooge?", mode="global")
answer = graph.query("Who is Scrooge?", mode="mix")      # Recommended
answer = graph.query("Who is Scrooge?", mode="naive")

Streaming Output

for chunk in graph.query("Who is Scrooge?", stream=True):
    print(chunk, end="", flush=True)

API Reference

GraphRAGLite

GraphRAGLite(
    storage_path: str = "./graphrag_data",  # Data storage directory
    api_key: str = None,                     # OpenAI API key
    base_url: str = None,                    # OpenAI API base URL
    model: str = "gpt-4o-mini",              # LLM model
    embedding_model: str = "text-embedding-3-small",  # Embedding model
    chunk_size: int = 1200,                  # Text chunk size
    chunk_overlap: int = 100,                # Chunk overlap
    enable_cache: bool = True,               # Enable LLM response caching
)

Methods

Method	Description
insert(text, doc_id=None)	Insert document and build knowledge graph
query(question, mode="mix", top_k=10, stream=False)	Query the knowledge graph
has_data()	Check if data exists
get_stats()	Get statistics
list_entities()	List all entities
list_relations()	List all relations
clear()	Clear all data

How It Works

1. Insert: Documents are chunked, entities and relations are extracted via LLM, then embedded and stored
2. Query: Question is used to search relevant entities/relations/chunks, context is built, LLM generates answer

Comparison with nano-graphrag

Feature	GraphRAG-Lite	nano-graphrag
Code Size	~600 lines	~1100 lines
Dependencies	openai, numpy, tiktoken	networkx, nano-vectordb, ...
LLM Support	OpenAI only	Multiple (OpenAI, Ollama, etc.)
Vector Storage	In-memory + JSON	Multiple backends
Async Support	❌	✅
Purpose	Educational	Production

GraphRAG-Lite is designed for learning and understanding GraphRAG principles, not for production use. If you need a production-ready solution, consider nano-graphrag or LightRAG.

Community & Support

• GitHub Issues: Have questions or feature requests? Submit an issue.
• WeChat: Join our developer community! Add WeChat ID xuming624 with note "llm" to join the group chat.

License

Apache License 2.0

Citation

If you find this project useful, please consider giving it a ⭐ on GitHub!

@software{graphrag-lite,
  author = {Xu Ming},
  title = {GraphRAG-Lite: Minimal GraphRAG Implementation},
  year = {2025},
  url = {https://github.com/shibing624/graphrag-lite}
}