Fix: Resolve 0-entity extraction error by adding NVIDIA LLM integration and robust error handling

.env.example

@@ -47,6 +47,9 @@ GROQ_MODEL=llama-3.3-70b-versatile
 GOOGLE_API_KEY=your_gemini_api_key_here
 GOOGLE_MODEL=gemini-2.0-flash
 
+OPENAI_API_KEY=your_openai_api_key_here
+OPENAI_MODEL=gpt-4o-mini
+
 # ============================================================
 # LangSmith Observability & Tracing (Optional)
 # ============================================================

backend/Dockerfile

@@ -21,6 +21,9 @@ RUN pip install --no-cache-dir --upgrade pip && \
 # Copy backend codebase
 COPY . /app/
 
+# Create volume directories so they exist with the correct permissions in the image
+RUN mkdir -p /app/chroma_db /app/uploaded_documents /app/logs /app/db
+
 # Collect static files (no-op if no static files, but ready for future)
 RUN python manage.py collectstatic --noinput 2>/dev/null || true
 

backend/clear_all_data.py

@@ -0,0 +1,68 @@
+import os
+import shutil
+import django
+
+# Set up Django settings context
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
+django.setup()
+
+from django.conf import settings
+from graphrag.services.neo4j_client import Neo4jClient
+
+def wipe_all_data():
+    print("=== STARTING FULL CLEANUP ===")
+
+    # 1. Wipe Neo4j Database
+    try:
+        print("Connecting to Neo4j...")
+        neo4j_client = Neo4jClient()
+        print("Wiping all nodes and relationships in Neo4j...")
+        neo4j_client.execute_query("MATCH (n) DETACH DELETE n")
+        print("✓ Neo4j database successfully wiped.")
+    except Exception as e:
+        print(f"✗ Failed to wipe Neo4j: {e}")
+
+    # 2. Delete ChromaDB folder
+    chroma_dir = settings.CHROMADB_DIR
+    if os.path.exists(chroma_dir):
+        try:
+            print(f"Removing ChromaDB directory: {chroma_dir}...")
+            shutil.rmtree(chroma_dir)
+            print("✓ ChromaDB vectors successfully wiped.")
+        except Exception as e:
+            print(f"✗ Failed to delete ChromaDB folder: {e}")
+    else:
+        print("ChromaDB directory does not exist, skipping.")
+
+    # 3. Delete Uploaded Documents
+    media_root = settings.MEDIA_ROOT
+    if os.path.exists(media_root):
+        try:
+            print(f"Emptying media root directory: {media_root}...")
+            shutil.rmtree(media_root)
+            os.makedirs(media_root, exist_ok=True)
+            print("✓ Uploaded documents successfully wiped.")
+        except Exception as e:
+            print(f"✗ Failed to empty media root: {e}")
+    else:
+        print("Media root directory does not exist, skipping.")
+
+    # 4. Delete SQLite Database file
+    sqlite_db = settings.DATABASES['default'].get('NAME')
+    if sqlite_db and os.path.exists(sqlite_db):
+        try:
+            print(f"Removing SQLite database: {sqlite_db}...")
+            os.remove(sqlite_db)
+            print("✓ Django SQLite database successfully wiped.")
+        except Exception as e:
+            print(f"✗ Failed to delete SQLite file: {e}")
+    else:
+        print("SQLite database file not found, skipping.")
+
+    print("\n=== CLEANUP COMPLETE ===")
+    print("To finalize the fresh start, run the migrations to rebuild your database tables:")
+    print("  python manage.py migrate")
+    print("=========================")
+
+if __name__ == "__main__":
+    wipe_all_data()

backend/config/settings.py

@@ -101,13 +101,18 @@ else:
     DATABASES = {
         'default': {
             'ENGINE': 'django.db.backends.sqlite3',
-            'NAME': BASE_DIR / 'db.sqlite3',
+            'NAME': BASE_DIR / 'db' / 'db.sqlite3',
         }
     }
 
 # Custom User Model
 AUTH_USER_MODEL = 'graphrag.User'
 
+AUTHENTICATION_BACKENDS = [
+    'graphrag.views.EmailOrUsernameModelBackend',
+    'django.contrib.auth.backends.ModelBackend',
+]
+
 # Password validation
 AUTH_PASSWORD_VALIDATORS = [
     {

backend/graphrag/services/graph_builder.py

@@ -27,9 +27,9 @@ class GraphBuilder:
         """Update document processing progress for frontend polling."""
         doc.processing_step = step
         doc.processing_progress = progress
-        doc.save(update_fields=['processing_step', 'processing_progress', 'updated_at'])
+        doc.save(update_fields=['processing_step', 'processing_progress'])
 
-    def _batch_create_entities(self, entities: List[dict], user_id: str):
+    def _batch_create_entities(self, entities: List[dict], user_id: str, document_id: str):
         """Batch create entities using UNWIND to reduce N+1 queries."""
         if not entities:
             return
@@ -40,8 +40,8 @@ class GraphBuilder:
                 "UNWIND $entities AS ent "
                 "MERGE (e:Entity {name: ent.name, user_id: $user_id}) "
                 "ON CREATE SET e.type = ent.type, e.description = ent.description, "
-                "              e.source_doc = ent.source_doc, e.page = ent.page, e.created_at = timestamp() "
-                "ON MATCH SET e.description = coalesce(e.description, ent.description)"
+                "              e.source_doc = ent.source_doc, e.source_doc_id = $document_id, e.page = ent.page, e.created_at = timestamp() "
+                "ON MATCH SET e.description = coalesce(e.description, ent.description), e.source_doc_id = $document_id, e.source_doc = ent.source_doc"
             )
             params = {
                 "entities": [
@@ -54,11 +54,12 @@ class GraphBuilder:
                     }
                     for e in batch
                 ],
-                "user_id": str(user_id)
+                "user_id": str(user_id),
+                "document_id": str(document_id)
             }
             self.neo4j_client.execute_query(query, params)
 
-    def _batch_create_relationships(self, relationships: List[dict], user_id: str):
+    def _batch_create_relationships(self, relationships: List[dict], user_id: str, document_id: str):
         """Batch create relationships grouped by type using UNWIND."""
         if not relationships:
             return
@@ -82,7 +83,8 @@ class GraphBuilder:
                     "MATCH (target:Entity {name: rel.target, user_id: $user_id}) "
                     f"MERGE (source)-[r:{rel_type}]->(target) "
                     "ON CREATE SET r.description = rel.description, r.confidence = rel.confidence, "
-                    "              r.source_doc = rel.source_doc, r.page = rel.page, r.created_at = timestamp() "
+                    "              r.source_doc = rel.source_doc, r.source_doc_id = $document_id, r.page = rel.page, r.created_at = timestamp() "
+                    "ON MATCH SET r.source_doc_id = $document_id, r.source_doc = rel.source_doc "
                     "RETURN r LIMIT 1"
                 )
                 params = {
@@ -97,7 +99,8 @@ class GraphBuilder:
                         }
                         for rel in batch
                     ],
-                    "user_id": str(user_id)
+                    "user_id": str(user_id),
+                    "document_id": str(document_id)
                 }
                 self.neo4j_client.execute_query(query, params)
 
@@ -161,6 +164,8 @@ class GraphBuilder:
 
             # 3. Perform Entity and Relationship Extraction per section (parallel)
             completed = 0
+            failed_count = 0
+            last_error = None
             with ThreadPoolExecutor(max_workers=5) as executor:
                 futures = {executor.submit(process_section, sec): sec for sec in sections}
                 for future in as_completed(futures):
@@ -172,10 +177,15 @@ class GraphBuilder:
                             all_relationships.extend(rels)
                     except Exception as e:
                         logger.error("Section processing failed: %s", str(e))
+                        failed_count += 1
+                        last_error = e
                     completed += 1
                     extraction_progress = 20 + int(55 * (completed / total_sections)) if total_sections > 0 else 20
                     self._update_progress(doc, f"Extracting entities... ({completed}/{total_sections})", extraction_progress)
 
+            if failed_count == total_sections and total_sections > 0:
+                raise RuntimeError(f"All sections failed to process. Last error: {last_error}")
+
             # 4. Run entity resolution (deduplicate entities and rewrite relationships)
             self._update_progress(doc, "Resolving duplicates...", 80)
             resolved_ents, rewritten_rels = self.entity_resolver.resolve_entities(
@@ -185,12 +195,12 @@ class GraphBuilder:
             # 5. Batch store resolved nodes inside Neo4j
             self._update_progress(doc, "Building knowledge graph...", 85)
             logger.info("Writing %d resolved entities to Neo4j...", len(resolved_ents))
-            self._batch_create_entities(resolved_ents, user_id)
+            self._batch_create_entities(resolved_ents, user_id, document_id)
 
             # 6. Batch store rewritten edges inside Neo4j
             self._update_progress(doc, "Writing relationships...", 92)
             logger.info("Writing %d rewritten relationships to Neo4j...", len(rewritten_rels))
-            self._batch_create_relationships(rewritten_rels, user_id)
+            self._batch_create_relationships(rewritten_rels, user_id, document_id)
 
             # 7. Update status to COMPLETED and record counts
             doc.entity_count = len(resolved_ents)
@@ -223,7 +233,7 @@ class GraphBuilder:
             vector_ok = True
 
             try:
-                self.neo4j_client.delete_document_nodes(doc.name, user_id)
+                self.neo4j_client.delete_document_nodes(doc.id, user_id)
             except Exception as e:
                 logger.error("Neo4j cleanup failed for Document: %s. Error: %s", doc.name, str(e))
                 neo4j_ok = False

backend/graphrag/services/graph_retriever.py

@@ -35,12 +35,12 @@ class GraphRetriever:
 
         self.chain = self.prompt | self.structured_llm
 
-    def retrieve_graph_context(self, query: str, user_id: str, hops: int = 2) -> str:
+    def retrieve_graph_context(self, query: str, user_id: str, hops: int = 2, doc_names: List[str] = None) -> 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)
+        logger.info("Retrieving graph context for query: '%s' (User: %s, Docs: %s)", query, user_id, doc_names)
         
         # 1. Extract entities from query using LLM
         query_entities = self._extract_entities_from_query(query)
@@ -56,7 +56,7 @@ class GraphRetriever:
         # 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)
+                paths = self.neo4j_client.get_entity_subgraph(entity_name, user_id, hops=hops, doc_names=doc_names)
                 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))
@@ -81,12 +81,12 @@ class GraphRetriever:
         logger.info("Generated graph context (%d characters).", len(serialized_context))
         return serialized_context
 
