Loading repository data…
BdTaha / repository
Privacy-first RAG platform combining semantic vector search, knowledge graph traversal, and a Q-Learning routing agent for intelligent, grounded question answering over domain-specific documents, built with FastAPI, React, and Neo4j.
A production-grade, privacy-first Retrieval-Augmented Generation system integrating Semantic Vector Search, Knowledge Graph Traversal, and a Q-Learning Routing Agent for intelligent, adaptive query orchestration.
Final Year Engineering Project — EMSI, École Marocaine des Sciences de l'Ingénieur Specialization: Artificial Intelligence & Data Science | Academic Year 2025–2026
Large Language Models are powerful — but structurally flawed for high-stakes, knowledge-intensive applications. They hallucinate, go stale at their training cutoff, and provide no source attribution. In regulated domains like medicine, law, or enterprise, this is a non-starter.
This project solves that problem with a multi-paradigm Retrieval-Augmented Generation platform that goes far beyond standard vector search. The architecture integrates three complementary retrieval paradigms within a single, unified system:
Vector RAG — semantic similarity search using dense embeddings and FAISS indexing.
Graph RAG — structured entity-relationship traversal using a locally-built knowledge graph synced to Neo4j Aura.
Agentic RAG — a Q-Learning agent that learns, from interaction rewards, which retrieval strategy to deploy for each query.
Rather than relying on static routing rules, the system features a Q-Learning agent acting as an intelligent meta-router. It extracts query features (semantic density, relational structure, length) and autonomously selects the optimal retrieval configuration — then continuously improves its policy through an epsilon-greedy exploration loop.
The result: a system that halves hallucination rates, surfaces structured relational knowledge, and adapts intelligently to query complexity.
The platform is organized across four interconnected layers:
┌──────────────────────────────────────────────────────────────┐
│ Presentation Layer (React 18 + Vite) │
│ ChatInterface · SourcePanel · GraphViz · Agent Policy View │
└─────────────────────────┬────────────────────────────────────┘
│ REST / JSON
┌─────────────────────────▼────────────────────────────────────┐
│ API Gateway (FastAPI + Pydantic v2) │
│ Async routing · Validation · CORS · Lifecycle hooks │
└────────────┬────────────────────────────┬────────────────────┘
│ │
┌────────────▼──────────────┐ ┌──────────▼──────────────────┐
│ Core AI Services │ │ Agentic Routing Layer │
│ EmbeddingService │ │ Q-Learning Agent │
│ ChunkingService │ │ 8-state ε-greedy policy │
│ RetrievalService │ │ Reward function tuning │
│ LLMService (FLAN-T5) │ │ Continuous policy update │
│ GraphService │ └─────────────────────────────┘
│ PromptService │
└────────────┬──────────────┘
│
┌────────────▼──────────────────────────────────────────────┐
│ Infrastructure Layer │
│ FAISS Vector Store · NetworkX Graph · Neo4j Aura (Bolt) │
└───────────────────────────────────────────────────────────┘
Handles dense unstructured retrieval with five fallback strategies:
| Strategy | Method | Description |
|---|---|---|
| Brute-force Similarity | Vector | Cosine search via FAISS |
| BM25 | Lexical | Term-frequency exact matching |
| DPR | Dense | Dense Passage Retrieval |
| Hybrid | Combined | BM25 (40%) + Vector (60%) with RRF fusion |
| Re-ranking | Two-stage | Initial retrieval + cross-encoder re-scoring |
Embedding Backbone: sentence-transformers/all-MiniLM-L6-v2 · GloVe · BERT · Word2Vec · TF-IDF · Instructor · OpenAI
Chunking Strategies (7): Fixed-size · Sentence-based · Paragraph-based · Semantic Similarity · Sliding Window · Recursive Splitting · Markdown/Structure
Transforms unstructured text into traversable relational structures for multi-hop queries.
flan-t5-large (local inference) extracts entities and relationships, with regex fallback.Concept, Entity, Document. Edge types — RELATED_TO, PART_OF, IS_A, CO_OCCURS.The cognitive core of the system — an RL agent that learns optimal retrieval routing.
| Component | Details |
|---|---|
| State Space | 8 states (semantic score × systematic score × query length) |
| Action Space | use_graph · use_vector_bm25 · use_vector_similarity · use_vector_hybrid · use_vector_rerank · fallback |
| Reward Signal | +1 for confident, relevant answers · −1 for errors or out-of-context |
| Learning Rate (α) | 0.1 |
| Discount Factor (γ) | 0.9 |
| Exploration Rate (ε) | 0.05 (ε-greedy) |
Based on benchmarking across 1,145 text vectors, the system auto-selects the optimal pipeline configuration on document ingestion (Note: These are preliminary offline benchmark results; full API integration is currently scheduled for Phase 4 of the roadmap):
Backend
| Technology | Role |
|---|---|
| FastAPI 0.115 | Async REST API gateway |
| FLAN-T5-Large (HuggingFace) | Local LLM inference (entity extraction + answer generation) |
| Sentence Transformers | Dense embedding generation |
| FAISS | Vector store & ANN search |
| NetworkX | In-memory knowledge graph |
| Neo4j Aura (Bolt/SSL) | Cloud graph database & Cypher query engine |
| spaCy / NLTK | NLP pipelines for text processing |
| LangChain / LangGraph | LLM orchestration utilities |
| rank-bm25 | Lexical keyword retrieval |
Frontend
| Technology | Role |
|---|---|
| React 18 + Vite | Component-based UI |
| react-force-graph-2d | Force-directed knowledge graph visualization |
| Recharts | Q-Table & reward history analytics |
| Vanilla CSS | Custom Design System styling |
| Axios | Typed HTTP client |
Evaluated on a benchmark of 152 query-answer pairs across 4 query categories, over 18 domain documents.
| Retrieval Mode | Factual Lookup | Conceptual | Multi-Entity | Cross-Document |
|---|---|---|---|---|
| Vector Only | 0.74 | 0.71 | 0.58 | 0.52 |
| Hybrid (BM25 + Vector) | 0.79 | 0.75 | 0.63 | 0.57 |
| Graph RAG | 0.65 | 0.69 | 0.74 | 0.63 |
| Agentic RAG | 0.76 | 0.78 | 0.72 | 0.81 |
| Retrieval Mode | Relevance | Faithfulness | Completeness |
|---|---|---|---|
| Vector | 4.1 | 4.2 | 3.7 |
| Hybrid | 4.3 | 4.4 | 3.9 |
| Graph | 4.0 | 4.3 | 4.1 |
| Agentic | 4.5 | 4.5 | 4.4 |
| Mode | Median Latency |
|---|---|
| Vector | ~2.1s |
| Hybrid | ~2.4s |
| Graph | ~3.2s |
| Agentic | ~8.5s |
LLM API inference accounts for ~65–75% of total latency across all modes.
1. Clone the repository
git clone [https://github.com/yourusername/Agentic-Vectorial-Graph-RAG.git](https://github.com/yourusername/Agentic-Vectorial-Graph-RAG.git)
cd Agentic-Vectorial-Graph-RAG
2. Configure environment variables
cd backend
cp .env.example .env
Open .env and fill in your credentials:
# LLM APIs (optional — system runs locally without these)
GOOGLE_API_KEY="your_gemini_key"
OPENAI_API_KEY="your_openai_key"
# Neo4j Graph Database
NEO4J_URI="neo4j+s://your-instance.databases.neo4j.io"
NEO4J_USER="neo4j"
NEO4J_PASSWORD="your_password"
Terminal 1 (Backend):
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
Terminal 2 (Frontend):
cd frontend
npm install
npm run dev
Navigate to http://localhost:5173
cd backend
docker build -t rag-backend .
docker run -p 8000:8000 --env-file .env rag-backend
The platform is divided into four operational panels:
| Panel | Description |
|---|---|
| Query Panel | Submit natural language queries. View real-time routing confidence (e.g., "Graph RAG — 92%") and retrieved source passages. |
| Vectorial RAG Panel | Visualize chunking strategies, 2D PCA embedding clusters, and manually test all 5 retrieval methods. |
Selected from shared topics, language and repository description—not editorial ratings.
Jayaragul /
⚡ A privacy-first, local AI platform with Agentic capabilities (Web Search, RAG, Tools). Runs entirely offline using Ollama & FastAPI. 🦙🔒