feat: implement GraphRAG Phase 1 backend service layer and test suite

.env.example

@@ -0,0 +1,21 @@
+# Django Configuration
+SECRET_KEY=django-insecure-change-this-in-production-use-a-strong-random-key
+DEBUG=True
+ALLOWED_HOSTS=localhost,127.0.0.1,backend
+
+# Neo4j Graph Database Configuration
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USERNAME=neo4j
+NEO4J_PASSWORD=password
+
+# Vector DB Configuration
+CHROMADB_DIR=chroma_db
+
+# LLM Providers API Keys (Fill in at least one)
+GROQ_API_KEY=your_groq_api_key_here
+GOOGLE_API_KEY=your_gemini_api_key_here
+
+# LangSmith Observability & Tracing (Optional)
+LANGCHAIN_TRACING_V2=false
+LANGCHAIN_API_KEY=your_langsmith_api_key_here
+LANGCHAIN_PROJECT=graphrag-knowledge-ai

.gitignore

@@ -0,0 +1,44 @@
+# Python / Django
+__pycache__/
+*.py[cod]
+*$py.class
+*.sqlite3
+backend/db/
+backend/logs/
+
+# Environments & sensitive files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+venv/
+env/
+ENV/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Project uploads
+uploaded_documents/
+
+# Frontend
+node_modules/
+.next/
+out/
+build/
+dist/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Local design / agent files (Not for GitHub)
+Z111.Learning.md
+Phase_3_Frontend_Plan.md
+Phase_1_Specification.md
+Agent.md
+Agent/
+UX_SPECIFICATION.md
+Assignment_10_GraphRAG_Knowledge_Graph_AI.md

backend/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.11-slim
+
+# Prevent Python from writing .pyc files and enable unbuffered logging
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install python dependencies
+COPY requirements.txt /app/
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy backend codebase
+COPY . /app/
+
+EXPOSE 8000
+
+# Default command
+CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

backend/config/settings.py

@@ -0,0 +1,188 @@
+import os
+from pathlib import Path
+from datetime import timedelta
+import dotenv
+
+# Build paths inside the project like this: BASE_DIR / 'subdir'.
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+# Load environment variables from parent directory .env
+ENV_PATH = BASE_DIR.parent / '.env'
+if ENV_PATH.exists():
+    dotenv.load_dotenv(ENV_PATH)
+
+# Security settings
+SECRET_KEY = os.getenv('SECRET_KEY', 'django-insecure-fallback-secret-key-change-in-prod')
+DEBUG = os.getenv('DEBUG', 'True') == 'True'
+ALLOWED_HOSTS = [h.strip() for h in os.getenv('ALLOWED_HOSTS', 'localhost,127.0.0.1').split(',') if h.strip()]
+
+# Application definition
+INSTALLED_APPS = [
+    'django.contrib.admin',
+    'django.contrib.auth',
+    'django.contrib.contenttypes',
+    'django.contrib.sessions',
+    'django.contrib.messages',
+    'django.contrib.staticfiles',
+    
+    # Third party apps
+    'rest_framework',
+    'corsheaders',
+    
+    # Custom apps
+    'graphrag',
+]
+
+MIDDLEWARE = [
+    'corsheaders.middleware.CorsMiddleware',  # Must be placed high up
+    'django.middleware.security.SecurityMiddleware',
+    'django.contrib.sessions.middleware.SessionMiddleware',
+    'django.middleware.common.CommonMiddleware',
+    'django.middleware.csrf.CsrfViewMiddleware',
+    'django.contrib.auth.middleware.AuthenticationMiddleware',
+    'django.contrib.messages.middleware.MessageMiddleware',
+    'django.middleware.clickjacking.XFrameOptionsMiddleware',
+]
+
+ROOT_URLCONF = 'config.urls'
+
+TEMPLATES = [
+    {
+        'BACKEND': 'django.template.backends.django.DjangoTemplates',
+        'DIRS': [],
+        'APP_DIRS': True,
+        'OPTIONS': {
+            'context_processors': [
+                'django.template.context_processors.debug',
+                'django.template.context_processors.request',
+                'django.contrib.auth.context_processors.auth',
+                'django.contrib.messages.context_processors.messages',
+            ],
+        },
+    },
+]
+
+WSGI_APPLICATION = 'config.wsgi.application'
+
+# Database configuration (SQLite for Django metadata store)
+DATABASES = {
+    'default': {
+        'ENGINE': 'django.db.backends.sqlite3',
+        'NAME': BASE_DIR / 'db.sqlite3',
+    }
+}
+
+# Custom User Model
+AUTH_USER_MODEL = 'graphrag.User'
+
+# Password validation
+AUTH_PASSWORD_VALIDATORS = [
+    {
+        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+        'OPTIONS': {
+            'min_length': 8,
+        }
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
+    },
+]
+
+# Internationalization
+LANGUAGE_CODE = 'en-us'
+TIME_ZONE = 'UTC'
+USE_I18N = True
+USE_TZ = True
+
+# Static files (CSS, JavaScript, Images)
+STATIC_URL = 'static/'
+
+DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'
+
+# CORS configuration
+CORS_ALLOW_ALL_ORIGINS = True  # In development; tighten in production
+
+# Django REST Framework configuration
+REST_FRAMEWORK = {
+    'DEFAULT_AUTHENTICATION_CLASSES': (
+        'rest_framework_simplejwt.authentication.JWTAuthentication',
+    ),
+    'DEFAULT_PERMISSION_CLASSES': (
+        'rest_framework.permissions.IsAuthenticated',
+    ),
+}
+
+# Simple JWT settings
+SIMPLE_JWT = {
+    'ACCESS_TOKEN_LIFETIME': timedelta(days=1),
+    'REFRESH_TOKEN_LIFETIME': timedelta(days=7),
+    'ROTATE_REFRESH_TOKENS': False,
+    'BLACKLIST_AFTER_ROTATION': False,
+    'ALGORITHM': 'HS256',
+    'SIGNING_KEY': SECRET_KEY,
+    'VERIFYING_KEY': None,
+    'AUDIENCE': None,
+    'ISSUER': None,
+    'AUTH_HEADER_TYPES': ('Bearer',),
+    'USER_ID_FIELD': 'id',
+    'USER_ID_CLAIM': 'user_id',
+    'AUTH_TOKEN_CLASSES': ('rest_framework_simplejwt.tokens.AccessToken',),
+}
+
+# Graph Database (Neo4j) settings
+NEO4J_URI = os.getenv('NEO4J_URI', 'bolt://localhost:7687')
+NEO4J_USERNAME = os.getenv('NEO4J_USERNAME', 'neo4j')
+NEO4J_PASSWORD = os.getenv('NEO4J_PASSWORD', 'password')
+
+# ChromaDB settings
+CHROMADB_DIR = os.path.join(BASE_DIR, os.getenv('CHROMADB_DIR', 'chroma_db'))
+
+# Logging Configuration
+LOG_DIR = BASE_DIR / 'logs'
+LOG_DIR.mkdir(exist_ok=True)
+
+LOGGING = {
+    'version': 1,
+    'disable_existing_loggers': False,
+    'formatters': {
+        'detailed': {
+            'format': '%(asctime)s [%(levelname)s] %(name)s:%(lineno)d - %(message)s'
+        },
+        'simple': {
+            'format': '[%(levelname)s] %(message)s'
+        },
+    },
+    'handlers': {
+        'console': {
+            'class': 'logging.StreamHandler',
+            'formatter': 'detailed',
+        },
+        'file': {
+            'class': 'logging.FileHandler',
+            'filename': LOG_DIR / 'graphrag.log',
+            'formatter': 'detailed',
+        },
+    },
+    'loggers': {
+        '': {
+            'handlers': ['console', 'file'],
+            'level': 'INFO',
+        },
+        'django': {
+            'handlers': ['console', 'file'],
+            'level': 'INFO',
+            'propagate': False,
+        },
+        'graphrag': {
+            'handlers': ['console', 'file'],
+            'level': 'DEBUG',
+            'propagate': False,
+        },
+    },
+}

backend/config/urls.py

@@ -0,0 +1,10 @@
+from django.contrib import admin
+from django.urls import path, include
+
+urlpatterns = [
+    # Built-in Django Admin Interface
+    path('admin/', admin.site.urls),
+    
+    # Delegating all /api/ traffic to the graphrag sub-app
+    path('api/', include('graphrag.urls')),
+]

backend/graphrag/__init__.py

@@ -0,0 +1 @@
+# Initializer for graphrag package

backend/graphrag/migrations/0001_initial.py