-    def get_graph_as_json(self, user_id: str) -> Dict[str, Any]:
+    def get_graph_as_json(self, user_id: str, doc_ids: List[str] = None) -> Dict[str, Any]:
         """
         Serializes the full graph as JSON for frontend visualization.
         Endpoint: GET /api/graph/
         """
-        raw_data = self.neo4j_client.get_all_graph_data(user_id)
+        raw_data = self.neo4j_client.get_all_graph_data(user_id, doc_ids=doc_ids)
 
         # Assign numeric IDs for vis.js / react-force-graph
         node_id_map = {}

backend/graphrag/services/hybrid_retriever.py

@@ -11,24 +11,24 @@ class HybridRetriever:
         self.graph_retriever = GraphRetriever()
         self.vector_retriever = VectorRetriever()
 
-    def retrieve_combined_context(self, query: str, user_id: str) -> Dict[str, Any]:
+    def retrieve_combined_context(self, query: str, user_id: str, doc_names: List[str] = None) -> 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)
+        logger.info("Running hybrid retrieval for query: '%s' (User: %s, Docs: %s)", query, user_id, doc_names)
 
         # 1. Execute Graph Retrieval
         graph_context = ""
         try:
-            graph_context = self.graph_retriever.retrieve_graph_context(query, user_id, hops=2)
+            graph_context = self.graph_retriever.retrieve_graph_context(query, user_id, hops=2, doc_names=doc_names)
         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)
+            vector_chunks = self.vector_retriever.retrieve_relevant_chunks(query, user_id, limit=4, doc_names=doc_names)
         except Exception as e:
             logger.error("Vector retrieval failed during hybrid step. Error: %s", str(e))
 

backend/graphrag/services/llm_client.py

@@ -1,8 +1,9 @@
 import os
 import logging
+from langchain_openai import ChatOpenAI
 from langchain_groq import ChatGroq
 from langchain_google_genai import ChatGoogleGenerativeAI
-from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+from langchain_core.runnables import Runnable
 
 logger = logging.getLogger(__name__)
 
@@ -10,39 +11,134 @@ logger = logging.getLogger(__name__)
 _llm_cache = {}
 
 
+
+class FallbackLLMWrapper(Runnable):
+    """
+    A wrapper around multiple LangChain ChatModels to provide dynamic
+    fallback when invoking models. Particularly useful for handling
+    API rate limits (e.g., HTTP 429) and transient errors.
+    """
+    def __init__(self, primary: Runnable, fallbacks: list):
+        self.primary = primary
+        self.fallbacks = fallbacks
+
+    def invoke(self, input, config=None, **kwargs):
+        last_exception = None
+        
+        # Try primary model
+        try:
+            primary_name = getattr(self.primary, "model", getattr(self.primary, "model_name", "Unknown"))
+            logger.info("Attempting primary LLM invocation (%s)...", primary_name)
+            return self.primary.invoke(input, config, **kwargs)
+        except Exception as e:
+            logger.error("Primary LLM invocation failed: %s. Trying fallbacks...", str(e))
+            last_exception = e
+
+        # Try fallback models in order
+        for i, fallback_llm in enumerate(self.fallbacks, 1):
+            try:
+                fb_name = getattr(fallback_llm, "model", getattr(fallback_llm, "model_name", "Unknown"))
+                logger.info("Attempting fallback LLM invocation #%d (%s)...", i, fb_name)
+                return fallback_llm.invoke(input, config, **kwargs)
+            except Exception as e:
+                logger.error("Fallback LLM invocation #%d failed: %s", i, str(e))
+                last_exception = e
+
+        raise last_exception
+
+    def with_structured_output(self, schema, **kwargs):
+        """
+        Applies structure requirements to both primary and fallback models.
+        """
+        structured_primary = self.primary.with_structured_output(schema, **kwargs)
+        structured_fallbacks = [
+            fb.with_structured_output(schema, **kwargs) for fb in self.fallbacks
+        ]
+        return FallbackLLMWrapper(structured_primary, structured_fallbacks)
+
+
 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.
+    Returns a configured LangChain LLM instance (wrapped in FallbackLLMWrapper if multiple providers are configured).
+    Prioritizes OpenAI, falling back to Groq, then Gemini if errors occur or keys are missing.
     Caches instances to avoid reloading models repeatedly.
     """
     cache_key = f"{temperature}"
     if cache_key in _llm_cache:
         return _llm_cache[cache_key]
 
+    openai_api_key = os.getenv("OPENAI_API_KEY", "")
     groq_api_key = os.getenv("GROQ_API_KEY", "")
     google_api_key = os.getenv("GOOGLE_API_KEY", "")
+    nvidia_api_key = os.getenv("NVIDIA_API_KEY", "")
 
-    llm = None
+    available_models = []
+
+    # 1. OpenAI (Primary option)
+    if openai_api_key:
+        try:
+            model_name = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+            logger.info("Initializing OpenAI Chat Model (%s) for fallback list", model_name)
+            available_models.append(ChatOpenAI(
+                model=model_name,
+                api_key=openai_api_key,
+                temperature=temperature
+            ))
+        except Exception as e:
+            logger.error("Failed to initialize OpenAI client: %s", str(e))
+
+    # 2. Groq (Secondary option)
     if groq_api_key:
-        model_name = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
-        logger.info("Initializing Groq Chat Model (%s)", model_name)
-        llm = 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)
-        llm = ChatGoogleGenerativeAI(
-            model=model_name,
-            api_key=google_api_key,
-            temperature=temperature
+        try:
+            model_name = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+            logger.info("Initializing Groq Chat Model (%s) for fallback list", model_name)
+            available_models.append(ChatGroq(
+                model=model_name,
+                api_key=groq_api_key,
+                temperature=temperature
+            ))
+        except Exception as e:
+            logger.error("Failed to initialize Groq client: %s", str(e))
+
+    # 3. Google Gemini (Tertiary option)
+    if google_api_key:
+        try:
+            model_name = os.getenv("GOOGLE_MODEL", "gemini-1.5-flash")
+            logger.info("Initializing Google Gemini Chat Model (%s) for fallback list", model_name)
+            available_models.append(ChatGoogleGenerativeAI(
+                model=model_name,
+                api_key=google_api_key,
+                temperature=temperature
+            ))
+        except Exception as e:
+            logger.error("Failed to initialize Google Gemini client: %s", str(e))
+
+    # 4. NVIDIA (OpenAI-compatible option)
+    if nvidia_api_key:
+        try:
+            model_name = os.getenv("NVIDIA_MODEL", "meta/llama-3.1-70b-instruct")
+            logger.info("Initializing NVIDIA Chat Model (%s) for fallback list", model_name)
+            available_models.append(ChatOpenAI(
+                model=model_name,
+                api_key=nvidia_api_key,
+                base_url="https://integrate.api.nvidia.com/v1",
+                temperature=temperature
+            ))
+        except Exception as e:
+            logger.error("Failed to initialize NVIDIA client: %s", str(e))
+
+    if not available_models:
+        logger.error("No API keys found or all LLM provider initializations failed.")
+        raise ValueError(
+            "Missing or invalid LLM API keys. Please configure OPENAI_API_KEY, GROQ_API_KEY, GOOGLE_API_KEY, or NVIDIA_API_KEY in your .env file."
         )
+
+    # Wrap in FallbackLLMWrapper if more than one model is available
+    if len(available_models) == 1:
+        llm = available_models[0]
     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.")
+        llm = FallbackLLMWrapper(available_models[0], available_models[1:])
 
     _llm_cache[cache_key] = llm
     return llm
+

backend/graphrag/services/neo4j_client.py

@@ -119,14 +119,14 @@ class Neo4jClient:
             result = session.run(query, parameters)
             return [record.data() for record in result]
 
-    def create_entity_node(self, name, entity_type, description, user_id, source_doc=None, page=None):
+    def create_entity_node(self, name, entity_type, description, user_id, source_doc=None, source_doc_id=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() "
+            "              e.source_doc = $source_doc, e.source_doc_id = $source_doc_id, e.page = $page, e.created_at = timestamp() "
             "ON MATCH SET e.description = coalesce(e.description, $description) "
             "RETURN e"
         )
@@ -136,11 +136,12 @@ class Neo4jClient:
             "description": description.strip(),
             "user_id": str(user_id),
             "source_doc": source_doc,
+            "source_doc_id": str(source_doc_id) if source_doc_id else None,
             "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):
+    def create_relationship_edge(self, source_name, target_name, rel_type, description, confidence, user_id, source_doc=None, source_doc_id=None, page=None):
         """
         Create a directed relationship edge between two existing Entity nodes.
         Uses strict allowlist to prevent Cypher injection.
@@ -155,7 +156,7 @@ class Neo4jClient:
             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"              r.source_doc = $source_doc, r.source_doc_id = $source_doc_id, r.page = $page, r.created_at = timestamp() "
             f"RETURN r"
         )
         params = {
@@ -165,20 +166,29 @@ class Neo4jClient:
             "confidence": float(confidence),
             "user_id": str(user_id),
             "source_doc": source_doc,
+            "source_doc_id": str(source_doc_id) if source_doc_id else None,
             "page": page
         }
         self.execute_query(query, params)
 
-    def get_entity_subgraph(self, name, user_id, hops=2):
+    def get_entity_subgraph(self, name, user_id, hops=2, doc_names=None):
         """
         Retrieve all connected entities and relationships up to N hops.
         """
         hops = max(1, min(int(hops), 10))
-        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)}
+        if doc_names:
+            query = (
+                f"MATCH path = (e:Entity {{name: $name, user_id: $user_id}})-[*1..{hops}]-(neighbor:Entity {{user_id: $user_id}}) "
+                f"WHERE all(r in relationships(path) WHERE r.source_doc IN $doc_names) "
+                f"RETURN path LIMIT 50"
+            )
+            params = {"name": name, "user_id": str(user_id), "doc_names": [str(d) for d in doc_names]}
+        else:
+            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):
@@ -247,27 +257,47 @@ class Neo4jClient:
     # Additional Methods — used by new endpoints (graph, search, etc.)
     # ----------------------------------------------------------------
 
-    def get_all_graph_data(self, user_id):
+    def get_all_graph_data(self, user_id, doc_ids=None):
         """
         Returns all nodes and relationships for frontend visualization.
-        Endpoint: GET /api/graph/
+        Allows filtering by a list of document IDs (doc_ids).
         """
