README.md

metadata

title: AtlasRAG Backend
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: mit

AtlasRAG

Hybrid Graph-Augmented Retrieval-Augmented Generation System

AtlasRAG is a production-ready document summarization and question-answering system that combines vector search, graph-based reasoning, and LLM-based generation to enable grounded, citation-aware responses over uploaded documents.

The system goes beyond naive vector similarity by incorporating concept co-occurrence graphs, enabling improved contextual coverage for complex, multi-section queries.

Live Demo →

---

✨ Features

• 📄 PDF Upload & Ingestion – Seamless document processing
• 🧠 Hybrid Retrieval Pipeline
  • Dense vector similarity search
  • BM25 keyword search
  • Concept co-occurrence graph expansion
• 💬 Unified Chat Interface – Question answering and full-document summarization
• 📚 Citation-Aware Responses – Grounded answers with source attribution
• 🧩 Conversation Memory – Short-term context retention across turns
• ✏️ Query Rewriting – Context-aware reformulation using chat history
• ⚡ Token Limit Protection – Automatic document size validation to prevent API errors
• 🔍 Evaluation Framework – Built-in retrieval quality assessment
• 🧪 Ablation Studies – Baseline comparisons and performance validation

---

🏗️ System Architecture

PDF Document
    ↓
Chunking & Parsing
    ↓
Embeddings Generation → Vector Index
    ↓
Concept Extraction → Co-occurrence Graph
    ↓
Hybrid Graph-RAG Retrieval
    ↓
Context Assembly & Prompt Construction
    ↓
LLM Generation
    ↓
Answer + Citations

---

🔍 Retrieval Strategy

AtlasRAG employs a three-stage hybrid retrieval pipeline:

1. Vector Search

Dense embeddings using sentence transformers for semantic similarity.

2. Lexical Search

BM25 scoring for keyword-based anchoring and exact term matching.

3. Graph Expansion

• Nodes: Extracted concepts from document chunks
• Edges: Co-occurrence relationships within the corpus
• Purpose: Expand retrieval to conceptually related sections

The graph augments (rather than replaces) traditional vector retrieval, providing structural context for multi-hop queries.

---

📊 Evaluation

Evaluation Corpus

All evaluations were conducted using:

"Attention Is All You Need" by Vaswani et al.

Rationale:

• Dense conceptual structure with cross-section dependencies
• Well-defined technical terminology
• Requires multi-hop reasoning for comprehensive answers
• Reflects real-world academic document QA scenarios

Query Types

The evaluation suite includes manually designed queries mapped to expected document pages:

• Localized queries – Single-concept retrieval
  Example: "What is scaled dot-product attention?"

• Distributed queries – Multi-section synthesis
  Example: "How does self-attention replace recurrence and convolution?"

• Comparative queries – Cross-concept analysis
  Example: "Compare encoder, decoder, and encoder-decoder architectures"

Metrics

• Recall@5 – Percentage of queries with at least one relevant page retrieved
• Coverage – Number of unique relevant pages retrieved
• Diversity – Fraction of unique pages in the retrieved set

Note: Precision was intentionally de-emphasized due to small K values and page-level evaluation granularity.

---

📈 Results

Baseline Comparison: Vector Search vs. Hybrid Graph-RAG

Key Findings:

• Recall@5 = 1.00 across all evaluated queries for both methods

  • Both approaches reliably retrieve relevant information

• Coverage & Diversity

  • Comparable performance between vector-only and hybrid retrieval
  • Hybrid Graph-RAG occasionally surfaces conceptually adjacent sections
  • No degradation introduced by graph expansion

Interpretation:
The graph component does not harm retrieval quality and provides a structural foundation for improvements on larger, more fragmented corpora.

Ablation Study

Isolated evaluation of graph reasoning impact:

• Vector Only
• Vector + Graph Expansion

Results:

• Recall, coverage, and diversity remained stable across configurations
• Graph augmentation introduces no noise or degradation
• Validates the architectural safety of hybrid approach for production use

---

🧠 Conversation Memory & Query Rewriting

• Short-term memory maintains recent conversation turns
• Context-aware rewriting reformulates follow-up queries using chat history
• Enables natural conversational flow without polluting the retrieval pipeline

---

🛠️ Tech Stack

Backend

• FastAPI
• LangChain (optional integration)
• Qdrant / Vector Store
• NetworkX (graph reasoning)
• Sentence Transformers
• Groq / OpenAI-compatible LLM APIs

Frontend

• Next.js
• Modern chat-style UI
• PDF upload interface

Development & Deployment

• Ruff (formatting & linting)
• Pre-commit hooks
• Docker
• Hugging Face Spaces (backend)
• Vercel (frontend)

---

🚀 Getting Started

Prerequisites

• Python 3.9+
• Node.js 18+
• Git

Clone Repository

git clone https://github.com/sanskarmodi8/Atlas-RAG
cd Atlas-RAG

Backend Setup

cd backend
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .
uvicorn app.main:app --reload

Backend runs at: http://127.0.0.1:8000

Frontend Setup

cd frontend
npm install
npm run dev

Frontend runs at: http://localhost:3000

---

🧹 Code Quality

This project enforces strict code quality standards.

Install Pre-commit Hooks

pre-commit install

Format & Lint

ruff check .
ruff format .

All code complies with:

• Ruff linting rules
• Black-style formatting
• Pre-commit validation

---

🌐 Deployment

Production Instances

• Frontend: https://atlas-rag.vercel.app/
  Deployed on Vercel

• Backend API: https://sanskarmodi-atlasrag-backend.hf.space/
  Deployed on Hugging Face Spaces

Binary document files are excluded from version control and handled at runtime.

---

📄 License

This project is licensed under the MIT License.
See the LICENSE file for details.

---

👤 Author

Sanskar Modi
GitHub: @sanskarmodi8

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📧 Contact

For questions or feedback, please open an issue on GitHub.