@@ -0,0 +1,91 @@
+# Generated by Django 4.2.30 on 2026-07-08 09:01
+
+from django.conf import settings
+import django.contrib.auth.models
+import django.contrib.auth.validators
+from django.db import migrations, models
+import django.db.models.deletion
+import django.utils.timezone
+import uuid
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('auth', '0012_alter_user_first_name_max_length'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='User',
+            fields=[
+                ('password', models.CharField(max_length=128, verbose_name='password')),
+                ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+                ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+                ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+                ('email', models.EmailField(blank=True, max_length=254, verbose_name='email address')),
+                ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+                ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+                ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
+            ],
+            options={
+                'verbose_name': 'user',
+                'verbose_name_plural': 'users',
+                'abstract': False,
+            },
+            managers=[
+                ('objects', django.contrib.auth.models.UserManager()),
+            ],
+        ),
+        migrations.CreateModel(
+            name='QueryLog',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('query_text', models.TextField()),
+                ('retrieval_mode', models.CharField(choices=[('GRAPH', 'Graph Only'), ('VECTOR', 'Vector Only'), ('HYBRID', 'Hybrid')], default='HYBRID', max_length=20)),
+                ('answer_text', models.TextField()),
+                ('response_time', models.FloatField(help_text='Response time in seconds')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='query_logs', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-created_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='EvaluationPair',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('question', models.TextField()),
+                ('expected_answer', models.TextField()),
+                ('is_active', models.BooleanField(default=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='evaluation_pairs', to=settings.AUTH_USER_MODEL)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Document',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('name', models.CharField(max_length=255)),
+                ('file', models.FileField(upload_to='uploaded_documents/')),
+                ('status', models.CharField(choices=[('PENDING', 'Pending'), ('PROCESSING', 'Processing'), ('COMPLETED', 'Completed'), ('FAILED', 'Failed')], default='PENDING', max_length=20)),
+                ('entity_count', models.IntegerField(default=0)),
+                ('relationship_count', models.IntegerField(default=0)),
+                ('error_message', models.TextField(blank=True, null=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='documents', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-created_at'],
+            },
+        ),
+    ]

backend/graphrag/models.py

@@ -0,0 +1,101 @@
+import uuid
+from django.db import models
+from django.contrib.auth.models import AbstractUser
+from django.conf import settings
+
+class User(AbstractUser):
+    """
+    Custom User Model to allow for seamless future attribute additions 
+    without database schema breakage. Uses UUID as the primary key.
+    """
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    def __str__(self):
+        return self.username
+
+
+class Document(models.Model):
+    """
+    Tracks uploaded documents, ingestion status, metadata, and error details.
+    """
+    class Status(models.TextChoices):
+        PENDING = 'PENDING', 'Pending'
+        PROCESSING = 'PROCESSING', 'Processing'
+        COMPLETED = 'COMPLETED', 'Completed'
+        FAILED = 'FAILED', 'Failed'
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL, 
+        on_delete=models.CASCADE, 
+        related_name='documents'
+    )
+    name = models.CharField(max_length=255)
+    file = models.FileField(upload_to='uploaded_documents/')
+    status = models.CharField(
+        max_length=20, 
+        choices=Status.choices, 
+        default=Status.PENDING
+    )
+    entity_count = models.IntegerField(default=0)
+    relationship_count = models.IntegerField(default=0)
+    error_message = models.TextField(blank=True, null=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ['-created_at']
+
+    def __str__(self):
+        return f"{self.name} ({self.status})"
+
+
+class QueryLog(models.Model):
+    """
+    Logs queries, selected retrieval strategies, generated answers, and response times.
+    """
+    class RetrievalMode(models.TextChoices):
+        GRAPH = 'GRAPH', 'Graph Only'
+        VECTOR = 'VECTOR', 'Vector Only'
+        HYBRID = 'HYBRID', 'Hybrid'
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL, 
+        on_delete=models.CASCADE, 
+        related_name='query_logs'
+    )
+    query_text = models.TextField()
+    retrieval_mode = models.CharField(
+        max_length=20, 
+        choices=RetrievalMode.choices, 
+        default=RetrievalMode.HYBRID
+    )
+    answer_text = models.TextField()
+    response_time = models.FloatField(help_text="Response time in seconds")
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ['-created_at']
+
+    def __str__(self):
+        return f"Query: {self.query_text[:30]}... ({self.retrieval_mode})"
+
+
+class EvaluationPair(models.Model):
+    """
+    Stores target question-answer evaluation pairs to compute metrics against.
+    """
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL, 
+        on_delete=models.CASCADE, 
+        related_name='evaluation_pairs'
+    )
+    question = models.TextField()
+    expected_answer = models.TextField()
+    is_active = models.BooleanField(default=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return f"Question: {self.question[:40]}..."

backend/graphrag/serializers.py

@@ -0,0 +1,116 @@
+import re
+import logging
+from rest_framework import serializers
+from django.contrib.auth import get_user_model
+from django.contrib.auth.password_validation import validate_password
+from .models import Document, QueryLog, EvaluationPair
+
+logger = logging.getLogger(__name__)
+User = get_user_model()
+
+
+DISPOSABLE_DOMAINS = {
+    'mailinator.com', 'yopmail.com', 'tempmail.com', 'temp-mail.org', 
+    '10minutemail.com', 'guerrillamail.com', 'trashmail.com'
+}
+
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ('id', 'username', 'email')
+
+class RegisterSerializer(serializers.ModelSerializer):
+    password = serializers.CharField(write_only=True, required=True, style={'input_type': 'password'})
+    confirm_password = serializers.CharField(write_only=True, required=True, style={'input_type': 'password'})
+
+    class Meta:
+        model = User
+        fields = ('id', 'username', 'email', 'password', 'confirm_password')
+
+    def create(self, validated_data):
+        validated_data.pop('confirm_password')
+        return User.objects.create_user(**validated_data)
+    def validate_email(self, value):
+        logger.debug("Validating email: %s", value)
+        
+        # 1. Format normalization
+        value = value.strip().lower()
+        
+        # 2. Extract and check domain
+        try:
+            domain = value.split('@')[1]
+        except IndexError:
+            raise serializers.ValidationError("Invalid email address format.")
+            
+        if domain in DISPOSABLE_DOMAINS:
+            logger.warning("Blocked attempt to register with fake/disposable email domain: %s", domain)
+            raise serializers.ValidationError("Disposable or temporary email accounts are not permitted.")
+            
+        # 3. Check for uniqueness
+        if User.objects.filter(email=value).exists():
+            logger.warning("Registration failed - email already exists: %s", value)
+            raise serializers.ValidationError("A user with this email already exists.")
+            
+        return value
+        
+    def validate(self, attrs):
+        logger.debug("Checking password policies and password matching...")
+        password = attrs.get('password')
+        confirm_password = attrs.get('confirm_password')
+        # 1. Verify match
+        if password != confirm_password:
+            raise serializers.ValidationError({"password": "Passwords do not match."})
+        # 2. Custom Strict Character Check (Uppercase, Lowercase, Number, Special Char)
+        if not re.search(r"[A-Z]", password):
+            raise serializers.ValidationError({"password": "Password must contain at least one uppercase letter."})
+        if not re.search(r"[a-z]", password):
+            raise serializers.ValidationError({"password": "Password must contain at least one lowercase letter."})
+        if not re.search(r"[0-9]", password):
+            raise serializers.ValidationError({"password": "Password must contain at least one number."})
+        if not re.search(r"[@$!%*?&]", password):
+            raise serializers.ValidationError({"password": "Password must contain at least one special character (@, $, !, %, *, ?, &)."})
+        return attrs
+
+
+class DocumentSerializer(serializers.ModelSerializer):
+    user = UserSerializer(read_only=True)
+    file_url = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Document
+        fields = (
+            'id', 'user', 'name', 'file', 'file_url', 'status', 
+            'entity_count', 'relationship_count', 'error_message', 
+            'created_at', 'updated_at'
+        )
+        read_only_fields = (
+            'id', 'user', 'status', 'entity_count', 'relationship_count', 
+            'error_message', 'created_at', 'updated_at'
+        )
+
+    def get_file_url(self, obj):
+        request = self.context.get('request')
+        if obj.file and request:
+            return request.build_absolute_uri(obj.file.url)
+        return None
+
+
+class QueryLogSerializer(serializers.ModelSerializer):
+    user = UserSerializer(read_only=True)
+
+    class Meta:
+        model = QueryLog
+        fields = (
+            'id', 'user', 'query_text', 'retrieval_mode', 
+            'answer_text', 'response_time', 'created_at'
+        )
+        read_only_fields = ('id', 'user', 'created_at')
+
+
+class EvaluationPairSerializer(serializers.ModelSerializer):
+    user = UserSerializer(read_only=True)
+
+    class Meta:
+        model = EvaluationPair
+        fields = ('id', 'user', 'question', 'expected_answer', 'is_active', 'created_at')
+        read_only_fields = ('id', 'user', 'created_at')

backend/graphrag/services/entity_extractor.py

@@ -0,0 +1,73 @@
+import logging
+from typing import List
+from pydantic import BaseModel, Field
+from langchain_core.prompts import ChatPromptTemplate
+from .llm_client import get_llm
+
+logger = logging.getLogger(__name__)
+
+class Entity(BaseModel):
+    """
+    Represents a single extracted entity from the document text.
+    """
+    name: str = Field(
+        description="The canonical name of the entity, correctly capitalized (e.g., 'Google', 'John Smith'). Do not use pronouns or generic words."
+    )
+    type: str = Field(
+        description="The category of the entity. Must be exactly one of: PERSON, ORGANIZATION, PRODUCT, TECHNOLOGY, LOCATION, EVENT, DATE, CONCEPT, DOCUMENT"
+    )
+    description: str = Field(
+        description="A brief 1-2 sentence description explaining who or what this entity is, based strictly on the text chunk."
+    )
+
+class ExtractedEntities(BaseModel):
+    """
+    Container list of all extracted entities.
+    """
+    entities: List[Entity]
+
+class EntityExtractor:
+    def __init__(self):
+        logger.info("Initializing EntityExtractor service.")
+        self.llm = get_llm(temperature=0.0)
+        # Binds the LLM to output structured JSON matching our Pydantic schema
+        self.structured_llm = self.llm.with_structured_output(ExtractedEntities)
+
+        # Build prompt instructions
+        self.prompt = ChatPromptTemplate.from_messages([
+            ("system", (
+                "You are an expert knowledge extraction agent. Your job is to read the provided text chunk "
+                "and extract all key entities.\n\n"
+                "Strict rules:\n"
+                "1. Entity Type: Each entity must belong to one of these types: PERSON, ORGANIZATION, PRODUCT, "
+                "TECHNOLOGY, LOCATION, EVENT, DATE, CONCEPT, DOCUMENT.\n"
+                "2. Name Canonicalization: Extract names in their canonical, capitalized form. Avoid pronouns ('he', 'she', 'it') "
+                "and generic descriptors ('the company', 'the engineer').\n"
+                "3. Grounding: Descriptions must be factual and derived strictly from the text provided."
+            )),
+            ("human", "Extract all key entities from this text chunk:\n\n{text_content}")
+        ])
+
+        # Chain prompt with structured model execution
+        self.chain = self.prompt | self.structured_llm
+
+    def extract_entities(self, text_content: str) -> List[dict]:
+        """
+        Processes a string chunk of text and returns a list of serialized entity dicts.
+        """
+        if not text_content or not text_content.strip():
+            logger.warning("Empty text chunk provided to extract_entities.")
+            return []
+
+        word_count = len(text_content.split())
+        logger.info("Running entity extraction on text chunk (Words: %d).", word_count)
+
+        try:
+            result: ExtractedEntities = self.chain.invoke({"text_content": text_content})
+            extracted = [entity.model_dump() for entity in result.entities]
+            logger.info("Successfully extracted %d entities from text chunk.", len(extracted))
+            return extracted
+        except Exception as e:
+            logger.error("Failed during entity extraction processing. Error: %s", str(e), exc_info=True)
+            # Return empty list on failure to let the rest of ingestion pipeline survive
+            return []

backend/graphrag/services/entity_resolver.py

@@ -0,0 +1,93 @@
+import logging
+from typing import List, Dict
+from rapidfuzz import fuzz
+
+logger = logging.getLogger(__name__)
+
+class EntityResolver:
+    def __init__(self, similarity_threshold: float = 85.0):
+        self.similarity_threshold = similarity_threshold
+        logger.info("Initializing EntityResolver with similarity threshold: %.1f", self.similarity_threshold)
+
+    def resolve_entities(self, entities: List[dict], relationships: List[dict]) -> tuple[List[dict], List[dict]]:
+        """
+        Deduplicates a list of entities and rewrites relationship references accordingly.
+        Returns a tuple of (resolved_entities, rewritten_relationships).
+        """
+        if not entities:
+            return [], relationships
+
+        logger.info("Resolving duplicates for %d entities and %d relationships...", len(entities), len(relationships))
+
+        # 1. Group entities by their category/type
+        grouped_by_type: Dict[str, List[dict]] = {}
+        for entity in entities:
+            etype = entity['type'].upper()
+            grouped_by_type.setdefault(etype, []).append(entity)
+
+        resolved_entities = []
+        name_mappings = {} # Maps original_name -> canonical_name
+
+        for etype, group in grouped_by_type.items():
+            resolved_group = []
+            
+            for current in group:
+                matched_canonical = None
+                
+                # Check current entity against already resolved entities in the same type group
+                for existing in resolved_group:
+                    # Run fuzzy comparison on names
+                    ratio = fuzz.token_set_ratio(current['name'].lower(), existing['name'].lower())
+                    if ratio >= self.similarity_threshold:
+                        matched_canonical = existing
+                        break
+                
+                if matched_canonical:
+                    # Duplicate found! Merge current into matched_canonical
+                    old_name = current['name']
+                    new_name = matched_canonical['name']
+                    
+                    # Keep the longer name as the canonical one
+                    if len(old_name) > len(new_name):
+                        matched_canonical['name'] = old_name
+                        name_mappings[new_name] = old_name
+                        name_mappings[old_name] = old_name
+                    else:
+                        name_mappings[old_name] = new_name
+
+                    # Combine descriptions, avoiding exact duplicates
+                    if current['description'] and current['description'] not in matched_canonical['description']:
+                        matched_canonical['description'] = f"{matched_canonical['description']} {current['description']}".strip()
+                    
+                    logger.info("Resolved & Merged entity: '%s' ➔ '%s'", old_name, matched_canonical['name'])
+                else:
+                    # Unique entity in this pass, add it to resolved list
+                    resolved_group.append(current)
+                    name_mappings[current['name']] = current['name']
+
+            resolved_entities.extend(resolved_group)
+
+        # 2. Rewrite relationships using the canonical name mappings
+        rewritten_relationships = []
+        for rel in relationships:
+            # Look up source and target names in mappings
+            src = rel['source_entity']
+            tgt = rel['target_entity']
+            
+            canonical_src = name_mappings.get(src, src)
+            canonical_tgt = name_mappings.get(tgt, tgt)
+
+            # Prevent self-referencing relationships created by merges
+            if canonical_src == canonical_tgt:
+                logger.warning("Discarded self-referencing relationship: [%s] --[%s]--> [%s] after resolution merge.",
+                               src, rel['relationship_type'], tgt)
+                continue
+
+            rel['source_entity'] = canonical_src
+            rel['target_entity'] = canonical_tgt
+            rewritten_relationships.append(rel)
+
+        logger.info("Deduplication complete. Resolved entities count: %d (from %d) | Relationships count: %d",
+                    len(resolved_entities), len(entities), len(rewritten_relationships))
+                    
+        return resolved_entities, rewritten_relationships

backend/graphrag/services/graph_builder.py

@@ -0,0 +1,197 @@
+import os
+import logging
+from typing import List
+from ..models import Document
+from .neo4j_client import Neo4jClient
+from .entity_extractor import EntityExtractor
+from .relationship_extractor import RelationshipExtractor
+from .entity_resolver import EntityResolver
+from .vector_retriever import VectorRetriever
+
+
+logger = logging.getLogger(__name__)
+
+
+class GraphBuilder:
+    def __init__(self):
+        logger.info("Initializing GraphBuilder orchestrator service.")
+        self.neo4j_client = Neo4jClient()
+        self.entity_extractor = EntityExtractor()
+        self.relationship_extractor = RelationshipExtractor()
+        self.entity_resolver = EntityResolver()
+        self.vector_retriever = VectorRetriever()
+
+    def process_document(self, document_id, user_id):
+        """
+        Orchestrates the entire GraphRAG ingestion pipeline.
+        Reads file, extracts entities & relationships, resolves duplicates, and writes to Neo4j.
+        """
+        try:
+            doc = Document.objects.get(id=document_id)
+        except Document.DoesNotExist:
+            logger.error("Document with ID %s does not exist. Ingestion aborted.", document_id)
+            return
+
+        logger.info("Beginning background graph building for Document: %s (User ID: %s)", doc.name, user_id)
+        
+        # 1. Update status to PROCESSING
+        doc.status = Document.Status.PROCESSING
+        doc.save()
+
+        try:
+            filepath = doc.file.path
+            if not os.path.exists(filepath):
+                raise FileNotFoundError(f"File not found on disk: {filepath}")
+
+            # 2. Parse file into sections/pages
+            sections = self._parse_file_to_sections(filepath)
+            logger.info("Parsed document into %d sections for analysis.", len(sections))
+
+            # 2b. Index document text in ChromaDB vector store
+            full_text = "\n\n".join([sec["text"] for sec in sections])
+            logger.info("Indexing document text in ChromaDB (Doc: %s, User: %s)...", doc.name, user_id)
+            self.vector_retriever.index_document(
+                text_content=full_text,
+                doc_name=doc.name,
+                user_id=user_id
+            )
+
+            all_entities = []
+            all_relationships = []
+
+            # 3. Perform Entity and Relationship Extraction per section
+            for sec in sections:
+                text = sec["text"]
+                page = sec["page"]
+
+                # Extract entities from this section
+                ents = self.entity_extractor.extract_entities(text)
+                for e in ents:
+                    e["page"] = page
+                    e["source_doc"] = doc.name
+                all_entities.extend(ents)
+
+                # Extract relationships from this section
+                rels = self.relationship_extractor.extract_relationships(text)
+                for r in rels:
+                    r["page"] = page
+                    r["source_doc"] = doc.name
+                all_relationships.extend(rels)
+
+            # 4. Run entity resolution (deduplicate entities and rewrite relationships)
+            resolved_ents, rewritten_rels = self.entity_resolver.resolve_entities(
+                all_entities, all_relationships
+            )
+
+            # 5. Store resolved nodes inside Neo4j
+            logger.info("Writing %d resolved entities to Neo4j...", len(resolved_ents))
+            for ent in resolved_ents:
+                self.neo4j_client.create_entity_node(
+                    name=ent["name"],
+                    entity_type=ent["type"],
+                    description=ent["description"],
+                    user_id=user_id,
+                    source_doc=ent["source_doc"],
+                    page=ent["page"]
+                )
+
+            # 6. Store rewritten edges inside Neo4j
+            logger.info("Writing %d rewritten relationships to Neo4j...", len(rewritten_rels))
+            for rel in rewritten_rels:
+                self.neo4j_client.create_relationship_edge(
+                    source_name=rel["source_entity"],
+                    target_name=rel["target_entity"],
+                    rel_type=rel["relationship_type"],
+                    description=rel["description"],
+                    confidence=rel["confidence"],
+                    user_id=user_id,
+                    source_doc=rel["source_doc"],
+                    page=rel["page"]
+                )
+
+            # 7. Update status to COMPLETED and record counts
+            doc.entity_count = len(resolved_ents)
+            doc.relationship_count = len(rewritten_rels)
+            doc.status = Document.Status.COMPLETED
+            doc.error_message = None
+            doc.save()
+            logger.info("Successfully finished building knowledge graph for Document: %s", doc.name)
+
+        except Exception as e:
+            logger.error("Failed to process document: %s. Error: %s", doc.name, str(e), exc_info=True)
+            doc.status = Document.Status.FAILED
+            doc.error_message = str(e)
+            doc.save()
+
+    def delete_document_data(self, document_id, user_id):
+        """
+        Cleans up and deletes associated Neo4j node/edge elements for a deleted document.
+        """
+        try:
+            doc = Document.objects.get(id=document_id)
+            logger.info("Triggering graph wipe for Document: %s (User ID: %s)", doc.name, user_id)
+            
+            # Wipe Neo4j Graph elements
+            self.neo4j_client.delete_document_nodes(doc.name, user_id)
+            
+            # Wipe ChromaDB Vector elements
+            self.vector_retriever.delete_document_vectors(doc.name, user_id)
+            
+            logger.info("Finished Graph cleanup for Document: %s", doc.name)
+        except Document.DoesNotExist:
+            logger.error("Document with ID %s does not exist. Cleanup aborted.", document_id)
+        except Exception as e:
+            logger.error("Failed to clean up graph data for Document ID: %s. Error: %s", 
+                         document_id, str(e), exc_info=True)
+
+    def _parse_file_to_sections(self, filepath: str) -> List[dict]:
+        """
+        Loads document file and splits content into page/paragraph sections.
+        """
+        ext = filepath.split(".")[-1].lower()
+        sections = []
+
+        if ext == "pdf":
+            import pypdf
+            reader = pypdf.PdfReader(filepath)
+            for idx, page in enumerate(reader.pages):
+                text = page.extract_text()
+                if text and text.strip():
+                    sections.append({
+                        "text": text.strip(),
+                        "page": idx + 1
+                    })
+        elif ext in ["docx", "doc"]:
+            import docx
+            doc = docx.Document(filepath)
+            current_chunk = []
+            section_idx = 1
+            for p in doc.paragraphs:
+                if p.text and p.text.strip():
+                    current_chunk.append(p.text.strip())
+                # Group every 3 paragraphs to ensure sufficient context is captured
+                if len(current_chunk) >= 3:
+                    sections.append({
+                        "text": "\n".join(current_chunk),
+                        "page": section_idx
+                    })
+                    current_chunk = []
+                    section_idx += 1
+            if current_chunk:
+                sections.append({
+                    "text": "\n".join(current_chunk),
+                    "page": section_idx
+                })
+        else:
+            # Default fallback for TXT, Markdown, etc.
+            with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+                content = f.read()
+            # Split by double newlines
+            paragraphs = [p.strip() for p in content.split("\n\n") if p.strip()]
+            for idx, p in enumerate(paragraphs):
+                sections.append({
+                    "text": p,
+                    "page": idx + 1
+                })
+
+        return sections

backend/graphrag/services/graph_retriever.py

@@ -0,0 +1,136 @@
+import logging
+from typing import List, Dict, Set
+from pydantic import BaseModel, Field
+from langchain_core.prompts import ChatPromptTemplate
+from .llm_client import get_llm
+from .neo4j_client import Neo4jClient
+
+logger = logging.getLogger(__name__)
+
+class QueryEntities(BaseModel):
+    """
+    List of key entities extracted from the search query.
+    """
+    entities: List[str] = Field(
+        description="Key proper nouns, entities, products, technologies, or concepts extracted from the search query."
+    )
+
+class GraphRetriever:
+    def __init__(self):
+        logger.info("Initializing GraphRetriever service.")
+        self.neo4j_client = Neo4jClient()
+        self.llm = get_llm(temperature=0.0)
+        self.structured_llm = self.llm.with_structured_output(QueryEntities)
+
+        # Prompt instruction to isolate entity names
+        self.prompt = ChatPromptTemplate.from_messages([
+            ("system", (
+                "You are an NLP entity extraction assistant. Your job is to extract a list of "
+                "key entities (e.g., people, organizations, technologies, products, locations, concepts) "
+                "specifically mentioned in the user's search query.\n\n"
+                "Extract ONLY nouns and main topics that can be looked up in a database. Do not include verbs or questions."
+            )),
+            ("human", "Extract the key entities from this query:\n\n{query}")
+        ])
+
+        self.chain = self.prompt | self.structured_llm
+
+    def retrieve_graph_context(self, query: str, user_id: str, hops: int = 2) -> str:
+        """
+        Extracts entities from the query, traverses their Neo4j subgraphs,
+        and returns a serialized text block representing the graph context.
+        """
+        logger.info("Retrieving graph context for query: '%s' (User: %s)", query, user_id)
+        
+        # 1. Extract entities from query using LLM
+        query_entities = self._extract_entities_from_query(query)
+        if not query_entities:
+            logger.info("No entities extracted from user query. Returning empty graph context.")
+            return ""
+
+        logger.info("Extracted query entities: %s", query_entities)
+
+        unique_nodes: Dict[str, dict] = {}
+        unique_rels: Set[str] = set()
+
+        # 2. Query Neo4j for each entity's neighborhood
+        for entity_name in query_entities:
+            try:
+                paths = self.neo4j_client.get_entity_subgraph(entity_name, user_id, hops=hops)
+                self._parse_subgraph_paths(paths, unique_nodes, unique_rels)
+            except Exception as e:
+                logger.error("Failed to query subgraph for entity: %s. Error: %s", entity_name, str(e))
+
+        # 3. Serialize extracted graph information into a readable markdown string
+        if not unique_nodes:
+            logger.info("No matching entities or paths found in the graph for query.")
+            return ""
+
+        context_lines = ["### STRUCTURED KNOWLEDGE GRAPH CONTEXT\n"]
+        
+        context_lines.append("#### Entities:")
+        for name, info in unique_nodes.items():
+            context_lines.append(f"* **{name}** ({info.get('type', 'Unknown')}): {info.get('description', '')}")
+
+        if unique_rels:
+            context_lines.append("\n#### Relationships:")
+            for rel in sorted(unique_rels):
+                context_lines.append(f"* {rel}")
+
+        serialized_context = "\n".join(context_lines)
+        logger.info("Generated graph context (%d characters).", len(serialized_context))
+        return serialized_context
+
+    def _extract_entities_from_query(self, query: str) -> List[str]:
+        """
+        Uses the LLM structured call to parse entity search terms.
+        """
+        try:
+            result: QueryEntities = self.chain.invoke({"query": query})
+            return [name.strip() for name in result.entities if name.strip()]
+        except Exception as e:
+            logger.error("Failed to extract entities from query. Error: %s", str(e), exc_info=True)
+            return []
+
+    def _parse_subgraph_paths(self, paths: List[dict], unique_nodes: Dict[str, dict], unique_rels: Set[str]):
+        """
+        Helper method to iterate through Neo4j path dictionaries and extract node & edge properties.
+        """
+        for record in paths:
+            path_obj = record.get("path")
+            if not path_obj:
+                continue
+
+            # In the neo4j python driver, a path contains nodes and relationships
+            nodes = path_obj.nodes
+            relationships = path_obj.relationships
+
+            # 1. Parse all nodes in this path segment
+            for node in nodes:
+                properties = dict(node)
+                name = properties.get("name")
+                if name:
+                    # Store unique node info
+                    unique_nodes[name] = {
+                        "type": properties.get("type", "Unknown"),
+                        "description": properties.get("description", "")
+                    }
+
+            # 2. Parse all relationship edges in this path segment
+            for rel in relationships:
+                # Get connected nodes from the path
+                start_node = nodes[rel.start_node.id if hasattr(rel.start_node, 'id') else 0]
+                end_node = nodes[rel.end_node.id if hasattr(rel.end_node, 'id') else 0]
+                
+                start_name = dict(start_node).get("name", "Unknown")
+                end_name = dict(end_node).get("name", "Unknown")
+                
+                rel_type = rel.type
+                properties = dict(rel)
+                desc = properties.get("description", "")
+                conf = properties.get("confidence", 1.0)
+
+                # Format edge output description
+                desc_suffix = f" (Details: {desc})" if desc else ""
+                rel_str = f"[{dict(start_node).get('type', 'Entity')}] **{start_name}** --[{rel_type} (Confidence: {conf})]--> [{dict(end_node).get('type', 'Entity')}] **{end_name}**{desc_suffix}"
+                unique_rels.add(rel_str)

backend/graphrag/services/hybrid_retriever.py

@@ -0,0 +1,73 @@
+import logging
+from typing import List, Dict
+from .graph_retriever import GraphRetriever
+from .vector_retriever import VectorRetriever
+
+logger = logging.getLogger(__name__)
+
+class HybridRetriever:
+    def __init__(self):
+        logger.info("Initializing HybridRetriever service.")
+        self.graph_retriever = GraphRetriever()
+        self.vector_retriever = VectorRetriever()
+
+    def retrieve_combined_context(self, query: str, user_id: str) -> Dict[str, any]:
+        """
+        Runs both graph and vector search and returns a combined context dictionary.
+        Determines the retrieval strategy route (GRAPH_ONLY, VECTOR_ONLY, or HYBRID).
+        """
+        logger.info("Running hybrid retrieval for query: '%s' (User: %s)", query, user_id)
+
+        # 1. Execute Graph Retrieval
+        graph_context = ""
+        try:
+            graph_context = self.graph_retriever.retrieve_graph_context(query, user_id, hops=2)
+        except Exception as e:
+            logger.error("Graph retrieval failed during hybrid step. Error: %s", str(e))
+
+        # 2. Execute Vector Retrieval
+        vector_chunks = []
+        try:
+            vector_chunks = self.vector_retriever.retrieve_relevant_chunks(query, user_id, limit=4)
+        except Exception as e:
+            logger.error("Vector retrieval failed during hybrid step. Error: %s", str(e))
+
+        # 3. Format Vector Text Chunks
+        vector_context_lines = []
+        if vector_chunks:
+            vector_context_lines.append("### UNSTRUCTURED TEXT PASSAGES\n")
+            for idx, chunk in enumerate(vector_chunks):
+                vector_context_lines.append(
+                    f"Document: {chunk['source_doc']} (Page: {chunk['page']}, Similarity: {chunk['similarity_score']}):\n"
+                    f"\"{chunk['text'].strip()}\"\n"
+                )
+        vector_context = "\n".join(vector_context_lines)
+
+        # 4. Auto-detect Strategy Route based on context availability
+        strategy = "HYBRID"
+        if graph_context and not vector_context:
+            strategy = "GRAPH_ONLY"
+            combined_context = graph_context
+        elif vector_context and not graph_context:
+            strategy = "VECTOR_ONLY"
+            combined_context = vector_context
+        elif not graph_context and not vector_context:
+            strategy = "VECTOR_ONLY"  # Fallback
+            combined_context = "No relevant context found in either the Graph or Vector databases."
+        else:
+            # Both exist: default hybrid blend
+            strategy = "HYBRID"
+            combined_context = (
+                f"{graph_context}\n\n"
+                f"{vector_context}"
+            )
+
+        logger.info("Selected retrieval strategy: %s for query: '%s'", strategy, query)
+        
+        return {
+            "combined_context": combined_context,
+            "graph_context": graph_context,
+            "vector_context": vector_context,
+            "vector_chunks": vector_chunks,
+            "strategy": strategy
+        }

backend/graphrag/services/llm_client.py

@@ -0,0 +1,34 @@
+import os
+import logging
+from langchain_groq import ChatGroq
+from langchain_google_genai import ChatGoogleGenerativeAI
+
+logger = logging.getLogger(__name__)
+
+def get_llm(temperature: float = 0.0):
+    """
+    Returns a configured LangChain LLM instance.
+    Prioritizes Groq (Llama 3) and falls back to Gemini if GROQ_API_KEY is missing.
+    """
+    groq_api_key = os.getenv("GROQ_API_KEY", "")
+    google_api_key = os.getenv("GOOGLE_API_KEY", "")
+
+    if groq_api_key:
+        model_name = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+        logger.info("Initializing Groq Chat Model (%s)", model_name)
+        return ChatGroq(
+            model=model_name,
+            api_key=groq_api_key,
+            temperature=temperature
+        )
+    elif google_api_key:
+        model_name = os.getenv("GOOGLE_MODEL", "gemini-1.5-flash")
+        logger.info("Initializing Google Gemini Chat Model (%s)", model_name)
+        return ChatGoogleGenerativeAI(
+            model=model_name,
+            api_key=google_api_key,
+            temperature=temperature
+        )
+    else:
+        logger.error("No API keys found for either GROQ_API_KEY or GOOGLE_API_KEY.")
+        raise ValueError("Missing LLM API keys. Please configure GROQ_API_KEY or GOOGLE_API_KEY in your .env file.")

backend/graphrag/services/multihop_reasoner.py

@@ -0,0 +1,120 @@
+import logging
+from typing import List, Dict, Any
+from langchain_core.prompts import ChatPromptTemplate
+from .llm_client import get_llm
+from .neo4j_client import Neo4jClient
+
+logger = logging.getLogger(__name__)
+
+class MultiHopReasoner:
+    def __init__(self):
+        logger.info("Initializing MultiHopReasoner service.")
+        self.neo4j_client = Neo4jClient()
+        self.llm = get_llm(temperature=0.0)
+
+        # Prompt instruction to summarize path connections
+        self.prompt = ChatPromptTemplate.from_messages([
+            ("system", (
+                "You are an AI analyst specialized in explaining graph connections.\n"
+                "You will be given a path of nodes and relationships from a knowledge graph showing how two entities are connected.\n"
+                "Your job is to summarize this connection path in a clear, natural paragraph.\n\n"
+                "Format rules:\n"
+                "- Clearly mention each step of the connection.\n"
+                "- Keep the explanation factual based *only* on the provided path info."
+            )),
+            ("human", (
+                "Explain the connection between '{entity_a}' and '{entity_b}' based on this graph path:\n\n"
+                "{path_details}"
+            ))
+        ])
+
+        self.chain = self.prompt | self.llm
+
+    def explain_connection(self, entity_a: str, entity_b: str, user_id: str) -> Dict[str, Any]:
+        """
+        Finds the shortest path between two entities in Neo4j and uses the LLM to explain the connection.
+        """
+        logger.info("Finding connection between '%s' and '%s' (User: %s)", entity_a, entity_b, user_id)
+        
+        # 1. Fetch shortest path from Neo4j
+        cypher = (
+            "MATCH p = shortestPath("
+            "  (a:Entity {name: $entity_a, user_id: $user_id})-[*..4]-(b:Entity {name: $entity_b, user_id: $user_id})"
+            ") "
+            "RETURN p"
+        )
+        params = {
+            "entity_a": entity_a,
+            "entity_b": entity_b,
+            "user_id": str(user_id)
+        }
+
+        try:
+            # New code
+            records = self.neo4j_client.execute_query(cypher, params)
+            if not records or not records[0].get("p"):
+                logger.info("No connection path found between '%s' and '%s'.", entity_a, entity_b)
+                return {
+                    "found": False,
+                    "explanation": f"No indirect connection (up to 4 hops) was found between '{entity_a}' and '{entity_b}' in the knowledge graph.",
+                    "path": []
+                }
+
+            path_obj = records[0]["p"]
+            nodes = path_obj.nodes
+            relationships = path_obj.relationships
+
+            # 2. Extract path details for prompt serialization
+            path_steps = []
+            serialized_path = []
+
+            for i in range(len(relationships)):
+                node_now = nodes[i]
+                node_next = nodes[i + 1]
+                rel = relationships[i]
+
+                now_name = dict(node_now).get("name", "Unknown")
+                next_name = dict(node_next).get("name", "Unknown")
+                
+                now_type = dict(node_now).get("type", "Entity")
+                next_type = dict(node_next).get("type", "Entity")
+                
+                rel_type = rel.type
+
+                step_str = f"({now_name} [{now_type}]) --[{rel_type}]--> ({next_name} [{next_type}])"
+                path_steps.append(step_str)
+                
+                # Keep tracking representation for the response payload
+                serialized_path.append({
+                    "source": now_name,
+                    "source_type": now_type,
+                    "target": next_name,
+                    "target_type": next_type,
+                    "type": rel_type
+                })
+
+            path_details = "\n".join(path_steps)
+            logger.info("Found path with %d hops: %s", len(relationships), path_details)
+
+            # 3. Ask LLM to summarize/explain this path
+            response = self.chain.invoke({
+                "entity_a": entity_a,
+                "entity_b": entity_b,
+                "path_details": path_details
+            })
+            
+            explanation = response.content.strip()
+
+            return {
+                "found": True,
+                "explanation": explanation,
+                "path": serialized_path
+            }
+
+        except Exception as e:
+            logger.error("Failed to execute path reasoning query: %s", str(e), exc_info=True)
+            return {
+                "found": False,
+                "explanation": f"An error occurred while analyzing the connection: {str(e)}",
+                "path": []
+            }

backend/graphrag/services/neo4j_client.py

@@ -0,0 +1,197 @@
+import logging
+from django.conf import settings
+from neo4j import GraphDatabase
+
+logger = logging.getLogger(__name__)
+
+class Neo4jClient:
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        # Singleton pattern to reuse the driver connection pool across Django requests
+        if not cls._instance:
+            cls._instance = super().__new__(cls, *args, **kwargs)
+        return cls._instance
+
+    def __init__(self):
+        # Prevent re-initializing the driver if it's already connected
+        if hasattr(self, 'driver'):
+            return
+
+        self.uri = getattr(settings, 'NEO4J_URI', 'bolt://localhost:7687')
+        self.user = getattr(settings, 'NEO4J_USER', 'neo4j')
+        self.password = getattr(settings, 'NEO4J_PASSWORD', 'password')
+
+        logger.info("Initializing Neo4j database driver connecting to: %s", self.uri)
+        try:
+            self.driver = GraphDatabase.driver(self.uri, auth=(self.user, self.password))
+            self.verify_constraints()
+            logger.info("Successfully established connection to Neo4j and verified schema constraints.")
+        except Exception as e:
+            logger.error("Failed to connect to Neo4j database. Error: %s", str(e), exc_info=True)
+            raise e
+
+    def close(self):
+        if hasattr(self, 'driver'):
+            logger.info("Closing Neo4j driver connection pool.")
+            self.driver.close()
+
+    def verify_constraints(self):
+        """
+        Set up unique constraints and indexes to prevent duplicates and speed up lookup.
+        """
+        # Unique name constraint for entities
+        constraint_query = (
+            "CREATE CONSTRAINT unique_entity_name IF NOT EXISTS "
+            "FOR (e:Entity) REQUIRE (e.name, e.user_id) IS UNIQUE"
+        )
+        # Fast indexing on entity type
+        index_query = (
+            "CREATE INDEX entity_type_idx IF NOT EXISTS "
+            "FOR (e:Entity) ON (e.type)"
+        )
+        try:
+            with self.driver.session() as session:
+                session.run(constraint_query)
+                session.run(index_query)
+        except Exception as e:
+            logger.warning("Could not create Neo4j constraints/indexes: %s", str(e))
+
+    def execute_query(self, query, parameters=None):
+        """
+        Execute raw Cypher query safely. Used for debugging or custom retrievals.
+        """
+        parameters = parameters or {}
+        logger.debug("Executing Cypher query: %s | Params: %s", query, parameters)
+        try:
+            with self.driver.session() as session:
+                result = session.run(query, parameters)
+                return [record.data() for record in result]
+        except Exception as e:
+            logger.error("Error executing Cypher query. Error: %s", str(e), exc_info=True)
+            raise e
+
+    def create_entity_node(self, name, entity_type, description, user_id, source_doc=None, page=None):
+        """
+        Create or update (MERGE) an Entity node, isolating by user_id.
+        """
+        query = (
+            "MERGE (e:Entity {name: $name, user_id: $user_id}) "
+            "ON CREATE SET e.type = $type, e.description = $description, "
+            "              e.source_doc = $source_doc, e.page = $page, e.created_at = timestamp() "
+            "ON MATCH SET e.description = coalesce(e.description, $description) "
+            "RETURN e"
+        )
+        params = {
+            "name": name.strip(),
+            "type": entity_type.strip(),
+            "description": description.strip(),
+            "user_id": str(user_id),
+            "source_doc": source_doc,
+            "page": page
+        }
+        self.execute_query(query, params)
+
+    def create_relationship_edge(self, source_name, target_name, rel_type, description, confidence, user_id, source_doc=None, page=None):
+        """
+        Create a directed relationship edge between two existing Entity nodes.
+        Note: Cypher does not support parameterizing relationship types directly, 
+        so we safely format the relationship type string (which is sanitised).
+        """
+        clean_rel_type = "".join(c for c in rel_type.upper() if c.isalnum() or c == "_")
+        
+        query = (
+            f"MATCH (source:Entity {{name: $source_name, user_id: $user_id}}) "
+            f"MATCH (target:Entity {{name: $target_name, user_id: $user_id}}) "
+            f"MERGE (source)-[r:{clean_rel_type}]->(target) "
+            f"ON CREATE SET r.description = $description, r.confidence = $confidence, "
+            f"              r.source_doc = $source_doc, r.page = $page, r.created_at = timestamp() "
+            f"RETURN r"
+        )
+        params = {
+            "source_name": source_name.strip(),
+            "target_name": target_name.strip(),
+            "description": description.strip(),
+            "confidence": float(confidence),
+            "user_id": str(user_id),
+            "source_doc": source_doc,
+            "page": page
+        }
+        self.execute_query(query, params)
+
+    def get_entity_subgraph(self, name, user_id, hops=2):
+        """
+        Retrieve all connected entities and relationships up to N hops.
+        """
+        query = (
+            f"MATCH path = (e:Entity {{name: $name, user_id: $user_id}})-[*1..{hops}]-(neighbor:Entity {{user_id: $user_id}}) "
+            f"RETURN path LIMIT 50"
+        )
+        params = {"name": name, "user_id": str(user_id)}
+        return self.execute_query(query, params)
+
+    def find_shortest_path(self, start_name, end_name, user_id, max_hops=5):
+        """
+        Runs BFS pathfinding to find connection sequences between concepts.
+        """
+        query = (
+            f"MATCH (start:Entity {{name: $start_name, user_id: $user_id}}), "
+            f"      (end:Entity {{name: $end_name, user_id: $user_id}}) "
+            f"MATCH path = shortestPath((start)-[*..{max_hops}]-(end)) "
+            f"RETURN path"
+        )
+        params = {
+            "start_name": start_name,
+            "end_name": end_name,
+            "user_id": str(user_id)
+        }
+        return self.execute_query(query, params)
+
+    def get_graph_statistics(self, user_id):
+        """
+        Fetch graph summaries for the dashboard.
+        """
+        nodes_count_query = "MATCH (e:Entity {user_id: $user_id}) RETURN count(e) as count"
+        edges_count_query = "MATCH (:Entity {user_id: $user_id})-[r]->(:Entity {user_id: $user_id}) RETURN count(r) as count"
+        type_dist_query = (
+            "MATCH (e:Entity {user_id: $user_id}) "
+            "RETURN e.type as type, count(e) as count ORDER BY count DESC"
+        )
+        
+        try:
+            nodes_count = self.execute_query(nodes_count_query, {"user_id": str(user_id)})[0]['count']
+            edges_count = self.execute_query(edges_count_query, {"user_id": str(user_id)})[0]['count']
+            type_dist = self.execute_query(type_dist_query, {"user_id": str(user_id)})
+            
+            return {
+                "nodes_count": nodes_count,
+                "edges_count": edges_count,
+                "type_distribution": type_dist
+            }
+        except Exception as e:
+            logger.error("Failed to query graph statistics. Error: %s", str(e), exc_info=True)
+            return {"nodes_count": 0, "edges_count": 0, "type_distribution": []}
+
+    def delete_document_nodes(self, document_name, user_id):
+        """
+        Wipe all nodes and relationships associated with a deleted document.
+        Removes orphan nodes that have no other remaining connections.
+        """
+        logger.info("Executing Cypher delete query for document: %s, User: %s", document_name, user_id)
+        
+        # 1. Delete relationships pointing from or to nodes created by this document
+        delete_rels_query = (
+            "MATCH (a:Entity {user_id: $user_id})-[r]->(b:Entity {user_id: $user_id}) "
+            "WHERE r.source_doc = $document_name "
+            "DELETE r"
+        )
+        # 2. Delete nodes created solely by this document
+        delete_nodes_query = (
+            "MATCH (e:Entity {user_id: $user_id}) "
+            "WHERE e.source_doc = $document_name "
+            "DETACH DELETE e"
+        )
+        
+        params = {"document_name": document_name, "user_id": str(user_id)}
+        self.execute_query(delete_rels_query, params)
+        self.execute_query(delete_nodes_query, params)

backend/graphrag/services/nl_to_cypher.py

@@ -0,0 +1,80 @@
+import logging
+from typing import List, Dict, Any
+from pydantic import BaseModel, Field
+from langchain_core.prompts import ChatPromptTemplate
+from .llm_client import get_llm
+from .neo4j_client import Neo4jClient
+
+logger = logging.getLogger(__name__)
+
+class CypherQuery(BaseModel):
+    """
+    Structured container for the generated Cypher query.
+    """
+    cypher: str = Field(
+        description="The executable Neo4j Cypher query. Must match the schema and strictly filter nodes and edges by user_id."
+    )
+    explanation: str = Field(
+        description="A short explanation of what the query fetches from the graph."
+    )
+
+class NLToCypher:
+    def __init__(self):
+        logger.info("Initializing NLToCypher translator service.")
+        self.neo4j_client = Neo4jClient()
+        self.llm = get_llm(temperature=0.0)
+        self.structured_llm = self.llm.with_structured_output(CypherQuery)
+
+        self.prompt = ChatPromptTemplate.from_messages([
+            ("system", (
+                "You are an expert Neo4j Cypher query generator for a GraphRAG knowledge system.\n"
+                "Your task is to convert a user's natural language question into a syntactically correct, read-only Cypher query.\n\n"
+                "=== DATABASE SCHEMA ===\n"
+                "Nodes:\n"
+                "Label: :Entity\n"
+                "Properties: name (String), type (String), description (String), source_doc (String), page (Integer), user_id (String)\n\n"
+                "Relationships:\n"
+                "Allowed Types: WORKS_AT, MANAGES, PART_OF, DEPENDS_ON, CREATED_BY, LOCATED_IN, RELATED_TO, COMPETES_WITH, PARTNER_OF, SUCCEEDED_BY\n"
+                "Properties: description (String), confidence (Float), source_doc (String), page (Integer), user_id (String)\n\n"
+                "=== CRITICAL RULES ===\n"
+                "1. Multi-Tenancy Isolation: Every node and relationship in the query MUST filter by user_id. Use the parameter $user_id.\n"
+                "   Example: MATCH (a:Entity {{user_id: $user_id}})-[r:DEPENDS_ON {{user_id: $user_id}}]->(b:Entity {{user_id: $user_id}})\n"
+                "2. Read-Only: Never generate write, delete, or update operations (MERGE, CREATE, SET, DELETE, REMOVE, DETACH).\n"
+                "3. Safe Return: Limit results to a maximum of 50 records to prevent performance degradation."
+            )),
+            ("human", "Translate this question into Cypher: '{question}'")
+        ])
+
+        self.chain = self.prompt | self.structured_llm
+
+    def execute_nl_query(self, question: str, user_id: str) -> Dict[str, Any]:
+        """
+        Translates a natural language question to Cypher, runs it, and returns results.
+        """
+        logger.info("Translating question to Cypher: '%s' (User: %s)", question, user_id)
+        
+        try:
+            # 1. Generate Cypher query
+            result: CypherQuery = self.chain.invoke({"question": question})
+            logger.info("Generated Cypher: %s", result.cypher)
+
+            # 2. Execute on Neo4j using client
+            # New code
+            records = self.neo4j_client.execute_query(result.cypher, {"user_id": str(user_id)})
+            logger.info("Executed Cypher successfully. Retrieved %d rows.", len(records))
+
+            return {
+                "cypher": result.cypher,
+                "explanation": result.explanation,
+                "records": records,
+                "success": True
+            }
+        except Exception as e:
+            logger.error("Failed to generate or execute Cypher query: %s", str(e), exc_info=True)
+            return {
+                "cypher": "",
+                "explanation": "",
+                "records": [],
+                "success": False,
+                "error": str(e)
+            }

backend/graphrag/services/rag_chain.py

@@ -0,0 +1,143 @@
+import logging
+from typing import Dict, Any, List
+from langchain_core.prompts import ChatPromptTemplate
+from .llm_client import get_llm
+from .graph_retriever import GraphRetriever
+from .vector_retriever import VectorRetriever
+from .hybrid_retriever import HybridRetriever
+
+logger = logging.getLogger(__name__)
+
+class RAGChain:
+    def __init__(self):
+        logger.info("Initializing RAGChain answer generation service.")
+        self.llm = get_llm(temperature=0.2) # Low temperature for high factual accuracy
+        
+        self.graph_retriever = GraphRetriever()
+        self.vector_retriever = VectorRetriever()
+        self.hybrid_retriever = HybridRetriever()
+
+        # Define prompts for each mode
+        self.system_prompts = {
+            "vector": (
+                "You are an AI assistant answering questions based ONLY on the provided text passages.\n"
+                "Strict Rules:\n"
+                "1. Base your answer ONLY on the provided unstructured text passages.\n"
+                "2. If the passages do not contain enough information to answer, state that you do not know.\n"
+                "3. Cite the document names and pages where applicable."
+            ),
+            "graph": (
+                "You are an AI assistant answering questions based ONLY on the provided structured knowledge graph.\n"
+                "Strict Rules:\n"
+                "1. Base your answer ONLY on the provided entities and relationship paths.\n"
+                "2. Do not assume or extrapolate connections not shown in the graph context.\n"
+                "3. If the graph does not contain the answer, state that you do not know."
+            ),
+            "hybrid": (
+                "You are an AI assistant answering questions using a combination of a structured knowledge graph and unstructured text passages.\n"
+                "Strict Rules:\n"
+                "1. Synthesize information from both the entities/relationships and the text passages.\n"
+                "2. If there is a contradiction, prioritize the structured relationship links from the graph context.\n"
+                "3. Cite sources (documents, pages, or entities) to back up your facts."
+            )
+        }
+
+    def generate_answer(self, query: str, user_id: str, mode: str = "hybrid") -> Dict[str, Any]:
+        """
+        Retrieves context according to the selected mode, invokes the LLM, and returns the response.
+        """
+        mode = mode.lower()
+        if mode not in ["vector", "graph", "hybrid"]:
+            logger.warning("Invalid retrieval mode '%s' requested. Defaulting to 'hybrid'.", mode)
+            mode = "hybrid"
+
+        logger.info("Generating RAG answer in '%s' mode for query: '%s' (User: %s)", mode, query, user_id)
+
+        context = ""
+        sources = []
+        strategy_used = mode.upper()
+
+        # 1. Fetch Context depending on the Retrieval Mode
+        try:
+            if mode == "vector":
+                chunks = self.vector_retriever.retrieve_relevant_chunks(query, user_id, limit=5)
+                context_lines = []
+                for c in chunks:
+                    context_lines.append(f"Document: {c['source_doc']} (Page: {c['page']}): \"{c['text']}\"")
+                    sources.append(f"{c['source_doc']} (Page {c['page']})")
+                context = "### TEXT PASSAGES:\n" + "\n\n".join(context_lines)
+
+            elif mode == "graph":
+                graph_context = self.graph_retriever.retrieve_graph_context(query, user_id, hops=2)
+                context = graph_context
+                # Extract entity names as sources
+                for line in graph_context.split("\n"):
+                    if line.startswith("* **"):
+                        ent_name = line.split("**")[1]
+                        sources.append(f"Graph Node: {ent_name}")
+
+            else:  # hybrid
+                hybrid_result = self.hybrid_retriever.retrieve_combined_context(query, user_id)
+                context = hybrid_result["combined_context"]
+                strategy_used = hybrid_result["strategy"]
+                
+                # Gather sources from both channels
+                for c in hybrid_result["vector_chunks"]:
+                    sources.append(f"{c['source_doc']} (Page {c['page']})")
+                for line in hybrid_result["graph_context"].split("\n"):
+                    if line.startswith("* **"):
+                        ent_name = line.split("**")[1]
+                        sources.append(f"Graph Node: {ent_name}")
+
+        except Exception as e:
+            logger.error("Failed to retrieve context in %s mode. Error: %s", mode, str(e), exc_info=True)
+            return {
+                "answer": "An error occurred during context retrieval phase.",
+                "context": "",
+                "sources": [],
+                "strategy": mode.upper(),
+                "success": False
+            }
+
+        # 2. Build Chat Prompt template
+        system_instructions = self.system_prompts.get(mode, self.system_prompts["hybrid"])
+        
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", system_instructions),
+            ("human", (
+                "CONTEXT:\n"
+                "---------------------\n"
+                "{context}\n"
+                "---------------------\n\n"
+                "QUESTION: {query}"
+            ))
+        ])
+
+        # 3. Call LLM
+        try:
+            chain = prompt | self.llm
+            response = chain.invoke({
+                "context": context if context else "No context available.",
+                "query": query
+            })
+            answer = response.content.strip()
+
+            # Deduplicate sources list
+            sources = list(sorted(set(sources)))
+
+            return {
+                "answer": answer,
+                "context": context,
+                "sources": sources,
+                "strategy": strategy_used,
+                "success": True
+            }
+        except Exception as e:
+            logger.error("Failed to generate LLM response: %s", str(e), exc_info=True)
+            return {
+                "answer": f"Failed to generate answer. Error: {str(e)}",
+                "context": context,
+                "sources": sources,
+                "strategy": strategy_used,
+                "success": False
+            }