-        nodes_query = (
-            "MATCH (e:Entity {user_id: $user_id}) "
-            "RETURN e.name AS name, e.type AS type, e.description AS description, "
-            "       e.source_doc AS source_doc, e.page AS page "
-            "LIMIT 500"
-        )
-        edges_query = (
-            "MATCH (s:Entity {user_id: $user_id})-[r]->(t:Entity {user_id: $user_id}) "
-            "RETURN s.name AS source, t.name AS target, "
-            "       type(r) AS relationship_type, r.description AS description, "
-            "       r.confidence AS confidence, r.source_doc AS source_doc "
-            "LIMIT 1000"
-        )
+        if doc_ids:
+            nodes_query = (
+                "MATCH (e:Entity {user_id: $user_id}) "
+                "WHERE e.source_doc_id IN $doc_ids "
+                "RETURN e.name AS name, e.type AS type, e.description AS description, "
+                "       e.source_doc AS source_doc, e.source_doc_id AS source_doc_id, e.page AS page "
+                "LIMIT 500"
+            )
+            edges_query = (
+                "MATCH (s:Entity {user_id: $user_id})-[r]->(t:Entity {user_id: $user_id}) "
+                "WHERE r.source_doc_id IN $doc_ids "
+                "RETURN s.name AS source, t.name AS target, "
+                "       type(r) AS relationship_type, r.description AS description, "
+                "       r.confidence AS confidence, r.source_doc AS source_doc, r.source_doc_id AS source_doc_id "
+                "LIMIT 1000"
+            )
+            params = {"user_id": str(user_id), "doc_ids": [str(d) for d in doc_ids]}
+        else:
+            nodes_query = (
+                "MATCH (e:Entity {user_id: $user_id}) "
+                "RETURN e.name AS name, e.type AS type, e.description AS description, "
+                "       e.source_doc AS source_doc, e.source_doc_id AS source_doc_id, e.page AS page "
+                "LIMIT 500"
+            )
+            edges_query = (
+                "MATCH (s:Entity {user_id: $user_id})-[r]->(t:Entity {user_id: $user_id}) "
+                "RETURN s.name AS source, t.name AS target, "
+                "       type(r) AS relationship_type, r.description AS description, "
+                "       r.confidence AS confidence, r.source_doc AS source_doc, r.source_doc_id AS source_doc_id "
+                "LIMIT 1000"
+            )
+            params = {"user_id": str(user_id)}
+
         try:
-            nodes = self.execute_query(nodes_query, {"user_id": str(user_id)})
-            edges = self.execute_query(edges_query, {"user_id": str(user_id)})
+            nodes = self.execute_query(nodes_query, params)
+            edges = self.execute_query(edges_query, params)
             return {"nodes": nodes, "edges": edges}
         except Exception as e:
             logger.error("Failed to get all graph data: %s", str(e))
@@ -384,26 +414,25 @@ class Neo4jClient:
 
         return ft_results[:limit]
 
-    def delete_document_nodes(self, document_name, user_id):
+    def delete_document_nodes(self, document_id, user_id):
         """
-        Wipe all nodes and relationships associated with a deleted document.
-        Removes orphan nodes that have no other remaining connections.
+        Wipe all nodes and relationships associated with a deleted document ID.
         """
-        logger.info("Executing Cypher delete query for document: %s, User: %s", document_name, user_id)
+        logger.info("Executing Cypher delete query for document ID: %s, User: %s", document_id, user_id)
         
-        # 1. Delete relationships pointing from or to nodes created by this document
+        # 1. Delete relationships pointing from or to nodes created by this document ID
         delete_rels_query = (
             "MATCH (a:Entity {user_id: $user_id})-[r]->(b:Entity {user_id: $user_id}) "
-            "WHERE r.source_doc = $document_name "
+            "WHERE r.source_doc_id = $document_id "
             "DELETE r"
         )
-        # 2. Delete nodes created solely by this document
+        # 2. Delete nodes created by this document ID that are now orphans
         delete_nodes_query = (
             "MATCH (e:Entity {user_id: $user_id}) "
-            "WHERE e.source_doc = $document_name "
-            "DETACH DELETE e"
+            "WHERE e.source_doc_id = $document_id AND NOT (e)-[]-() "
+            "DELETE e"
         )
         
-        params = {"document_name": document_name, "user_id": str(user_id)}
+        params = {"document_id": str(document_id), "user_id": str(user_id)}
         self.execute_query(delete_rels_query, params)
         self.execute_query(delete_nodes_query, params)

backend/graphrag/services/rag_chain.py

@@ -57,7 +57,7 @@ class RAGChain:
             )
         }
 
-    def generate_answer(self, query: str, user_id: str, mode: str = "hybrid") -> Dict[str, Any]:
+    def generate_answer(self, query: str, user_id: str, mode: str = "hybrid", doc_ids: List[str] = None) -> Dict[str, Any]:
         """
         Retrieves context according to the selected mode, invokes the LLM, and returns the response.
         """
@@ -66,7 +66,17 @@ class RAGChain:
             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)
+        logger.info("Generating RAG answer in '%s' mode for query: '%s' (User: %s, Doc IDs: %s)", mode, query, user_id, doc_ids)
+
+        # Resolve doc_ids to names
+        doc_names = None
+        if doc_ids:
+            try:
+                from graphrag.models import Document
+                doc_names = list(Document.objects.filter(id__in=doc_ids).values_list('name', flat=True))
+                logger.info("Resolved filter doc IDs to names: %s", doc_names)
+            except Exception as e:
+                logger.error("Failed to resolve doc_ids to names: %s", str(e))
 
         context = ""
         sources = []
@@ -76,7 +86,7 @@ class RAGChain:
         # 1. Fetch Context depending on the Retrieval Mode
         try:
             if mode == "vector":
-                chunks = self.vector_retriever.retrieve_relevant_chunks(query, user_id, limit=5)
+                chunks = self.vector_retriever.retrieve_relevant_chunks(query, user_id, limit=5, doc_names=doc_names)
                 context_lines = []
                 for c in chunks:
                     context_lines.append(f"Document: {c['source_doc']} (Page: {c['page']}): \"{c['text']}\"")
@@ -84,7 +94,7 @@ class RAGChain:
                 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)
+                graph_context = self.graph_retriever.retrieve_graph_context(query, user_id, hops=2, doc_names=doc_names)
                 context = graph_context
                 # Extract entity names as sources
                 for line in graph_context.split("\n"):
@@ -93,7 +103,7 @@ class RAGChain:
                         sources.append(f"Graph Node: {ent_name}")
 
             else:  # hybrid
-                hybrid_result = self.hybrid_retriever.retrieve_combined_context(query, user_id)
+                hybrid_result = self.hybrid_retriever.retrieve_combined_context(query, user_id, doc_names=doc_names)
                 context = hybrid_result["combined_context"]
                 strategy_used = hybrid_result["strategy"]
                 

backend/graphrag/services/vector_retriever.py

@@ -19,7 +19,7 @@ class VectorRetriever:
 
         # 2. Load the Embedding Model via ChromaDB's built-in ONNX path
         # Uses ONNX runtime only — no torch/CUDA needed, no sentence-transformers package
-        self.embedding_fn = ONNXMiniLM_L6_V2(preferred_provider="CPUExecutionProvider")
+        self.embedding_fn = ONNXMiniLM_L6_V2(preferred_providers=["CPUExecutionProvider"])
 
         # 3. Setup text splitter for document chunking
         def chunk_text(text: str, chunk_size: int = 800, chunk_overlap: int = 100) -> List[str]:
@@ -81,19 +81,23 @@ class VectorRetriever:
             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]:
+    def retrieve_relevant_chunks(self, query: str, user_id: str, limit: int = 5, doc_names: List[str] = None) -> 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)
+        logger.info("Searching ChromaDB for query: '%s' (Limit: %d, User: %s, Docs: %s)", query, limit, user_id, doc_names)
         try:
             collection = self._get_user_collection(user_id)
             query_vector = self.embedding_fn([query])[0]
 
-            results = collection.query(
-                query_embeddings=[query_vector],
-                n_results=limit
-            )
+            query_params = {
+                "query_embeddings": [query_vector],
+                "n_results": limit
+            }
+            if doc_names:
+                query_params["where"] = {"source_doc": {"$in": [str(d) for d in doc_names]}}
+
+            results = collection.query(**query_params)
 
             retrieved = []
             if results and results["documents"]:

backend/graphrag/tests.py

@@ -76,6 +76,17 @@ class GraphRAGTests(APITestCase):
         self.assertIn("access", response.data)
         self.assertIn("refresh", response.data)
 
+    def test_login_with_email_and_jwt_issuance(self):
+        url = reverse('auth_login')
+        data = {
+            "username": self.email,
+            "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')

backend/graphrag/views.py

@@ -37,8 +37,29 @@ _ingestion_semaphore = threading.Semaphore(settings.MAX_INGESTION_WORKERS)
 
 logger = logging.getLogger(__name__)
 
+from django.contrib.auth.backends import ModelBackend
+from django.db.models import Q
+
 User = get_user_model()
 
+class EmailOrUsernameModelBackend(ModelBackend):
+    """
+    Custom authentication backend that allows authenticating with either
+    a username or an email address.
+    """
+    def authenticate(self, request, username=None, password=None, **kwargs):
+        if username is None:
+            username = kwargs.get('username')
+        
+        # Check if input matches username OR email (case-insensitive)
+        user = User.objects.filter(
+            Q(username__iexact=username) | Q(email__iexact=username)
+        ).first()
+
+        if user and user.check_password(password):
+            return user
+        return None
+
 
 # ============================================================
 # Custom Throttle Classes
@@ -229,6 +250,14 @@ class DocumentUploadView(APIView):
                 status=status.HTTP_400_BAD_REQUEST
             )
 
