RAGx - Advanced Retrieval-Augmented Generation System

Table of Contents

Overview

Features

Core RAG Pipeline

Query Processing

Retrieval Strategies

Verification (CoVe)

Architecture

User Query
 |
 v
+------------------------------------------+
| 1. LINGUISTIC ANALYSIS (spaCy) |
| - POS tagging, dependency parsing |
| - Entity extraction, clause counting |
+------------------------------------------+
 |
 v
+------------------------------------------+
| 2. ADAPTIVE QUERY REWRITING (LLM) |
| - Query type detection |
| - Decomposition decision |
| - Sub-query generation |
+------------------------------------------+
 |
 +---------------+---------------+
 | | |
 [Simple] [Multihop]
 | |
 v v
+-------------+ +------------------------+
| Single | | Parallel Retrieval |
| Retrieval | | (per sub-query) |
+-------------+ +------------------------+
 | |
 v v
+-------------+ +------------------------+
| Standard | | Three-Stage Reranking: |
| Reranking | | 1. Local (per query) |
| | | 2. Fusion (by doc_id) |
| | | 3. Global (original Q) |
+-------------+ +------------------------+
 | |
 +-------+-------+
 |
 v
+------------------------------------------+
| 3. PROMPT ENGINEERING |
| - Template selection (basic/enhanced) |
| - Context formatting with metadata |
| - Language detection |
+------------------------------------------+
 |
 v
+------------------------------------------+
| 4. LLM GENERATION |
| - Multi-provider (HF/Ollama/vLLM/API) |
| - Chain-of-Thought reasoning |
| - Citation formatting |
+------------------------------------------+
 |
 v
+------------------------------------------+
| 5. CHAIN-OF-VERIFICATION (CoVe) |
| - Claim extraction |
| - NLI verification |
| - Correction and citation injection |
+------------------------------------------+
 |
 v
Final Answer + Sources + Metadata

Requirements

Development Environment

Production Environment (curtesy of Military University of Technology Cloud Laboratory)

Shared Configuration

Software Requirements

Installation

1. Clone Repository

git clone https://github.com/floressek/ragx.git
cd ragx

2. Install Dependencies

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

pip install -e .

make install

3. Install spaCy Models

python -m spacy download pl_core_news_md
python -m spacy download en_core_web_sm

4. Start Qdrant

docker-compose up -d qdrant

5. Configure Environment

cp .env.example .env
# Edit .env with your settings

Configuration

Environment Variables

# Vector Store
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=ragx_documents_v3
# Embeddings
EMBEDDING_MODEL=Alibaba-NLP/gte-multilingual-base
EMBEDDING_BATCH_SIZE=64
EMBEDDING_USE_PREFIXES=true
# Reranking
RERANKER_MODEL=jinaai/jina-reranker-v2-base-multilingual
RERANKER_BATCH_SIZE=16
# LLM Provider: huggingface | ollama | vllm | api
LLM_PROVIDER=huggingface
LLM_MODEL=Qwen/Qwen2.5-7B-Instruct
LLM_LOAD_IN_4BIT=true
LLM_TEMPERATURE=0.2
LLM_MAX_NEW_TOKENS=2000
# Ollama (alternative)
# LLM_PROVIDER=ollama
# OLLAMA_HOST=http://localhost:11434
# LLM_MODEL_NAME_OLLAMA=qwen3:4b
# vLLM (production)
# LLM_PROVIDER=vllm
# LLM_API_BASE_URL=http://localhost:8000/v1
# LLM_API_MODEL_NAME=Qwen/Qwen3-32B
# Query Rewriting
REWRITE_ENABLED=true
REWRITE_TEMPERATURE=0.2
REWRITE_MAX_TOKENS=4096
# Multihop Configuration
MULTIHOP_FUSION_STRATEGY=max
MULTIHOP_GLOBAL_RANKER_WEIGHT=0.6
MULTIHOP_TOP_K_PER_SUBQUERY=20
MULTIHOP_FINAL_TOP_K=10
# Retrieval Pipeline
TOP_K_RETRIEVE=100
RERANK_TOP_M=80
CONTEXT_TOP_N=8
# Chain-of-Verification
COVE_ENABLED=true
COVE_USE_BATCH_NLI=true

Configuration Files

Usage

Data Ingestion

# Download Polish Wikipedia dump
make download-wiki
# Extract articles
make extract-wiki
# Ingest to Qdrant (test - 1k articles)
make ingest-test
# Ingest full corpus (200k+ articles)
make ingest-full
# Custom ingestion
make ingest-custom MAX_ARTICLES=50000

API Server

# Start FastAPI server
make api
# Or with auto-reload for development
make api-dev
# Manual start
python -m uvicorn src.ragx.api.main:app --host 0.0.0.0 --port 8000

Interactive Chat UI

./launch_ui.sh
# Or directly
streamlit run src/ragx/ui/chat_app.py

