$ show iMoonLab/Hyper-RAG
Hyper-RAG is a hypergraph-driven Retrieval-Augmented Generation (RAG) system designed to reduce LLM hallucinations by modeling beyond-pairwise correlations in domain knowledge. The repository provides both a Python library (`hyperrag`) and a full-stack web application with a FastAPI backend and React frontend. The core innovation is the use of hypergraphs to represent complex relationships among entities, outperforming traditional graph-based RAG methods like Graph RAG and Light RAG. The system supports multiple query modes: hyper (full hypergraph), hyper-lite, graph, naive, and direct LLM, with streaming responses. Architecture: The Python library (`hyperrag/`) implements the RAG pipeline: text chunking, entity extraction via LLM, hypergraph construction, vector embedding storage (NanoVectorDB), and query execution. The web UI (`web-ui/`) consists of a FastAPI backend (`main.py`) exposing REST endpoints for file upload, database CRUD, and HyperRAG queries, plus a React frontend with Ant Design and Graphin for interactive chat, hypergraph visualization, and settings management. Docker Compose orchestrates the frontend, backend, and Nginx reverse proxy. Key entry points: `hyperrag/hyperrag.py` (HyperRAG class), `service_api.py` (standalone API), `web-ui/backend/main.py` (FastAPI app). External dependencies include OpenAI/Azure/Bedrock LLM APIs, NanoVectorDB, tenacity, aiofiles, and various Python packages. The system is configurable via `config_temp.py` and `settings.json`. Data flows: Raw text (uploaded or provided) is chunked, entities and relationships are extracted via LLM, hyperedges are constructed, and embeddings are stored. Queries are processed by selecting relevant hyperedges and entities, constructing a context, and generating a response. The system caches LLM responses and supports real-time logging via WebSocket during embedding.
The LLM identified 4 files worth highlighting for reuse:
The main HyperRAG class that orchestrates the entire RAG pipeline: text insertion, entity extraction, hypergraph construction, vector storage, and multi-mode query execution. It provides a clean, async-first API (`insert`, `aquery`, `astream_query`) and is designed to be used as a standalone library. The class encapsulates all internal modules (storage, LLM, prompts) behind a simple interface, making it highly reusable for any RAG application.
Defines abstract base classes (`BaseKVStorage`, `BaseVectorStorage`, `BaseGraphStorage`) and concrete implementations (`JsonKVStorage`, `NanoVectorDBStorage`, `HypergraphStorage`) for persistent storage of knowledge graph data, vectors, and hypergraphs. The abstraction allows swapping storage backends without changing the core logic. The `HypergraphStorage` class manages vertices and hyperedges with JSON serialization, demonstrating a clean repository pattern for graph data.
A standalone hypergraph database implementation with CRUD operations for vertices and hyperedges, using pickle for persistence. It is fully self-contained (no internal imports from the rest of the project) and can be extracted and used in any Python project requiring hypergraph storage. The class provides methods for adding/removing vertices and hyperedges, querying by properties, and saving/loading from disk, making it a reusable data structure component.
A React component that visualizes the hypergraph retrieval results using Graphin (a graph visualization library). It displays vertices, hyperedges, and their relationships with interactive features like zoom, pan, and node selection. The component is self-contained, accepts data via props, and can be reused in any React application that needs to display hypergraph structures. It demonstrates clean separation of concerns and effective use of a graph visualization library.