GraphContainer provides a unified workflow for working with graph RAG systems. It is designed to load graphs produced by different methods, convert them into a shared internal representation, run retrieval pipelines on top of that representation, visualize retrieval traces in a browser, and execute experiments through a consistent interface.

The main idea behind GraphContainer is simple: different graph RAG methods store graph data in different formats, but once those graphs are converted into a common structure, they can be searched, visualized, and compared in a much more consistent way. In this repository, that common structure is implemented through the Unified Graph State, which stores nodes, edges, adjacency information, and vector indexes in a form that downstream components can access without caring about the original source format.

At the core of the implementation are SimpleGraphContainer and SearchableGraphContainer. SimpleGraphContainer is responsible for holding the in-memory graph itself, while SearchableGraphContainer extends that base structure with pluggable vector indexes such as node_vector. On top of this container layer, the repository provides adapters for different upstream graph formats, including import_graph_from_component_graph (Component Graph), import_graph_from_attribute_bundle_graph (Attribute Bundle Graph), import_graph_from_topology_semantic_graph (Topology-Semantic Graph), and import_graph_from_subgraph_union_graph (Subgraph Union Graph). These adapters are the entry points that translate method-specific graph storage into the unified internal graph state used by the rest of the system.

Once a graph has been loaded, retrieval is handled by the RAG modules under src/rag. The embedding path is managed through src/rag/embeddings.py, and the retrieval logic lives in src/rag/retrievers.py. The repository currently includes two retrieval strategies: OneHopRetriever, which starts from vector-retrieved seed nodes and expands to their immediate neighbors, and FastInsightRetriever, which applies a multi-stage retrieval process with seed selection, deeper exploration, and final filtering. In the current experiment setup, the initial retrieval size is set to 10, and FastInsight keeps the final 5 nodes before answer generation.

The end-to-end experiment pipeline is implemented in test/rag_experiment.py. This script loads the available graphs, applies the retrievers, builds prompts from the retrieved content, sends the prompts to the generator model, and writes the outputs as JSONL files. In other words, the implementation path is: load a graph from a method-specific source, convert it into the unified graph container, run retrieval on top of the shared representation, assemble the retrieved evidence into a prompt, generate an answer, and finally save the result for evaluation.

Before running the project, make sure uv itself is installed. On macOS and Linux, you can install it with the official standalone installer:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows PowerShell, you can install it with:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

If you prefer another installation method, such as Homebrew, WinGet, Scoop, or pipx, you can use the official uv installation guide. Once uv is available in your shell, install the project dependencies with:

uv sync

After installation, restart bash and use the command below to activate the virtual environment.

source .venv/bin/activate

Preconstructed graph artifacts are distributed through the Hugging Face dataset repository at https://huggingface.co/datasets/hchaejeong/graphcontainer-graphs. The stored graph artifacts are about 10.1 GB total. The G-Retriever SceneGraphs artifact is stored as tar archives to avoid uploading more than 160k small files; extracting it requires additional temporary disk space roughly comparable to the extracted artifact size.

Install the Hugging Face Hub client if needed:

uv pip install -U huggingface_hub

Run this from the GraphContainer repository root:

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="hchaejeong/graphcontainer-graphs",
    repo_type="dataset",
    local_dir="./data/rag_storage",
    allow_patterns=[
        "fastinsight/**",
        "g_retriever/**",
        "hipporag/**",
        "lightrag/**",
    ],
)

The allow_patterns list downloads only the graph artifact directories, so README.md and manifest.jsonl from the Hugging Face repository are not placed under data/rag_storage.

Expected layout:

data/rag_storage/
├── fastinsight/
│   └── scifact-bge-m3/
├── g_retriever/
│   └── scene_graphs/
├── hipporag/
│   └── 2wikimultihopqa/
└── lightrag/
    └── bsard/

To download only one artifact, narrow the allow_patterns value. For example:

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="hchaejeong/graphcontainer-graphs",
    repo_type="dataset",
    local_dir="./data/rag_storage",
    allow_patterns=["hipporag/2wikimultihopqa/**"],
)

Before using the Subgraph Union Graph example, extract the G-Retriever tar archives:

cd ./data/rag_storage/g_retriever/scene_graphs

tar -xf nodes.tar
tar -xf edges.tar
tar -xf graphs.tar

cd ../../../..

After confirming extraction succeeded, you may optionally remove nodes.tar, edges.tar, and graphs.tar to reclaim disk space.

The web interface is powered by the live visualizer. You can launch it directly from the command line by passing one or more --graph FORMAT:PATH arguments.

The table below shows example commands for the four main graph formats:

To serve all four formats at once, run:

python serve.py \
  --graph component_graph:./data/rag_storage/fastinsight/scifact-bge-m3 \
  --graph attribute_bundle_graph:./data/rag_storage/lightrag/bsard \
  --graph topology_semantic_graph:./data/rag_storage/hipporag/2wikimultihopqa \
  --graph subgraph_union_graph:./data/rag_storage/g_retriever/scene_graphs \
  --host 127.0.0.1 \
  --port 8765 \
  --hops 2

subgraph_union_graph expects extracted nodes/, edges/, and graphs/ directories, so extract the G-Retriever tar archives before launching that format.

After the server starts, open http://127.0.0.1:8765 in your browser. The page renders the graph or subgraph associated with the current retrieval session and lets you inspect how the retriever moved through the graph. Nodes and edges selected during retrieval can be highlighted, and the visualizer keeps track of session progress so that a query can be inspected step by step instead of only as a final result.

If you already have a graph object in memory, you can launch the same interface from Python by using serve_graph:

from GraphContainer import serve_graph

visualizer = serve_graph(
    graph,
    host="127.0.0.1",
    port=8765,
    default_hops=2,
)

print(visualizer.url)

If your graph is stored in Component Graph format, you can also serve it directly from storage:

from GraphContainer import serve_component_graph

visualizer = serve_component_graph(
    "data/rag_storage/fastinsight/scifact-bge-m3",
    host="127.0.0.1",
    port=8765,
    default_hops=2,
)

In practice, the web page is useful for understanding what happened during retrieval rather than only checking the final answer. A typical flow is to start the visualizer, open the browser page, submit a query or connect to an existing retrieval session, and then inspect the highlighted nodes, edges, and progress updates. This makes it easier to see which evidence was selected, how graph traversal expanded from the initial seeds, and how the retrieved subgraph contributed to the final answer.

The default experiment path in this repository is provided through scripts/run_batch_experiment.sh. This script is intentionally fixed to the current experimental setup and can be run with:

uv run bash scripts/run_batch_experiment.sh

By default, this runs the experiment on the bsard dataset with query_limit=-1, top_k=10, index_name=node_vector, ollama_url=http://localhost:11434/v1, ollama_model=gemma3:12b, and max_context_chunks=10. The current setup uses text-embedding-3-small for embeddings, and the experiment script iterates over the configured graph imports while applying both retrieval methods to each graph.

If you want to run the experiment entry point directly rather than going through the batch script, you can execute:

uv run python test/rag_experiment.py \
  --dataset bsard \
  --query_limit -1 \
  --top_k 10 \
  --index_name node_vector \
  --outputs_dir ./outputs/bsard \
  --ollama_url http://localhost:11434/v1 \
  --ollama_model gemma3:12b \
  --max_context_chunks 10

The outputs are saved as JSONL files under ./outputs/bsard/, typically in files named like <graph_name>_<retriever>.jsonl. Each line contains a single query-output pair in the form {"query": "question text", "outputs": "generated answer"}. This makes the results easy to evaluate later with a separate judging or comparison pipeline.

After downloading the Hugging Face artifacts, you can run a local smoke test:

uv run python scripts/verify_hf_artifacts.py --root ./data/rag_storage

The default check verifies required artifact paths and adapter-compatible storage layouts. To run full importer loads, use:

uv run python scripts/verify_hf_artifacts.py --root ./data/rag_storage --full-import

--full-import can take many minutes for large LightRAG and G-Retriever artifacts. The script exits with a non-zero status if a required artifact is missing or a selected importer check fails.

GraphContainer source code is released under the MIT License in this GitHub repository.

The graph artifacts on Hugging Face are derived from multiple upstream datasets and graph construction systems. The MIT License for this source code does not automatically apply to every source dataset or derived graph artifact. Artifact-specific provenance and license notes are tracked in DATA_LICENSES.md and summarized in the Hugging Face Dataset Card.

@misc{an2026graphcontainer,
  title        = {GraphContainer: A Unified Platform for Comparing and Debugging Graph RAG Methods},
  author       = {Seonho An and Chaejeong Hyun and Min-Soo Kim},
  year         = {2026},
  eprint       = {2607.19362},
  archivePrefix = {arXiv}
}