+        # --- Duplicate Check ---
+        if Document.objects.filter(user=request.user, name=file_obj.name).exists():
+            logger.warning("Document upload request rejected: Duplicate filename '%s' found for user: %s", file_obj.name, request.user.username)
+            return Response(
+                {"error": "A document with this name has already been uploaded."},
+                status=status.HTTP_409_CONFLICT
+            )
+
         # Save document record with initial PENDING status
         doc = Document.objects.create(
             user=request.user,
@@ -317,6 +346,7 @@ class QueryView(APIView):
     def post(self, request):
         query = request.data.get("query")
         mode = request.data.get("mode", "hybrid")
+        document_ids = request.data.get("document_ids", None)
 
         if not query or not query.strip():
             return Response(
@@ -324,11 +354,11 @@ class QueryView(APIView):
                 status=status.HTTP_400_BAD_REQUEST
             )
 
-        logger.info("Executing RAG Query for user: %s | Mode: %s", request.user.username, mode)
+        logger.info("Executing RAG Query for user: %s | Mode: %s | Docs: %s", request.user.username, mode, document_ids)
         start_time = time.time()
         try:
             rag_chain = RAGChain()
-            result = rag_chain.generate_answer(query, request.user.id, mode)
+            result = rag_chain.generate_answer(query, request.user.id, mode, doc_ids=document_ids)
             elapsed = time.time() - start_time
 
             # Log query
@@ -518,8 +548,13 @@ class GraphDataView(APIView):
 
     def get(self, request):
         try:
+            document_ids_str = request.GET.get("document_ids", None)
+            doc_ids = None
+            if document_ids_str:
+                doc_ids = [d.strip() for d in document_ids_str.split(",") if d.strip()]
+            
             graph_retriever = GraphRetriever()
-            graph_json = graph_retriever.get_graph_as_json(request.user.id)
+            graph_json = graph_retriever.get_graph_as_json(request.user.id, doc_ids=doc_ids)
             return Response(graph_json, status=status.HTTP_200_OK)
         except Exception as e:
             logger.error("Error in GraphDataView: %s", str(e), exc_info=True)

backend/requirements.txt

@@ -15,3 +15,4 @@ pydantic>=2.5.0
 python-dotenv>=1.0.0
 gunicorn>=21.2.0
 psycopg2-binary>=2.9.9
+langchain-openai>=0.1.0

docker-compose.yml

@@ -39,6 +39,9 @@ services:
       context: ./backend
       dockerfile: Dockerfile
     container_name: graphrag_backend
+    command: >
+      sh -c "python manage.py migrate --noinput &&
+             gunicorn config.wsgi:application --bind 0.0.0.0:8000 --workers 4 --threads 2 --timeout 300 --access-logfile - --error-logfile -"
     restart: unless-stopped
     ports:
       # Only expose to localhost — not 0.0.0.0
@@ -52,7 +55,7 @@ services:
       - ALLOWED_HOSTS=localhost,127.0.0.1,backend
     volumes:
       # Persist SQLite database (user accounts, document metadata)
-      - sqlite_data:/app
+      - sqlite_data:/app/db
       # Persist ChromaDB vector store
       - chroma_data:/app/chroma_db
       # Persist uploaded documents

eval_dataset/eval_questions.json

@@ -1,182 +0,0 @@
-[
-  {
-    "id": 1,
-    "category": "single_entity",
-    "difficulty": "easy",
-    "question": "Who is the CEO of Google?",
-    "expected_answer": "Sundar Pichai is the CEO of Google.",
-    "retrieval_mode": "graph",
-    "notes": "Tests basic entity-relationship traversal"
-  },
-  {
-    "id": 2,
-    "category": "single_entity",
-    "difficulty": "easy",
-    "question": "What technology does React depend on?",
-    "expected_answer": "React depends on JavaScript and the Virtual DOM.",
-    "retrieval_mode": "graph",
-    "notes": "Tests DEPENDS_ON relationship traversal"
-  },
-  {
-    "id": 3,
-    "category": "multi_hop",
-    "difficulty": "medium",
-    "question": "Who manages the team that works on Project X?",
-    "expected_answer": "The project manager of the team working on Project X is [extracted name].",
-    "retrieval_mode": "graph",
-    "notes": "Tests 2-hop traversal: Person MANAGES Person WORKS_AT Project"
-  },
-  {
-    "id": 4,
-    "category": "multi_hop",
-    "difficulty": "hard",
-    "question": "What skills does the manager of the team working on the authentication service have?",
-    "expected_answer": "The manager has skills in [extracted from graph].",
-    "retrieval_mode": "graph",
-    "notes": "Tests 3-hop traversal: Service → Team → Manager → Skills"
-  },
-  {
-    "id": 5,
-    "category": "multi_hop",
-    "difficulty": "hard",
-    "question": "Which organizations are located in the same city as the headquarters of the company that created ChatGPT?",
-    "expected_answer": "Organizations located in San Francisco include [extracted names].",
-    "retrieval_mode": "graph",
-    "notes": "Tests 3-hop: Product CREATED_BY Org LOCATED_IN Location ← Org"
-  },
-  {
-    "id": 6,
-    "category": "relationship",
-    "difficulty": "easy",
-    "question": "What companies are competitors of Google?",
-    "expected_answer": "Google's competitors include Microsoft, Apple, and Meta.",
-    "retrieval_mode": "graph",
-    "notes": "Tests COMPETES_WITH relationship"
-  },
-  {
-    "id": 7,
-    "category": "relationship",
-    "difficulty": "medium",
-    "question": "List all partnerships mentioned in the document.",
-    "expected_answer": "The partnerships include [list of PARTNER_OF relationships].",
-    "retrieval_mode": "graph",
-    "notes": "Tests PARTNER_OF relationship enumeration"
-  },
-  {
-    "id": 8,
-    "category": "summarization",
-    "difficulty": "medium",
-    "question": "Give me an overview of the organizational structure described in the document.",
-    "expected_answer": "The document describes [hierarchy summary with entities and relationships].",
-    "retrieval_mode": "hybrid",
-    "notes": "Tests community-level summarization capability"
-  },
-  {
-    "id": 9,
-    "category": "summarization",
-    "difficulty": "hard",
-    "question": "Summarize the key technology stack and dependencies mentioned across all documents.",
-    "expected_answer": "The technology stack includes [technologies] with dependencies on [dependencies].",
-    "retrieval_mode": "hybrid",
-    "notes": "Tests cross-document synthesis"
-  },
-  {
-    "id": 10,
-    "category": "vector_specific",
-    "difficulty": "easy",
-    "question": "What is the main topic of the uploaded documents?",
-    "expected_answer": "The documents primarily discuss [topic].",
-    "retrieval_mode": "vector",
-    "notes": "Tests basic vector similarity retrieval"
-  },
-  {
-    "id": 11,
-    "category": "vector_specific",
-    "difficulty": "medium",
-    "question": "Find all sections that discuss machine learning concepts.",
-    "expected_answer": "Machine learning is discussed in [sections with ML-related content].",
-    "retrieval_mode": "vector",
-    "notes": "Tests semantic similarity for topic-specific retrieval"
-  },
-  {
-    "id": 12,
-    "category": "hybrid",
-    "difficulty": "medium",
-    "question": "How does the authentication system work and who is responsible for it?",
-    "expected_answer": "The authentication system [description] and is managed by [person/team].",
-    "retrieval_mode": "hybrid",
-    "notes": "Tests combining vector context with graph relationships"
-  },
-  {
-    "id": 13,
-    "category": "hybrid",
-    "difficulty": "hard",
-    "question": "What are the risks to the project timeline and which teams are affected?",
-    "expected_answer": "Risks include [risks from text] affecting [teams from graph].",
-    "retrieval_mode": "hybrid",
-    "notes": "Tests combining textual risk analysis with organizational graph"
-  },
-  {
-    "id": 14,
-    "category": "community",
-    "difficulty": "medium",
-    "question": "What are the main topic clusters in this knowledge graph?",
-    "expected_answer": "The graph contains communities focused on [community themes].",
-    "retrieval_mode": "graph",
-    "notes": "Tests community detection and thematic grouping"
-  },
-  {
-    "id": 15,
-    "category": "community",
-    "difficulty": "hard",
-    "question": "Which community of entities is most central to the overall knowledge graph?",
-    "expected_answer": "The most central community focuses on [theme] with [key entities].",
-    "retrieval_mode": "graph",
-    "notes": "Tests community importance ranking via degree centrality"
-  },
-  {
-    "id": 16,
-    "category": "comparison",
-    "difficulty": "medium",
-    "question": "Compare graph-based retrieval with vector-based retrieval for this question: What is the company structure?",
-    "expected_answer": "Graph retrieval provides structured org chart data; vector retrieval provides relevant text passages.",
-    "retrieval_mode": "compare",
-    "notes": "Tests retrieval mode comparison capability"
-  },
-  {
-    "id": 17,
-    "category": "cypher",
-    "difficulty": "medium",
-    "question": "Show me all Person nodes that have more than 3 connections.",
-    "expected_answer": "Cypher: MATCH (p:Person)-[r]-() WITH p, count(r) AS degree WHERE degree > 3 RETURN p.name, degree",
-    "retrieval_mode": "graph",
-    "notes": "Tests NL-to-Cypher translation"
-  },
-  {
-    "id": 18,
-    "category": "cypher",
-    "difficulty": "hard",
-    "question": "Find all entities that are within 2 hops of 'Google' and belong to the TECHNOLOGY type.",
-    "expected_answer": "Cypher: MATCH path = (g:Organization {name: 'Google'})-[*1..2]-(t:Technology) RETURN t",
-    "retrieval_mode": "graph",
-    "notes": "Tests multi-hop Cypher with type filtering"
-  },
-  {
-    "id": 19,
-    "category": "edge_case",
-    "difficulty": "hard",
-    "question": "What entities exist in the graph that have no relationships?",
-    "expected_answer": "Orphan entities include [list of disconnected nodes].",
-    "retrieval_mode": "graph",
-    "notes": "Tests handling of disconnected graph components"
-  },
-  {
-    "id": 20,
-    "category": "edge_case",
-    "difficulty": "hard",
-    "question": "Which entities appear in multiple documents?",
-    "expected_answer": "Entities found in multiple documents: [list with document references].",
-    "retrieval_mode": "graph",
-    "notes": "Tests cross-document entity resolution"
-  }
-]

frontend/package-lock.json

@@ -260,6 +260,66 @@
         "glob": "10.3.10"
       }
     },