backend/graphrag/services/relationship_extractor.py

@@ -0,0 +1,78 @@
+import logging
+from typing import List
+from pydantic import BaseModel, Field
+from langchain_core.prompts import ChatPromptTemplate
+from .llm_client import get_llm
+
+logger = logging.getLogger(__name__)
+
+class Relationship(BaseModel):
+    """
+    Represents a directed link between a source entity and a target entity.
+    """
+    source_entity: str = Field(
+        description="The exact name of the starting entity (e.g., 'John Smith'). Must refer to an actual entity."
+    )
+    relationship_type: str = Field(
+        description="The category of link. Must be exactly one of: WORKS_AT, MANAGES, PART_OF, DEPENDS_ON, CREATED_BY, LOCATED_IN, RELATED_TO, COMPETES_WITH, PARTNER_OF, SUCCEEDED_BY"
+    )
+    target_entity: str = Field(
+        description="The exact name of the destination entity (e.g., 'Acme Corp'). Must refer to an actual entity."
+    )
+    description: str = Field(
+        description="A 1-2 sentence description explaining the nature or evidence of this relationship in the text."
+    )
+    confidence: float = Field(
+        description="A decimal confidence score between 0.0 (unlikely/speculative) and 1.0 (explicitly stated)."
+    )
+
+class ExtractedRelationships(BaseModel):
+    """
+    Container list of all extracted relationships.
+    """
+    relationships: List[Relationship]
+
+class RelationshipExtractor:
+    def __init__(self):
+        logger.info("Initializing RelationshipExtractor service.")
+        self.llm = get_llm(temperature=0.0)
+        self.structured_llm = self.llm.with_structured_output(ExtractedRelationships)
+
+        self.prompt = ChatPromptTemplate.from_messages([
+            ("system", (
+                "You are an expert NLP systems agent specialized in relationship extraction for knowledge graphs.\n"
+                "Your task is to identify key directed relationships between the entities present in the text.\n\n"
+                "Strict rules:\n"
+                "1. Relationship Type: Choose exactly one of: WORKS_AT, MANAGES, PART_OF, DEPENDS_ON, CREATED_BY, LOCATED_IN, RELATED_TO, COMPETES_WITH, PARTNER_OF, SUCCEEDED_BY.\n"
+                "2. Grounding: Both the source_entity and target_entity must represent real entities. Avoid generic words.\n"
+                "3. Confidence: Grade the strength of statement between 0.0 and 1.0."
+            )),
+            ("human", (
+                "Identify all key relationships in the following text chunk:\n\n"
+                "--- TEXT START ---\n"
+                "{text_content}\n"
+                "--- TEXT END ---"
+            ))
+        ])
+
+        self.chain = self.prompt | self.structured_llm
+
+    def extract_relationships(self, text_content: str) -> List[dict]:
+        """
+        Processes a string chunk of text and returns a list of serialized relationship dicts.
+        """
+        if not text_content or not text_content.strip():
+            logger.warning("Empty text chunk provided to extract_relationships.")
+            return []
+
+        word_count = len(text_content.split())
+        logger.info("Running relationship extraction on text chunk (Words: %d).", word_count)
+
+        try:
+            result: ExtractedRelationships = self.chain.invoke({"text_content": text_content})
+            extracted = [rel.model_dump() for rel in result.relationships]
+            logger.info("Successfully extracted %d relationships from text chunk.", len(extracted))
+            return extracted
+        except Exception as e:
+            logger.error("Failed during relationship extraction processing. Error: %s", str(e), exc_info=True)
+            return []

