Graph-RAG Engine 🕸️⚡

A production-grade Hybrid Retrieval-Augmented Generation (Graph-RAG) engine combining Knowledge Graph Traversal (Neo4j) with Dense Semantic Vector Search (HuggingFace Embeddings) and Ultra-Fast LLM Reasoning (Groq Cloud).

Designed specifically for complex multi-hop reasoning over unstructured cloud infrastructure topology, IAM permission boundaries, and cybersecurity threat vectors (e.g., CVE dependency attack chains).

---

🚀 Key Highlights & Architecture

Traditional Vector-only RAG systems perform similarity matching on isolated text chunks, failing to resolve multi-step relationship chains ($A \rightarrow B \rightarrow C$). Graph-RAG Engine extracts entity-relation triples directly into a property graph database and executes unified hybrid retrieval to reason across non-adjacent dependencies.

                  +------------------------+
                  | Raw Text Documentation |
                  +-----------+------------+
                              | (Groq LLM Entity & Relation Extraction)
                              v
        +-------------------------------------------+
        |       Neo4j Knowledge Graph Storage       |
        +---------------------+---------------------+
        |  Graph Nodes/Edges  | Dense Vector Index  |
        +----------+----------+----------+----------+
                   |                     |
  Multi-Hop Cypher |                     | Cosine Similarity (all-MiniLM-L6-v2)
  Traversal Paths  |                     | Top-K Seed Entities
                   v                     v
        +-------------------------------------------+
        |          Hybrid Context Fusion            |
        +---------------------+---------------------+
                              |
                              v
        +-------------------------------------------+
        |     LLM Synthesis & Reasoning (Groq)      |
        +-------------------------------------------+

• Domain Schema: Nodes (Service, Role, Policy, Vulnerability, Resource) and Edges (ATTACHED_TO, PERMITS, TARGETS, DEPENDS_ON, EXPOSES).
• Multi-Hop Traversal: Resolves path connections up to 4 hops deep using native Cypher pattern matching.
• Interactive 2D Visualization: Dynamic, physics-based network topology rendering via Pyvis inside a Streamlit web interface.
• Rich CLI Telemetry: Formatted terminal outputs, progress steps, and relation tables powered by rich.

---

🛠️ Tech Stack

• Language & Runtime: Python 3.10+
• Graph Database: Neo4j Community Edition 5.20 (via Docker)
• LLM & Inference: Groq Cloud API (openai/gpt-oss-120b, qwen/qwen3.8-27b, llama-3.3-70b-versatile)
• Vector Store & Embeddings: Neo4j Vector Index + HuggingFace all-MiniLM-L6-v2
• Visualization & Frontend: Streamlit, Pyvis Interactive Network
• Telemetry & CLI: Rich

---

📁 Repository Structure

graph-rag-engine/
├── assets/               # Dashboard preview and UI media
├── app.py                # Interactive Streamlit Web UI Dashboard
├── docker-compose.yml    # Neo4j Container with APOC plugins
├── main.py               # Headless CLI execution & rich logging
├── requirements.txt      # Python dependencies
├── .env.example          # Environment variable template
├── data/
│   └── sample_docs.txt   # Multi-hop cloud & vulnerability dataset
└── src/
    ├── __init__.py
    ├── extractor.py      # LLM-based entity & relation triple extractor
    ├── graph_db.py       # Neo4j connection pool and DB reset operations
    ├── logger.py         # Rich CLI telemetry, tables, and panels
    ├── retriever.py      # Hybrid (Vector + Cypher Traversal) engine
    └── visualizer.py     # Pyvis 2D network generation module

---

⚡ Quickstart Guide

1. Clone & Configure Environment

git clone https://github.com/ekrmcakir/graph-rag-engine.git
cd graph-rag-engine

cp .env.example .env

Configure your credentials in .env:

GROQ_API_KEY=gsk_your_groq_api_key_here
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=graphragpassword

Get your free Groq API key from Groq Console.

2. Launch Neo4j Infrastructure

Run the database container in the background:

docker compose up -d

Neo4j Browser will be available at http://localhost:7474 (Auth: neo4j / graphragpassword).

3. Install Dependencies

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

---

💻 Usage Modes

Option A: Interactive Web Dashboard (Streamlit)

Launch the visual interface to inspect nodes, drag graph structures, and run dynamic queries:

streamlit run app.py

Open http://localhost:8501 in your browser.

---

Option B: Headless CLI Mode

Run the automated pipeline with full terminal logging:

python main.py

---

🧪 Example Multi-Hop Reasoning Query

Query:

"Which S3 bucket is indirectly put at risk by vulnerability CVE-2024-3094?"

Traversed Graph Path:

CVE-2024-3094 
  --[TARGETS]--> PaymentService 
  --[ATTACHED_TO]--> PaymentAdminRole 
  --[ATTACHED_TO]--> S3AccessPolicy 
  --[PERMITS]--> ProductionDataS3

Synthesized Resolution:

The ProductionDataS3 bucket is identified as the indirect target of CVE-2024-3094 via the propagation path of the associated IAM role and permission policy.

---

🔒 License

MIT License. Open source and built for security & cloud infrastructure research.