+    "node_modules/@next/swc-darwin-arm64": {
+      "version": "14.2.5",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-14.2.5.tgz",
+      "integrity": "sha512-/9zVxJ+K9lrzSGli1///ujyRfon/ZneeZ+v4ptpiPoOU+GKZnm8Wj8ELWU1Pm7GHltYRBklmXMTUqM/DqQ99FQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-darwin-x64": {
+      "version": "14.2.5",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-14.2.5.tgz",
+      "integrity": "sha512-vXHOPCwfDe9qLDuq7U1OYM2wUY+KQ4Ex6ozwsKxp26BlJ6XXbHleOUldenM67JRyBfVjv371oneEvYd3H2gNSA==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-linux-arm64-gnu": {
+      "version": "14.2.5",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-14.2.5.tgz",
+      "integrity": "sha512-vlhB8wI+lj8q1ExFW8lbWutA4M2ZazQNvMWuEDqZcuJJc78iUnLdPPunBPX8rC4IgT6lIx/adB+Cwrl99MzNaA==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-linux-arm64-musl": {
+      "version": "14.2.5",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-14.2.5.tgz",
+      "integrity": "sha512-NpDB9NUR2t0hXzJJwQSGu1IAOYybsfeB+LxpGsXrRIb7QOrYmidJz3shzY8cM6+rO4Aojuef0N/PEaX18pi9OA==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
     "node_modules/@next/swc-linux-x64-gnu": {
       "version": "14.2.5",
       "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-14.2.5.tgz",
@@ -276,6 +336,66 @@
         "node": ">= 10"
       }
     },
+    "node_modules/@next/swc-linux-x64-musl": {
+      "version": "14.2.5",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-14.2.5.tgz",
+      "integrity": "sha512-6QLwi7RaYiQDcRDSU/os40r5o06b5ue7Jsk5JgdRBGGp8l37RZEh9JsLSM8QF0YDsgcosSeHjglgqi25+m04IQ==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-win32-arm64-msvc": {
+      "version": "14.2.5",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-14.2.5.tgz",
+      "integrity": "sha512-1GpG2VhbspO+aYoMOQPQiqc/tG3LzmsdBH0LhnDS3JrtDx2QmzXe0B6mSZZiN3Bq7IOMXxv1nlsjzoS1+9mzZw==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-win32-ia32-msvc": {
+      "version": "14.2.5",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-ia32-msvc/-/swc-win32-ia32-msvc-14.2.5.tgz",
+      "integrity": "sha512-Igh9ZlxwvCDsu6438FXlQTHlRno4gFpJzqPjSIBZooD22tKeI4fE/YMRoHVJHmrQ2P5YL1DoZ0qaOKkbeFWeMg==",
+      "cpu": [
+        "ia32"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-win32-x64-msvc": {
+      "version": "14.2.5",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-14.2.5.tgz",
+      "integrity": "sha512-tEQ7oinq1/CjSG9uSTerca3v4AZ+dFa+4Yu6ihaG8Ud8ddqLQgFGcnwYls13H5X5CPDPZJdYxyeMui6muOLd4g==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
     "node_modules/@nodelib/fs.scandir": {
       "version": "2.1.5",
       "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",

frontend/src/app/(dashboard)/documents/page.tsx

@@ -1,31 +1,56 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useRouter } from 'next/navigation';
 import api from '@/lib/axios';
 import { useDocumentPolling } from '@/hooks/useDocumentPolling';
-import { useDocumentsStore } from '@/store/documents';
+import { useDocumentsStore, DocumentItem } from '@/store/documents';
 import { useGraphStore } from '@/store/graph';
 import { DocumentUpload } from '@/components/documents/DocumentUpload';
 import { DocumentRow } from '@/components/documents/DocumentRow';
 import { Card, CardContent } from '@/components/ui/card';
+import { Search, X, Layers, AlertCircle } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { useGraphData } from '@/hooks/useGraphData';
 
 export default function DocumentsPage() {
   useDocumentPolling();
+  useGraphData(); // Keep graph data updated
+  
   const documents = useDocumentsStore((s) => s.documents);
-  const setHighlighted = useGraphStore((s) => s.setHighlighted);
+  const selectedIds = useDocumentsStore((s) => s.selectedDocumentIds);
+  const toggleSelectDocument = useDocumentsStore((s) => s.toggleSelectDocument);
   const graphData = useGraphStore((s) => s.data);
-  const router = useRouter();
   const [notice, setNotice] = useState('');
+  const [selectedDetailDoc, setSelectedDetailDoc] = useState<DocumentItem | null>(null);
+  const [deleteConfirmId, setDeleteConfirmId] = useState<string | null>(null);
 
   const completed = documents.filter((d) => d.status === 'COMPLETED').length;
 
-  function filterToDoc(docName: string) {
-    const ids = graphData.nodes
-      .filter((n) => n.sourceDoc === docName)
-      .map((n) => n.id);
-    if (ids.length) setHighlighted(ids);
-    router.push('/');
+  async function deleteDocument(id: string) {
+    try {
+      await api.delete(`/documents/${id}/`);
+      
+      // Update documents list
+      useDocumentsStore.getState().setDocuments(
+        useDocumentsStore.getState().documents.filter((d) => d.id !== id)
+      );
+
+      // Deselect if currently selected
+      const store = useDocumentsStore.getState();
+      if (store.selectedDocumentIds.includes(id)) {
+        store.toggleSelectDocument(id);
+      }
+
+      // Close details panel if this document was open
+      if (selectedDetailDoc?.id === id) {
+        setSelectedDetailDoc(null);
+      }
+
+      setNotice('Document successfully deleted.');
+    } catch {
+      setNotice('Could not delete the document. Please try again.');
+    }
+    setTimeout(() => setNotice(''), 4000);
   }
 
   async function retryDocument(id: string) {
@@ -41,62 +66,291 @@ export default function DocumentsPage() {
     setTimeout(() => setNotice(''), 4000);
   }
 
+  // Filter local entities and relations for the selected detail document
+  const docEntities = selectedDetailDoc
+    ? graphData.nodes.filter((n) => n.sourceDoc === selectedDetailDoc.name)
+    : [];
+  const docLinks = selectedDetailDoc
+    ? graphData.links.filter((l) => l.sourceDoc === selectedDetailDoc.name)
+    : [];
+
+  const [entityQuery, setEntityQuery] = useState('');
+  const [relationQuery, setRelationQuery] = useState('');
+  const [activeTab, setActiveTab] = useState<'entities' | 'relations'>('entities');
+
+  const filteredEntities = docEntities.filter(
+    (e) =>
+      e.name.toLowerCase().includes(entityQuery.toLowerCase()) ||
+      e.type.toLowerCase().includes(entityQuery.toLowerCase())
+  );
+
+  const filteredLinks = docLinks.filter(
+    (l) =>
+      l.source.toLowerCase().includes(relationQuery.toLowerCase()) ||
+      l.target.toLowerCase().includes(relationQuery.toLowerCase()) ||
+      l.type.toLowerCase().includes(relationQuery.toLowerCase())
+  );
+
+  // Sync selectedDetailDoc when document properties change
+  useEffect(() => {
+    if (selectedDetailDoc) {
+      const match = documents.find((d) => d.id === selectedDetailDoc.id);
+      if (match) setSelectedDetailDoc(match);
+      else setSelectedDetailDoc(null);
+    }
+  }, [documents]);
+
   return (
-    <div className="flex h-full flex-col gap-4 overflow-y-auto p-4 scrollbar-thin">
-      <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
-        <Card>
-          <CardContent className="p-4">
-            <h2 className="mb-3 text-sm font-semibold">Upload Document</h2>
-            <DocumentUpload />
-          </CardContent>
-        </Card>
-
-        <Card>
-          <CardContent className="p-4">
-            <div className="grid grid-cols-3 gap-3 text-center">
-              <div className="rounded-md bg-bg-elevated p-3">
-                <p className="text-xl font-bold text-accent-violet">{documents.length}</p>
-                <p className="text-xs text-text-muted">Total</p>
-              </div>
-              <div className="rounded-md bg-bg-elevated p-3">
-                <p className="text-xl font-bold text-success">{completed}</p>
-                <p className="text-xs text-text-muted">Completed</p>
-              </div>
-              <div className="rounded-md bg-bg-elevated p-3">
-                <p className="text-xl font-bold text-warning">
-                  {documents.filter((d) => d.status === 'PROCESSING' || d.status === 'PENDING').length}
-                </p>
-                <p className="text-xs text-text-muted">Active</p>
+    <div className="flex h-full gap-4 p-4 overflow-hidden">
+      {/* Left side master view */}
+      <div className="flex-1 flex flex-col gap-4 overflow-y-auto scrollbar-thin pr-1">
+        <div className="grid grid-cols-1 gap-4 lg:grid-cols-2 shrink-0">
+          <Card>
+            <CardContent className="p-4">
+              <h2 className="mb-3 text-sm font-semibold text-text-primary">Upload Document</h2>
+              <DocumentUpload />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardContent className="p-4">
+              <div className="grid grid-cols-3 gap-3 text-center">
+                <div className="rounded-md bg-bg-elevated p-3 border border-border/20">
+                  <p className="text-xl font-bold text-accent-violet">{documents.length}</p>
+                  <p className="text-xs text-text-muted font-medium">Total</p>
+                </div>
+                <div className="rounded-md bg-bg-elevated p-3 border border-border/20">
+                  <p className="text-xl font-bold text-success">{completed}</p>
+                  <p className="text-xs text-text-muted font-medium">Completed</p>
+                </div>
+                <div className="rounded-md bg-bg-elevated p-3 border border-border/20">
+                  <p className="text-xl font-bold text-warning">
+                    {documents.filter((d) => d.status === 'PROCESSING' || d.status === 'PENDING').length}
+                  </p>
+                  <p className="text-xs text-text-muted font-medium">Active</p>
+                </div>
               </div>
+              <p className="mt-3 text-[11px] text-text-muted leading-relaxed">
+                Check boxes to select source context. Click rows to view extracted entities and relationships.
+              </p>
+            </CardContent>
+          </Card>
+        </div>
+
+        <div className="flex-1 flex flex-col min-h-0 bg-bg-surface rounded-lg border border-border p-4">
+          <div className="flex items-center justify-between pb-3 mb-3 border-b border-border shrink-0">
+            <h2 className="text-sm font-semibold text-text-primary">Document List</h2>
+            <div className="flex items-center gap-3">
+              <button
+                type="button"
+                onClick={() => useDocumentsStore.getState().selectAllDocuments()}
+                className="text-[11px] text-accent-violet hover:underline font-medium"
+              >
+                Select All
+              </button>
+              <span className="text-[11px] text-text-muted">|</span>
+              <button
+                type="button"
+                onClick={() => useDocumentsStore.getState().deselectAllDocuments()}
+                className="text-[11px] text-text-muted hover:underline font-medium"
+              >
+                Deselect All
+              </button>
             </div>
-            <p className="mt-3 text-xs text-text-muted">
-              Click a completed document to filter the graph to its entities.
-            </p>
-          </CardContent>
-        </Card>
+          </div>
+
+          <div className="flex-1 overflow-y-auto space-y-2 pr-1 scrollbar-thin min-h-0">
+            {documents.length === 0 ? (
+              <p className="text-sm text-text-muted py-8 text-center">No documents uploaded yet.</p>
+            ) : (
+              documents.map((doc) => (
+                <DocumentRow
+                  key={doc.id}
+                  doc={doc}
+                  isSelected={selectedIds.includes(doc.id)}
+                  onToggleSelect={toggleSelectDocument}
+                  onViewDetails={setSelectedDetailDoc}
+                  onDelete={setDeleteConfirmId}
+                  onRetry={retryDocument}
+                />
+              ))
+            )}
+            
+            {notice && (
+              <div className="mt-3 p-2.5 rounded-md border border-accent-cyan/20 bg-accent-cyan/10 text-xs text-accent-cyan font-medium">
+                {notice}
+              </div>
+            )}
+          </div>
+        </div>
       </div>
 
-      <div>
-        <h2 className="mb-2 text-sm font-semibold">Document List</h2>
-        <div className="space-y-2">
-          {documents.length === 0 && (
-            <p className="text-sm text-text-muted">No documents yet. Upload one to begin.</p>
+      {/* Right side details card */}
+      <Card className="w-[380px] shrink-0 hidden lg:flex flex-col h-full overflow-hidden border border-border bg-bg-surface">
+        <CardContent className="p-4 flex flex-col h-full overflow-hidden min-h-0">
+          {selectedDetailDoc ? (
+            <div className="flex flex-col h-full overflow-hidden min-h-0">
+              <div className="flex items-center justify-between pb-3 border-b border-border shrink-0">
+                <div className="min-w-0 flex-1">
+                  <h3 className="text-sm font-semibold truncate text-text-primary pr-2" title={selectedDetailDoc.name}>
+                    {selectedDetailDoc.name}
+                  </h3>
+                  <p className="text-[10px] text-text-muted font-medium mt-0.5">Extracted graph metadata</p>
+                </div>
+                <button
+                  type="button"
+                  onClick={() => setSelectedDetailDoc(null)}
+                  className="p-1 hover:bg-bg-elevated rounded transition-colors text-text-muted hover:text-text-primary"
+                >
+                  <X className="h-4 w-4" />
+                </button>
+              </div>
+
+              <div className="flex border-b border-border text-xs mt-3 shrink-0">
+                <button
+                  type="button"
+                  onClick={() => setActiveTab('entities')}
+                  className={cn(
+                    'flex-1 pb-2 font-semibold border-b-2 transition-colors text-center',
+                    activeTab === 'entities'
+                      ? 'border-accent-violet text-accent-violet'
+                      : 'border-transparent text-text-muted hover:text-text-primary'
+                  )}
+                >
+                  Entities ({docEntities.length})
+                </button>
+                <button
+                  type="button"
+                  onClick={() => setActiveTab('relations')}
+                  className={cn(
+                    'flex-1 pb-2 font-semibold border-b-2 transition-colors text-center',
+                    activeTab === 'relations'
+                      ? 'border-accent-violet text-accent-violet'
+                      : 'border-transparent text-text-muted hover:text-text-primary'
+                  )}
+                >
+                  Relationships ({docLinks.length})
+                </button>
+              </div>
+
+              <div className="flex-1 mt-3 overflow-hidden flex flex-col min-h-0">
+                {activeTab === 'entities' ? (
+                  <div className="flex flex-col h-full min-h-0">
+                    <div className="relative mb-2 shrink-0">
+                      <Search className="absolute left-2.5 top-2 h-3.5 w-3.5 text-text-muted" />
+                      <input
+                        type="text"
+                        placeholder="Search entities..."
+                        value={entityQuery}
+                        onChange={(e) => setEntityQuery(e.target.value)}
+                        className="w-full pl-8 pr-3 py-1.5 text-xs rounded border border-border bg-bg-elevated focus:outline-none focus:ring-1 focus:ring-accent-violet text-text-primary placeholder:text-text-muted/65"
+                      />
+                    </div>
+                    <div className="flex-1 overflow-y-auto space-y-2 pr-1 scrollbar-thin min-h-0">
+                      {filteredEntities.length === 0 ? (
+                        <p className="text-xs text-text-muted text-center py-6">No matching entities found.</p>
+                      ) : (
+                        filteredEntities.map((ent, i) => (
+                          <div key={i} className="p-2.5 rounded bg-bg-elevated border border-border/40 text-xs">
+                            <div className="flex items-center justify-between gap-2 mb-1">
+                              <span className="font-semibold text-text-primary truncate">{ent.name}</span>
+                              <span className="px-1.5 py-0.5 rounded-full bg-accent-violet/15 text-accent-violet text-[9px] uppercase font-bold shrink-0">
+                                {ent.type}
+                              </span>
+                            </div>
+                            {ent.description && (
+                              <p className="text-text-muted text-[11px] leading-relaxed mt-1 font-normal">{ent.description}</p>
+                            )}
+                          </div>
+                        ))
+                      )}
+                    </div>
+                  </div>
+                ) : (
+                  <div className="flex flex-col h-full min-h-0">
+                    <div className="relative mb-2 shrink-0">
+                      <Search className="absolute left-2.5 top-2 h-3.5 w-3.5 text-text-muted" />
+                      <input
+                        type="text"
+                        placeholder="Search relationships..."
+                        value={relationQuery}
+                        onChange={(e) => setRelationQuery(e.target.value)}
+                        className="w-full pl-8 pr-3 py-1.5 text-xs rounded border border-border bg-bg-elevated focus:outline-none focus:ring-1 focus:ring-accent-violet text-text-primary placeholder:text-text-muted/65"
+                      />
+                    </div>
+                    <div className="flex-1 overflow-y-auto space-y-2 pr-1 scrollbar-thin min-h-0">
+                      {filteredLinks.length === 0 ? (
+                        <p className="text-xs text-text-muted text-center py-6">No matching relationships found.</p>
+                      ) : (
+                        filteredLinks.map((link, i) => (
+                          <div key={i} className="p-2.5 rounded bg-bg-elevated border border-border/40 text-xs space-y-1">
+                            <div className="flex flex-wrap items-center gap-1.5 text-[11px] leading-relaxed">
+                              <span className="font-semibold text-text-primary">{link.source}</span>
+                              <span className="px-1.5 py-0.5 rounded bg-accent-cyan/15 text-accent-cyan text-[9px] font-bold shrink-0">
+                                {link.type}
+                              </span>
+                              <span className="font-semibold text-text-primary">{link.target}</span>
+                            </div>
+                            {link.description && (
+                              <p className="text-text-muted text-[11px] leading-relaxed mt-1 font-normal">{link.description}</p>
+                            )}
+                            {link.confidence !== undefined && (
+                              <p className="text-[10px] text-text-muted/75 font-medium mt-1">Confidence: {link.confidence.toFixed(2)}</p>
+                            )}
+                          </div>
+                        ))
+                      )}
+                    </div>
+                  </div>
+                )}
+              </div>
+            </div>
+          ) : (
+            <div className="flex flex-col items-center justify-center h-full text-center p-4">
+              <div className="w-12 h-12 rounded-full bg-accent-violet/10 flex items-center justify-center text-accent-violet mb-3 shrink-0">
+                <Layers className="h-5 w-5" />
+              </div>
+              <h4 className="text-xs font-semibold text-text-primary mb-1">No Document Selected</h4>
+              <p className="text-[11px] text-text-muted max-w-[220px] leading-relaxed">
+                Click a completed document card on the left to explore its extracted entities and relationships.
+              </p>
+            </div>
           )}
-          {documents.map((doc) => (
-            <DocumentRow
-              key={doc.id}
-              doc={doc}
-              onFilter={filterToDoc}
-              onRetry={retryDocument}
-            />
-          ))}
-          {notice && (
-            <p className="rounded-md border border-accent-cyan/30 bg-accent-cyan/10 px-3 py-2 text-xs text-accent-cyan">
-              {notice}
+        </CardContent>
+      </Card>
+
+      {deleteConfirmId && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 backdrop-blur-sm">
+          <div className="w-full max-w-md rounded-lg border border-border bg-bg-surface p-6 shadow-2xl animate-in fade-in zoom-in-95 duration-150">
+            <div className="flex items-center gap-3 text-error mb-4">
+              <AlertCircle className="h-6 w-6" />
+              <h3 className="text-lg font-bold text-text-primary">Confirm Deletion</h3>
+            </div>
+            <p className="text-sm text-text-secondary leading-relaxed mb-6">
+              Are you sure you want to delete this document? This will remove all its nodes and relationships from the database. This action cannot be undone.
             </p>
-          )}
+            <div className="flex justify-end gap-3">
+              <button
+                type="button"
+                onClick={() => setDeleteConfirmId(null)}
+                className="rounded-md border border-border px-4 py-2 text-xs font-semibold text-text-secondary hover:bg-bg-elevated hover:text-text-primary transition-colors"
+              >
+                Cancel
+              </button>
+              <button
+                type="button"
+                onClick={() => {
+                  deleteDocument(deleteConfirmId);
+                  setDeleteConfirmId(null);
+                }}
+                className="rounded-md bg-error px-4 py-2 text-xs font-semibold text-white hover:bg-error/90 transition-colors"
+              >
+                Delete
+              </button>
+            </div>
+          </div>
         </div>
-      </div>
+      )}
     </div>
   );
 }

frontend/src/app/(dashboard)/layout.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect } from 'react';
+import { useEffect, useState } from 'react';
 import { useRouter } from 'next/navigation';
 import { useAuthStore } from '@/store/auth';
 import { DashboardLayout } from '@/components/layout/DashboardLayout';
@@ -8,12 +8,21 @@ import { DashboardLayout } from '@/components/layout/DashboardLayout';
 export default function DashboardGroupLayout({ children }: { children: React.ReactNode }) {
   const isAuthed = useAuthStore((s) => s.isAuthenticated);
   const router = useRouter();
+  const [isReady, setIsReady] = useState(false);
 
   useEffect(() => {
-    if (!isAuthed) router.replace('/login');
-  }, [isAuthed, router]);
+    // Wait for Zustand persisted state to rehydrate (50ms)
+    const timer = setTimeout(() => setIsReady(true), 50);
+    return () => clearTimeout(timer);
+  }, []);
 
-  if (!isAuthed) return null;
+  useEffect(() => {
+    if (isReady && !isAuthed) {
+      router.replace('/login');
+    }
+  }, [isReady, isAuthed, router]);
+
+  if (!isReady || !isAuthed) return null;
 
   return <DashboardLayout>{children}</DashboardLayout>;
 }

frontend/src/components/dashboard/MainQueryView.tsx

@@ -13,6 +13,7 @@ import { GraphVisualization } from '@/components/graph/GraphVisualization';
 import { Upload, Sparkles } from 'lucide-react';
 import Link from 'next/link';
 import api from '@/lib/axios';
+import { useDocumentsStore } from '@/store/documents';
 
 interface QueryResult {
   answer: string;
@@ -30,6 +31,8 @@ export function MainQueryView() {
   const selectEntity = useGraphStore((s) => s.selectEntity);
   const data = useGraphStore((s) => s.data);
 
+  const selectedIds = useDocumentsStore((s) => s.selectedDocumentIds);
+
   const [query, setQuery] = useState('');
   const [mode, setMode] = useState<QueryMode>('hybrid');
   const [loading, setLoading] = useState(false);
@@ -52,7 +55,11 @@ export function MainQueryView() {
     setLoading(true);
     setResult(null);
     try {
-      const { data: res } = await api.post('/query/', { query, mode });
+      const { data: res } = await api.post('/query/', {
+        query,
+        mode,
+        document_ids: selectedIds.length > 0 ? selectedIds : undefined
+      });
       const mapped: QueryResult = {
         answer: res.answer,
         confidence: res.confidence,

frontend/src/components/documents/DocumentRow.tsx

@@ -1,4 +1,4 @@
-import { FileText, AlertCircle, RotateCcw } from 'lucide-react';
+import { FileText, AlertCircle, RotateCcw, Trash2 } from 'lucide-react';
 import { DocumentItem } from '@/store/documents';
 import { StatusBadge } from './StatusBadge';
 import { ProcessingSteps } from './ProcessingSteps';
@@ -19,35 +19,65 @@ function formatDate(iso: string) {
 
 export function DocumentRow({
   doc,
-  onFilter,
+  isSelected,
+  onToggleSelect,
+  onViewDetails,
+  onDelete,
   onRetry,
 }: {
   doc: DocumentItem;
-  onFilter?: (name: string) => void;
+  isSelected?: boolean;
+  onToggleSelect?: (id: string) => void;
+  onViewDetails?: (doc: DocumentItem) => void;
+  onDelete?: (id: string) => void;
   onRetry?: (id: string) => void;
 }) {
   return (
     <div
       className={cn(
-        'rounded-md border border-border bg-bg-surface p-3',
-        doc.status === 'COMPLETED' && 'cursor-pointer hover:border-accent-violet/40'
+        'rounded-md border border-border bg-bg-surface p-3 transition-colors',
+        doc.status === 'COMPLETED' && 'hover:border-accent-violet/30 cursor-pointer'
       )}
-      onClick={() => doc.status === 'COMPLETED' && onFilter?.(doc.name)}
+      onClick={() => doc.status === 'COMPLETED' && onViewDetails?.(doc)}
     >
       <div className="flex items-center justify-between gap-3">
-        <div className="flex min-w-0 items-center gap-2">
+        <div className="flex min-w-0 flex-1 items-center gap-2">
+          {doc.status === 'COMPLETED' ? (
+            <input
+              type="checkbox"
+              checked={isSelected}
+              onChange={(e) => {
+                e.stopPropagation();
+                onToggleSelect?.(doc.id);
+              }}
+              className="h-4 w-4 rounded border-border bg-bg-surface text-accent-violet focus:ring-accent-violet cursor-pointer"
+            />
+          ) : (
+            <div className="w-4 h-4 shrink-0" /> // Spacer to preserve alignment
+          )}
           <FileText className="h-4 w-4 shrink-0 text-text-muted" />
           <span className="truncate text-sm font-medium text-text-primary">{doc.name}</span>
         </div>
-        <StatusBadge status={doc.status} />
+        
+        <div className="flex items-center gap-2" onClick={(e) => e.stopPropagation()}>
+          <StatusBadge status={doc.status} />
+          <button
+            type="button"
+            onClick={() => onDelete?.(doc.id)}
+            className="rounded p-1 text-text-muted hover:bg-bg-elevated hover:text-error transition-colors"
+            title="Delete document"
+          >
+            <Trash2 className="h-4 w-4" />
+          </button>
+        </div>
       </div>
 
       {doc.status === 'PROCESSING' ? (
-        <div className="mt-2">
-          <ProcessingSteps currentStep={doc.processingStep} />
+        <div className="mt-2 pl-6">
+          <ProcessingSteps currentStep={doc.processingStep} status={doc.status} />
         </div>
       ) : (
-        <div className="mt-2 flex flex-wrap items-center gap-x-4 gap-y-1 text-xs text-text-muted">
+        <div className="mt-2 pl-6 flex flex-wrap items-center gap-x-4 gap-y-1 text-xs text-text-muted">
           {doc.entities !== undefined && <span>{doc.entities} entities</span>}
           {doc.relationships !== undefined && <span>{doc.relationships} relations</span>}
           <span>{formatDate(doc.uploadedAt)}</span>
@@ -55,7 +85,7 @@ export function DocumentRow({
       )}
 
       {doc.status === 'FAILED' && (
-        <div className="mt-2 flex items-center justify-between gap-2 rounded-md bg-error/10 px-2 py-1.5 text-xs text-error">
+        <div className="mt-2 ml-6 flex items-center justify-between gap-2 rounded-md bg-error/10 px-2 py-1.5 text-xs text-error">
           <span className="flex items-center gap-1">
             <AlertCircle className="h-3.5 w-3.5" /> {doc.error || 'Processing failed'}
           </span>
@@ -65,7 +95,7 @@ export function DocumentRow({
               e.stopPropagation();
               onRetry?.(doc.id);
             }}
-            className="inline-flex items-center gap-1 font-medium hover:underline"
+            className="inline-flex items-center gap-1 font-medium hover:underline text-error"
           >
             <RotateCcw className="h-3 w-3" /> Retry
           </button>

frontend/src/components/documents/DocumentUpload.tsx

@@ -18,9 +18,7 @@ export function DocumentUpload() {
 
   // Track real processing progress from the document store
   const liveDoc = uploadedDocId ? documents.find((d) => d.id === uploadedDocId) : null;
-  const liveProgress = liveDoc?.status === 'COMPLETED' ? 100
-    : liveDoc?.status === 'FAILED' ? 0
-    : 50;
+  const liveProgress = liveDoc?.processingProgress ?? 0;
   const liveStep = liveDoc?.processingStep || null;
 
   // Clear upload state when document completes or fails
@@ -79,6 +77,7 @@ export function DocumentUpload() {
         status: doc.status,
         uploadedAt: doc.uploaded_at ?? new Date().toISOString(),
         processingStep: doc.processing_step ?? null,
+        processingProgress: doc.processing_progress ?? 0,
       });
       setUploadedDocId(doc.id);
     } catch (err: any) {

frontend/src/components/documents/ProcessingSteps.tsx

@@ -2,11 +2,11 @@ import { CheckCircle2, Circle, Loader2 } from 'lucide-react';
 
 export const PROCESSING_STEPS = [
   'Loading document',
+  'Indexing vectors',
   'Extracting entities',
-  'Extracting relationships',
   'Resolving duplicates',
   'Building graph',
-  'Indexing vectors',
+  'Extracting relationships',
 ];
 
 interface StepCounts {
@@ -17,12 +17,29 @@ interface StepCounts {
 
 export function ProcessingSteps({
   currentStep,
+  status,
   counts,
 }: {
   currentStep?: string | null;
+  status?: string;
   counts?: StepCounts;
 }) {
-  const active = currentStep ? PROCESSING_STEPS.indexOf(currentStep) : -1;
+  const isCompleted = status === 'COMPLETED' || currentStep === 'Complete';
+  const active = isCompleted
+    ? PROCESSING_STEPS.length
+    : currentStep
+      ? PROCESSING_STEPS.findIndex((s) => {
+          const lowerStep = s.toLowerCase();
+          const lowerCurrent = currentStep.toLowerCase();
+          return (
+            lowerCurrent.includes(lowerStep) ||
+            (lowerStep === 'loading document' && lowerCurrent.includes('parsing')) ||
+            (lowerStep === 'indexing vectors' && lowerCurrent.includes('indexing')) ||
+            (lowerStep === 'building graph' && lowerCurrent.includes('building')) ||
+            (lowerStep === 'extracting relationships' && (lowerCurrent.includes('writing relationships') || lowerCurrent.includes('extracting relationships')))
+          );
+        })
+      : -1;
 
   function getCountLabel(step: string): string | null {
     if (!counts) return null;

frontend/src/components/graph/ForceGraphWrapper.tsx

@@ -0,0 +1,11 @@
+'use client';
+
+import React, { forwardRef } from 'react';
+import ForceGraph2D from 'react-force-graph-2d';
+
+const ForceGraphWrapper = forwardRef((props: any, ref: any) => {
+  return <ForceGraph2D {...props} ref={ref} />;
+});
+
+ForceGraphWrapper.displayName = 'ForceGraphWrapper';
+export default ForceGraphWrapper;

frontend/src/components/graph/GraphVisualization.tsx

@@ -10,7 +10,7 @@ import { GraphControls } from './GraphControls';
 import { GraphLegend } from './GraphLegend';
 import { GraphSearch } from './GraphSearch';
 
-const ForceGraph2D = dynamic(() => import('react-force-graph-2d'), { ssr: false }) as any;
+const ForceGraph2D = dynamic(() => import('./ForceGraphWrapper'), { ssr: false }) as any;
 
 interface FGNode extends GraphNode {
   x?: number;

frontend/src/components/query/DocumentFilterDropdown.tsx

@@ -0,0 +1,123 @@
+'use client';
+
+import { useState, useRef, useEffect } from 'react';
+import { Filter, ChevronDown, Search, Square, CheckSquare } from 'lucide-react';
+import { useDocumentsStore } from '@/store/documents';
+
+export function DocumentFilterDropdown() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [searchQuery, setSearchQuery] = useState('');
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  const documents = useDocumentsStore((s) => s.documents);
+  const selectedIds = useDocumentsStore((s) => s.selectedDocumentIds);
+  const toggleSelect = useDocumentsStore((s) => s.toggleSelectDocument);
+  const selectAll = useDocumentsStore((s) => s.selectAllDocuments);
+  const deselectAll = useDocumentsStore((s) => s.deselectAllDocuments);
+
+  const completedDocs = documents.filter((d) => d.status === 'COMPLETED');
+  const filteredDocs = completedDocs.filter((d) =>
+    d.name.toLowerCase().includes(searchQuery.toLowerCase())
+  );
+
+  // Close dropdown on click outside
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  let label = 'All Documents';
+  if (selectedIds.length === 0) {
+    label = 'No Documents selected';
+  } else if (selectedIds.length < completedDocs.length) {
+    label = `${selectedIds.length}/${completedDocs.length} selected`;
+  }
+
+  return (
+    <div className="relative inline-block text-left" ref={dropdownRef}>
+      <button
+        type="button"
+        onClick={() => setIsOpen((prev) => !prev)}
+        className="inline-flex items-center gap-1.5 rounded-md border border-border bg-bg-surface px-3 py-1.5 text-xs font-semibold text-text-primary hover:border-accent-violet/50 hover:bg-bg-elevated transition-all"
+      >
+        <Filter className="h-3.5 w-3.5 text-text-muted" />
+        <span>{label}</span>
+        <ChevronDown className="h-3 w-3 text-text-muted" />
+      </button>
+
+      {isOpen && (
+        <div className="absolute right-0 z-50 mt-1.5 w-64 origin-top-right rounded-md border border-border bg-bg-surface shadow-lg focus:outline-none flex flex-col max-h-80 overflow-hidden">
+          {/* Quick Actions Header */}
+          <div className="flex items-center justify-between border-b border-border p-2 bg-bg-elevated/40">
+            <span className="text-[10px] font-bold text-text-muted uppercase tracking-wider">
+              Filter context
+            </span>
+            <div className="flex items-center gap-2">
+              <button
+                type="button"
+                onClick={selectAll}
+                className="text-[10px] font-semibold text-accent-violet hover:underline"
+              >
+                Select All
+              </button>
+              <span className="text-[10px] text-text-muted">|</span>
+              <button
+                type="button"
+                onClick={deselectAll}
+                className="text-[10px] font-semibold text-text-muted hover:underline"
+              >
+                Clear
+              </button>
+            </div>
+          </div>
+
+          {/* Search Input */}
+          <div className="relative p-2 border-b border-border">
+            <Search className="absolute left-4 top-3.5 h-3.5 w-3.5 text-text-muted" />
+            <input
+              type="text"
+              placeholder="Search documents..."
+              value={searchQuery}
+              onChange={(e) => setSearchQuery(e.target.value)}
+              className="w-full pl-8 pr-3 py-1.5 text-xs rounded border border-border bg-bg-elevated focus:outline-none focus:ring-1 focus:ring-accent-violet text-text-primary placeholder:text-text-muted/60"
+            />
+          </div>
+
+          {/* Scrollable list */}
+          <div className="flex-1 overflow-y-auto p-1.5 space-y-0.5 scrollbar-thin max-h-48">
+            {completedDocs.length === 0 ? (
+              <p className="text-center text-xs text-text-muted py-4">No completed documents.</p>
+            ) : filteredDocs.length === 0 ? (
+              <p className="text-center text-xs text-text-muted py-4">No matching documents.</p>
+            ) : (
+              filteredDocs.map((doc) => {
+                const checked = selectedIds.includes(doc.id);
+                return (
+                  <div
+                    key={doc.id}
+                    onClick={() => toggleSelect(doc.id)}
+                    className="flex items-center gap-2 rounded px-2 py-1.5 hover:bg-bg-elevated cursor-pointer transition-colors"
+                  >
+                    {checked ? (
+                      <CheckSquare className="h-4 w-4 shrink-0 text-accent-violet" />
+                    ) : (
+                      <Square className="h-4 w-4 shrink-0 text-text-muted" />
+                    )}
+                    <span className="truncate text-xs font-medium text-text-primary" title={doc.name}>
+                      {doc.name}
+                    </span>
+                  </div>
+                );
+              })
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/query/QueryPanel.tsx

@@ -5,6 +5,8 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { cn } from '@/lib/utils';
 
+import { DocumentFilterDropdown } from './DocumentFilterDropdown';
+
 export type QueryMode = 'graph' | 'vector' | 'hybrid';
 
 const MODES: { value: QueryMode; label: string }[] = [
@@ -32,26 +34,30 @@ export function QueryPanel({
 }: QueryPanelProps) {
   return (
     <div className="space-y-3">
-      <div className="flex items-center gap-2">
-        <span className="text-xs font-semibold uppercase tracking-wide text-text-muted">
-          Mode
-        </span>
-        <div className="inline-flex rounded-md border border-border p-0.5">
-          {MODES.map((m) => (
-            <button
-              key={m.value}
-              onClick={() => onModeChange(m.value)}
-              className={cn(
-                'rounded px-2.5 py-1 text-xs font-medium transition-colors',
-                mode === m.value
-                  ? 'bg-accent-violet text-white'
-                  : 'text-text-secondary hover:text-text-primary'
-              )}
-            >
-              {m.label}
-            </button>
-          ))}
+      <div className="flex items-center justify-between gap-4">
+        <div className="flex items-center gap-2">
+          <span className="text-xs font-semibold uppercase tracking-wide text-text-muted">
+            Mode
+          </span>
+          <div className="inline-flex rounded-md border border-border p-0.5">
+            {MODES.map((m) => (
+              <button
+                key={m.value}
+                onClick={() => onModeChange(m.value)}
+                className={cn(
+                  'rounded px-2.5 py-1 text-xs font-medium transition-colors',
+                  mode === m.value
+                    ? 'bg-accent-violet text-white'
+                    : 'text-text-secondary hover:text-text-primary'
+                )}
+              >
+                {m.label}
+              </button>
+            ))}
+          </div>
         </div>
+
+        <DocumentFilterDropdown />
       </div>
 
       <div className="flex gap-2">

frontend/src/hooks/useDocumentPolling.ts

@@ -27,6 +27,7 @@ export function useDocumentPolling(enabled = true) {
           error: d.error_message,
           source: d.source || '',
           processingStep: d.processing_step ?? d.processingStep ?? null,
+          processingProgress: d.processing_progress ?? d.processingProgress ?? 0,
         }));
         if (docs.length > 0) {
           setDocuments(docs);
@@ -57,6 +58,7 @@ export function useDocumentPolling(enabled = true) {
           error: d.error_message,
           source: d.source || '',
           processingStep: d.processing_step ?? d.processingStep ?? null,
+          processingProgress: d.processing_progress ?? d.processingProgress ?? 0,
         }));
         const active = docs.filter(
           (d) => d.status === 'PENDING' || d.status === 'PROCESSING'

frontend/src/hooks/useGraphData.ts

@@ -2,13 +2,7 @@ import { useEffect, useState } from 'react';
 import api from '@/lib/axios';
 import { useGraphStore, GraphData } from '@/store/graph';
 import { mockGraph } from '@/lib/mockData';
-
-// Module-level dedupe so multiple components calling useGraphData
-// (HeroSection, MainQueryView, ExplorePage, CommunityView) don't race
-// or fire redundant requests.
-let inFlight: Promise<void> | null = null;
-let lastFetchedAt = 0;
-const CACHE_TTL_MS = 30_000;
+import { useDocumentsStore } from '@/store/documents';
 
 function mapResponse(data: any): GraphData {
   return {
@@ -32,48 +26,40 @@ function mapResponse(data: any): GraphData {
   };
 }
 
-function fetchGraph(setData: (d: GraphData) => void, setError: (e: string | null) => void) {
-  if (inFlight) return inFlight;
-  inFlight = (async () => {
-    try {
-      const { data } = await api.get('/graph/');
-      setData(mapResponse(data));
-      setError(null);
-      lastFetchedAt = Date.now();
-    } catch {
-      setError('Using demo graph data (backend unavailable).');
-      setData(mockGraph);
-      lastFetchedAt = Date.now();
-    } finally {
-      inFlight = null;
-    }
-  })();
-  return inFlight;
-}
-
 export function useGraphData() {
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const setData = useGraphStore((s) => s.setData);
-  const existing = useGraphStore((s) => s.data);
+  const selectedIds = useDocumentsStore((s) => s.selectedDocumentIds);
+  const selectedIdsStr = selectedIds.join(',');
 
   useEffect(() => {
-    // Skip if we already have fresh data within the TTL.
-    if (existing.nodes.length > 0 && Date.now() - lastFetchedAt < CACHE_TTL_MS) {
-      return;
-    }
     let cancelled = false;
     setLoading(true);
-    fetchGraph(
-      (d) => !cancelled && setData(d),
-      (e) => !cancelled && setError(e)
-    ).finally(() => {
-      if (!cancelled) setLoading(false);
-    });
+    
+    const url = selectedIdsStr ? `/graph/?document_ids=${selectedIdsStr}` : '/graph/';
+    
+    api.get(url)
+      .then(({ data }) => {
+        if (!cancelled) {
+          setData(mapResponse(data));
+          setError(null);
+        }
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setError('Using demo graph data (backend unavailable).');
+          setData(mockGraph);
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+
     return () => {
       cancelled = true;
     };
-  }, [setData, existing.nodes.length]);
+  }, [setData, selectedIdsStr]);
 
   return { loading, error };
 }

frontend/src/store/documents.ts

@@ -1,4 +1,5 @@
 import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
 
 export type DocStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
 
@@ -12,29 +13,62 @@ export interface DocumentItem {
   error?: string;
   source?: string;
   processingStep?: string | null;
+  processingProgress?: number;
 }
 
 interface DocumentsState {
   documents: DocumentItem[];
   activeJobs: number;
+  selectedDocumentIds: string[];
   setDocuments: (docs: DocumentItem[]) => void;
   upsertDocument: (doc: DocumentItem) => void;
   setActiveJobs: (n: number) => void;
+  toggleSelectDocument: (id: string) => void;
+  setSelectedDocumentIds: (ids: string[]) => void;
+  selectAllDocuments: () => void;
+  deselectAllDocuments: () => void;
 }
 
-export const useDocumentsStore = create<DocumentsState>((set) => ({
-  documents: [],
-  activeJobs: 0,
-  setDocuments: (documents) => set({ documents }),
-  upsertDocument: (doc) =>
-    set((state) => {
-      const idx = state.documents.findIndex((d) => d.id === doc.id);
-      if (idx >= 0) {
-        const next = [...state.documents];
-        next[idx] = doc;
-        return { documents: next };
-      }
-      return { documents: [doc, ...state.documents] };
+export const useDocumentsStore = create<DocumentsState>()(
+  persist(
+    (set) => ({
+      documents: [],
+      activeJobs: 0,
+      selectedDocumentIds: [],
+      setDocuments: (documents) => set({ documents }),
+      upsertDocument: (doc) =>
+        set((state) => {
+          const idx = state.documents.findIndex((d) => d.id === doc.id);
+          if (idx >= 0) {
+            const next = [...state.documents];
+            next[idx] = doc;
+            return { documents: next };
+          }
+          return { documents: [doc, ...state.documents] };
+        }),
+      setActiveJobs: (activeJobs) => set({ activeJobs }),
+      toggleSelectDocument: (id) =>
+        set((state) => {
+          const isSel = state.selectedDocumentIds.includes(id);
+          const next = isSel
+            ? state.selectedDocumentIds.filter((x) => x !== id)
+            : [...state.selectedDocumentIds, id];
+          return { selectedDocumentIds: next };
+        }),
+      setSelectedDocumentIds: (selectedDocumentIds) => set({ selectedDocumentIds }),
+      selectAllDocuments: () =>
+        set((state) => {
+          const completedIds = state.documents
+            .filter((d) => d.status === 'COMPLETED')
+            .map((d) => d.id);
+          return { selectedDocumentIds: completedIds };
+        }),
+      deselectAllDocuments: () => set({ selectedDocumentIds: [] }),
     }),
-  setActiveJobs: (activeJobs) => set({ activeJobs }),
-}));
+    {
+      name: 'graphrag-selected-documents',
+      partialize: (state) => ({ selectedDocumentIds: state.selectedDocumentIds }),
+    }
+  )
+);
+