Command Line

# Search
make search QUERY="sztuczna inteligencja"
# Check status
make status

API Reference

Endpoints

Example Requests

curl -X POST "http://localhost:8000/ask/baseline" \
 -H "Content-Type: application/json" \
 -d '{"query": "Co to jest sztuczna inteligencja?", "top_k": 5}'

curl -X POST "http://localhost:8000/ask/enhanced" \
 -H "Content-Type: application/json" \
 -d '{"query": "ziemniaki vs pomidory, co ma wiecej blonnika?"}'

curl -X POST "http://localhost:8000/eval/ablation" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "Kto zalozyl Krakow?",
 "top_k": 8,
 "query_analysis_enabled": true,
 "reranker_enabled": true,
 "cot_enabled": true,
 "cove_mode": "auto",
 "prompt_template": "auto"
 }'

Response Format

{
 "answer": "Answer text with citations [1][2]...",
 "sources": [
 {
 "id": "doc_id",
 "text": "Source text...",
 "doc_title": "Document Title",
 "retrieval_score": 0.85,
 "rerank_score": 0.92
 }
 ],
 "metadata": {
 "pipeline": "enhanced",
 "is_multihop": true,
 "sub_queries": ["sub-query 1", "sub-query 2"],
 "query_type": "comparison",
 "rewrite_time_ms": 450.2,
 "retrieval_time_ms": 25.8,
 "rerank_time_ms": 180.5,
 "llm_time_ms": 920.1,
 "cove_time_ms": 340.0,
 "total_time_ms": 1916.6
 }
}

Evaluation

Methodology

Why Synthetic Questions?

Test Set Generation

{
 "question": "Jak nazywa sie wspolnik do Neville'a Roundego?",
 "ground_truth": "Tekstor zostal przez Aldine...",
 "type": "simple",
 "source_title": "Neville'a...",
 "contexts": [
 "https://pl.wikipedia.org/wiki/Aldine#12661"
 ]
}

RAGAS Metrics

Running Evaluation

# Generate test questions (default: 1000)
make eval-generate NUM_QUESTIONS=1000
# Start RAG API server
make eval-api
# Run ablation study with checkpointing
make eval-run
# Resume interrupted evaluation
make eval-resume RUN_ID=study_20240115_143022
# Quick validation (10 questions, 3 configs)
make eval-quick
# Clean checkpoints and results
make eval-clean

Experimental Results

Ablation Study Results

Component Impact Analysis

Key Findings

Multihop Classification Distribution

Quality vs Latency Trade-off

Recommended Configurations

Project Structure

ragx/
├── src/ragx/
│ ├── api/ # FastAPI server
│ │ ├── routers/ # Endpoint handlers
│ │ ├── schemas/ # Pydantic models
│ │ ├── dependencies.py # Dependency injection
│ │ └── main.py # Application entry point
│ │
│ ├── ingestion/ # Data ingestion pipeline
│ │ ├── chunkers/ # Text chunking strategies
│ │ ├── pipelines/ # Ingestion orchestration
│ │ ├── extractions/ # Wikipedia extraction
│ │ └── utils/ # Ingestion utilities
│ │
│ ├── retrieval/ # Retrieval components
│ │ ├── embedder/ # Bi-encoder embeddings
│ │ ├── rerankers/ # Cross-encoder reranking
│ │ ├── analyzers/ # Linguistic analysis
│ │ ├── rewriters/ # Query rewriting
│ │ ├── cove/ # Chain-of-Verification
│ │ └── vector_stores/ # Qdrant integration
│ │
│ ├── pipelines/ # RAG pipelines
│ │ ├── base.py # Abstract base
│ │ ├── baseline.py # Simple RAG
│ │ ├── enhanced.py # Full pipeline
│ │ └── enhancers/ # Pipeline enhancers
│ │
│ ├── generation/ # LLM generation
│ │ ├── inference.py # Multi-provider inference
│ │ ├── providers/ # Provider implementations
│ │ └── prompts/ # Prompt templates
│ │
│ ├── ui/ # Streamlit chat interface -> claude generated, beta testing.
│ │ ├── chat_app.py # Main application
│ │ ├── components/ # UI components
│ │ └── config/ # UI configuration
│ │
│ └── utils/ # Shared utilities
│ ├── settings.py # Configuration management
│ ├── logging_config.py # Logging setup
│ └── model_registry.py # Model caching
│
├── configs/ # Configuration files
├── data/ # Data directory
│ ├── raw/ # Raw Wikipedia dumps
│ ├── processed/ # Extracted articles
│ └── db_snapshots/ # Qdrant snapshots
├── scripts/ # Utility scripts
├── results/ # Evaluation results
├── docker-compose.yml # Docker services
├── Makefile # Build commands
├── pyproject.toml # Project dependencies
└── README.md

License

References

Papers

Libraries

Models