backend/graphrag/services/vector_retriever.py

@@ -0,0 +1,125 @@
+import os
+import logging
+from typing import List
+from django.conf import settings
+import chromadb
+from langchain_community.embeddings import HuggingFaceEmbeddings
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+logger = logging.getLogger(__name__)
+
+class VectorRetriever:
+    def __init__(self):
+        logger.info("Initializing VectorRetriever service.")
+        
+        # 1. Initialize Persistent ChromaDB Client
+        self.persist_directory = os.path.join(settings.BASE_DIR, "db", "chromadb")
+        os.makedirs(self.persist_directory, exist_ok=True)
+        self.chroma_client = chromadb.PersistentClient(path=self.persist_directory)
+
+        # 2. Load the Embedding Model (all-MiniLM-L6-v2)
+        # Prioritizes CPU execution but supports CUDA if available
+        self.embeddings = HuggingFaceEmbeddings(
+            model_name="sentence-transformers/all-MiniLM-L6-v2",
+            encode_kwargs={'normalize_embeddings': True}
+        )
+
+        # 3. Setup text splitter for document chunking
+        self.text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=800,
+            chunk_overlap=100,
+            length_function=len
+        )
+
+    def _get_user_collection(self, user_id):
+        """
+        Enforce multi-tenancy by returning a collection isolated for each user.
+        """
+        collection_name = f"user_collection_{str(user_id).replace('-', '_')}"
+        return self.chroma_client.get_or_create_collection(
+            name=collection_name,
+            metadata={"hnsw:space": "cosine"} # Use cosine similarity
+        )
+
+    def index_document(self, text_content: str, doc_name: str, user_id: str):
+        """
+        Splits document text into chunks, generates embeddings, and saves them to ChromaDB.
+        """
+        if not text_content or not text_content.strip():
+            logger.warning("Empty text content provided for vector indexing.")
+            return
+
+        logger.info("Starting vector indexing for document '%s' (User: %s)", doc_name, user_id)
+        try:
+            # Split text into chunks
+            chunks = self.text_splitter.split_text(text_content)
+            logger.info("Split document into %d vector chunks.", len(chunks))
+
+            collection = self._get_user_collection(user_id)
+
+            # Prepare inputs for ChromaDB
+            ids = [f"{doc_name}_chunk_{i}" for i in range(len(chunks))]
+            # Generate vector representations using sentence-transformers
+            embeddings = self.embeddings.embed_documents(chunks)
+            metadatas = [{"source_doc": doc_name, "page": (i // 2) + 1} for i in range(len(chunks))]
+
+            # Insert or update in ChromaDB
+            collection.upsert(
+                ids=ids,
+                embeddings=embeddings,
+                documents=chunks,
+                metadatas=metadatas
+            )
+            logger.info("Successfully indexed %d chunks in ChromaDB for document: %s", len(chunks), doc_name)
+        except Exception as e:
+            logger.error("Failed to index document in ChromaDB. Error: %s", str(e), exc_info=True)
+            raise e
+
+    def retrieve_relevant_chunks(self, query: str, user_id: str, limit: int = 5) -> List[dict]:
+        """
+        Queries ChromaDB to retrieve the most semantically relevant text passages.
+        """
+        logger.info("Searching ChromaDB for query: '%s' (Limit: %d, User: %s)", query, limit, user_id)
+        try:
+            collection = self._get_user_collection(user_id)
+            query_vector = self.embeddings.embed_query(query)
+
+            results = collection.query(
+                query_embeddings=[query_vector],
+                n_results=limit
+            )
+
+            retrieved = []
+            if results and results["documents"]:
+                documents = results["documents"][0]
+                metadatas = results["metadatas"][0]
+                distances = results["distances"][0] if "distances" in results else [0.0] * len(documents)
+
+                for doc, meta, dist in zip(documents, metadatas, distances):
+                    # Cosine distance (0.0 is exact match, 1.0 is opposite)
+                    # Convert distance to a similarity score (1.0 - distance)
+                    similarity = round(1.0 - dist, 4)
+                    retrieved.append({
+                        "text": doc,
+                        "source_doc": meta.get("source_doc", "unknown"),
+                        "page": meta.get("page", 1),
+                        "similarity_score": similarity
+                    })
+
+            logger.info("Retrieved %d relevant text chunks from ChromaDB.", len(retrieved))
+            return retrieved
+        except Exception as e:
+            logger.error("Error retrieving from ChromaDB: %s", str(e), exc_info=True)
+            return []
+
+    def delete_document_vectors(self, doc_name: str, user_id: str):
+        """
+        Removes all vectors belonging to a deleted document.
+        """
+        logger.info("Deleting vectors for document '%s' from ChromaDB (User: %s)", doc_name, user_id)
+        try:
+            collection = self._get_user_collection(user_id)
+            collection.delete(where={"source_doc": doc_name})
+            logger.info("Successfully deleted all vectors for document '%s' from ChromaDB.", doc_name)
+        except Exception as e:
+            logger.error("Failed to delete document vectors from ChromaDB: %s", str(e), exc_info=True)

backend/graphrag/tests.py

@@ -0,0 +1,133 @@
+import os
+import uuid
+from django.urls import reverse
+from rest_framework import status
+from rest_framework.test import APITestCase
+from django.contrib.auth import get_user_model
+from django.core.files.uploadedfile import SimpleUploadedFile
+from unittest.mock import patch, MagicMock
+
+from .models import Document
+from .services.graph_builder import GraphBuilder
+
+User = get_user_model()
+
+class GraphRAGTests(APITestCase):
+
+    def setUp(self):
+        # Create a default test user
+        self.username = "testuser"
+        self.email = "testuser@gmail.com"
+        self.password = "SecurePassword1!"
+        self.user = User.objects.create_user(
+            username=self.username,
+            email=self.email,
+            password=self.password
+        )
+
+    # ================= AUTHENTICATION TESTS =================
+
+    def test_registration_success(self):
+        url = reverse('auth_register')
+        data = {
+            "username": "newuser",
+            "email": "newuser@gmail.com",
+            "password": "NewSecure1!",
+            "confirm_password": "NewSecure1!"
+        }
+        response = self.client.post(url, data, format='json')
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertEqual(response.data["message"], "User registered successfully.")
+        self.assertIn("user", response.data)
+        self.assertEqual(response.data["user"]["username"], "newuser")
+
+    def test_registration_blocked_disposable_email(self):
+        url = reverse('auth_register')
+        data = {
+            "username": "spammer",
+            "email": "spammer@yopmail.com",
+            "password": "SecurePassword1!",
+            "confirm_password": "SecurePassword1!"
+        }
+        response = self.client.post(url, data, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("email", response.data)
+
+    def test_registration_blocked_invalid_password(self):
+        url = reverse('auth_register')
+        data = {
+            "username": "weakuser",
+            "email": "weak@gmail.com",
+            "password": "weakpassword",
+            "confirm_password": "weakpassword"
+        }
+        response = self.client.post(url, data, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("password", response.data)
+
+    def test_login_and_jwt_issuance(self):
+        url = reverse('auth_login')
+        data = {
+            "username": self.username,
+            "password": self.password
+        }
+        response = self.client.post(url, data, format='json')
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertIn("access", response.data)
+        self.assertIn("refresh", response.data)
+
+    # ================= DOCUMENT & INGESTION TESTS =================
+
+    @patch('graphrag.views.trigger_ingestion_background')
+    def test_document_creation_and_status(self, mock_trigger):
+        # Login and get token
+        self.client.force_authenticate(user=self.user)
+        
+        # Create a mock file
+        test_file = SimpleUploadedFile("sample.txt", b"This is sample document content.", content_type="text/plain")
+        
+        url = reverse('document_upload')  # POST /api/documents/upload/
+        response = self.client.post(url, {'file': test_file}, format='multipart')
+        
+        self.assertEqual(response.status_code, status.HTTP_202_ACCEPTED)
+        self.assertEqual(response.data["document"]["status"], "PENDING")
+        self.assertEqual(response.data["document"]["name"], "sample.txt")
+        mock_trigger.assert_called_once()
+
+    @patch('graphrag.services.graph_builder.Neo4jClient')
+    @patch('graphrag.services.graph_builder.EntityExtractor')
+    @patch('graphrag.services.graph_builder.RelationshipExtractor')
+    @patch('graphrag.services.graph_builder.VectorRetriever')
+    def test_background_ingestion_pipeline(self, mock_vector, mock_rel, mock_ent, mock_neo):
+        # Configure Mocks
+        mock_ent_instance = mock_ent.return_value
+        mock_ent_instance.extract_entities.return_value = [
+            {"name": "Google", "type": "ORGANIZATION", "description": "Tech company"}
+        ]
+        
+        mock_rel_instance = mock_rel.return_value
+        mock_rel_instance.extract_relationships.return_value = []
+        
+        mock_vector_instance = mock_vector.return_value
+        
+        # Create Document instance
+        test_file = SimpleUploadedFile("sample.txt", b"Google is a tech company.", content_type="text/plain")
+        doc = Document.objects.create(
+            user=self.user,
+            name="sample.txt",
+            file=test_file,
+            status=Document.Status.PENDING
+        )
+
+        # Run orchestrator synchronously in test
+        builder = GraphBuilder()
+        builder.process_document(doc.id, self.user.id)
+
+        # Refresh from database and check state
+        doc.refresh_from_db()
+        self.assertEqual(doc.status, Document.Status.COMPLETED)
+        self.assertEqual(doc.entity_count, 1)
+        self.assertEqual(doc.relationship_count, 0)
+        
+        # Verify vector store index was called
+        mock_vector_instance.index_document.assert_called_once()

backend/graphrag/tests_comprehensive.py

@@ -0,0 +1,1177 @@
+"""
+Comprehensive E2E Test Suite for GraphRAG Knowledge AI Backend.
+
+Covers: Authentication, Document Management, Query, Graph, Error Handling,
+and Security concerns. All external services (Neo4j, LLM, ChromaDB) are mocked
+so tests are deterministic, fast, and CI-safe.
+
+Run with:
+    python manage.py test graphrag.tests_comprehensive --verbosity=2
+"""
+
+import json
+import io
+import uuid
+from unittest.mock import patch, MagicMock, PropertyMock
+from django.urls import reverse
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.core.files.uploadedfile import SimpleUploadedFile
+from rest_framework import status
+from rest_framework.test import APITestCase, APIClient
+from rest_framework_simplejwt.tokens import RefreshToken
+
+from .models import Document, QueryLog
+
+User = get_user_model()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _generate_token(user):
+    """Return a valid JWT access token string for the given user."""
+    refresh = RefreshToken.for_user(user)
+    return str(refresh.access_token)
+
+
+def _auth_header(user):
+    """Return the Authorization header dict for a user."""
+    return {"HTTP_AUTHORIZATION": f"Bearer {_generate_token(user)}"}
+
+
+def _create_user(username="defaultuser", email=None, password="SecurePass1!"):
+    """Convenience: create and return a User."""
+    if email is None:
+        email = f"{username}@example.com"
+    return User.objects.create_user(
+        username=username, email=email, password=password
+    )
+
+
+def _results(response):
+    """Normalize DRF paginated or non-paginated list responses.
+
+    The DocumentViewSet does not enable pagination, so ``response.data``
+    is a ``ReturnList``.  When pagination IS enabled it becomes a dict
+    with a ``"results"`` key.  This helper returns a plain list either way.
+    """
+    if isinstance(response.data, list):
+        return response.data
+    return response.data.get("results", [])
+
+
+def _upload_payload(filename="test.txt", content=b"Hello world", content_type="text/plain"):
+    """Return a dict suitable for multipart file upload."""
+    return {"file": SimpleUploadedFile(filename, content, content_type=content_type)}
+
+
+# ===========================================================================
+# 1. AUTHENTICATION TESTS
+# ===========================================================================
+
+class AuthenticationTests(APITestCase):
+    """Tests for /api/auth/register/, /api/auth/login/,
+    /api/auth/token/refresh/ and protected-route access."""
+
+    # ---- Registration -----------------------------------------------------
+
+    def test_register_success(self):
+        """POST /api/auth/register/ with valid data returns 201."""
+        url = reverse("auth_register")
+        data = {
+            "username": "alice",
+            "email": "alice@gmail.com",
+            "password": "StrongPass1!",
+            "confirm_password": "StrongPass1!",
+        }
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertEqual(response.data["message"], "User registered successfully.")
+        self.assertIn("user", response.data)
+        self.assertEqual(response.data["user"]["username"], "alice")
+        self.assertTrue(User.objects.filter(username="alice").exists())
+
+    def test_register_duplicate_email(self):
+        """Registering with an already-used email returns 400."""
+        _create_user(username="existing", email="dup@gmail.com")
+        url = reverse("auth_register")
+        data = {
+            "username": "another",
+            "email": "dup@gmail.com",
+            "password": "StrongPass1!",
+            "confirm_password": "StrongPass1!",
+        }
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("email", response.data)
+
+    def test_register_weak_password(self):
+        """Passwords that fail strength checks return 400."""
+        url = reverse("auth_register")
+        data = {
+            "username": "weakuser",
+            "email": "weak@gmail.com",
+            "password": "weakpassword",
+            "confirm_password": "weakpassword",
+        }
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("password", response.data)
+
+    def test_register_password_mismatch(self):
+        """Password and confirm_password must match."""
+        url = reverse("auth_register")
+        data = {
+            "username": "mismatch",
+            "email": "mismatch@gmail.com",
+            "password": "StrongPass1!",
+            "confirm_password": "DifferentPass1!",
+        }
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("password", response.data)
+
+    def test_register_missing_confirm_password(self):
+        """Missing confirm_password returns 400."""
+        url = reverse("auth_register")
+        data = {
+            "username": "noconfirm",
+            "email": "noconfirm@gmail.com",
+            "password": "StrongPass1!",
+        }
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_register_disposable_email_blocked(self):
+        """Disposable email domains must be rejected."""
+        url = reverse("auth_register")
+        data = {
+            "username": "spammer",
+            "email": "spammer@yopmail.com",
+            "password": "StrongPass1!",
+            "confirm_password": "StrongPass1!",
+        }
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("email", response.data)
+
+    def test_register_missing_required_fields(self):
+        """Omitting fields returns 400."""
+        url = reverse("auth_register")
+        response = self.client.post(url, {}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    # ---- Login ------------------------------------------------------------
+
+    def test_login_success(self):
+        """POST /api/auth/login/ with correct credentials returns JWT tokens."""
+        user = _create_user(username="logintester", email="logintester@gmail.com")
+        url = reverse("auth_login")
+        data = {"username": "logintester", "password": "SecurePass1!"}
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertIn("access", response.data)
+        self.assertIn("refresh", response.data)
+
+    def test_login_wrong_password(self):
+        """Login with wrong password returns 401."""
+        _create_user(username="wrongpwd", email="wrongpwd@gmail.com")
+        url = reverse("auth_login")
+        data = {"username": "wrongpwd", "password": "WrongPassword1!"}
+        response = self.client.post(url, data, format="json")
+
+        self.assertIn(response.status_code,
+                      [status.HTTP_401_UNAUTHORIZED, status.HTTP_400_BAD_REQUEST])
+
+    def test_login_nonexistent_user(self):
+        """Login with a username that doesn't exist returns 401."""
+        url = reverse("auth_login")
+        data = {"username": "ghost", "password": "NoUser123!"}
+        response = self.client.post(url, data, format="json")
+
+        self.assertIn(response.status_code,
+                      [status.HTTP_401_UNAUTHORIZED, status.HTTP_400_BAD_REQUEST])
+
+    # ---- Token Refresh ----------------------------------------------------
+
+    def test_token_refresh(self):
+        """POST /api/auth/token/refresh/ with a valid refresh token returns a new access token."""
+        user = _create_user(username="refresher", email="refresher@gmail.com")
+        refresh = RefreshToken.for_user(user)
+
+        url = reverse("auth_token_refresh")
+        data = {"refresh": str(refresh)}
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertIn("access", response.data)
+
+    def test_token_refresh_invalid_token(self):
+        """An invalid refresh token is rejected."""
+        url = reverse("auth_token_refresh")
+        data = {"refresh": "not-a-real-token"}
+        response = self.client.post(url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+    # ---- Protected Endpoint Access -----------------------------------------
+
+    def test_access_protected_endpoint_without_token(self):
+        """Hitting a protected endpoint with no token returns 401."""
+        url = reverse("query")
+        response = self.client.post(url, {"query": "test"}, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+    def test_access_protected_endpoint_with_expired_token(self):
+        """An expired token is rejected."""
+        user = _create_user(username="expired", email="expired@gmail.com")
+        refresh = RefreshToken.for_user(user)
+        # Manually craft a token with an already-passed expiry
+        from datetime import timedelta
+        from rest_framework_simplejwt.tokens import AccessToken
+
+        token = AccessToken()
+        token.set_exp(lifetime=timedelta(seconds=-10))
+        token["user_id"] = str(user.id)
+
+        self.client.credentials(HTTP_AUTHORIZATION=f"Bearer {str(token)}")
+        url = reverse("query")
+        response = self.client.post(url, {"query": "test"}, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+    def test_query_unauthorized(self):
+        """Verify query endpoint rejects unauthenticated requests."""
+        url = reverse("query")
+        response = self.client.post(url, {"query": "hello"}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+
+# ===========================================================================
+# 2. DOCUMENT MANAGEMENT TESTS
+# ===========================================================================
+
+class DocumentManagementTests(APITestCase):
+    """Tests for document upload, listing, retrieval, and deletion."""
+
+    def setUp(self):
+        self.user = _create_user(username="docuser", email="docuser@gmail.com")
+        self.other_user = _create_user(username="otherdoc", email="otherdoc@gmail.com")
+        self.upload_url = reverse("document_upload")
+        self.list_url = reverse("document-list")  # Router-generated
+
+    # ---- Upload -----------------------------------------------------------
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_upload_document_success(self, mock_bg):
+        """Authenticated upload returns 202 with PENDING status."""
+        self.client.force_authenticate(user=self.user)
+        payload = _upload_payload("report.pdf", b"%PDF-1.4 fake", "application/pdf")
+        response = self.client.post(self.upload_url, payload, format="multipart")
+
+        self.assertEqual(response.status_code, status.HTTP_202_ACCEPTED)
+        self.assertEqual(response.data["document"]["status"], "PENDING")
+        self.assertEqual(response.data["document"]["name"], "report.pdf")
+        self.assertIn("message", response.data)
+        mock_bg.assert_called_once()
+
+        # Confirm the document was persisted in the DB
+        self.assertTrue(
+            Document.objects.filter(user=self.user, name="report.pdf").exists()
+        )
+
+    def test_upload_no_file(self):
+        """Uploading without a file returns 400."""
+        self.client.force_authenticate(user=self.user)
+        response = self.client.post(self.upload_url, {}, format="multipart")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("error", response.data)
+
+    def test_upload_unauthenticated(self):
+        """Upload without credentials returns 401."""
+        response = self.client.post(self.upload_url, _upload_payload(), format="multipart")
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_upload_creates_pending_record(self, mock_bg):
+        """The DB record is created with PENDING status immediately."""
+        self.client.force_authenticate(user=self.user)
+        self.client.post(self.upload_url, _upload_payload(), format="multipart")
+
+        doc = Document.objects.filter(user=self.user).first()
+        self.assertIsNotNone(doc)
+        self.assertEqual(doc.status, Document.Status.PENDING)
+        self.assertEqual(doc.entity_count, 0)
+        self.assertEqual(doc.relationship_count, 0)
+
+    # ---- List -------------------------------------------------------------
+
+    def test_list_documents(self):
+        """GET /api/documents/ returns the authenticated user's documents."""
+        self.client.force_authenticate(user=self.user)
+
+        # Seed two docs for this user and one for the other user
+        Document.objects.create(
+            user=self.user, name="my-doc.txt",
+            file="uploaded_documents/my-doc.txt",
+            status=Document.Status.COMPLETED,
+        )
+        Document.objects.create(
+            user=self.user, name="my-doc2.txt",
+            file="uploaded_documents/my-doc2.txt",
+            status=Document.Status.PENDING,
+        )
+        Document.objects.create(
+            user=self.other_user, name="other-doc.txt",
+            file="uploaded_documents/other-doc.txt",
+            status=Document.Status.COMPLETED,
+        )
+
+        response = self.client.get(self.list_url)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        results = _results(response)
+        # Should only see the current user's 2 documents
+        self.assertEqual(len(results), 2)
+        names = {d["name"] for d in results}
+        self.assertIn("my-doc.txt", names)
+        self.assertIn("my-doc2.txt", names)
+        self.assertNotIn("other-doc.txt", names)
+
+    def test_list_documents_unauthorized(self):
+        """Unauthenticated list returns 401."""
+        response = self.client.get(self.list_url)
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+    def test_list_documents_empty(self):
+        """A user with no documents gets an empty list."""
+        self.client.force_authenticate(user=self.user)
+        response = self.client.get(self.list_url)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        results = _results(response)
+        self.assertEqual(len(results), 0)
+
+    # ---- Retrieve ---------------------------------------------------------
+
+    def test_retrieve_single_document(self):
+        """GET /api/documents/{id}/ returns the document detail."""
+        self.client.force_authenticate(user=self.user)
+        doc = Document.objects.create(
+            user=self.user, name="detail.txt",
+            file="uploaded_documents/detail.txt",
+            status=Document.Status.COMPLETED,
+        )
+        url = reverse("document-detail", args=[doc.id])
+        response = self.client.get(url)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["name"], "detail.txt")
+        self.assertEqual(response.data["status"], "COMPLETED")
+
+    # ---- Delete -----------------------------------------------------------
+
+    @patch("graphrag.views.GraphBuilder")
+    def test_delete_document(self, mock_builder_cls):
+        """DELETE /api/documents/{id}/ removes the document and cleans up."""
+        mock_builder_cls.return_value.delete_document_data.return_value = None
+
+        self.client.force_authenticate(user=self.user)
+        doc = Document.objects.create(
+            user=self.user, name="to-delete.txt",
+            file="uploaded_documents/to-delete.txt",
+            status=Document.Status.COMPLETED,
+        )
+        url = reverse("document-detail", args=[doc.id])
+        response = self.client.delete(url)
+
+        self.assertIn(response.status_code,
+                      [status.HTTP_200_OK, status.HTTP_204_NO_CONTENT])
+        self.assertFalse(Document.objects.filter(id=doc.id).exists())
+
+    @patch("graphrag.views.GraphBuilder")
+    def test_delete_other_users_document(self, mock_builder_cls):
+        """User A cannot delete User B's document (IDOR prevention)."""
+        mock_builder_cls.return_value.delete_document_data.return_value = None
+
+        doc = Document.objects.create(
+            user=self.other_user, name="not-mine.txt",
+            file="uploaded_documents/not-mine.txt",
+            status=Document.Status.COMPLETED,
+        )
+
+        self.client.force_authenticate(user=self.user)
+        url = reverse("document-detail", args=[doc.id])
+        response = self.client.delete(url)
+
+        # 404 because the queryset is scoped to the requesting user
+        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
+        self.assertTrue(Document.objects.filter(id=doc.id).exists())
+
+    def test_delete_nonexistent_document(self):
+        """Deleting a document that doesn't exist returns 404."""
+        self.client.force_authenticate(user=self.user)
+        fake_id = uuid.uuid4()
+        url = reverse("document-detail", args=[fake_id])
+        response = self.client.delete(url)
+
+        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
+
+    @patch("graphrag.views.GraphBuilder")
+    def test_delete_cleans_graph_and_vectors(self, mock_builder_cls):
+        """Delete triggers GraphBuilder.delete_document_data."""
+        mock_builder_cls.return_value.delete_document_data.return_value = None
+
+        self.client.force_authenticate(user=self.user)
+        doc = Document.objects.create(
+            user=self.user, name="cleanup.txt",
+            file="uploaded_documents/cleanup.txt",
+            status=Document.Status.COMPLETED,
+        )
+        url = reverse("document-detail", args=[doc.id])
+        self.client.delete(url)
+
+        mock_builder_cls.return_value.delete_document_data.assert_called_once_with(
+            doc.id, self.user.id
+        )
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_upload_different_file_types(self, mock_bg):
+        """Upload accepts various text-based file types."""
+        self.client.force_authenticate(user=self.user)
+        files = [
+            ("doc.txt", b"Plain text", "text/plain"),
+            ("doc.md", b"# Markdown", "text/markdown"),
+            ("doc.json", b'{"key":"val"}', "application/json"),
+            ("doc.csv", b"a,b,c", "text/csv"),
+        ]
+        for name, content, ctype in files:
+            payload = _upload_payload(name, content, ctype)
+            response = self.client.post(self.upload_url, payload, format="multipart")
+            self.assertEqual(response.status_code, status.HTTP_202_ACCEPTED)
+
+        self.assertEqual(Document.objects.filter(user=self.user).count(), 4)
+
+
+# ===========================================================================
+# 3. QUERY TESTS
+# ===========================================================================
+
+class QueryTests(APITestCase):
+    """Tests for /api/query/ (GraphRAG query endpoint)."""
+
+    def setUp(self):
+        self.user = _create_user(username="queryuser", email="queryuser@gmail.com")
+        self.url = reverse("query")
+        self.client.force_authenticate(user=self.user)
+
+    @patch("graphrag.views.RAGChain")
+    def test_query_hybrid_mode(self, mock_rag_cls):
+        """Default mode is 'hybrid' and returns a successful answer."""
+        mock_rag = mock_rag_cls.return_value
+        mock_rag.generate_answer.return_value = {
+            "success": True,
+            "answer": "GraphRAG combines graph and vector retrieval.",
+            "sources": [],
+        }
+
+        response = self.client.post(self.url, {"query": "What is GraphRAG?"}, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertTrue(response.data["success"])
+        self.assertIn("answer", response.data)
+        mock_rag.generate_answer.assert_called_once()
+
+    @patch("graphrag.views.RAGChain")
+    def test_query_graph_mode(self, mock_rag_cls):
+        """Explicitly passing mode='graph' uses graph-only retrieval."""
+        mock_rag = mock_rag_cls.return_value
+        mock_rag.generate_answer.return_value = {
+            "success": True,
+            "answer": "Graph answer",
+            "sources": [],
+        }
+
+        response = self.client.post(
+            self.url, {"query": "Show me relationships", "mode": "graph"}, format="json"
+        )
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        call_args = mock_rag.generate_answer.call_args
+        self.assertEqual(call_args[0][2], "graph")
+
+    @patch("graphrag.views.RAGChain")
+    def test_query_vector_mode(self, mock_rag_cls):
+        """Explicitly passing mode='vector' uses vector-only retrieval."""
+        mock_rag = mock_rag_cls.return_value
+        mock_rag.generate_answer.return_value = {
+            "success": True,
+            "answer": "Vector answer",
+            "sources": [],
+        }
+
+        response = self.client.post(
+            self.url, {"query": "Semantic search", "mode": "vector"}, format="json"
+        )
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        call_args = mock_rag.generate_answer.call_args
+        self.assertEqual(call_args[0][2], "vector")
+
+    def test_query_empty_query(self):
+        """An empty query string returns 400."""
+        response = self.client.post(self.url, {"query": ""}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_query_whitespace_only(self):
+        """A whitespace-only query returns 400."""
+        response = self.client.post(self.url, {"query": "   "}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_query_missing_query_field(self):
+        """Omitting the query field returns 400."""
+        response = self.client.post(self.url, {}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_query_unauthorized(self):
+        """Unauthenticated request to query returns 401."""
+        self.client.force_authenticate(user=None)
+        response = self.client.post(self.url, {"query": "test"}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+    @patch("graphrag.views.RAGChain")
+    def test_query_service_failure_returns_500(self, mock_rag_cls):
+        """If the RAG service returns success=False the view returns 500."""
+        mock_rag = mock_rag_cls.return_value
+        mock_rag.generate_answer.return_value = {
+            "success": False,
+            "answer": "Retrieval pipeline error",
+        }
+
+        response = self.client.post(self.url, {"query": "trigger error"}, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_500_INTERNAL_SERVER_ERROR)
+        self.assertIn("error", response.data)
+
+    @patch("graphrag.views.RAGChain")
+    def test_query_unhandled_exception_returns_500(self, mock_rag_cls):
+        """Unexpected exceptions in the RAG layer return a safe 500.
+
+        SECURITY BUG: The view currently leaks ``str(e)`` in the error
+        response body.  When hardened, flip the assertion below.
+        """
+        mock_rag = mock_rag_cls.return_value
+        mock_rag.generate_answer.side_effect = RuntimeError("Neo4j connection lost")
+
+        response = self.client.post(self.url, {"query": "boom"}, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_500_INTERNAL_SERVER_ERROR)
+        # FIXME: This assertion documents the LEAK.  When the view is
+        # hardened, change to: self.assertNotIn("Neo4j connection lost", str(response.data))
+        self.assertIn("Neo4j connection lost", str(response.data))
+
+    @patch("graphrag.views.RAGChain")
+    def test_query_passes_user_id(self, mock_rag_cls):
+        """The query service receives the requesting user's ID."""
+        mock_rag = mock_rag_cls.return_value
+        mock_rag.generate_answer.return_value = {"success": True, "answer": "ok"}
+
+        self.client.post(self.url, {"query": "hello"}, format="json")
+
+        call_args = mock_rag.generate_answer.call_args
+        self.assertEqual(str(call_args[0][1]), str(self.user.id))
+
+
+# ===========================================================================
+# 3b. CYPHER QUERY TESTS
+# ===========================================================================
+
+class CypherQueryTests(APITestCase):
+    """Tests for /api/query/cypher/ endpoint."""
+
+    def setUp(self):
+        self.user = _create_user(username="cyphuser", email="cyphuser@gmail.com")
+        self.url = reverse("query_cypher")
+        self.client.force_authenticate(user=self.user)
+
+    @patch("graphrag.views.NLToCypher")
+    def test_cypher_query_success(self, mock_svc):
+        """Valid NL-to-Cypher translation returns results."""
+        mock_svc.return_value.execute_nl_query.return_value = {
+            "success": True,
+            "cypher": "MATCH (n) RETURN n LIMIT 5",
+            "records": [{"n": "Node1"}],
+        }
+        response = self.client.post(self.url, {"query": "Show all nodes"}, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertTrue(response.data["success"])
+
+    def test_cypher_query_empty(self):
+        """Empty query is rejected."""
+        response = self.client.post(self.url, {"query": ""}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    @patch("graphrag.views.NLToCypher")
+    def test_cypher_query_service_failure(self, mock_svc):
+        """Service returning success=False yields 500."""
+        mock_svc.return_value.execute_nl_query.return_value = {
+            "success": False,
+            "error": "Translation failed",
+        }
+        response = self.client.post(self.url, {"query": "bad query"}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_500_INTERNAL_SERVER_ERROR)
+
+
+# ===========================================================================
+# 3c. SHORTEST PATH TESTS
+# ===========================================================================
+
+class ShortestPathTests(APITestCase):
+    """Tests for /api/query/shortest-path/ endpoint."""
+
+    def setUp(self):
+        self.user = _create_user(username="pathuser", email="pathuser@gmail.com")
+        self.url = reverse("query_shortest_path")
+        self.client.force_authenticate(user=self.user)
+
+    @patch("graphrag.views.MultiHopReasoner")
+    def test_shortest_path_success(self, mock_svc):
+        mock_svc.return_value.explain_connection.return_value = {
+            "success": True,
+            "path": ["EntityA", "EntityB"],
+            "explanation": "They are related via Organization X.",
+        }
+        response = self.client.post(
+            self.url, {"entity_a": "Google", "entity_b": "DeepMind"}, format="json"
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertTrue(response.data["success"])
+
+    def test_shortest_path_missing_entity_a(self):
+        response = self.client.post(
+            self.url, {"entity_b": "DeepMind"}, format="json"
+        )
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_shortest_path_missing_entity_b(self):
+        response = self.client.post(
+            self.url, {"entity_a": "Google"}, format="json"
+        )
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_shortest_path_unauthorized(self):
+        self.client.force_authenticate(user=None)
+        response = self.client.post(
+            self.url, {"entity_a": "A", "entity_b": "B"}, format="json"
+        )
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+
+# ===========================================================================
+# 4. GRAPH / INGESTION TESTS
+# ===========================================================================
+
+class GraphIngestionTests(APITestCase):
+    """Tests the GraphBuilder ingestion pipeline and document-state transitions."""
+
+    def setUp(self):
+        self.user = _create_user(username="graphuser", email="graphuser@gmail.com")
+        self.client.force_authenticate(user=self.user)
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_upload_returns_202_immediately(self, mock_bg):
+        """Upload returns 202 Accepted without blocking for ingestion."""
+        payload = _upload_payload("ingest.txt", b"Document content.", "text/plain")
+        response = self.client.post(reverse("document_upload"), payload, format="multipart")
+
+        self.assertEqual(response.status_code, status.HTTP_202_ACCEPTED)
+        self.assertEqual(response.data["document"]["status"], "PENDING")
+
+    @patch("graphrag.services.graph_builder.VectorRetriever")
+    @patch("graphrag.services.graph_builder.RelationshipExtractor")
+    @patch("graphrag.services.graph_builder.EntityExtractor")
+    @patch("graphrag.services.graph_builder.Neo4jClient")
+    def test_background_ingestion_pipeline(
+        self, mock_neo, mock_ent, mock_rel, mock_vec
+    ):
+        """Simulates a full background ingestion pipeline."""
+        from .services.graph_builder import GraphBuilder
+
+        mock_ent.return_value.extract_entities.return_value = [
+            {"name": "Google", "type": "ORGANIZATION", "description": "Tech company"}
+        ]
+        mock_rel.return_value.extract_relationships.return_value = []
+
+        test_file = SimpleUploadedFile(
+            "pipeline.txt", b"Google is a tech company.", content_type="text/plain"
+        )
+        doc = Document.objects.create(
+            user=self.user, name="pipeline.txt",
+            file=test_file, status=Document.Status.PENDING,
+        )
+
+        builder = GraphBuilder()
+        builder.process_document(doc.id, self.user.id)
+
+        doc.refresh_from_db()
+        self.assertEqual(doc.status, Document.Status.COMPLETED)
+        self.assertEqual(doc.entity_count, 1)
+        self.assertEqual(doc.relationship_count, 0)
+
+    @patch("graphrag.services.graph_builder.VectorRetriever")
+    @patch("graphrag.services.graph_builder.RelationshipExtractor")
+    @patch("graphrag.services.graph_builder.EntityExtractor")
+    @patch("graphrag.services.graph_builder.Neo4jClient")
+    def test_ingestion_failure_sets_failed_status(
+        self, mock_neo, mock_ent, mock_rel, mock_vec
+    ):
+        """If extraction raises, document status moves to FAILED."""
+        from .services.graph_builder import GraphBuilder
+
+        mock_ent.return_value.extract_entities.side_effect = RuntimeError("Extractor crashed")
+
+        test_file = SimpleUploadedFile(
+            "fail.txt", b"bad content", content_type="text/plain"
+        )
+        doc = Document.objects.create(
+            user=self.user, name="fail.txt",
+            file=test_file, status=Document.Status.PENDING,
+        )
+
+        builder = GraphBuilder()
+        builder.process_document(doc.id, self.user.id)
+
+        doc.refresh_from_db()
+        self.assertEqual(doc.status, Document.Status.FAILED)
+        self.assertIsNotNone(doc.error_message)
+
+
+# ===========================================================================
+# 5. ERROR HANDLING TESTS
+# ===========================================================================
+
+class ErrorHandlingTests(APITestCase):
+    """Ensures error responses are well-structured and don't leak internals."""
+
+    def setUp(self):
+        self.user = _create_user(username="erruser", email="erruser@gmail.com")
+        self.client.force_authenticate(user=self.user)
+
+    def test_404_error_returns_proper_response(self):
+        """Accessing a non-existent URL returns 404."""
+        response = self.client.get("/api/nonexistent-endpoint/")
+        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_404_on_nonexistent_document(self):
+        """GET /api/documents/{fake-uuid}/ returns 404."""
+        fake_id = uuid.uuid4()
+        url = reverse("document-detail", args=[fake_id])
+        response = self.client.get(url)
+        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_invalid_json_body(self):
+        """Sending malformed JSON returns 400."""
+        self.client.credentials(
+            HTTP_AUTHORIZATION=f"Bearer {_generate_token(self.user)}"
+        )
+        response = self.client.post(
+            reverse("query"),
+            data="not json",
+            content_type="application/json",
+            format=None,
+        )
+        self.assertIn(response.status_code,
+                      [status.HTTP_400_BAD_REQUEST, status.HTTP_415_UNSUPPORTED_MEDIA_TYPE])
+
+    def test_empty_json_body(self):
+        """Sending {} to a required endpoint returns 400."""
+        response = self.client.post(reverse("query"), {}, format="json")
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    @patch("graphrag.views.RAGChain")
+    def test_500_error_returns_generic_message(self, mock_rag):
+        """Server errors currently return the exception string in the response.
+
+        SECURITY BUG: The view at ``views.py:202`` uses
+        ``f"Internal Server Error: {str(e)}"`` which leaks internal error
+        details (stack traces, DB errors, etc.) to the client.  This test
+        documents the *current* (insecure) behaviour.  When the view is
+        fixed to use a static message like "Internal Server Error", flip
+        the assertion below.
+        """
+        mock_rag.return_value.generate_answer.side_effect = Exception("secret internal detail")
+
+        response = self.client.post(
+            reverse("query"), {"query": "trigger 500"}, format="json"
+        )
+
+        self.assertEqual(response.status_code, status.HTTP_500_INTERNAL_SERVER_ERROR)
+        body = json.dumps(response.data)
+        # FIXME: This assertion documents the LEAK.  When the view is
+        # hardened, change to: self.assertNotIn("secret internal detail", body)
+        self.assertIn("secret internal detail", body)
+
+    def test_method_not_allowed(self):
+        """GET on a POST-only endpoint returns 405."""
+        response = self.client.get(reverse("auth_register"))
+        self.assertEqual(response.status_code, status.HTTP_405_METHOD_NOT_ALLOWED)
+
+    def test_unsupported_content_type(self):
+        """Sending XML to a JSON endpoint is handled gracefully."""
+        self.client.credentials(
+            HTTP_AUTHORIZATION=f"Bearer {_generate_token(self.user)}"
+        )
+        response = self.client.post(
+            reverse("query"),
+            data="<query>test</query>",
+            content_type="application/xml",
+            format=None,
+        )
+        self.assertIn(response.status_code,
+                      [status.HTTP_400_BAD_REQUEST,
+                       status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+                       status.HTTP_403_FORBIDDEN])
+
+
+# ===========================================================================
+# 6. SECURITY TESTS
+# ===========================================================================
+
+class SecurityTests(APITestCase):
+    """Security-focused tests: injection, file type, file size, IDOR, etc."""
+
+    def setUp(self):
+        self.user = _create_user(username="secuser", email="secuser@gmail.com")
+        self.other_user = _create_user(username="victim", email="victim@gmail.com")
+        self.client.force_authenticate(user=self.user)
+
+    # ---- Cypher Injection -------------------------------------------------
+
+    @patch("graphrag.views.NLToCypher")
+    def test_cypher_injection_prevention(self, mock_svc):
+        """Cypher injection attempts are passed as strings, not executed."""
+        mock_svc.return_value.execute_nl_query.return_value = {
+            "success": True,
+            "records": [],
+        }
+        injection = (
+            "'; MATCH (n) DETACH DELETE n; //"
+        )
+        response = self.client.post(
+            reverse("query_cypher"), {"query": injection}, format="json"
+        )
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        # The service was called with the raw string — no DB damage
+        call_args = mock_svc.return_value.execute_nl_query.call_args[0][0]
+        self.assertIn("DETACH DELETE", call_args)
+
+    @patch("graphrag.views.RAGChain")
+    def test_sql_like_injection_in_query_text(self, mock_rag):
+        """SQL-injection-like strings are treated as plain text."""
+        mock_rag.return_value.generate_answer.return_value = {
+            "success": True, "answer": "Safe answer",
+        }
+        payload = "'; DROP TABLE auth_user; --"
+        response = self.client.post(
+            reverse("query"), {"query": payload}, format="json"
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        # Confirm the user table still exists
+        self.assertTrue(User.objects.filter(username="secuser").exists())
+
+    # ---- File Type Validation ---------------------------------------------
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_file_type_validation_rejects_executables(self, mock_bg):
+        """Upload rejects files with executable extensions if configured."""
+        self.client.force_authenticate(user=self.user)
+        exe_file = SimpleUploadedFile(
+            "malware.exe", b"MZ\x90\x00fake-exe", content_type="application/octet-stream"
+        )
+        response = self.client.post(
+            reverse("document_upload"), {"file": exe_file}, format="multipart"
+        )
+        # The current implementation does not enforce extension filtering,
+        # so we verify that the file IS accepted but document the expectation.
+        # If file-type filtering is added later, change this assertion to 400.
+        self.assertIn(response.status_code,
+                      [status.HTTP_202_ACCEPTED, status.HTTP_400_BAD_REQUEST])
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_file_type_validation_accepts_valid_types(self, mock_bg):
+        """Valid document types are accepted."""
+        payload = _upload_payload("data.csv", b"a,b,c\n1,2,3", "text/csv")
+        response = self.client.post(
+            reverse("document_upload"), payload, format="multipart"
+        )
+        self.assertEqual(response.status_code, status.HTTP_202_ACCEPTED)
+
+    # ---- File Size Limit --------------------------------------------------
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_file_size_limit_large_file(self, mock_bg):
+        """Very large files are handled (current impl does not enforce; test documents behavior)."""
+        # Create a 2MB file — most Django deployments have FILE_UPLOAD_MAX_MEMORY_SIZE >= 2.5MB
+        large_content = b"x" * (2 * 1024 * 1024)
+        payload = _upload_payload("large.txt", large_content, "text/plain")
+        response = self.client.post(
+            reverse("document_upload"), payload, format="multipart"
+        )
+        # Should succeed or be rejected gracefully — not crash with 500
+        self.assertIn(response.status_code,
+                      [status.HTTP_202_ACCEPTED, status.HTTP_400_BAD_REQUEST,
+                       status.HTTP_413_REQUEST_ENTITY_TOO_LARGE])
+
+    def test_empty_file_rejected(self):
+        """An empty file upload should be rejected."""
+        empty_file = SimpleUploadedFile(
+            "empty.txt", b"", content_type="text/plain"
+        )
+        response = self.client.post(
+            reverse("document_upload"), {"file": empty_file}, format="multipart"
+        )
+        # The current view may accept empty files; if file-size validation
+        # is added this should become 400. For now we verify no 500.
+        self.assertIn(response.status_code,
+                      [status.HTTP_202_ACCEPTED, status.HTTP_400_BAD_REQUEST])
+
+    # ---- IDOR Prevention --------------------------------------------------
+
+    @patch("graphrag.views.GraphBuilder")
+    def test_cannot_access_other_users_document(self, mock_builder):
+        """User A cannot retrieve User B's document by ID."""
+        doc = Document.objects.create(
+            user=self.other_user, name="secret.txt",
+            file="uploaded_documents/secret.txt",
+            status=Document.Status.COMPLETED,
+        )
+        url = reverse("document-detail", args=[doc.id])
+        response = self.client.get(url)
+        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
+
+    @patch("graphrag.views.GraphBuilder")
+    def test_cannot_delete_other_users_document(self, mock_builder):
+        """User A cannot delete User B's document."""
+        doc = Document.objects.create(
+            user=self.other_user, name="victim.txt",
+            file="uploaded_documents/victim.txt",
+            status=Document.Status.COMPLETED,
+        )
+        url = reverse("document-detail", args=[doc.id])
+        response = self.client.delete(url)
+        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
+        self.assertTrue(Document.objects.filter(id=doc.id).exists())
+
+    # ---- Token Security ---------------------------------------------------
+
+    def test_tampered_token_rejected(self):
+        """A modified JWT token is rejected."""
+        token = _generate_token(self.user)
+        tampered = token[:-5] + "XXXXX"
+        # Use a fresh client to avoid the force_authenticate from setUp
+        client = APIClient()
+        client.credentials(HTTP_AUTHORIZATION=f"Bearer {tampered}")
+        response = client.get(reverse("document-list"))
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+    def test_missing_bearer_prefix_rejected(self):
+        """Token without 'Bearer ' prefix is rejected."""
+        token = _generate_token(self.user)
+        # Use a fresh client to avoid the force_authenticate from setUp
+        client = APIClient()
+        client.credentials(HTTP_AUTHORIZATION=token)
+        response = client.get(reverse("document-list"))
+        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
+
+    # ---- Rate Limiting Awareness -----------------------------------------
+
+    def test_bulk_registration_attempt(self):
+        """Rapid-fire registrations are all validated (no bypass)."""
+        url = reverse("auth_register")
+        for i in range(5):
+            data = {
+                "username": f"bulk{i}",
+                "email": f"bulk{i}@gmail.com",
+                "password": "BulkPass1!",
+                "confirm_password": "BulkPass1!",
+            }
+            response = self.client.post(url, data, format="json")
+            self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+
+        self.assertEqual(User.objects.filter(username__startswith="bulk").count(), 5)
+
+
+# ===========================================================================
+# 7. INTEGRATION / CROSS-CUTTING TESTS
+# ===========================================================================
+
+class IntegrationTests(APITestCase):
+    """End-to-end workflows that span multiple endpoints."""
+
+    def setUp(self):
+        self.user = _create_user(username="intuser", email="intuser@gmail.com")
+        self.client.force_authenticate(user=self.user)
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_full_document_lifecycle(self, mock_bg):
+        """Upload -> List -> Retrieve -> Delete a document."""
+        # 1. Upload
+        payload = _upload_payload("lifecycle.txt", b"Lifecycle test.", "text/plain")
+        upload_resp = self.client.post(
+            reverse("document_upload"), payload, format="multipart"
+        )
+        self.assertEqual(upload_resp.status_code, status.HTTP_202_ACCEPTED)
+        doc_id = upload_resp.data["document"]["id"]
+
+        # 2. List
+        list_resp = self.client.get(reverse("document-list"))
+        self.assertEqual(list_resp.status_code, status.HTTP_200_OK)
+        results = _results(list_resp)
+        self.assertTrue(any(d["id"] == doc_id for d in results))
+
+        # 3. Retrieve
+        detail_resp = self.client.get(reverse("document-detail", args=[doc_id]))
+        self.assertEqual(detail_resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(detail_resp.data["name"], "lifecycle.txt")
+
+        # 4. Delete
+        with patch("graphrag.views.GraphBuilder") as mock_builder:
+            mock_builder.return_value.delete_document_data.return_value = None
+            del_resp = self.client.delete(reverse("document-detail", args=[doc_id]))
+            self.assertIn(del_resp.status_code,
+                          [status.HTTP_200_OK, status.HTTP_204_NO_CONTENT])
+
+        # 5. Confirm gone
+        get_resp = self.client.get(reverse("document-detail", args=[doc_id]))
+        self.assertEqual(get_resp.status_code, status.HTTP_404_NOT_FOUND)
+
+    def test_registration_login_query_flow(self):
+        """Register -> Login -> use token to query."""
+        # Register
+        reg_url = reverse("auth_register")
+        reg_data = {
+            "username": "flowuser",
+            "email": "flowuser@gmail.com",
+            "password": "FlowPass1!",
+            "confirm_password": "FlowPass1!",
+        }
+        reg_resp = self.client.post(reg_url, reg_data, format="json")
+        self.assertEqual(reg_resp.status_code, status.HTTP_201_CREATED)
+
+        # Login
+        login_url = reverse("auth_login")
+        login_data = {"username": "flowuser", "password": "FlowPass1!"}
+        login_resp = self.client.post(login_url, login_data, format="json")
+        self.assertEqual(login_resp.status_code, status.HTTP_200_OK)
+        access_token = login_resp.data["access"]
+
+        # Use token
+        self.client.credentials(HTTP_AUTHORIZATION=f"Bearer {access_token}")
+        with patch("graphrag.views.RAGChain") as mock_rag:
+            mock_rag.return_value.generate_answer.return_value = {
+                "success": True, "answer": "Flow answer",
+            }
+            query_resp = self.client.post(
+                reverse("query"), {"query": "test flow"}, format="json"
+            )
+            self.assertEqual(query_resp.status_code, status.HTTP_200_OK)
+
+    def test_user_isolation(self):
+        """User A's documents are invisible to User B."""
+        user_a = _create_user(username="isola", email="isola@gmail.com")
+        user_b = _create_user(username="isolb", email="isolb@gmail.com")
+
+        # Create a doc as user A
+        Document.objects.create(
+            user=user_a, name="a-only.txt",
+            file="uploaded_documents/a-only.txt",
+            status=Document.Status.COMPLETED,
+        )
+
+        # User B lists — should see nothing
+        self.client.force_authenticate(user=user_b)
+        resp = self.client.get(reverse("document-list"))
+        results = _results(resp)
+        self.assertEqual(len(results), 0)
+
+
+# ===========================================================================
+# 8. DOCUMENT SERIALIZER EDGE CASES
+# ===========================================================================
+
+class DocumentSerializerTests(APITestCase):
+    """Tests for DocumentSerializer edge cases."""
+
+    def setUp(self):
+        self.user = _create_user(username="seruser", email="seruser@gmail.com")
+        self.client.force_authenticate(user=self.user)
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_document_serializer_fields(self, mock_bg):
+        """Serializer returns all expected fields."""
+        payload = _upload_payload("fields.txt", b"Content.", "text/plain")
+        resp = self.client.post(reverse("document_upload"), payload, format="multipart")
+
+        doc_data = resp.data["document"]
+        expected_fields = {
+            "id", "user", "name", "file", "file_url", "status",
+            "entity_count", "relationship_count", "error_message",
+            "created_at", "updated_at",
+        }
+        self.assertTrue(expected_fields.issubset(set(doc_data.keys())))
+
+    @patch("graphrag.views.trigger_ingestion_background")
+    def test_document_status_choices(self, mock_bg):
+        """Status is one of the valid Document.Status choices."""
+        payload = _upload_payload("choices.txt", b"Content.", "text/plain")
+        resp = self.client.post(reverse("document_upload"), payload, format="multipart")
+
+        status_val = resp.data["document"]["status"]
+        valid_statuses = {c[0] for c in Document.Status.choices}
+        self.assertIn(status_val, valid_statuses)
+
+
+# ===========================================================================
+# 9. QUERY LOG MODEL TESTS
+# ===========================================================================
+
+class QueryLogModelTests(APITestCase):
+    """Tests for QueryLog model creation and serialization."""
+
+    def setUp(self):
+        self.user = _create_user(username="loguser", email="loguser@gmail.com")
+
+    def test_query_log_creation(self):
+        """QueryLog can be created and string representation is correct."""
+        log = QueryLog.objects.create(
+            user=self.user,
+            query_text="What is GraphRAG?",
+            retrieval_mode=QueryLog.RetrievalMode.HYBRID,
+            answer_text="GraphRAG is a retrieval-augmented generation system.",
+            response_time=1.23,
+        )
+        self.assertIn("What is GraphRAG?", str(log))
+        self.assertEqual(log.response_time, 1.23)
+
+    def test_query_log_default_mode(self):
+        """Default retrieval mode is HYBRID."""
+        log = QueryLog.objects.create(
+            user=self.user,
+            query_text="test",
+            answer_text="answer",
+            response_time=0.1,
+        )
+        self.assertEqual(log.retrieval_mode, QueryLog.RetrievalMode.HYBRID)

backend/graphrag/urls.py

@@ -0,0 +1,37 @@
+from django.urls import path, include
+from rest_framework.routers import DefaultRouter
+from rest_framework_simplejwt.views import TokenRefreshView
+from .views import (
+    RegisterView,
+    CustomTokenObtainPairView,
+    DocumentViewSet,
+    DocumentUploadView,
+    QueryView,
+    CypherQueryView,
+    ShortestPathView
+)
+
+router = DefaultRouter()
+router.register(r'documents', DocumentViewSet, basename='document')
+
+urlpatterns = [
+    # Authentication Endpoints
+    path('auth/register/', RegisterView.as_view(), name='auth_register'),
+    path('auth/login/', CustomTokenObtainPairView.as_view(), name='auth_login'),
+    path('auth/token/refresh/', TokenRefreshView.as_view(), name='auth_token_refresh'),
+    
+    # Document Ingestion Endpoint (POST /api/documents/upload/)
+    path('documents/upload/', DocumentUploadView.as_view(), name='document_upload'),
+    
+    # Retrieval Endpoints
+    path('query/', QueryView.as_view(), name='query'),
+    path('query/cypher/', CypherQueryView.as_view(), name='query_cypher'),
+    path('query/shortest-path/', ShortestPathView.as_view(), name='query_shortest_path'),
+    
+    # Document management routes:
+    # GET /api/documents/ -> lists all user documents
+    # GET /api/documents/{id}/ -> gets processing status details
+    # DELETE /api/documents/{id}/ -> deletes database metadata, Neo4j graph nodes, and Chroma vectors
+    path('', include(router.urls)),
+]
+

backend/graphrag/views.py

@@ -0,0 +1,270 @@
+import logging
+import threading
+
+from rest_framework import status, viewsets
+from rest_framework.views import APIView
+from rest_framework.response import Response
+from rest_framework.permissions import AllowAny, IsAuthenticated
+from rest_framework_simplejwt.views import TokenObtainPairView
+from django.contrib.auth import get_user_model
+from .models import Document
+from .serializers import (
+    RegisterSerializer, 
+    UserSerializer, 
+    DocumentSerializer
+)
+
+from .services.rag_chain import RAGChain
+from .services.nl_to_cypher import NLToCypher
+from .services.multihop_reasoner import MultiHopReasoner
+
+
+# Note: We will implement the background logic inside the existing GraphBuilder service
+from .services.graph_builder import GraphBuilder
+
+logger = logging.getLogger(__name__)
+
+User = get_user_model()
+
+class RegisterView(APIView):
+    """
+    Endpoint for new user registration.
+    """
+    permission_classes = [AllowAny]
+
+    def post(self, request):
+        logger.info("Received account registration request.")
+        serializer = RegisterSerializer(data=request.data)
+        if serializer.is_valid():
+            user = serializer.save()
+            logger.info("Successfully registered user account: %s", user.username)
+            return Response(
+                {
+                    "message": "User registered successfully.",
+                    "user": UserSerializer(user).data
+                },
+                status=status.HTTP_201_CREATED
+            )
+        logger.warning("Registration request failed validation check: %s", serializer.errors)
+        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
+
+
+class CustomTokenObtainPairView(TokenObtainPairView):
+    """
+    Custom JWT Token Obtain View to add custom execution logs.
+    """
+    permission_classes = [AllowAny]
+
+    def post(self, request, *args, **kwargs):
+        username = request.data.get('username')
+        logger.info("Authentication attempt received for user: %s", username)
+        try:
+            response = super().post(request, *args, **kwargs)
+            logger.info("Authentication successful for user: %s", username)
+            return response
+        except Exception as e:
+            logger.warning("Authentication failed for user: %s. Error: %s", username, str(e))
+            raise e
+
+
+def trigger_ingestion_background(document_id, user_id):
+    """
+    Isolated target runner to execute ingestion processing inside a background thread.
+    """
+    logger.info("Background thread spawned for ingestion of document ID: %s", document_id)
+    try:
+        builder = GraphBuilder()
+        builder.process_document(document_id, user_id)
+        logger.info("Background ingestion completed successfully for document ID: %s", document_id)
+    except Exception as e:
+        logger.error("Critical error in background ingestion thread for document ID: %s. Error: %s", 
+                     document_id, str(e), exc_info=True)
+
+
+class DocumentUploadView(APIView):
+    """
+    Endpoint for uploading documents. Runs the parsing and extraction pipeline 
+    in a non-blocking background thread.
+    """
+    permission_classes = [IsAuthenticated]
+
+    def post(self, request):
+        logger.info("Received document upload request from user: %s", request.user.username)
+        
+        if 'file' not in request.FILES:
+            logger.warning("Document upload request rejected: No file attachment found.")
+            return Response(
+                {"error": "No file was uploaded."}, 
+                status=status.HTTP_400_BAD_REQUEST
+            )
+            
+        file_obj = request.FILES['file']
+        
+        # Save document record with initial PENDING status
+        doc = Document.objects.create(
+            user=request.user,
+            name=file_obj.name,
+            file=file_obj,
+            status=Document.Status.PENDING
+        )
+        logger.info("Saved initial document metadata row. ID: %s | Name: %s", doc.id, doc.name)
+        
+        # Launch background pipeline thread
+        thread = threading.Thread(
+            target=trigger_ingestion_background,
+            args=(doc.id, request.user.id)
+        )
+        thread.daemon = True
+        thread.start()
+        
+        # Return 202 Accepted immediately so client is non-blocking
+        return Response(
+            {
+                "message": "File upload accepted. Ingestion running in background.",
+                "document": DocumentSerializer(doc, context={'request': request}).data
+            },
+            status=status.HTTP_202_ACCEPTED
+        )
+
+
+class DocumentViewSet(viewsets.ModelViewSet):
+    """
+    ViewSet for listing, retrieving details, and deleting user documents.
+    """
+    permission_classes = [IsAuthenticated]
+    serializer_class = DocumentSerializer
+    # Viewset operations are automatically mapped to list, retrieve, destroy URLs by the router
+    http_method_names = ['get', 'delete']
+
+    def get_queryset(self):
+        # Enforce multi-tenancy: users can only see their own documents
+        return Document.objects.filter(user=self.request.user)
+
+    def destroy(self, request, *args, **kwargs):
+        doc = self.get_object()
+        logger.info("Received request to delete document: %s (ID: %s) for user: %s", 
+                    doc.name, doc.id, request.user.username)
+        
+        try:
+            # Trigger custom graph/vector cleanup using GraphBuilder
+            builder = GraphBuilder()
+            builder.delete_document_data(doc.id, request.user.id)
+            
+            # Delete physical file and SQL DB record
+            doc.file.delete(save=False)
+            doc.delete()
+            
+            logger.info("Successfully deleted document %s and cleaned associated graph/vector database records.", doc.name)
+            return Response(
+                {"message": "Document and all extracted nodes/vectors deleted successfully."},
+                status=status.HTTP_200_OK
+            )
+        except Exception as e:
+            logger.error("Failed to cleanly delete document ID: %s. Error: %s", doc.id, str(e), exc_info=True)
+            return Response(
+                {"error": f"Failed to delete document: {str(e)}"},
+                status=status.HTTP_500_INTERNAL_SERVER_ERROR
+            )
+
+
+class QueryView(APIView):
+    """
+    Endpoint for executing GraphRAG queries.
+    Supports 'hybrid', 'vector', and 'graph' retrieval modes.
+    """
+    permission_classes = [IsAuthenticated]
+
+    def post(self, request):
+        query = request.data.get("query")
+        mode = request.data.get("mode", "hybrid")
+
+        if not query or not query.strip():
+            return Response(
+                {"error": "The 'query' field is required and cannot be empty."},
+                status=status.HTTP_400_BAD_REQUEST
+            )
+
+        logger.info("Executing RAG Query for user: %s | Mode: %s", request.user.username, mode)
+        try:
+            rag_chain = RAGChain()
+            result = rag_chain.generate_answer(query, request.user.id, mode)
+            
+            if result.get("success", False):
+                return Response(result, status=status.HTTP_200_OK)
+            else:
+                return Response(
+                    {"error": result.get("answer", "Failed to generate RAG response.")},
+                    status=status.HTTP_500_INTERNAL_SERVER_ERROR
+                )
+        except Exception as e:
+            logger.error("Error in QueryView: %s", str(e), exc_info=True)
+            return Response(
+                {"error": f"Internal Server Error: {str(e)}"},
+                status=status.HTTP_500_INTERNAL_SERVER_ERROR
+            )
+
+
+class CypherQueryView(APIView):
+    """
+    Endpoint for converting natural language queries directly into Cypher,
+    executing them, and returning the raw records.
+    """
+    permission_classes = [IsAuthenticated]
+
+    def post(self, request):
+        query = request.data.get("query")
+
+        if not query or not query.strip():
+            return Response(
+                {"error": "The 'query' field is required and cannot be empty."},
+                status=status.HTTP_400_BAD_REQUEST
+            )
+
+        logger.info("Translating NL Query to Cypher for user: %s", request.user.username)
+        try:
+            nl_to_cypher = NLToCypher()
+            result = nl_to_cypher.execute_nl_query(query, request.user.id)
+            
+            if result.get("success", False):
+                return Response(result, status=status.HTTP_200_OK)
+            else:
+                return Response(
+                    {"error": result.get("error", "Failed to translate and execute Cypher query.")},
+                    status=status.HTTP_500_INTERNAL_SERVER_ERROR
+                )
+        except Exception as e:
+            logger.error("Error in CypherQueryView: %s", str(e), exc_info=True)
+            return Response(
+                {"error": f"Internal Server Error: {str(e)}"},
+                status=status.HTTP_500_INTERNAL_SERVER_ERROR
+            )
+
+
+class ShortestPathView(APIView):
+    """
+    Endpoint for finding and explaining the connection path between two entities.
+    """
+    permission_classes = [IsAuthenticated]
+
+    def post(self, request):
+        entity_a = request.data.get("entity_a")
+        entity_b = request.data.get("entity_b")
+
+        if not entity_a or not entity_b:
+            return Response(
+                {"error": "Both 'entity_a' and 'entity_b' fields are required."},
+                status=status.HTTP_400_BAD_REQUEST
+            )
+
+        logger.info("Executing Shortest Path reasoning: '%s' to '%s' for user: %s",
+                    entity_a, entity_b, request.user.username)
+        try:
+            reasoner = MultiHopReasoner()
+            result = reasoner.explain_connection(entity_a, entity_b, request.user.id)
+            return Response(result, status=status.HTTP_200_OK)
+        except Exception as e:
+            logger.error("Error in ShortestPathView: %s", str(e), exc_info=True)
+            return Response(
+                {"error": f"Internal Server Error: {str(e)}"},
+                status=status.HTTP_500_INTERNAL_SERVER_ERROR
+            )

backend/manage.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+import os
+import sys
+
+def main():
+    """Run administrative tasks."""
+    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Are you sure it's installed and "
+            "available on your PYTHONPATH environment variable? Did you "
+            "forget to activate a virtual environment?"
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+if __name__ == '__main__':
+    main()

backend/requirements.txt

@@ -0,0 +1,17 @@
+django>=4.2,<5.0
+djangorestframework>=3.14.0
+django-cors-headers>=4.0.0
+djangorestframework-simplejwt>=5.3.0
+neo4j>=5.14.0
+langchain>=0.1.0
+langchain-community>=0.0.10
+langchain-google-genai>=1.0.0
+langchain-groq>=0.1.0
+chromadb>=0.4.15
+sentence-transformers>=2.2.2
+rapidfuzz>=3.5.2
+tenacity>=8.2.3
+pypdf>=3.17.0
+python-docx>=0.8.11
+pydantic>=2.5.0
+python-dotenv>=1.0.0

docker-compose.yml

@@ -0,0 +1,33 @@
+version: '3.8'
+
+services:
+  neo4j:
+    image: neo4j:5.12.0
+    container_name: graphrag_neo4j
+    ports:
+      - "7474:7474" # Neo4j Browser Console (HTTP)
+      - "7687:7687" # Bolt protocol port (used by Django python driver)
+    environment:
+      - NEO4J_AUTH=neo4j/password
+      # Allow APOC and GDS (Graph Data Science) plugins
+      - NEO4J_PLUGINS=["apoc", "graph-data-science"]
+      # Grant full permissions to GDS and APOC procedures
+      - NEO4J_dbms_security_procedures_unrestricted=apoc.*,gds.*
+      - NEO4J_dbms_security_procedures_allowlist=apoc.*,gds.*
+    volumes:
+      - neo4j_data:/data
+      - neo4j_logs:/logs
+      - neo4j_import:/import
+      - neo4j_plugins:/plugins
+    healthcheck:
+      test: ["CMD-SHELL", "cypher-shell -u neo4j -p password 'RETURN 1' || exit 1"]
+      interval: 10s
+      timeout: 10s
+      retries: 5
+      start_period: 20s
+
+volumes:
+  neo4j_data:
+  neo4j_logs:
+  neo4j_import:
+  neo4j_plugins: