Skip to content

README.md

Latest commit

 

History

History
207 lines (149 loc) · 6.63 KB

README.md

File metadata and controls

207 lines (149 loc) · 6.63 KB
Raw
H-RAG Logo
*Hierarchical Vector Compression & Topic-Guided Retrieval for RAG*

License Python 3.10+ CI Code style: ruff

A novel RAG architecture that organizes document chunks into a hierarchical topic-tree forest, enabling efficient top-down retrieval that mirrors how humans navigate knowledge — from broad topics to specific details.

Quick Start · How It Works · API Reference · Contributing · Paper

✨ Features

  • 🌲 Hierarchical Indexing — Builds a topic-tree forest from document embeddings using HDBSCAN clustering and saliency-weighted vector compression
  • ⚡ Efficient Retrieval — Top-down forest traversal with O(D + B·L) comparisons vs O(N) for flat search
  • 🔍 Topic-Guided Search — Prunes irrelevant topic branches early, focusing computation on the most relevant subtrees
  • 📊 Built-in Benchmarking — Compare hierarchical vs flat retrieval side-by-side with latency and accuracy metrics
  • 🤖 LLM Integration — Pluggable answer generation with Ollama (local) or extractive fallback
  • 📄 Multi-format Ingestion — Supports PDF, TXT, and Markdown documents out of the box

🏗 How It Works

graph TD
    A["📄 Documents"] --> B["✂️ Chunking"]
    B --> C["🔢 Embedding<br/>(sentence-transformers)"]
    C --> D["🧮 HDBSCAN Clustering"]
    D --> E["📐 Saliency-Weighted<br/>Compression"]
    E --> F{"More levels<br/>needed?"}
    F -->|Yes| D
    F -->|No| G["🌳 Topic-Tree<br/>Forest"]
    
    H["❓ Query"] --> I["🔢 Query Embedding"]
    I --> J["🔍 Top-Down<br/>Forest Traversal"]
    G --> J
    J --> K["📋 Retrieved<br/>Chunks"]
    K --> L["🤖 LLM Answer<br/>Generation"]
Loading

Architecture Overview

H-RAG implements a four-level hierarchy: Root → Topic → Subtopic → Leaf

Level Role Vector
Root Domain-level entry point Saliency-weighted mean of topic vectors
Topic Broad thematic cluster Compressed concept vector
Subtopic Fine-grained sub-theme Compressed concept vector
Leaf Original document chunk Raw embedding from encoder

At query time, the retriever performs a top-down BFS traversal:

  1. Score query against all root vectors → prune trees below threshold τ → keep top-B
  2. At each surviving node, score children → prune below τ → keep top-B
  3. Collect reached leaf nodes → rank by similarity → return top-k

🚀 Quick Start

Installation

# From source (recommended for development)
git clone https://github.com/AnasAmchaar/HRAG.git
cd H-RAG
pip install -e ".[dev]"

# From PyPI (coming soon)
# pip install humanized-rag

Basic Usage

CLI:

# Ingest documents
hrag ingest --source ./docs/

# Query the index
hrag query "What is semantic vector compression?"

# Compare hierarchical vs flat retrieval
hrag compare "How does topic-guided retrieval work?"

# View index statistics
hrag stats

Python API:

from hrag import HumanizedRAGPipeline

# Initialize and ingest
pipeline = HumanizedRAGPipeline()
pipeline.ingest(source="./docs/")

# Query
result = pipeline.query("What is semantic vector compression?")
print(result["answer"])

# Access retrieval details
for chunk in result["results"]:
    print(f"  [{chunk.score:.3f}] {chunk.text[:100]}...")

# View latency breakdown
print(result["latency"])

Configuration

All settings can be overridden via environment variables:

Variable Default Description
HRAG_EMBEDDING_MODEL all-mpnet-base-v2 Sentence-transformer model name
HRAG_CHUNK_SIZE 384 Target chunk size in tokens
HRAG_CHUNK_OVERLAP 0.15 Overlap ratio between chunks
HRAG_MAX_TREE_DEPTH 4 Maximum tree depth
HRAG_SIMILARITY_THRESHOLD 0.5 Pruning threshold (τ)
HRAG_BRANCHING_FACTOR 3 Max branches per level (B)
HRAG_TOP_K 5 Default number of results
HRAG_STORAGE_DIR ./storage Index storage directory
OLLAMA_BASE_URL http://localhost:11434 Ollama API endpoint
OLLAMA_MODEL llama3.2 Ollama model for generation

📖 API Reference

HumanizedRAGPipeline

The main interface for H-RAG:

from hrag import HumanizedRAGPipeline

pipeline = HumanizedRAGPipeline(index_path="./storage/forest_index.json")
Method Description
ingest(source, save=True) Ingest documents from file/directory and build the index
query(question, k=5, tau=0.5, B=3, use_ollama=True) Query the index and generate an answer
compare(question, k=5) Compare hierarchical vs flat retrieval
load_index() Load a previously saved index
stats() Return index statistics

Core Components

Class Description
TopicForest Forest of topic trees — the complete hierarchical index
TopicTree A single topic tree with a root node
TreeNode A node in the tree carrying a vector, level, and children
Embedder Wrapper around sentence-transformers
RetrievalResult A single result with text, score, and traversal path
Chunk A document chunk with metadata

🧪 Development

# Clone and install in development mode
git clone https://github.com/AnasAmchaar/HRAG.git
cd H-RAG
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check hrag/

# Run type checker
mypy hrag/

See CONTRIBUTING.md for the full development guide.

📄 Paper

This implementation is based on the paper:

"Toward Human-Inspired RAG: Hierarchical Vector Compression and Topic-Guided Retrieval"

If you use H-RAG in your research, please cite:

@article{hrag2026,
  title   = {Toward Human-Inspired RAG: Hierarchical Vector Compression and Topic-Guided Retrieval},
  year    = {2026},
}

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

📜 License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.