Automated sync to Hugging Face

.env.example

@@ -0,0 +1,68 @@
+# Application
+APP_NAME="Graph RAG Service"
+DEBUG=false
+ENVIRONMENT=development
+
+# API Server
+API_HOST=0.0.0.0
+API_PORT=8000
+
+# Security
+# ⚠️  CRITICAL: Change SECRET_KEY before ANY deployment.
+# Generate one with: python -c "import secrets; print(secrets.token_hex(32))"
+SECRET_KEY=change-this-in-production-to-a-secure-random-key
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+
+# CORS: comma-separated list of allowed origins.
+# Default allows only the local Vite dev server.
+# Example for production: CORS_ORIGINS=https://yourdomain.com
+CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# Neo4j
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=password
+NEO4J_DATABASE=neo4j
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+
+# Celery
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/0
+
+# LLMs
+DEFAULT_LLM_PROVIDER=ollama
+
+# OpenAI
+OPENAI_API_KEY=
+
+# Anthropic
+ANTHROPIC_API_KEY=
+
+# Google Gemini
+GOOGLE_API_KEY=
+
+# LlamaCloud (for LlamaParse)
+LLAMA_CLOUD_API_KEY=
+USE_LLAMA_PARSE=true
+
+# Ollama
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=deepseek-v3.1:671b-cloud
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Embedding
+EMBEDDING_PROVIDER=ollama
+EMBEDDING_DIMENSION=768
+
+# Agent Configuration
+MAX_AGENT_ITERATIONS=5
+AGENT_TIMEOUT_SECONDS=30
+
+# Observability
+ENABLE_TRACING=true
+ENABLE_METRICS=true
+LOG_LEVEL=INFO

.gitattributes

@@ -0,0 +1,3 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.ico filter=lfs diff=lfs merge=lfs -text

.github/prompts/Solution_Architecture.prompt.md

@@ -0,0 +1,169 @@
+# Solution Architecture: Agentic Graph RAG as a Service
+
+This document outlines a detailed technical approach to building the Agentic Graph RAG platform. It focuses on modularity, scalability, and the specific requirements of the Lyzr Hackathon, with a strong emphasis on production-grade robustness.
+
+## 1. High-Level Architecture
+
+The system is designed as a set of modular services centered around a shared Knowledge Graph and Vector Store, fortified with enterprise-grade security and observability layers.
+
+```mermaid
+graph TD
+    User[User / Client] --> Auth[Auth & Access Control]
+    Auth --> API[Unified API Gateway]
+    
+    subgraph "Observability Layer (OpenTelemetry)"
+        Logs[Structured Logging]
+        Traces[Agent Traces]
+        Metrics[Performance Metrics]
+    end
+    
+    API -.-> Logs & Traces & Metrics
+
+    subgraph "Ingestion Pipeline (Async Workers)"
+        API --> Queue[Task Queue (Redis/Celery)]
+        Queue --> Ingest[Ingestion Worker]
+        Ingest --> Chunking[Text Chunking]
+        Chunking --> OntologyGen[LLM Ontology Gen (Versioned)]
+        OntologyGen --> Extract[Entity & Relation Extraction]
+        Extract --> Resolution[Entity Resolution / Dedup]
+        Resolution --> GraphDB[(Neo4j / Neptune)]
+        Resolution --> VectorDB[(Vector Store)]
+    end
+    
+    subgraph "Retrieval Context"
+        API --> Agent[Agent Orchestrator]
+        Agent --> Decomp[Query Decomposer]
+        Decomp --> Router[Query Router / Planner]
+        
+        Router --> |Semantic Query| VectorSearch[Vector Search]
+        Router --> |Deep Relation| GraphSearch[Graph Traversal / Cypher]
+        Router --> |Structured| FilterSearch[Metadata Filter]
+        
+        VectorSearch & GraphSearch & FilterSearch --> Validator[Hallucination Guard / Schema Validator]
+        Validator --> Synthesizer[Response Synthesizer]
+        Synthesizer --> Agent
+    end
+```
+
+## 2. Technology Stack Selection
+
+*   **Language:** Python 3.12 (Standard for AI/ML engineering).
+*   **API Framework:** FastAPI (Async support, auto-documentation).
+*   **Orchestration:** LlamaIndex (Preferred for Graph RAG).
+*   **LLM:** multi-LLM support like ollama, open ai, gemini,claude (use lang-graph) (Reasoning & Extraction) & `BAAI bge-m3` this model is available on ollama so we will use from ollama (Embeddings).
+*   **Graph Database:** Neo4j (Primary) .
+*   **Vector Store:** Neo4j Vector Index (for unified storage) or Qdrant/Chroma.
+*   **Task Queue:** Celery with Redis (for async ingestion).
+*   **Monitoring:** OpenTelemetry + Prometheus/Grafana.
+*   **Frontend:**  React vite + tailwind css (for Visual Ontology Editor).
+
+## 3. Production-Grade Components
+
+### A. Document-to-Graph Pipeline (Ingestion)
+
+This pipeline converts unstructured text into a structured Knowledge Graph, robust to schema changes and duplicates.
+
+1.  **Ontology Generation & Evolution:**
+    *   *Initial:* Ask LLM to identify high-level concepts (nodes) and interactions (edges) from first $N$ chunks.
+    *   *Visual Editor:* Human approval step to refine the JSON schema.
+    *   **Drift Handling:** Incorporate an "Ontology Versioning" system. Every node/edge is tagged with `ontology_version: v1.0`. New documents causing schema changes trigger a "Migration Proposal" for approval.
+
+2.  **Extraction & Embedding:**
+    *   **Prompt Engineering:** "Given text + Ontology v1.0, extract entities/relationships."
+    *   **Hybrid Nodes:** Create `(:Chunk)` nodes linked to `(:Entity)` nodes (`(:Chunk)-[:MENTIONS]->(:Entity)`). This preserves ground truth source text alongside abstract graph relationships.
+
+3.  **Advanced Entity Resolution:**
+    *   *Naive:* Exact string match.
+    *   *Production:* Multi-stage blocking and merging.
+        1.  **Blocking:** Group entities by Label and similar name (e.g., phonetic match).
+        2.  **Semantic Check:** Compare embeddings of candidates.
+        3.  **Threshold:** If similarity > 0.95 -> Auto-merge. If 0.85-0.95 -> Flag for "Human Review Queue".
+
+### B. The Agentic Retrieval System (The Brain)
+
+A state machine loop designed for accuracy and fail-safe operation.
+
+**1. Query Decomposition & Routing**
+Instead of a single step, the Agent breaks down complexity:
+*   *User Query:* "How is the CEO of Lyzr related to OpenAI?"
+*   *Decomposition:*
+    1.  "Identify Lyzr CEO" (Vector/Graph lookup) -> *Result: user_X*
+    2.  "Find path between user_X and OpenAI" (Graph traversal).
+*   *Router:* Dynamically selects tools for each sub-step.
+
+**2. Tool Implementation with Guardrails:**
+*   **Vector Tool:** Top-k retrieval using embedding similarity.
+*   **Graph Tool (Text-to-Cypher):** Uses LLM to generate Cypher.
+    *   **Hallucination Guard:** The tool injects the *strict* allowed schema into the prompt. Generated Cypher is parsed and validated against a "Relationship Whitelist" before execution to prevent schema injection or invalid edge types.
+*   **Filter Tool:** Converts natural language to structured DB filters (WHERE clauses).
+
+**3. Latency & Performance Strategy:**
+*   **Timeouts:** Hard limit on agent reasoning steps (e.g., max 5 loops).
+*   **Fallback:** If Graph tool fails or times out, degrade gracefully to pure Vector Search for a "best effort" answer.
+
+### C. Parity & Extensibility Layer
+
+We define abstract base class interfaces to ensure no vendor lock-in.
+
+```python
+class GraphStore(ABC):
+    @abstractmethod
+    def execute_query(self, query: str, params: dict): pass
+
+class VectorStore(ABC):
+    @abstractmethod
+    def search(self, query_vector: List[float], k: int): pass
+
+class LLMProvider(ABC):
+    @abstractmethod
+    def complete(self, prompt: str): pass
+
+# Implementations: Neo4jStore, NeptuneStore, QdrantStore, OpenAIProvider, etc.
+```
+
+## 4. Scalability, Security & Observability
+
+To meet "Production-Grade" criteria, these non-functional requirements are critical:
+
+1.  **Access Control (RBAC):**
+    *   Pre-retrieval enforcement.
+    *   All queries filter by `user.tenant_id` or `user.permissions` to ensure users only retrieve data they are authorized to see.
+    
+2.  **Observability:**
+    *   **Tracing:** Log every step of the Agent's reasoning chain (Input -> Decomp -> Tool Call -> Result). This is vital for debugging "why did the bot say that?".
+    *   **Metrics:** Track Token Usage, Latency p95, and Cache Hit Rates.
+
+3.  **Async Ingestion:**
+    *   Ingestion is decoupled from the user request loop.
+    *   File Upload API -> Pushes ID to Redis Queue -> Background Worker picks up -> Runs Extraction -> Updates Graph.
+
+4.  **Caching Strategy:**
+    *   **Semantic Cache (Redis):** Before hitting the LLM, check if a semantically similar query has been answered recently. reduces cost and latency.
+    *   **Embedding Cache:** Store computed embeddings to avoid re-calculation for identical text chunks.
+
+## 5. Implementation Plan
+
+### Phase 1: Foundation (Hours 1-4)
+1.  Set up Repository, Python envf (Neo4j/Redis).
+2.  Implement `GraphStore` & `VectorStore` abstractions.
+3.  Create Basic Auth & Middleware logging.
+
+### Phase 2: Ingestion Engine (Hours 5-12)
+1.  Implement PDF extractor & Async Worker skeleton.
+2.  Build "Ontology Proposer" & "Graph Extractor" prompts.
+3.  Implement Entity Resolution logic.
+
+### Phase 3: The Retrieval Agent (Hours 13-20)
+1.  Set up Agent loop with Query Decomposition.
+2.  Implement `Text2Cypher` with schema validation.
+3.  Implement Latency Timeouts & Fallbacks.
+
+### Phase 4: Refinement & UI (Hours 21-24)
+1.  Build Visual Editor (Streamlit).
+2.  Add simple Evaluation Script (run known queries, check answers).
+3.  Write `README.md` highlighting the "Production Thinking" (RBAC, Async, Observability).
+
+## 6. Key Innovations
+1.  **Hybrid Chunk Nodes:** Storing source text explicitly in the graph for ground-truth verification.
+2.  **Self-Correcting Cypher:** If Cypher execution fails, feed the error back to the LLM to fix syntax automatically.
+3.  **Adaptive Retrieval:** The agent assigns a "confidence score" to each retrieval method. If Vector Search confidence is low (<0.7), it automatically triggers Graph Traversal to boost context.

.github/workflows/sync_to_hf.yml

@@ -0,0 +1,33 @@
+name: Sync to Hugging Face
+on:
+  push:
+    branches: [master]
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Push to hub
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          # 1. Turn on Large File Storage (LFS)
+          git lfs install
+          
+          # 2. Tell Hugging Face to properly handle images
+          echo "*.png filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
+          echo "*.jpg filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
+          echo "*.ico filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
+          
+          # 3. Wipe the hidden git history in the runner to clear past image errors
+          rm -rf .git
+          git config --global user.email "action@github.com"
+          git config --global user.name "GitHub Action"
+          
+          # 4. Create a fresh, clean package and force push it
+          git init
+          git checkout -b main
+          git add .
+          git commit -m "Automated sync to Hugging Face"
+          git push --force https://anky2002:$HF_TOKEN@huggingface.co/spaces/anky2002/graph-rag main 

.gitignore

@@ -0,0 +1,91 @@
+# ── Python ───────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[oc]
+*.pyo
+*.pyd
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+*.egg
+
+# ── Virtual environments ──────────────────────────────────────────────────────
+.venv/
+venv/
+ENV/
+env/
+
+# ── Environment / Secrets (NEVER commit real keys) ────────────────────────────
+.env
+.env.local
+.env.*.local
+*.secret
+
+# ── Node.js / NPM ─────────────────────────────────────────────────────────────
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.npm/
+
+# ── Uploaded user data ────────────────────────────────────────────────────────
+data/uploads/*
+!data/uploads/.gitkeep
+
+# ── One-off debug / experiment test files ─────────────────────────────────────
+test_combinations.py
+test_document_embedding.py
+test_embedding.py
+test_exact_combination.py
+test_narrow_down.py
+test_nomic.py
+test_resume_text.py
+
+# ── IDE / OS ──────────────────────────────────────────────────────────────────
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ── Logs & temp ───────────────────────────────────────────────────────────────
+*.log
+*.tmp
+*.temp
+htmlcov/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# ── Docs that are project-internal notes (not needed in repo) ─────────────────
+BGE_M3_ISSUE_ANALYSIS.md
+CONFIGURATION_CHANGES.md
+PROJECT_COMPLETION_CHECKLIST.md
+LLAMAPARSE_SETUP.md
+
+# ── Lyzr Hackathon source material (not part of the submitted codebase) ────────
+Lyzr_Hackathon_Problem_Statement.md
+
+# ── UV lock / python version pins (repo-specific, not portable) ─────────────────
+# uv.lock          # keep: ensures reproducible installs for reviewers
+.python-version
+
+# ── pyvis / notebook temp files ──────────────────────────────────────────────
+*.html
+!frontend-react/index.html
+!frontend-react/*.html
+!frontend/*.html
+
+# ── Celery / task artefacts ───────────────────────────────────────────────────
+celerybeat-schedule
+celerybeat.pid
+
+# ── Neo4j local data (if ever mounted) ───────────────────────────────────────
+neo4j_data/
+
+# ── Windows shortcuts / artifacts ────────────────────────────────────────────
+*.lnk

ARCHITECTURE.md

@@ -0,0 +1,297 @@
+# Graph RAG Service - Project Documentation
+
+## System Architecture
+
+### Overview
+The Graph RAG Service is built as a modular, production-grade platform with the following key components:
+
+1. **API Gateway (FastAPI)**: Handles all HTTP requests, authentication, and routing
+2. **Ingestion Pipeline**: Processes documents and constructs knowledge graphs
+3. **Retrieval Agent (LangGraph)**: Intelligent query routing and response synthesis
+4. **Storage Layer**: Neo4j for graph + vector storage
+5. **Task Queue**: Celery + Redis for async processing
+6. **Observability**: OpenTelemetry for tracing and metrics
+
+### Design Principles
+
+#### 1. No Vendor Lock-in
+All core components are abstracted behind interfaces:
+- `GraphStore`: Can swap Neo4j for AWS Neptune
+- `VectorStore`: Supports multiple vector databases
+- `LLMProvider`: Works with any LLM (OpenAI, Anthropic, Gemini, Ollama)
+
+#### 2. Production-Ready
+- **Async Processing**: Non-blocking I/O for all database operations
+- **Background Jobs**: Celery workers handle heavy ingestion tasks
+- **Authentication**: JWT-based with RBAC support
+- **Error Handling**: Graceful degradation and fallback mechanisms
+- **Observability**: Full tracing and metrics collection
+
+#### 3. Intelligent Retrieval
+The agentic system:
+- Decomposes complex queries into sub-queries
+- Dynamically selects retrieval methods (vector vs graph vs cypher)
+- Validates outputs against schema (hallucination guard)
+- Provides reasoning chains for transparency
+
+## Components Deep Dive
+
+### Core Abstractions (`src/graph_rag_service/core/`)
+
+#### GraphStore Interface
+```python
+class GraphStore(ABC):
+    @abstractmethod
+    async def create_node(entity: Entity) -> str
+    @abstractmethod
+    async def create_relationship(relationship: Relationship) -> str
+    @abstractmethod
+    async def execute_query(query: str, params: dict) -> List[dict]
+    @abstractmethod
+    async def find_path(source: str, target: str, max_depth: int) -> List[dict]
+```
+
+Implementation: `Neo4jStore` provides unified graph + vector storage using Neo4j 5.x vector capabilities.
+
+#### LLMProvider Interface
+```python
+class LLMProvider(ABC):
+    @abstractmethod
+    async def complete(prompt: str, **kwargs) -> str
+    @abstractmethod
+    async def embed(text: str) -> List[float]
+```
+
+Implementation: `UnifiedLLMProvider` wraps OpenAI, Anthropic, Gemini, and Ollama with a consistent interface.
+
+#### Entity Resolution
+Multi-stage resolution:
+1. **Blocking**: Group by entity type and name similarity (fast reject)
+2. **Semantic Check**: Compare embeddings for deep similarity
+3. **Threshold Matching**: Configurable thresholds (0.85 default)
+4. **Auto-merge**: High confidence merges (>0.95)
+5. **Human Review Queue**: Medium confidence flagged for review (0.85-0.95)
+
+### Ingestion Pipeline (`src/graph_rag_service/ingestion/`)
+
+#### Flow
+1. **Document Processing**: Extract text from PDF/TXT/MD/DOCX
+2. **Chunking**: Split into overlapping chunks (1024 tokens, 200 overlap)
+3. **Ontology Generation**: LLM analyzes samples to propose entity/relationship types
+4. **Entity Extraction**: Extract entities and relationships per chunk
+5. **Entity Resolution**: Deduplicate and merge entities
+6. **Embedding Generation**: Create vector embeddings (BGE-M3)
+7. **Graph Construction**: Store in Neo4j with hybrid nodes
+
+#### Hybrid Nodes
+Each chunk is stored as both:
+- A `(:Chunk)` node with text and embedding
+- Connected to `(:Entity)` nodes via `[:MENTIONS]` relationships
+
+This preserves source text for grounding while enabling abstract graph queries.
+
+### Retrieval System (`src/graph_rag_service/retrieval/`)
+
+#### Tools
+1. **VectorSearchTool**: Semantic similarity using embeddings
+2. **GraphTraversalTool**: Relationship exploration and path finding
+3. **CypherGenerationTool**: Text-to-Cypher with validation
+4. **MetadataFilterTool**: Structured queries on attributes
+
+#### Agent Workflow (LangGraph)
+```
+[Query] → [Decompose] → [Route] → [Vector/Graph/Cypher] → [Synthesize] → [Response]
+                           ↑                                      ↓
+                           └─────────────────────────────────────┘
+                                    (Iterative refinement)
+```
+
+#### Hallucination Guards
+- **Schema Injection**: Prompt includes allowed entity/relationship types
+- **Cypher Validation**: Parse and validate against whitelist
+- **Self-Correction**: Feed errors back to LLM to fix syntax
+- **Fallback**: If graph fails, degrade to vector search
+
+### API Layer (`src/graph_rag_service/api/`)
+
+#### Endpoints
+- `POST /api/auth/login`: Get JWT token
+- `POST /api/documents/upload`: Upload document (returns task ID)
+- `GET /api/documents/status/{task_id}`: Check ingestion progress
+- `POST /api/query`: Execute agentic query
+- `GET /api/ontology`: Get current ontology schema
+- `PUT /api/ontology`: Update ontology (admin only)
+- `GET /api/graph/visualization`: Get graph data for visualization
+- `GET /api/system/health`: System health check
+- `GET /api/system/stats`: System statistics
+
+#### Authentication
+- JWT tokens with configurable expiration (default: 30 min)
+- RBAC with scopes: `read`, `write`, `admin`
+- Dependency injection for protected endpoints
+
+### Workers (`src/graph_rag_service/workers/`)
+
+#### Celery Tasks
+- `ingest_document`: Process single document
+- `ingest_documents_batch`: Process multiple documents
+- `health_check`: Worker health verification
+
+#### Configuration
+- Broker: Redis
+- Result Backend: Redis
+- Serializer: JSON
+- Task timeout: 1 hour (configurable)
+
+### Observability (`src/graph_rag_service/observability/`)
+
+#### OpenTelemetry Integration
+- **Traces**: Agent reasoning steps, tool calls, database queries
+- **Metrics**: 
+  - `documents_ingested`: Counter
+  - `queries_executed`: Counter
+  - `query_duration_seconds`: Histogram
+  - `entities_extracted`: Counter
+
+#### Structured Logging
+- Log level: INFO (configurable)
+- Format: `%(asctime)s - %(name)s - %(levelname)s - %(message)s`
+- All async operations logged with context
+
+## Configuration
+
+### Environment Variables
+Key settings in `.env`:
+- **Neo4j**: `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`
+- **Redis**: `REDIS_HOST`, `REDIS_PORT`
+- **LLM Provider**: `DEFAULT_LLM_PROVIDER` (openai/anthropic/gemini/ollama)
+- **API Keys**: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`
+- **Ollama**: `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, `OLLAMA_EMBEDDING_MODEL`
+- **Security**: `SECRET_KEY`, `ACCESS_TOKEN_EXPIRE_MINUTES`
+
+### Tuning Parameters
+- `CHUNK_SIZE`: 1024 (text chunk size)
+- `CHUNK_OVERLAP`: 200 (overlap between chunks)
+- `MAX_AGENT_ITERATIONS`: 5 (max reasoning steps)
+- `AGENT_TIMEOUT_SECONDS`: 30 (query timeout)
+- `ENTITY_RESOLUTION_THRESHOLD`: 0.85 (similarity threshold)
+- `DEFAULT_TOP_K`: 5 (retrieval results)
+- `GRAPH_MAX_DEPTH`: 3 (graph traversal depth)
+
+## Deployment
+
+### Local Development
+```bash
+# 1. Ensure Neo4j and Redis are running
+# 2. Configure .env with connection details
+
+# 3. Start API server
+./start-server.sh  # or start-server.bat on Windows
+
+# 4. Start workers
+./start-worker.sh  # or start-worker.bat on Windows
+```
+
+### Production Considerations
+1. **Database**: Use managed Neo4j (Aura) or self-hosted cluster
+2. **Redis**: Use managed Redis (AWS ElastiCache, Redis Cloud)
+3. **Worker Scaling**: Add more Celery workers based on ingestion load
+4. **API Scaling**: Run multiple API instances behind load balancer
+5. **Monitoring**: Integrate with Prometheus/Grafana for metrics
+6. **Secrets**: Use secret management (AWS Secrets Manager, HashiCorp Vault)
+
+## Extensibility
+
+### Adding New LLM Provider
+1. Implement `LLMProvider` interface
+2. Add to `LLMFactory.create()` method
+3. Update config with new provider settings
+
+### Adding New Graph Database
+1. Implement `GraphStore` interface
+2. Update `IngestionPipeline` to use new store
+3. Test with existing workflows
+
+### Custom Retrieval Tools
+1. Create new tool class with `run()` method
+2. Add to `AgentRetrievalSystem.tools`
+3. Update routing logic in `_route_query()`
+
+## Testing Strategy
+
+### Unit Tests
+- Test each component independently
+- Mock external dependencies (Neo4j, Redis, LLMs)
+- Focus on business logic
+
+### Integration Tests
+- Test component interactions
+- Use test database instances
+- Verify end-to-end flows
+
+### Performance Tests
+- Benchmark ingestion throughput
+- Measure query latencies
+- Stress test with concurrent requests
+
+## Future Enhancements
+
+### Phase 1 (Current MVP)
+- ✅ Core ingestion pipeline
+- ✅ Agentic retrieval system
+- ✅ Multi-LLM support
+- ✅ Entity resolution
+- ✅ Async workers
+
+### Phase 2 (Next Steps)
+- [ ] React frontend with visual ontology editor
+- [ ] Graph visualization (D3.js/Cytoscape)
+- [ ] Advanced ontology evolution with migrations
+- [ ] Semantic cache with Redis
+- [ ] Batch ingestion optimization
+
+### Phase 3 (Advanced Features)
+- [ ] Multi-tenant support with data isolation
+- [ ] Fine-tuned entity extraction models
+- [ ] Graph neural network embeddings
+- [ ] Automated ontology quality metrics
+- [ ] Export/import ontology schemas
+
+## Troubleshooting
+
+### Common Issues
+
+#### Neo4j Connection Failed
+- Verify Neo4j is running and accessible
+- Verify credentials in `.env`
+- Try connecting with cypher-shell: `cypher-shell -u neo4j -p password`
+
+#### Celery Worker Not Processing
+- Check Redis is running: `redis-cli ping`
+- Verify broker URL in `.env`
+- Check worker logs
+
+#### Ollama Models Not Found
+- Pull models: `ollama pull llama3.2 && ollama pull bge-m3`
+- Verify Ollama is running: `curl http://localhost:11434/api/tags`
+
+#### Query Returns No Results
+- Verify documents are ingested: `GET /api/system/stats`
+- Check ontology exists: `GET /api/ontology`
+- Try simpler queries first
+
+## Support
+
+For issues or questions:
+1. Check documentation and troubleshooting guide
+2. Search existing GitHub issues
+3. Open new issue with:
+   - Clear description
+   - Steps to reproduce
+   - Environment details
+   - Relevant logs
+
+---
+
+**Last Updated**: February 2026
+**Version**: 0.1.0

QUICKSTART.md

@@ -0,0 +1,265 @@
+# Quick Start Guide
+
+Get the Graph RAG Service up and running in 10 minutes!
+
+## Prerequisites
+
+Before starting, make sure you have:
+- Python 3.12 or higher
+- Neo4j database (running locally or remotely)
+- Redis server (running locally or remotely)
+- UV package manager (will be installed if missing)
+
+## Step 1: Clone and Setup
+
+```bash
+cd graph-RAG
+
+# Install UV if you don't have it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies
+uv sync
+```
+
+## Step 2: Configure Environment
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit .env with your settings
+# Configure NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD
+# Configure REDIS_URL
+```
+
+## Step 3: Ensure Backend Services Are Running
+
+Make sure Neo4j and Redis are running and accessible:
+- Neo4j should be available at the URI specified in your .env file (default: bolt://localhost:7687)
+- Redis should be available at the URL specified in your .env file (default: redis://localhost:6379)
+
+## Step 4: Start the API Server
+
+### On Windows:
+```bash
+start-server.bat
+```
+
+### On Mac/Linux:
+```bash
+chmod +x start-server.sh
+./start-server.sh
+```
+
+### Or directly (any OS):
+```bash
+uv run python main.py
+```
+
+The API server will start on `http://localhost:8000`
+
+## Step 5: Start Celery Worker
+
+For asynchronous document ingestion, start a worker in a **new terminal**:
+
+### On Windows:
+```bash
+start-worker.bat
+```
+
+### On Mac/Linux:
+```bash
+chmod +x start-worker.sh
+./start-worker.sh
+```
+
+### Or directly:
+```bash
+uv run celery -A src.graph_rag_service.workers.celery_worker worker --loglevel=info
+```
+
+## Step 6: Start the React Frontend
+
+In a **new terminal**:
+
+```bash
+cd frontend-react
+
+# Install Node dependencies (first time only)
+npm install
+
+# Start the dev server
+npm run dev
+```
+
+The React UI will open at `http://localhost:5173`
+
+> **Note:** The project uses a **React/Vite** frontend (`frontend-react/`).  
+> There is no `streamlit run app.py` — any references to Streamlit in older docs are outdated.
+
+Login with: **username** `admin` / **password** `admin`
+
+## Step 7: Test the API
+
+### Using cURL
+
+1. **Get Access Token**
+```bash
+curl -X POST "http://localhost:8000/api/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{"username": "demo", "password": "demo"}'
+```
+
+Save the `access_token` from the response.
+
+2. **Upload a Document**
+```bash
+curl -X POST "http://localhost:8000/api/documents/upload" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -F "file=@sample.pdf"
+```
+
+3. **Query the Knowledge Base**
+```bash
+curl -X POST "http://localhost:8000/api/query" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "What is this document about?",
+    "top_k": 5
+  }'
+```
+
+### Using the Interactive Docs
+
+Open your browser and go to:
+- Swagger UI: `http://localhost:8000/docs`
+- ReDoc: `http://localhost:8000/redoc`
+
+Click "Authorize" and enter your access token to test endpoints interactively.
+
+## Step 8: Setup Ollama (Optional)
+
+If you want to use local LLMs instead of OpenAI/Anthropic:
+
+```bash
+# Install Ollama (https://ollama.ai)
+# Then pull models:
+ollama pull llama3.2
+ollama pull bge-m3
+```
+
+Update `.env`:
+```
+DEFAULT_LLM_PROVIDER=ollama
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=llama3.2
+OLLAMA_EMBEDDING_MODEL=bge-m3
+```
+
+## Common Commands
+
+### Check System Health
+```bash
+curl http://localhost:8000/api/system/health
+```
+
+### Get System Stats
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://localhost:8000/api/system/stats
+```
+
+### View Ontology
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://localhost:8000/api/ontology
+```
+
+### Visualize Graph
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "http://localhost:8000/api/graph/visualization?limit=50"
+```
+
+## Troubleshooting
+
+### Neo4j Connection Error
+```bash
+# Verify credentials in .env
+# Check Neo4j is accessible
+
+# Access Neo4j browser
+open http://localhost:7474
+
+# Try connecting with cypher-shell
+cypher-shell -u neo4j -p password
+```
+
+### Redis Connection Error
+```bash
+# Check Redis is running
+redis-cli ping
+
+# Test Redis connection
+redis-cli -h localhost -p 6379 ping
+```
+
+### Worker Not Processing
+```bash
+# Check worker logs
+# If running locally:
+celery -A src.graph_rag_service.workers.celery_worker inspect active
+```
+
+### API Server Won't Start
+```bash
+# Check for port conflicts
+lsof -i :8000  # On Mac/Linux
+netstat -ano | findstr :8000  # On Windows
+
+# View detailed logs
+uv run python main.py
+```
+
+## Next Steps
+
+- Read the [README.md](README.md) for comprehensive documentation
+- Check [ARCHITECTURE.md](ARCHITECTURE.md) for system design details
+- Explore the API docs at `http://localhost:8000/docs`
+
+## Using with Different LLM Providers
+
+### OpenAI
+```bash
+# In .env:
+DEFAULT_LLM_PROVIDER=openai
+OPENAI_API_KEY=sk-your-key-here
+```
+
+### Anthropic
+```bash
+# In .env:
+DEFAULT_LLM_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+```
+
+### Google Gemini
+```bash
+# In .env:
+DEFAULT_LLM_PROVIDER=gemini
+GOOGLE_API_KEY=your-key-here
+```
+
+Services will be available at:
+- API: `http://localhost:8000`
+- Neo4j Browser: `http://localhost:7474`
+
+## Need Help?
+
+- Check the troubleshooting section above
+- Read the full [README.md](README.md)
+- Open an issue on GitHub
+
+Happy building! 🚀

README.md

@@ -0,0 +1,456 @@
+# CORTEX — Agentic Graph RAG Platform
+
+> **CORTEX** is a production-grade, agentic Knowledge Graph platform that transforms unstructured documents and web content into an intelligent, queryable knowledge graph — with a full-featured React UI, streaming AI chat, real-time graph visualization, simulation personas, and deep ontology governance.
+
+---
+
+## ✨ What's Been Built
+
+### 🖥️ Full-Stack Application
+
+| Layer | Stack |
+|---|---|
+| **Backend API** | FastAPI (async) + Python 3.12 |
+| **Task Queue** | Celery + Redis |
+| **Graph + Vector DB** | Neo4j 5.x (unified) |
+| **LLM Layer** | OpenAI, Anthropic, Google Gemini, Ollama |
+| **Frontend** | React 18 + TypeScript + Vite |
+| **Unified Start** | `npm run rag` (concurrently launches all 3 processes) |
+
+---
+
+## 🚀 Features
+
+### 📥 Document Ingestion Pipeline
+
+- **Multi-format ingestion**: PDF, TXT, MD, DOCX, CSV, XLSX, PPTX, JSON
+- **Web scraping**: Single-page scrape via `POST /api/documents/scrape`
+- **Deep web crawling**: Multi-depth Playwright-powered crawler (`POST /api/documents/crawl`) via Crawl4AI
+- **Async Celery workers**: Upload returns instantly with a `task_id`; background workers build the graph
+- **Re-ingest**: Admin can trigger re-processing of any stored document
+- **Document preview & download**: In-browser preview of text/Markdown; PDF download via API
+
+### 🔭 Ontology Management
+
+- **Auto-generation**: LLM analyzes document chunks to propose entity types & relationship types
+- **LLM-powered refinement**: `POST /api/ontology/refine` — refine schema with optional human feedback
+- **Versioning**: Each schema change bumps the version (`v1.0` → `v1.1`, etc.)
+- **Document-scoped stats**: `/api/ontology/stats?document_id=...` returns entity/relationship breakdowns for a specific document
+- **Visual editor**: Ontology view in UI with editable entity types and relationship types
+- **Ontology Drift Detection**: Automated drift detection compares live graph against new chunk samples; exposes pending/approved/rejected drift reports with admin approve/reject workflow
+
+### 🤖 Agentic Retrieval System
+
+- **LangGraph orchestration**: State-machine ReACT agent with multi-step reasoning and fallback mechanisms
+- **Tool routing**: Dynamically selects from Vector Search, Graph Traversal, Cypher Generation, Metadata Filtering, Community Search, and Temporal Queries
+- **Streaming responses**: Server-Sent Events (SSE) with real-time reasoning steps surfaced in the UI
+- **Multi-turn conversations**: Persistent conversation threads stored in Neo4j, per-user
+- **Document-scoped queries**: Filter retrieval to a specific document via `document_id`
+- **Graph of Thoughts (GoT)**: Optional GoT reasoning mode for complex multi-hop queries
+- **LLM-as-a-Judge (inline)**: Optional per-response quality scoring with hallucination risk, grounded/ungrounded claims, and confidence reasoning displayed in chat
+- **Confidence display**: Confidence score, hallucination risk, and judge reasoning shown directly in the chat bubble
+
+### 📊 RAGAS Evaluation & Quality Dashboard
+
+- **`POST /api/eval/score`**: Run RAGAS-style evaluation on any Q&A pair (faithfulness, relevancy, context precision, hallucination detection)
+- **`GET /api/eval/dashboard`**: Aggregate evaluation history — avg scores, hallucination rate, trend timeline
+- Results persisted in Neo4j for longitudinal quality tracking
+
+### 🗺️ Graph Intelligence
+
+- **D3 force-directed visualization**: Interactive knowledge graph with zoom, pan, node selection, and a details modal
+- **Graph Export**: Export full or document-scoped graph as JSON, Cypher, or GraphML
+- **Community Detection**: Weakly-connected-components (WCC) community assignment with `POST /api/graph/communities/assign`
+- **Community listing**: `GET /api/graph/communities` — top communities by entity count
+- **Temporal Queries**: `GET /api/entities/{entity_name}/at-time` — retrieve entity relationships at a historical point in time
+- **Semantic Entity Deduplication**: Multi-stage entity resolution with configurable similarity thresholds (`POST /api/entities/deduplicate`)
+- **Entity Enrichment**: LLM-synthesized profile summaries for every entity, stored as `e.summary` (`POST /api/entities/enrich`)
+- **Entity Chat (scoped)**: `POST /api/entities/{entity_name}/chat` — multi-turn conversation scoped entirely to a single entity's graph neighborhood
+- **Graph Memory Updater**: Push raw text directly into the live knowledge graph without re-ingesting a document (`POST /api/graph/update`)
+
+### 📝 Analytical Report Agent (ReACT)
+
+- **`POST /api/report`**: ReACT multi-step report agent using InsightForge / PanoramaSearch / QuickSearch tools
+- Decomposes topic into sub-questions → retrieves graph data → synthesizes sections → compiles structured markdown report
+- Exposed in the **Insights** view (copy/download report as Markdown)
+
+### 🎭 Simulation & Persona Engine
+
+- **Persona generation**: Celery task that generates personas from graph entities (`POST /api/v1/simulation/generate_personas`)
+- **Simulation ticks**: Background tick loop (`POST /api/v1/simulation/tick`)
+- **Live persona interview**: `POST /api/v1/simulation/interview` — roleplay chat with any graph entity injecting their Neo4j memory as system context
+- **SimulationRunView**: Dedicated UI view for managing and interacting with simulation personas
+
+### 🛡️ Admin Dashboard
+
+- **System statistics**: Node count, relationship count, LLM provider, environment
+- **User management**: List users, update scopes/roles (RBAC)
+- **Document vault**: View and delete all ingested documents
+- **Graph CRUD**: Search, inspect, and delete graph nodes from the admin panel
+- **Ontology governance**: Review and approve/reject pending ontology proposals
+- **Celery task monitor**: View active and reserved tasks from the admin panel
+- **Self-demotion guard**: Admins cannot demote their own account
+- **Re-ingest button**: Re-queue any stored document from the document vault
+- **User activity metrics**: Per-user conversation count, message count, last active timestamp
+
+### 🔐 Authentication & Security
+
+- **JWT authentication**: Token-based auth with configurable expiry
+- **RBAC scopes**: `read`, `write`, `admin` scopes enforced per endpoint
+- **User registration**: `POST /api/auth/register`
+- **Pydantic validation**: All API inputs validated at the model layer
+- **Cypher injection prevention**: Schema validation and query whitelisting
+- **File upload limits**: File size and MIME type enforcement
+
+### 🌐 Frontend (React/TypeScript)
+
+Seven fully implemented views accessible from the `CORTEX` top navigation bar:
+
+| Route | View | Description |
+|---|---|---|
+| `/` | **Home** | Animated stats dashboard — documents, entities, relationships, graph health |
+| `/process` | **Process** | Upload files or scrape/crawl URLs; view ingestion queue and document list |
+| `/ontology` | **Ontology** | View/edit the live ontology schema; run LLM refinement; inspect entity/relationship stats per doc |
+| `/interact` | **Interact** | Streaming AI chat with reasoning steps, confidence, hallucination risk; conversation history |
+| `/simulate` | **Simulate** | Simulation persona management and live interview interface |
+| `/insights` | **Insights** | Topic-driven analytical report generation with copy/download |
+| `/admin` | **Admin** _(admin-only)_ | Full admin panel for users, docs, tasks, ontology governance |
+
+### 🔭 Observability
+
+- **OpenTelemetry**: Distributed tracing (silenced from console; configured for export)
+- **Health check**: `GET /api/system/health` — Neo4j, Redis, Celery worker status
+- **System stats**: `GET /api/system/stats` — document, entity, relationship, chunk counts
+- **User stats**: `GET /api/system/my-stats` — per-user conversation and message activity
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          React Frontend (CORTEX)                             │
+│    Home │ Process │ Ontology │ Interact │ Simulate │ Insights │ Admin        │
+└─────────────────────────────┬───────────────────────────────────────────────┘
+                              │ HTTP / SSE
+┌─────────────────────────────▼───────────────────────────────────────────────┐
+│                     FastAPI Gateway (port 8000)                              │
+│          JWT Auth · RBAC Scopes · CORS · OpenTelemetry                      │
+└──────┬──────────────────────┬──────────────────────┬────────────────────────┘
+       │                      │                      │
+┌──────▼──────┐   ┌───────────▼──────────┐  ┌───────▼────────────────────┐
+│  Ingestion  │   │  ReACT Agent System  │  │  Report Agent (ReACT)      │
+│  Pipeline   │   │  - Vector Search     │  │  - InsightForge            │
+│  - Parser   │   │  - Graph Traversal   │  │  - PanoramaSearch          │
+│  - Ontology │   │  - Cypher Gen (GoT)  │  │  - QuickSearch             │
+│  - Extractor│   │  - Community Search  │  │  - Markdown output         │
+│  - Web      │   │  - Temporal Queries  │  └────────────────────────────┘
+│    Crawler  │   │  - LLM-as-a-Judge    │
+└──────┬──────┘   └─────────┬────────────┘
+       │                    │
+┌──────▼────────────────────▼──────────────────┐
+│              Neo4j 5.x Database               │
+│  Entities · Chunks · Relationships ·          │
+│  Vector Index · Conversations ·               │
+│  EvalResults · DriftReports · Users           │
+└───────────────────────────────────────────────┘
+       │
+┌──────▼──────────────────────┐
+│  Celery Workers (Redis)     │
+│  - Async document ingestion │
+│  - Persona generation       │
+│  - Simulation ticks         │
+└─────────────────────────────┘
+```
+
+---
+
+## 📦 Project Structure
+
+```
+graph-RAG/
+├── src/graph_rag_service/
+│   ├── api/
+│   │   ├── server.py          # Main FastAPI app + all API routes (1900 lines)
+│   │   ├── auth.py            # JWT auth + RBAC helpers
+│   │   ├── admin.py           # Admin sub-router
+│   │   ├── simulation.py      # Simulation / persona interview router
+│   │   └── models.py          # All Pydantic request/response models
+│   ├── core/
+│   │   ├── abstractions.py    # Abstract base classes (GraphStore, VectorStore, LLMProvider)
+│   │   ├── models.py          # Domain data models
+│   │   ├── neo4j_store.py     # Full Neo4j implementation (graph + vector)
+│   │   ├── llm_factory.py     # Multi-LLM provider factory + UnifiedLLMProvider
+│   │   ├── entity_resolver.py # Semantic entity deduplication
+│   │   └── storage.py         # File storage abstraction
+│   ├── ingestion/
+│   │   ├── pipeline.py        # End-to-end ingestion orchestrator
+│   │   ├── document_processor.py  # Multi-format document parsing
+│   │   ├── ontology_generator.py  # LLM ontology generation + refinement
+│   │   ├── extractor.py       # Entity + relationship extraction
+│   │   ├── web_crawler.py     # Playwright-based deep web crawler (Crawl4AI)
+│   │   └── persona_generator.py   # Simulation persona generation
+│   ├── retrieval/
+│   │   ├── agent.py           # LangGraph ReACT retrieval agent
+│   │   ├── tools.py           # Retrieval tools + RAGEvaluator (RAGAS)
+│   │   └── report_agent.py    # ReACT analytical report agent
+│   ├── services/
+│   │   ├── graph_memory_updater.py   # Push raw text → live graph
+│   │   ├── entity_enricher.py        # LLM entity profile summaries
+│   │   └── ontology_drift_detector.py # Automated schema drift detection
+│   ├── workers/
+│   │   └── celery_worker.py   # Celery app + ingest_document_task
+│   ├── observability/
+│   │   └── tracing.py         # OpenTelemetry setup (console suppressed)
+│   ├── config.py              # Pydantic settings (all env vars)
+│   └── main.py                # Uvicorn entry point
+├── frontend-react/
+│   └── src/
+│       ├── views/
+│       │   ├── Home.tsx            # Animated stats dashboard
+│       │   ├── Process.tsx         # Document upload + URL scrape/crawl
+│       │   ├── Ontology.tsx        # Schema editor + stats
+│       │   ├── InteractionView.tsx # Streaming chat + conversation history
+│       │   ├── SimulationRunView.tsx # Persona simulation UI
+│       │   ├── InsightsView.tsx    # Report generation + copy/download
+│       │   ├── AdminDashboard.tsx  # Full admin panel
+│       │   └── Login.tsx           # Login page
+│       ├── components/
+│       │   └── GraphCanvas.tsx     # D3 force-directed graph + node modal
+│       ├── context/
+│       │   └── AuthContext.tsx     # JWT auth context + hooks
+│       └── App.tsx                 # Router + top-nav (CORTEX branding)
+├── tests/                      # Test suite
+├── data/uploads/               # Uploaded documents (local storage)
+├── .env.example                # All configurable environment variables
+├── pyproject.toml              # Python project + uv dependencies
+├── package.json                # Unified start scripts (npm run rag)
+├── ARCHITECTURE.md             # Detailed architecture design doc
+└── QUICKSTART.md               # 5-minute quick start guide
+```
+
+---
+
+## ⚡ Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- Node.js 18+
+- Neo4j 5.x (running) with **APOC** and **Graph Data Science (GDS)** plugins installed
+- Redis (running)
+- Ollama *(optional, for local LLMs)*
+
+### 1. Clone & Install
+
+```bash
+git clone <repository-url>
+cd graph-RAG
+
+# Installs Python deps (uv), frontend (npm), and Playwright Chromium
+npm install
+```
+
+### 2. Configure Environment
+
+```bash
+cp .env.example .env
+# Fill in NEO4J_URI, NEO4J_PASSWORD, and your LLM API keys
+```
+
+### 3. Start Neo4j
+
+```bash
+docker run -d --name neo4j \
+  -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/password \
+  neo4j:latest
+```
+
+### 4. Start Redis
+
+```bash
+docker run -d --name redis -p 6379:6379 redis:alpine
+```
+
+### 5. Launch Everything
+
+```bash
+npm run rag
+```
+
+This starts three color-coded processes concurrently:
+
+| Process | URL |
+|---|---|
+| **API Server** | `http://localhost:8000` |
+| **API Docs** | `http://localhost:8000/docs` |
+| **React Frontend** | `http://localhost:5173` |
+
+> Default credentials: `admin` / `admin`
+
+---
+
+## 🔑 Environment Variables
+
+Copy `.env.example` to `.env` and configure:
+
+```env
+# Neo4j
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=password
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# LLM Provider (openai | anthropic | gemini | ollama)
+DEFAULT_LLM_PROVIDER=gemini
+GOOGLE_API_KEY=your-key-here
+
+# Optional: OpenAI / Anthropic
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Optional: Ollama (local)
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=deepseek-r1:7b
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Feature flags
+ENABLE_LLM_JUDGE=true
+
+# Security
+SECRET_KEY=change-this-in-production
+ACCESS_TOKEN_EXPIRE_MINUTES=1440
+```
+
+---
+
+## 🌐 API Reference
+
+### Authentication
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/api/auth/register` | Register new user |
+| `POST` | `/api/auth/login` | Login → JWT token |
+| `GET` | `/api/auth/me` | Get current user info |
+
+### Documents
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/api/documents/upload` | Upload file (PDF, DOCX, TXT, MD, CSV, XLSX, PPTX, JSON) |
+| `POST` | `/api/documents/scrape` | Scrape single URL → ingest |
+| `POST` | `/api/documents/crawl` | Deep multi-page Playwright crawl → ingest *(API Only)* |
+| `GET` | `/api/documents` | List all ingested documents |
+| `DELETE` | `/api/documents/{id}` | Delete document + graph chunks |
+| `GET` | `/api/documents/{id}/download` | Download source file |
+| `GET` | `/api/documents/{id}/preview` | Preview text content |
+| `GET` | `/api/documents/status/{task_id}` | Ingestion task status |
+
+### Query & Chat
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/api/query` | Agentic query (streaming or JSON); supports `document_id`, `use_got` |
+| `GET` | `/api/conversations` | List conversation threads |
+| `GET` | `/api/conversations/{id}` | Get conversation + messages |
+| `DELETE` | `/api/conversations/{id}` | Delete conversation |
+
+### Ontology
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/ontology` | Get current ontology |
+| `PUT` | `/api/ontology` | Update ontology (admin) |
+| `POST` | `/api/ontology/refine` | LLM-powered ontology refinement |
+| `GET` | `/api/ontology/stats` | Entity/relationship counts (optional doc filter) |
+| `POST` | `/api/ontology/drift/detect` | Trigger drift detection |
+| `GET` | `/api/ontology/drift` | List drift reports |
+| `POST` | `/api/ontology/drift/{id}/approve` | Approve drift → merge into ontology |
+| `POST` | `/api/ontology/drift/{id}/reject` | Reject drift report |
+
+### Graph
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/graph/visualization` | Graph nodes + edges for D3 rendering |
+| `GET` | `/api/graph/export` | Export graph (json \| cypher \| graphml) |
+| `POST` | `/api/graph/update` | Push raw text → merge into live graph |
+| `POST` | `/api/graph/communities/assign` | Run WCC community detection |
+| `GET` | `/api/graph/communities` | List top communities |
+
+### Entities
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/api/entities/deduplicate` | Semantic entity resolution + merge |
+| `POST` | `/api/entities/enrich` | Generate LLM summaries for all entities |
+| `GET` | `/api/entities/{name}/summary` | Get enriched entity profile |
+| `POST` | `/api/entities/{name}/chat` | Multi-turn entity-scoped chat |
+| `GET` | `/api/entities/{name}/at-time` | Temporal query (ISO 8601 date) |
+
+### Reports & Evaluation
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/api/report` | Generate ReACT analytical report (markdown) |
+| `POST` | `/api/eval/score` | RAGAS evaluation of a Q&A pair |
+| `GET` | `/api/eval/dashboard` | Evaluation history dashboard |
+
+### Simulation
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/api/v1/simulation/interview` | Live persona interview (in-character LLM) |
+| `GET` | `/api/v1/simulation/report` | Sandbox analytical report *(API Only)* |
+| `POST` | `/api/v1/simulation/generate_personas` | Queue persona generation task *(API Only)* |
+| `POST` | `/api/v1/simulation/tick` | Advance simulation tick *(API Only)* |
+
+### System & Admin
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/system/health` | Neo4j + Redis + Celery health |
+| `GET` | `/api/system/stats` | Document, entity, relationship counts |
+| `GET` | `/api/system/my-stats` | Current user's activity stats |
+| `GET` | `/api/system/formats` | Supported ingestion file formats |
+| `GET` | `/api/admin/stats` | Admin-only system stats |
+| `GET` | `/api/admin/users` | List all users |
+| `PUT` | `/api/admin/users/{username}/role` | Update user scopes |
+| `GET` | `/api/admin/tasks` | View Celery tasks |
+| `GET` | `/api/admin/documents` | Admin document vault |
+| `POST` | `/api/admin/documents/{id}/reingest` | Re-queue document for ingestion |
+| `GET` | `/api/admin/graph/nodes` | Search graph nodes |
+| `DELETE` | `/api/admin/graph/nodes/{id}` | Delete a graph node |
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run tests
+uv run pytest
+
+# With coverage
+uv run pytest --cov=src/graph_rag_service
+```
+
+---
+
+## 🚀 Production Deployment
+
+| Process | Command |
+|---|---|
+| **API Server** | `uv run python main.py` |
+| **Celery Worker** | `uv run celery -A src.graph_rag_service.workers.celery_worker worker --loglevel=info --concurrency=4 --pool=threads` |
+| **React Build** | `cd frontend-react && npm run build` |
+
+The built React assets can be served directly by FastAPI (static file mount), or deployed to a CDN separately. Neo4j and Redis can be run via Docker, managed cloud services (AuraDB, Redis Cloud), or self-hosted.
+
+---
+
+## 📄 Additional Documentation
+
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** — Deep dive into the system design, data flow, and component interactions
+- **[QUICKSTART.md](./QUICKSTART.md)** — 5-minute environment setup guide
+- **`/docs`** — Interactive Swagger UI (auto-generated from FastAPI)
+
+---
+
+**Project Status**: Production-grade MVP · Actively developed  
+**License**: Proprietary — all rights reserved

data/uploads/.gitkeep

@@ -0,0 +1 @@
+# This file ensures the data/uploads directory is created in git

fix_datetime.py

@@ -0,0 +1,21 @@
+import os
+
+target_dir = r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service"
+
+for root, dirs, files in os.walk(target_dir):
+    for f in files:
+        if f.endswith(".py"):
+            p = os.path.join(root, f)
+            with open(p, "r", encoding="utf-8") as file:
+                content = file.read()
+            
+            if "datetime.utcnow()" in content:
+                content = content.replace("datetime.utcnow()", "datetime.now(timezone.utc).replace(tzinfo=None)")
+                if "from datetime import datetime" in content and "timezone" not in content:
+                    content = content.replace("from datetime import datetime", "from datetime import datetime, timezone")
+                elif "import datetime" in content and "timezone" not in content:
+                    content = "from datetime import timezone\n" + content
+                
+                with open(p, "w", encoding="utf-8") as file:
+                    file.write(content)
+                print(f"Updated {p}")

fix_default_factory.py

@@ -0,0 +1,12 @@
+import os
+import glob
+
+for f in glob.glob(r'D:\Desktop_March_26\LYZR\graph-RAG\src\**\*.py', recursive=True):
+    with open(f, 'r', encoding='utf-8') as file:
+        content = file.read()
+    
+    if 'default_factory=datetime.utcnow' in content:
+        new_content = content.replace('default_factory=datetime.utcnow', 'default_factory=lambda: datetime.now(timezone.utc).replace(tzinfo=None)')
+        with open(f, 'w', encoding='utf-8') as file:
+            file.write(new_content)
+        print(f"Fixed {f}")

fix_print_statements.py

@@ -0,0 +1,21 @@
+import os
+import glob
+import re
+
+for f in glob.glob(r'D:\Desktop_March_26\LYZR\graph-RAG\src\**\*.py', recursive=True):
+    with open(f, 'r', encoding='utf-8') as file:
+        content = file.read()
+    
+    if 'print(' in content:
+        # Add import logging and logger if not exists
+        if 'import logging' not in content:
+            content = "import logging\nlogger = logging.getLogger(__name__)\n" + content
+        elif 'logger = ' not in content:
+            content = content.replace('import logging\n', 'import logging\nlogger = logging.getLogger(__name__)\n', 1)
+            
+        # Replace print( with logger.info(
+        content = re.sub(r'\bprint\(', 'logger.info(', content)
+        
+        with open(f, 'w', encoding='utf-8') as file:
+            file.write(content)
+        print(f"Fixed {f}")

fix_timezone_imports.py

@@ -0,0 +1,33 @@
+import os
+
+files = [
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\api\auth.py",
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\api\routers\ontology.py",
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\api\routers\system.py",
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\ingestion\document_processor.py",
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\ingestion\ontology_generator.py",
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\retrieval\report_agent.py",
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\services\graph_memory_updater.py",
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\services\ontology_drift_detector.py",
+    r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\workers\simulation_runner.py"
+]
+
+for f in files:
+    with open(f, 'r', encoding='utf-8') as file:
+        content = file.read()
+    
+    # Check if 'from datetime import datetime' exists
+    if "from datetime import datetime\n" in content:
+        content = content.replace("from datetime import datetime\n", "from datetime import datetime, timezone\n")
+    elif "from datetime import datetime," in content:
+        if "timezone" not in content:
+            content = content.replace("from datetime import datetime,", "from datetime import datetime, timezone,")
+    elif "import datetime\n" in content:
+        content = content.replace("import datetime\n", "import datetime\nfrom datetime import timezone\n")
+    else:
+        # Just put it at the top
+        content = "from datetime import timezone\n" + content
+        
+    with open(f, 'w', encoding='utf-8') as file:
+        file.write(content)
+    print(f"Fixed {f}")

frontend-react/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

frontend-react/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

frontend-react/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

frontend-react/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>frontend-react</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend-react/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "frontend-react",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "server": "cd ../ && .\\venv\\Scripts\\python.exe -m uvicorn src.graph_rag_service.api.server:app --reload",
+    "worker": "cd ../ && .\\venv\\Scripts\\celery.exe -A src.graph_rag_service.workers.celery_worker worker --loglevel=info --pool=solo",
+    "backend": "concurrently \"npm run server\" \"npm run worker\""
+  },
+  "dependencies": {
+    "@heroicons/react": "^2.2.0",
+    "@types/d3": "^7.4.3",
+    "d3": "^7.9.0",
+    "lucide-react": "^1.7.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.13.2",
+    "remark-gfm": "^4.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@tailwindcss/vite": "^4.2.4",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "autoprefixer": "^10.5.0",
+    "concurrently": "^9.2.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "openapi-typescript-codegen": "^0.30.0",
+    "postcss": "^8.5.10",
+    "tailwindcss": "^4.2.4",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.57.0",
+    "vite": "^8.0.1"
+  }
+}

frontend-react/public/_redirects

@@ -0,0 +1 @@
+/*    /index.html   200

frontend-react/src/App.css

@@ -0,0 +1 @@
+/* Empty file to override default vite styles */

frontend-react/src/App.tsx

@@ -0,0 +1,179 @@
+import React from 'react';
+import { BrowserRouter, Routes, Route, Navigate, NavLink } from 'react-router-dom';
+import { AuthProvider, useAuth } from './context/AuthContext';
+
+import Login from './views/Login';
+import Home from './views/Home';
+import Process from './views/Process';
+import InteractionView from './views/InteractionView';
+import SimulationRunView from './views/SimulationRunView';
+import Ontology from './views/Ontology';
+import InsightsView from './views/InsightsView';
+import AdminDashboard from './views/AdminDashboard';
+
+const ProtectedRoute = ({ children }: { children: React.ReactNode }) => {
+  const { isAuthenticated } = useAuth();
+  if (!isAuthenticated) return <Navigate to="/login" />;
+  return children;
+};
+
+const Navigation: React.FC = () => {
+  const { logout, user } = useAuth();
+  return (
+    <nav className="top-nav">
+      <div className="nav-brand">CORTEX</div>
+
+      <div className="nav-links">
+        <NavLink to="/" end className={({ isActive }) => isActive ? 'nav-link active' : 'nav-link'}>HOME</NavLink>
+        <NavLink to="/process" className={({ isActive }) => isActive ? 'nav-link active' : 'nav-link'}>PROCESS</NavLink>
+        <NavLink to="/ontology" className={({ isActive }) => isActive ? 'nav-link active' : 'nav-link'}>ONTOLOGY</NavLink>
+        <NavLink to="/interact" className={({ isActive }) => isActive ? 'nav-link active' : 'nav-link'}>INTERACT</NavLink>
+        <NavLink to="/simulate" className={({ isActive }) => isActive ? 'nav-link active' : 'nav-link'}>SIMULATE</NavLink>
+        <NavLink to="/insights" className={({ isActive }) => isActive ? 'nav-link active' : 'nav-link'}>INSIGHTS</NavLink>
+        {user?.scopes?.includes('admin') && (
+          <NavLink to="/admin" className={({ isActive }) => isActive ? 'nav-link active' : 'nav-link'}>ADMIN</NavLink>
+        )}
+      </div>
+
+      <div className="nav-right">
+        <span className="user-badge" title={`Logged in as ${user?.username}`}>
+          {user?.username}
+        </span>
+        <button onClick={logout} className="logout-btn">LOGOUT</button>
+      </div>
+
+      <style>{`
+        .top-nav {
+          position: sticky;
+          top: 0;
+          z-index: 1000;
+          padding: 0 2rem;
+          height: 60px;
+          border-bottom: 2px solid #000;
+          background: #fff;
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: 1rem;
+        }
+
+        .nav-brand {
+          font-family: var(--font-mono);
+          font-weight: 700;
+          letter-spacing: 3px;
+          font-size: 1rem;
+          white-space: nowrap;
+          flex-shrink: 0;
+        }
+
+        .nav-links {
+          display: flex;
+          gap: 0;
+          align-items: stretch;
+          height: 100%;
+        }
+
+        .nav-link {
+          display: flex;
+          align-items: center;
+          padding: 0 1rem;
+          font-family: var(--font-mono);
+          font-size: 0.78rem;
+          font-weight: 600;
+          letter-spacing: 1px;
+          text-decoration: none;
+          color: #000;
+          border-left: 1px solid transparent;
+          border-right: 1px solid transparent;
+          transition: background 0.15s ease, color 0.15s ease;
+          white-space: nowrap;
+        }
+
+        .nav-link:hover {
+          background: #f0f0f0;
+          color: #000;
+        }
+
+        .nav-link.active {
+          background: #000;
+          color: #fff;
+          border-color: #000;
+        }
+
+        .nav-right {
+          display: flex;
+          align-items: center;
+          gap: 0.75rem;
+          flex-shrink: 0;
+        }
+
+        .user-badge {
+          font-family: var(--font-mono);
+          font-size: 0.75rem;
+          font-weight: 700;
+          background: #000;
+          color: #fff;
+          padding: 0.2rem 0.6rem;
+          letter-spacing: 0.5px;
+          max-width: 120px;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+
+        .logout-btn {
+          font-family: var(--font-mono);
+          font-size: 0.75rem;
+          font-weight: 700;
+          background: transparent;
+          color: #000;
+          border: 1.5px solid #000;
+          padding: 0.25rem 0.75rem;
+          cursor: pointer;
+          letter-spacing: 0.5px;
+          transition: all 0.15s ease;
+          white-space: nowrap;
+        }
+        .logout-btn:hover {
+          background: #000;
+          color: #fff;
+        }
+
+        @media (max-width: 768px) {
+          .top-nav { padding: 0 1rem; height: auto; flex-wrap: wrap; padding: 0.5rem 1rem; }
+          .nav-link { padding: 0.4rem 0.6rem; font-size: 0.7rem; }
+          .nav-brand { width: 100%; padding: 0.25rem 0; }
+        }
+      `}</style>
+    </nav>
+  );
+};
+
+const Layout = ({ children }: { children: React.ReactNode }) => (
+  <>
+    <Navigation />
+    {children}
+  </>
+);
+
+function App() {
+  return (
+    <AuthProvider>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/login" element={<Login />} />
+
+          <Route path="/" element={<ProtectedRoute><Layout><Home /></Layout></ProtectedRoute>} />
+          <Route path="/process" element={<ProtectedRoute><Layout><Process /></Layout></ProtectedRoute>} />
+          <Route path="/ontology" element={<ProtectedRoute><Layout><Ontology /></Layout></ProtectedRoute>} />
+          <Route path="/interact" element={<ProtectedRoute><Layout><InteractionView /></Layout></ProtectedRoute>} />
+          <Route path="/simulate" element={<ProtectedRoute><Layout><SimulationRunView /></Layout></ProtectedRoute>} />
+          <Route path="/insights" element={<ProtectedRoute><Layout><InsightsView /></Layout></ProtectedRoute>} />
+          <Route path="/admin" element={<ProtectedRoute><Layout><AdminDashboard /></Layout></ProtectedRoute>} />
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+
+export default App;

frontend-react/src/components/GraphCanvas.tsx

@@ -0,0 +1,570 @@
+import { useEffect, useRef, forwardRef, useImperativeHandle, useState } from 'react';
+import * as d3 from 'd3';
+import { X, Tag, FileText, Database } from 'lucide-react';
+
+// 12-color categorical palette for node types
+const TYPE_COLORS = [
+  '#e63946', '#457b9d', '#2a9d8f', '#e9c46a', '#f4a261',
+  '#6a4c93', '#1982c4', '#8ac926', '#ff595e', '#6a994e',
+  '#bc4749', '#a8dadc'
+];
+
+export interface GraphOptions {
+  colorByType: boolean;
+  showLabels: boolean;
+  showEdgeLabels: boolean;
+  nodeRadius: number;
+  linkDistance: number;
+  chargeStrength: number;
+  showCurvedEdges: boolean;
+  nodeSizeByDegree: boolean;
+  centerGravity: number;       // 0 = no gravity, 0.1 = default
+}
+
+export const DEFAULT_OPTIONS: GraphOptions = {
+  colorByType: true,
+  showLabels: true,
+  showEdgeLabels: false,
+  nodeRadius: 16,
+  linkDistance: 120,
+  chargeStrength: -300,
+  showCurvedEdges: false,
+  nodeSizeByDegree: false,
+  centerGravity: 0.05,
+};
+
+interface GraphCanvasProps {
+  data: { nodes: any[]; edges: any[] };
+  onNodeUpdate?: (nodeId: string, newName: string) => void;
+  options?: GraphOptions;
+  highlightNodeIds?: Set<string>;  // nodes to highlight (from search)
+}
+
+export interface GraphCanvasHandle {
+  exportPNG: () => void;
+  exportSVG: () => void;
+  fitView: () => void;
+  highlightNode: (id: string) => void;
+}
+
+const GraphCanvas = forwardRef<GraphCanvasHandle, GraphCanvasProps>(
+  ({ data, onNodeUpdate, options = DEFAULT_OPTIONS, highlightNodeIds }, ref) => {
+    const [activeNode, setActiveNode] = useState<any>(null);
+    const containerRef = useRef<HTMLDivElement>(null);
+    const svgRef = useRef<SVGSVGElement>(null);
+    const zoomRef = useRef<d3.ZoomBehavior<SVGSVGElement, unknown> | null>(null);
+    const gRef = useRef<d3.Selection<SVGGElement, unknown, null, undefined> | null>(null);
+    const simulationRef = useRef<d3.Simulation<any, any> | null>(null);
+    const typeColorMap = useRef<Map<string, string>>(new Map());
+
+    // ── Imperative API ─────────────────────────────────────────────────────
+    useImperativeHandle(ref, () => ({
+      exportPNG() {
+        if (!svgRef.current) return;
+        const svgEl = svgRef.current;
+        const serializer = new XMLSerializer();
+        const svgStr = serializer.serializeToString(svgEl);
+        const canvas = document.createElement('canvas');
+        canvas.width = svgEl.clientWidth * 2;
+        canvas.height = svgEl.clientHeight * 2;
+        const ctx = canvas.getContext('2d')!;
+        const img = new Image();
+        const blob = new Blob([svgStr], { type: 'image/svg+xml;charset=utf-8' });
+        const url = URL.createObjectURL(blob);
+        img.onload = () => {
+          ctx.fillStyle = '#fff';
+          ctx.fillRect(0, 0, canvas.width, canvas.height);
+          ctx.scale(2, 2);
+          ctx.drawImage(img, 0, 0);
+          URL.revokeObjectURL(url);
+          const a = document.createElement('a');
+          a.download = 'graph.png';
+          a.href = canvas.toDataURL('image/png');
+          a.click();
+        };
+        img.src = url;
+      },
+      exportSVG() {
+        if (!svgRef.current) return;
+        const serializer = new XMLSerializer();
+        const svgStr = serializer.serializeToString(svgRef.current);
+        const blob = new Blob([svgStr], { type: 'image/svg+xml;charset=utf-8' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.download = 'graph.svg';
+        a.href = url;
+        a.click();
+        URL.revokeObjectURL(url);
+      },
+      fitView() {
+        if (!svgRef.current || !zoomRef.current) return;
+        d3.select(svgRef.current).transition().duration(600).call(
+          zoomRef.current.transform, d3.zoomIdentity
+        );
+      },
+      highlightNode(id: string) {
+        if (!svgRef.current || !zoomRef.current) return;
+        const node = simulationRef.current?.nodes().find((n: any) => n.id === id);
+        if (!node || node.x === undefined) return;
+        const svg = d3.select(svgRef.current);
+        const w = svgRef.current.clientWidth;
+        const h = svgRef.current.clientHeight;
+        const t = d3.zoomIdentity.translate(w / 2 - node.x, h / 2 - node.y);
+        svg.transition().duration(700).call(zoomRef.current.transform, t);
+      }
+    }));
+
+    // ── Main D3 render effect ──────────────────────────────────────────────
+    useEffect(() => {
+      if (!data.nodes.length || !containerRef.current || !svgRef.current) return;
+
+      const width = containerRef.current.clientWidth;
+      const height = containerRef.current.clientHeight;
+
+      // Build type→color map (stable)
+      const types = [...new Set(data.nodes.map(n => n.type || 'Unknown'))];
+      types.forEach((t, i) => {
+        if (!typeColorMap.current.has(t)) {
+          typeColorMap.current.set(t, TYPE_COLORS[i % TYPE_COLORS.length]);
+        }
+      });
+
+      const svg = d3.select(svgRef.current);
+      svg.selectAll('*').remove();
+
+      const nodes: any[] = data.nodes.map(d => ({ ...d }));
+      const nodeIds = new Set(nodes.map(n => n.id));
+      const links: any[] = data.edges
+        .filter(d => nodeIds.has(d.source) && nodeIds.has(d.target))
+        .map(d => ({ ...d }));
+
+      // Degree map for node-size-by-degree
+      const degreeMap = new Map<string, number>();
+      nodes.forEach(n => degreeMap.set(n.id, 0));
+      links.forEach(l => {
+        const sid = typeof l.source === 'object' ? l.source.id : l.source;
+        const tid = typeof l.target === 'object' ? l.target.id : l.target;
+        degreeMap.set(sid, (degreeMap.get(sid) || 0) + 1);
+        degreeMap.set(tid, (degreeMap.get(tid) || 0) + 1);
+      });
+      const maxDegree = Math.max(1, ...degreeMap.values());
+
+      const nodeR = (d: any) => {
+        if (!options.nodeSizeByDegree) return options.nodeRadius;
+        const deg = degreeMap.get(d.id) || 0;
+        return Math.max(8, options.nodeRadius * (0.5 + 1.0 * (deg / maxDegree)));
+      };
+
+      // ── Defs: arrowhead markers ──────────────────────────────────────────
+      const defs = svg.append('defs');
+      if (options.colorByType) {
+        types.forEach(t => {
+          const color = typeColorMap.current.get(t) || '#000';
+          defs.append('marker')
+            .attr('id', `arrow-${t.replace(/\s+/g, '_')}`)
+            .attr('viewBox', '-0 -5 10 10').attr('refX', options.nodeRadius + 10)
+            .attr('refY', 0).attr('orient', 'auto')
+            .attr('markerWidth', 6).attr('markerHeight', 6)
+            .append('path').attr('d', 'M 0,-5 L 10,0 L 0,5').attr('fill', color);
+        });
+      } else {
+        defs.append('marker')
+          .attr('id', 'arrow-default')
+          .attr('viewBox', '-0 -5 10 10').attr('refX', options.nodeRadius + 10)
+          .attr('refY', 0).attr('orient', 'auto')
+          .attr('markerWidth', 6).attr('markerHeight', 6)
+          .append('path').attr('d', 'M 0,-5 L 10,0 L 0,5').attr('fill', '#666');
+      }
+
+      // ── Force simulation ──────────────────────────────────────────────────
+      const sim = d3.forceSimulation(nodes)
+        .force('link', d3.forceLink(links).id((d: any) => d.id).distance(options.linkDistance))
+        .force('charge', d3.forceManyBody().strength(options.chargeStrength))
+        .force('center', d3.forceCenter(width / 2, height / 2).strength(options.centerGravity))
+        .force('collide', d3.forceCollide().radius((d: any) => nodeR(d) + 14));
+
+      simulationRef.current = sim;
+
+      const g = svg.append('g').attr('class', 'graph-root');
+      gRef.current = g;
+
+      // ── Tooltip ───────────────────────────────────────────────────────────
+      const tooltip = d3.select(containerRef.current)
+        .selectAll('.graph-tooltip').data([null]).join('div')
+        .attr('class', 'graph-tooltip')
+        .style('position', 'absolute')
+        .style('pointer-events', 'none')
+        .style('background', '#000')
+        .style('color', '#fff')
+        .style('padding', '6px 12px')
+        .style('font-family', '"JetBrains Mono", monospace')
+        .style('font-size', '11px')
+        .style('line-height', '1.5')
+        .style('opacity', 0)
+        .style('border', '1px solid #333')
+        .style('z-index', '999')
+        .style('max-width', '220px')
+        .style('word-break', 'break-word');
+
+      // ── Links ────────────────────────────────────────────────────────────
+      const linkG = g.append('g').attr('class', 'links');
+
+      // Adjacency set for hover highlight
+      const adjacentIds = new Set<string>();
+
+      // Straight lines or curved paths
+      const linkEl = options.showCurvedEdges
+        ? linkG.selectAll('path').data(links).enter().append('path')
+            .attr('fill', 'none')
+            .attr('stroke', (d: any) => {
+              if (!options.colorByType) return '#aaa';
+              const srcNode = nodes.find(n => n.id === (typeof d.source === 'object' ? d.source.id : d.source));
+              return srcNode ? (typeColorMap.current.get(srcNode.type) || '#aaa') : '#aaa';
+            })
+            .attr('stroke-width', 1.5)
+            .attr('stroke-opacity', 0.55)
+            .attr('marker-end', (d: any) => {
+              if (!options.colorByType) return 'url(#arrow-default)';
+              const srcNode = nodes.find(n => n.id === (typeof d.source === 'object' ? d.source.id : d.source));
+              const t = srcNode?.type?.replace(/\s+/g, '_') || 'Unknown';
+              return `url(#arrow-${t})`;
+            })
+        : linkG.selectAll('line').data(links).enter().append('line')
+            .attr('stroke', (d: any) => {
+              if (!options.colorByType) return '#aaa';
+              const srcNode = nodes.find(n => n.id === (typeof d.source === 'object' ? d.source.id : d.source));
+              return srcNode ? (typeColorMap.current.get(srcNode.type) || '#aaa') : '#aaa';
+            })
+            .attr('stroke-width', 1.5)
+            .attr('stroke-opacity', 0.55)
+            .attr('marker-end', (d: any) => {
+              if (!options.colorByType) return 'url(#arrow-default)';
+              const srcNode = nodes.find(n => n.id === (typeof d.source === 'object' ? d.source.id : d.source));
+              const t = srcNode?.type?.replace(/\s+/g, '_') || 'Unknown';
+              return `url(#arrow-${t})`;
+            });
+
+      // ── Nodes ─────────────────────────────────────────────────────────────
+      const node = g.append('g').attr('class', 'nodes')
+        .selectAll<SVGGElement, any>('g').data(nodes).enter().append('g')
+        .call(d3.drag<SVGGElement, any>()
+          .on('start', (event, d) => { if (!event.active) sim.alphaTarget(0.3).restart(); d.fx = d.x; d.fy = d.y; })
+          .on('drag', (event, d) => { d.fx = event.x; d.fy = event.y; })
+          .on('end', (event, d) => { if (!event.active) sim.alphaTarget(0); d.fx = null; d.fy = null; })
+        )
+        .on('mouseover', (_, d: any) => {
+          // Build adjacent set
+          adjacentIds.clear();
+          adjacentIds.add(d.id);
+          links.forEach(l => {
+            const sid = typeof l.source === 'object' ? l.source.id : l.source;
+            const tid = typeof l.target === 'object' ? l.target.id : l.target;
+            if (sid === d.id) adjacentIds.add(tid);
+            if (tid === d.id) adjacentIds.add(sid);
+          });
+          // Dim non-adjacent
+          node.select('circle')
+            .style('opacity', (n: any) => adjacentIds.has(n.id) ? 1 : 0.15)
+            .style('stroke-width', (n: any) => n.id === d.id ? 4 : 2);
+          (linkEl as any)
+            .style('stroke-opacity', (l: any) => {
+              const sid = typeof l.source === 'object' ? l.source.id : l.source;
+              const tid = typeof l.target === 'object' ? l.target.id : l.target;
+              return (sid === d.id || tid === d.id) ? 0.9 : 0.04;
+            });
+          tooltip
+            .style('opacity', 1)
+            .html(`<strong>${d.label}</strong><br/>ID: ${d.id}<br/>Type: ${d.type || '—'}<br/>Degree: ${degreeMap.get(d.id) || 0}`);
+        })
+        .on('mousemove', (event) => {
+          const rect = containerRef.current!.getBoundingClientRect();
+          tooltip
+            .style('left', (event.clientX - rect.left + 14) + 'px')
+            .style('top', (event.clientY - rect.top - 32) + 'px');
+        })
+        .on('mouseout', () => {
+          adjacentIds.clear();
+          node.select('circle')
+            .style('opacity', (n: any) => {
+              if (!highlightNodeIds || highlightNodeIds.size === 0) return 1;
+              return highlightNodeIds.has(n.id) ? 1 : 0.2;
+            })
+            .style('stroke-width', (n: any) => highlightNodeIds?.has(n.id) ? 4 : 2);
+          (linkEl as any).style('stroke-opacity', 0.55);
+          tooltip.style('opacity', 0);
+        })
+        .on('click', (event, d: any) => {
+          setActiveNode(d);
+          // Zoom to node on single click
+          if (!svgRef.current || !zoomRef.current) return;
+          const w = svgRef.current.clientWidth;
+          const h = svgRef.current.clientHeight;
+          const t = d3.zoomIdentity.translate(w / 2 - d.x, h / 2 - d.y).scale(1.4);
+          d3.select(svgRef.current).transition().duration(500).call(zoomRef.current.transform, t);
+          event.stopPropagation();
+        })
+        .on('dblclick', (event, d: any) => {
+          const newName = window.prompt('Update entity name:', d.label);
+          if (newName && newName.trim() && newName.trim() !== d.label) {
+            const updated = newName.trim();
+            d.label = updated;
+            d3.select(event.currentTarget).select('text.node-label').text(
+              updated.length > 18 ? updated.substring(0, 16) + '…' : updated
+            );
+            if (onNodeUpdate) onNodeUpdate(d.id, updated);
+          }
+        });
+
+      // Circle
+      node.append('circle')
+        .attr('r', (d: any) => nodeR(d))
+        .attr('fill', (d: any) => options.colorByType
+          ? (typeColorMap.current.get(d.type) || '#ccc')
+          : '#fff')
+        .attr('stroke', (d: any) => {
+          if (highlightNodeIds && highlightNodeIds.size > 0) {
+            return highlightNodeIds.has(d.id) ? '#ff0' : (options.colorByType
+              ? d3.color(typeColorMap.current.get(d.type) || '#ccc')!.darker(1).toString()
+              : '#000');
+          }
+          return options.colorByType
+            ? d3.color(typeColorMap.current.get(d.type) || '#ccc')!.darker(1).toString()
+            : '#000';
+        })
+        .attr('stroke-width', (d: any) => highlightNodeIds?.has(d.id) ? 4 : 2)
+        .style('opacity', (d: any) => {
+          if (!highlightNodeIds || highlightNodeIds.size === 0) return 1;
+          return highlightNodeIds.has(d.id) ? 1 : 0.2;
+        })
+        .style('filter', 'drop-shadow(1px 2px 3px rgba(0,0,0,0.15))')
+        .style('cursor', 'pointer');
+
+      // Type abbreviation inside circle
+      node.append('text')
+        .attr('class', 'node-type-badge')
+        .text((d: any) => (d.type || '?').substring(0, 2).toUpperCase())
+        .attr('text-anchor', 'middle').attr('dy', '0.35em')
+        .style('font-family', '"JetBrains Mono", monospace')
+        .style('font-size', (d: any) => `${Math.max(8, nodeR(d) - 6)}px`)
+        .style('font-weight', '700')
+        .style('fill', (d: any) => {
+          if (!options.colorByType) return '#000';
+          const c = d3.color(typeColorMap.current.get(d.type) || '#ccc');
+          if (!c) return '#000';
+          const { r, g: gv, b } = c.rgb();
+          return (r * 0.299 + gv * 0.587 + b * 0.114) > 150 ? '#111' : '#fff';
+        })
+        .style('pointer-events', 'none');
+
+      // Node name label below circle
+      if (options.showLabels) {
+        node.append('text')
+          .attr('class', 'node-label')
+          .text((d: any) => d.label && d.label.length > 18 ? d.label.substring(0, 16) + '…' : d.label)
+          .attr('text-anchor', 'middle')
+          .attr('dy', (d: any) => nodeR(d) + 14)
+          .style('font-family', '"JetBrains Mono", monospace')
+          .style('font-size', '10px')
+          .style('font-weight', '600')
+          .style('fill', '#222')
+          .style('pointer-events', 'none');
+      }
+
+      // Edge labels
+      let edgeLabel: d3.Selection<SVGTextElement, any, SVGGElement, unknown> | null = null;
+      if (options.showEdgeLabels) {
+        edgeLabel = g.append('g').attr('class', 'edge-labels')
+          .selectAll('text').data(links).enter().append('text')
+          .text((d: any) => d.type || '')
+          .style('font-family', '"JetBrains Mono", monospace')
+          .style('font-size', '9px')
+          .style('fill', '#777')
+          .style('text-anchor', 'middle')
+          .style('pointer-events', 'none')
+          .attr('dy', -5);
+      }
+
+      // ── Tick ──────────────────────────────────────────────────────────────
+      sim.on('tick', () => {
+        if (options.showCurvedEdges) {
+          (linkEl as d3.Selection<SVGPathElement, any, SVGGElement, unknown>)
+            .attr('d', (d: any) => {
+              const sx = d.source.x, sy = d.source.y;
+              const tx = d.target.x, ty = d.target.y;
+              const dx = tx - sx, dy = ty - sy;
+              const dr = Math.sqrt(dx * dx + dy * dy) * 0.8;
+              return `M${sx},${sy}A${dr},${dr} 0 0,1 ${tx},${ty}`;
+            });
+        } else {
+          (linkEl as d3.Selection<SVGLineElement, any, SVGGElement, unknown>)
+            .attr('x1', (d: any) => d.source.x).attr('y1', (d: any) => d.source.y)
+            .attr('x2', (d: any) => d.target.x).attr('y2', (d: any) => d.target.y);
+        }
+        node.attr('transform', (d: any) => `translate(${d.x},${d.y})`);
+        if (edgeLabel) {
+          edgeLabel
+            .attr('x', (d: any) => (d.source.x + d.target.x) / 2)
+            .attr('y', (d: any) => (d.source.y + d.target.y) / 2);
+        }
+      });
+
+      // ── Zoom / Pan ────────────────────────────────────────────────────────
+      const zoom = d3.zoom<SVGSVGElement, unknown>()
+        .scaleExtent([0.03, 8])
+        .on('zoom', (event) => g.attr('transform', event.transform));
+
+      svg.call(zoom);
+      // Click on SVG background resets highlighting and active node
+      svg.on('click', () => {
+        setActiveNode(null);
+        node.select('circle').style('opacity', 1).style('stroke-width', 2);
+        (linkEl as any).style('stroke-opacity', 0.55);
+      });
+
+      zoomRef.current = zoom;
+
+      return () => { sim.stop(); };
+    }, [data, options, highlightNodeIds]);
+
+    return (
+      <div ref={containerRef} style={{ width: '100%', height: '100%', position: 'relative', overflow: 'hidden' }}>
+        <svg ref={svgRef} width="100%" height="100%" />
+
+        {/* ── Node details modal ────────────────────────────────────────────── */}
+        {activeNode && (
+          <div className="gc-node-modal">
+            <div className="gc-node-modal-header">
+              <div style={{ display: 'flex', alignItems: 'center', gap: '0.4rem' }}>
+                <h3 className="mono-text" style={{ margin: 0, fontSize: '0.85rem' }}>NODE DETAILS</h3>
+                <span className="gc-node-badge" style={{ background: typeColorMap.current.get(activeNode.type) || '#000' }}>
+                  {activeNode.type || 'Unknown'}
+                </span>
+              </div>
+              <button className="gc-node-close" onClick={() => setActiveNode(null)}>
+                <X size={16} />
+              </button>
+            </div>
+
+            <div className="gc-node-modal-body">
+              <div className="gc-node-row">
+                <span className="gc-node-key"><Tag size={12}/> Name:</span>
+                <span className="gc-node-val" style={{ fontWeight: 600 }}>{activeNode.label || '—'}</span>
+              </div>
+              <div className="gc-node-row">
+                <span className="gc-node-key"><Database size={12}/> UUID:</span>
+                <span className="gc-node-val" style={{ wordBreak: 'break-all', fontSize: '0.7em' }}>{activeNode.id}</span>
+              </div>
+
+              {activeNode.properties && Object.keys(activeNode.properties).length > 0 && (
+                <>
+                  <div className="gc-node-divider" />
+                  <div className="gc-node-section-title">PROPERTIES</div>
+                  <div className="gc-node-props">
+                    {Object.entries(activeNode.properties).map(([k, v]) => (
+                      <div className="gc-node-prop-item" key={k}>
+                        <span className="gc-node-prop-k">{k}:</span>
+                        <span className="gc-node-prop-v">{String(v)}</span>
+                      </div>
+                    ))}
+                  </div>
+                </>
+              )}
+
+              {activeNode.description && (
+                <>
+                  <div className="gc-node-divider" />
+                  <div className="gc-node-section-title"><FileText size={12}/> DESCRIPTION / SUMMARY</div>
+                  <div className="gc-node-summary">
+                    {activeNode.description}
+                  </div>
+                </>
+              )}
+            </div>
+          </div>
+        )}
+
+        <style>{`
+          .gc-node-modal {
+            position: absolute;
+            top: 20px;
+            right: 20px;
+            width: 320px;
+            max-height: calc(100% - 40px);
+            background: #fff;
+            border: 3px solid #000;
+            box-shadow: 6px 6px 0 rgba(0,0,0,0.1);
+            display: flex;
+            flex-direction: column;
+            z-index: 1000;
+            animation: slideInR 0.15s ease-out;
+          }
+          @keyframes slideInR { from { transform: translateX(20px); opacity: 0; } to { transform: translateX(0); opacity: 1; } }
+          
+          .gc-node-modal-header {
+            padding: 0.75rem 1rem;
+            border-bottom: 3px solid #000;
+            background: #fafafa;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+          }
+          .gc-node-close {
+            background: none; border: none; cursor: pointer; padding: 2px; display: flex; align-items: center; opacity: 0.5; transition: 0.12s;
+          }
+          .gc-node-close:hover { opacity: 1; color: #ef4444; }
+          
+          .gc-node-badge {
+            color: #fff;
+            font-size: 0.6rem;
+            font-family: var(--font-mono);
+            font-weight: 700;
+            padding: 2px 6px;
+            border-radius: 20px;
+            text-transform: uppercase;
+          }
+
+          .gc-node-modal-body {
+            padding: 1rem;
+            overflow-y: auto;
+            flex: 1;
+            display: flex;
+            flex-direction: column;
+            gap: 0.6rem;
+            background: #fff;
+          }
+
+          .gc-node-row {
+            display: flex;
+            align-items: flex-start;
+            gap: 0.75rem;
+            font-family: var(--font-mono);
+            font-size: 0.8rem;
+          }
+          .gc-node-key { width: 60px; flex-shrink: 0; color: #777; display: flex; align-items: center; gap: 4px; }
+          .gc-node-val { flex: 1; color: #111; }
+
+          .gc-node-divider { height: 1px; border-bottom: 1px dashed #ccc; margin: 0.4rem 0; }
+          .gc-node-section-title { font-family: var(--font-mono); font-size: 0.7rem; font-weight: 700; color: #444; letter-spacing: 1px; margin-bottom: 0.2rem; display: flex; align-items: center; gap: 6px; }
+
+          .gc-node-props { display: flex; flex-direction: column; gap: 4px; background: #f8f8f8; border: 1px solid #ddd; padding: 0.5rem; }
+          .gc-node-prop-item { font-family: var(--font-mono); font-size: 0.7rem; display: flex; gap: 6px; align-items: flex-start; }
+          .gc-node-prop-k { color: #555; }
+          .gc-node-prop-v { color: #111; word-break: break-all; }
+
+          .gc-node-summary {
+            font-family: var(--font-mono);
+            font-size: 0.75rem;
+            line-height: 1.5;
+            color: #333;
+            background: #fff9c4;
+            border-left: 3px solid #fbc02d;
+            padding: 0.5rem 0.75rem;
+          }
+        `}</style>
+      </div>
+    );
+  }
+);
+
+GraphCanvas.displayName = 'GraphCanvas';
+export default GraphCanvas;

frontend-react/src/context/AuthContext.tsx

@@ -0,0 +1,64 @@
+import React, { createContext, useContext, useState, useEffect } from 'react';
+
+// This acts as our authentication context for the React application
+
+interface User {
+  username: string;
+  email?: string;
+  full_name?: string;
+  scopes: string[];
+}
+
+interface AuthContextType {
+  token: string | null;
+  user: User | null;
+  login: (token: string, user: User) => void;
+  logout: () => void;
+  isAuthenticated: boolean;
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [token, setToken] = useState<string | null>(localStorage.getItem('token'));
+  const [user, setUser] = useState<User | null>(null);
+
+  useEffect(() => {
+    const storedUser = localStorage.getItem('user');
+    if (storedUser) {
+      try {
+        setUser(JSON.parse(storedUser));
+      } catch (e) {
+        console.error('Failed to parse stored user', e);
+      }
+    }
+  }, []);
+
+  const login = (newToken: string, newUser: User) => {
+    localStorage.setItem('token', newToken);
+    localStorage.setItem('user', JSON.stringify(newUser));
+    setToken(newToken);
+    setUser(newUser);
+  };
+
+  const logout = () => {
+    localStorage.removeItem('token');
+    localStorage.removeItem('user');
+    setToken(null);
+    setUser(null);
+  };
+
+  return (
+    <AuthContext.Provider value={{ token, user, login, logout, isAuthenticated: !!token }}>
+      {children}
+    </AuthContext.Provider>
+  );
+};
+
+export const useAuth = () => {
+  const context = useContext(AuthContext);
+  if (context === undefined) {
+    throw new Error('useAuth must be used within an AuthProvider');
+  }
+  return context;
+};

frontend-react/src/index.css

@@ -0,0 +1,494 @@
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&family=Noto+Sans+SC:wght@400;500;700&family=Space+Grotesk:wght@300;400;500;600;700&display=swap');
+@import "tailwindcss";
+
+/* ── Design Tokens ─────────────────────────────────────────────────────── */
+:root {
+  --bg-color: #ffffff;
+  --text-color: #000000;
+  --border-color: #000000;
+  --surface-color: #f5f5f5;   /* subtle off-white for secondary surfaces */
+  --hover-bg: #f0f0f0;
+  --muted-color: #666666;
+  --success-color: #16a34a;
+  --error-color: #dc2626;
+  --warning-color: #d97706;
+
+  --font-sans: 'Inter', 'Noto Sans SC', sans-serif;
+  --font-display: 'Space Grotesk', 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  --transition-speed: 0.18s;
+  --nav-height: 60px;
+}
+
+/* ── Reset ─────────────────────────────────────────────────────────────── */
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: var(--font-sans);
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  min-height: 100vh;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--font-display);
+  font-weight: 600;
+  margin-bottom: 0.75rem;
+  line-height: 1.2;
+}
+
+code, pre, .technical { font-family: var(--font-mono); }
+
+/* ── Links ─────────────────────────────────────────────────────────────── */
+a {
+  color: var(--text-color);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  transition: background var(--transition-speed), color var(--transition-speed);
+}
+a:hover {
+  background-color: var(--text-color);
+  color: var(--bg-color);
+}
+
+/* ── Buttons ───────────────────────────────────────────────────────────── */
+button, .app-btn {
+  font-family: var(--font-display);
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  border: 2px solid var(--border-color);
+  padding: 0.5rem 1rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background var(--transition-speed) ease, color var(--transition-speed) ease;
+  font-size: 0.9rem;
+  text-transform: uppercase;
+  letter-spacing: 0.8px;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+button:hover, .app-btn:hover {
+  background-color: var(--text-color);
+  color: var(--bg-color);
+}
+button:disabled, .app-btn:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+/* Text-only button (no border, no background) */
+.text-btn {
+  background: none !important;
+  border: none !important;
+  color: var(--text-color);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  cursor: pointer;
+  font-family: var(--font-mono);
+  font-size: 0.8rem;
+  font-weight: 600;
+  transition: background var(--transition-speed), color var(--transition-speed);
+  padding: 0.2rem 0.4rem;
+}
+.text-btn:hover {
+  background: var(--text-color) !important;
+  color: var(--bg-color) !important;
+}
+
+/* ── Toast dismiss button ──────────────────────────────────────────────── */
+/* Prevents global button:hover from flipping the close button inside toasts */
+.toast-dismiss-btn {
+  background: transparent !important;
+  border: none !important;
+  color: inherit !important;
+  cursor: pointer !important;
+  margin-left: auto !important;
+  padding: 0 0.3rem !important;
+  font-size: 1.2rem !important;
+  line-height: 1 !important;
+  opacity: 0.7;
+  flex-shrink: 0;
+  transition: opacity 0.12s ease !important;
+}
+.toast-dismiss-btn:hover {
+  background: transparent !important;
+  color: inherit !important;
+  opacity: 1 !important;
+}
+
+/* ── Status toast ──────────────────────────────────────────────────────── */
+.status-toast {
+  position: fixed;
+  bottom: 2rem;
+  right: 2rem;
+  background: var(--text-color);
+  color: var(--bg-color);
+  padding: 0.9rem 1.2rem;
+  border-left: 5px solid #000;
+  box-shadow: 4px 4px 0 rgba(0,0,0,0.3);
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  z-index: 9999;
+  font-family: var(--font-mono);
+  font-weight: 700;
+  font-size: 0.85rem;
+  max-width: 420px;
+  animation: slideUpToast 0.28s ease-out both;
+  will-change: transform;
+}
+.status-toast.error { border-left-color: var(--error-color); }
+.status-toast.success { border-left-color: var(--success-color); }
+
+/* ── Form Controls ─────────────────────────────────────────────────────── */
+input, textarea, select {
+  font-family: var(--font-sans);
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  border: 2px solid var(--border-color);
+  padding: 0.5rem 0.75rem;
+  font-size: 0.95rem;
+  transition: box-shadow var(--transition-speed) ease;
+}
+input:focus, textarea:focus, select:focus {
+  outline: none;
+  box-shadow: 3px 3px 0 var(--border-color);
+}
+
+/* ── Scrollbars ────────────────────────────────────────────────────────── */
+::-webkit-scrollbar { width: 8px; height: 8px; }
+::-webkit-scrollbar-track { background: #f9f9f9; border-left: 1px solid #e5e5e5; }
+::-webkit-scrollbar-thumb { background: #ccc; }
+::-webkit-scrollbar-thumb:hover { background: #999; }
+
+/* ── Layout Utilities ──────────────────────────────────────────────────── */
+.container {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+}
+
+.card {
+  border: 2px solid var(--border-color);
+  padding: 1.5rem;
+  background-color: var(--bg-color);
+  transition: transform var(--transition-speed) ease, box-shadow var(--transition-speed) ease;
+}
+.card:hover {
+  transform: translateY(-2px);
+  box-shadow: 5px 5px 0 var(--border-color);
+}
+
+.mono-text { font-family: var(--font-mono); font-size: 0.88em; }
+
+.flex-center {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.flex-between {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 1rem;
+}
+
+.full-width { width: 100%; }
+
+.page-header {
+  border-bottom: 3px solid var(--border-color);
+  padding-bottom: 1rem;
+  margin-bottom: 2rem;
+}
+
+/* ── Keyframes ─────────────────────────────────────────────────────────── */
+@keyframes fadeIn {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes slideUpToast {
+  from { transform: translateY(80px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+
+@keyframes slideUp {
+  from { transform: translateY(20px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+
+@keyframes spin {
+  100% { transform: rotate(360deg); }
+}
+
+.fade-in { animation: fadeIn 0.4s ease both; }
+
+/* ── Status indicators ─────────────────────────────────────────────────── */
+.status-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+.status-dot.online { background: var(--success-color); }
+.status-dot.offline { background: var(--error-color); }
+
+/* ── Responsive ────────────────────────────────────────────────────────── */
+@media (max-width: 768px) {
+  .container { padding: 1rem; }
+  .card { padding: 1rem; }
+}
+
+/* ── Admin / shared aliases ─────────────────────────────────────────────── */
+/* These classes are referenced in AdminDashboard and other views.          */
+/* They map onto the existing design system so everything is uniform.       */
+
+/* Base btn — same as global button but without uppercase transform */
+.btn {
+  font-family: var(--font-display);
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  border: 2px solid var(--border-color);
+  padding: 0.5rem 1rem;
+  font-weight: 600;
+  cursor: pointer;
+  font-size: 0.85rem;
+  letter-spacing: 0.5px;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  transition: background var(--transition-speed) ease, color var(--transition-speed) ease;
+}
+.btn:hover:not(:disabled) {
+  background-color: var(--text-color);
+  color: var(--bg-color);
+}
+.btn:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+/* Primary button — filled black */
+.btn-primary {
+  background-color: var(--text-color);
+  color: var(--bg-color);
+  border: 2px solid var(--text-color);
+}
+.btn-primary:hover:not(:disabled) {
+  background-color: #333;
+  border-color: #333;
+}
+
+/* Outline / ghost button */
+.btn-outline {
+  background: transparent;
+  color: var(--text-color);
+  border: 2px solid var(--border-color);
+}
+.btn-outline:hover:not(:disabled) {
+  background: var(--text-color);
+  color: var(--bg-color);
+}
+
+/* Danger button */
+.btn-danger {
+  color: var(--error-color);
+  border-color: var(--error-color);
+}
+.btn-danger:hover:not(:disabled) {
+  background: var(--error-color);
+  color: #fff;
+}
+
+/* Uniform search / select input (matches global input but explicit class) */
+.search-input {
+  font-family: var(--font-sans);
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  border: 2px solid var(--border-color);
+  padding: 0.5rem 0.75rem;
+  font-size: 0.9rem;
+  transition: box-shadow var(--transition-speed) ease;
+  width: 100%;
+}
+.search-input:focus {
+  outline: none;
+  box-shadow: 3px 3px 0 var(--border-color);
+}
+
+/* Status / metric cards */
+.status-card {
+  border: 2px solid var(--border-color);
+  padding: 1.25rem 1.5rem;
+  background: var(--bg-color);
+}
+
+.metric-value {
+  font-family: var(--font-mono);
+  font-size: 2rem;
+  font-weight: 900;
+  line-height: 1;
+  margin-top: 0.25rem;
+}
+
+.status-label {
+  font-family: var(--font-mono);
+  font-size: 0.68rem;
+  font-weight: 700;
+  color: var(--muted-color);
+  letter-spacing: 1px;
+  text-transform: uppercase;
+}
+
+/* Online / offline indicator dots */
+.indicator {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+.indicator.online  { background: var(--success-color); }
+.indicator.offline { background: var(--error-color); }
+.indicator.pending { background: var(--warning-color); }
+
+/* Typography */
+.title-lg {
+  font-family: var(--font-display);
+  font-size: 1.8rem;
+  font-weight: 700;
+  line-height: 1.1;
+}
+.title-md {
+  font-family: var(--font-display);
+  font-size: 1.15rem;
+  font-weight: 700;
+}
+.title-sm {
+  font-family: var(--font-mono);
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 1px;
+  text-transform: uppercase;
+  color: var(--muted-color);
+}
+
+/* Data table */
+.data-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.9rem;
+}
+.data-table thead tr {
+  background: var(--surface-color);
+  border-bottom: 2px solid var(--border-color);
+}
+.data-table th,
+.data-table td {
+  padding: 0.75rem 1rem;
+  text-align: left;
+  border-bottom: 1px solid #eaeaea;
+}
+.data-table th {
+  font-family: var(--font-mono);
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.8px;
+  text-transform: uppercase;
+  color: var(--muted-color);
+}
+.data-table tbody tr:hover {
+  background: var(--surface-color);
+}
+.data-table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+/* Tag / badge chips */
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  border: 1.5px solid var(--border-color);
+  padding: 2px 8px;
+  font-family: var(--font-mono);
+  font-size: 0.72rem;
+  font-weight: 700;
+}
+.chip.success { border-color: var(--success-color); color: var(--success-color); }
+.chip.error   { border-color: var(--error-color);   color: var(--error-color);   }
+.chip.warning { border-color: var(--warning-color); color: var(--warning-color); }
+.chip.filled  { background: var(--text-color); color: var(--bg-color); }
+
+/* Empty state */
+.empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 4rem 2rem;
+  color: var(--muted-color);
+  gap: 0.75rem;
+  border: 2px dashed var(--border-color);
+  font-family: var(--font-mono);
+  font-size: 0.85rem;
+  letter-spacing: 0.5px;
+  text-align: center;
+}
+
+/* Help tooltip */
+.help-tooltip {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+.help-tooltip [data-tip] {
+  cursor: help;
+  color: var(--muted-color);
+}
+.help-tooltip [data-tip]:hover::after {
+  content: attr(data-tip);
+  position: absolute;
+  bottom: 125%;
+  left: 50%;
+  transform: translateX(-50%);
+  background: var(--text-color);
+  color: var(--bg-color);
+  padding: 0.4rem 0.75rem;
+  font-family: var(--font-mono);
+  font-size: 0.75rem;
+  white-space: nowrap;
+  z-index: 9999;
+  pointer-events: none;
+  max-width: 260px;
+  white-space: normal;
+  text-align: center;
+}
+
+/* Page info bar */
+.page-info-bar {
+  background: var(--surface-color);
+  border-left: 4px solid var(--border-color);
+  padding: 0.75rem 1rem;
+  font-size: 0.82rem;
+  line-height: 1.6;
+  margin-bottom: 1.5rem;
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+  color: var(--muted-color);
+}
+.page-info-bar strong { color: var(--text-color); font-family: var(--font-mono); }

frontend-react/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

frontend-react/src/types/api.ts

@@ -0,0 +1,182 @@
+export interface LoginRequest {
+  username: string;
+  password: string;
+}
+
+export interface RegisterRequest {
+  username: string;
+  password: string;
+  email?: string;
+  full_name?: string;
+  scopes?: string[];
+  tenant_id?: string;
+}
+
+export interface TokenResponse {
+  access_token: string;
+  token_type: string;
+}
+
+export interface DocumentUploadResponse {
+  document_id: string;
+  filename: string;
+  size_bytes: number;
+  task_id?: string;
+  message: string;
+}
+
+export interface ScrapeRequest {
+  url: string;
+}
+
+export interface CrawlRequest {
+  url: string;
+  max_depth?: number;
+  max_pages?: number;
+}
+
+export interface IngestionStatusResponse {
+  task_id: string;
+  status: string;
+  progress?: Record<string, any>;
+  result?: Record<string, any>;
+}
+
+export interface DocumentInfo {
+  id: string;
+  filename: string;
+  file_type: string;
+  size_bytes: number;
+  upload_date: string;
+}
+
+export interface DocumentListResponse {
+  documents: DocumentInfo[];
+  total: number;
+}
+
+export interface QueryRequest {
+  query: string;
+  top_k?: number;
+  streaming?: boolean;
+  document_id?: string;
+  conversation_id?: string;
+  use_got?: boolean;
+  at_time?: string; 
+}
+
+export interface ConfidenceJudgmentResponse {
+  score: number;
+  reasoning: string;
+  grounded_claims: number;
+  ungrounded_claims: number;
+  hallucination_risk: 'low' | 'medium' | 'high';
+}
+
+export interface QueryResponse {
+  answer: string;
+  sources: Array<Record<string, any>>;
+  reasoning_chain: string[];
+  confidence: number;
+  confidence_judgment?: ConfidenceJudgmentResponse;
+  retrieval_method: string;
+  processing_time_seconds: number;
+  conversation_id?: string;
+  drift_expanded?: boolean;
+  total_sub_queries?: number;
+}
+
+export interface EvalResultData {
+  overall_score?: number;
+  faithfulness: number;
+  answer_relevancy?: number;
+  relevancy?: number;
+  context_precision?: number;
+  precision?: number;
+}
+
+export interface Message {
+  id: string;
+  role: string;
+  content: string;
+  reasoning?: string[];
+  sources?: Array<Record<string, any>>;
+  confidence?: number;
+  hallucination_risk?: string;
+  confidence_reasoning?: string;
+  created_at: string;
+  eval_result?: EvalResultData;
+  evaluating?: boolean;
+}
+
+export interface Conversation {
+  id: string;
+  title: string;
+  created_at: string;
+  updated_at: string;
+  messages?: Message[];
+}
+
+export interface ConversationListResponse {
+  conversations: Conversation[];
+}
+
+export interface OntologyResponse {
+  version: string;
+  entity_types: string[];
+  relationship_types: string[];
+  properties: Record<string, string[]>;
+  created_at: string;
+  approved: boolean;
+}
+
+export interface OntologyUpdateRequest {
+  entity_types?: string[];
+  relationship_types?: string[];
+  properties?: Record<string, string[]>;
+  approved?: boolean;
+}
+
+export interface GraphNode {
+  id: string;
+  label: string;
+  type: string;
+  description?: string;
+  properties: Record<string, any>;
+  community_id?: number;
+  valid_from?: string;
+  valid_until?: string;
+}
+
+export interface GraphEdge {
+  source: string;
+  target: string;
+  type: string;
+  properties: Record<string, any>;
+  valid_from?: string;
+  confidence?: number;
+}
+
+export interface GraphVisualizationResponse {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+export interface SystemHealthResponse {
+  status: string;
+  version: string;
+  neo4j_connected: boolean;
+  redis_connected: boolean;
+  workers_active: number;
+  timestamp: string;
+}
+
+export interface SystemStatsResponse {
+  documents_count: number;
+  entities_count: number;
+  relationships_count: number;
+  chunks_count: number;
+  ontology_version: string;
+}
+
+export interface DriftReport { id: string; detected_at: string; new_entity_types: string[]; new_relationship_types: string[]; removed_entity_types: string[]; removed_relationship_types: string[]; sample_size: number; drift_score: number; status: string; approved_by?: string; approved_at?: string; }

frontend-react/src/views/AdminDashboard.tsx

@@ -0,0 +1,762 @@
+import React, { useState, useEffect, useCallback } from 'react';
+import { useAuth } from '../context/AuthContext';
+import {
+  BarChart2, Cpu, Users, Database, Settings,
+  Trash2, Check, X, Play, RefreshCw, Shield,
+  AlertTriangle, Zap, GitBranch, Info
+} from 'lucide-react';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000/api';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+const Spinner = () => (
+  <span className="inline-block w-[14px] h-[14px] border-2 border-[#ccc] border-t-black rounded-full animate-spin"/>
+);
+
+// ─── Tab Components ──────────────────────────────────────────────────────────
+
+const OverviewTab = ({ stats, health, onRefresh }: { stats: Partial<import('../types/api').SystemStatsResponse & {graph: any, total_nodes: number, total_relationships: number, documents: any, total_documents: number, costs: any}>; health: import('../types/api').SystemHealthResponse | any; onRefresh: () => void }) => (
+  <div>
+    {/* KPI Grid */}
+    <div className="grid grid-cols-[repeat(auto-fit,minmax(180px,1fr))] gap-4 mb-8">
+      {[
+        { label:'Graph Nodes', value: stats?.graph?.nodes ?? stats?.total_nodes ?? '—', icon:<Database size={16}/> },
+        { label:'Relationships', value: stats?.graph?.relationships ?? stats?.total_relationships ?? '—', icon:<GitBranch size={16}/> },
+        { label:'Documents', value: stats?.documents?.total ?? stats?.total_documents ?? '—', icon:<Database size={16}/> },
+        { label:'Est. LLM Cost', value: `$${(stats?.costs?.total_estimated_usd ?? 0).toFixed(4)}`, icon:<BarChart2 size={16}/> },
+      ].map(c => (
+        <div key={c.label} className="status-card">
+          <div className="flex justify-between items-center mb-2">
+            <div className="status-label">{c.label}</div>
+            {c.icon}
+          </div>
+          <div className="metric-value">{c.value}</div>
+        </div>
+      ))}
+    </div>
+
+    {/* System health */}
+    <div className="card mb-6">
+      <div className="flex justify-between items-center mb-4">
+        <h2 className="title-md">System Health</h2>
+        <button className="btn btn-outline py-1 px-3 text-xs" onClick={onRefresh}>
+          <RefreshCw size={13}/> Refresh
+        </button>
+      </div>
+      {health ? (
+        <div className="grid grid-cols-[repeat(auto-fit,minmax(150px,1fr))] gap-3">
+          {Object.entries(health).map(([k, v]: [string, any]) => {
+            const isOk = v === true || v === 'ok' || v === 'connected' || v === 'healthy';
+            const isErr = v === false || v === 'error' || v === 'disconnected';
+            return (
+              <div key={k} className="border-[1.5px] border-[#e5e5e5] py-2.5 px-3.5 flex items-center gap-2">
+                <span className={`indicator ${isOk ? 'online' : isErr ? 'offline' : 'pending'}`}/>
+                <div>
+                  <div className="status-label">{k.toUpperCase()}</div>
+                  <div className="font-mono text-[0.8rem] font-bold">
+                    {typeof v === 'object' ? JSON.stringify(v) : String(v)}
+                  </div>
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      ) : (
+        <div className="text-center p-6 text-[var(--muted-color)] font-mono text-[0.85rem]">
+          Loading health data…
+        </div>
+      )}
+    </div>
+
+    {/* Provider info */}
+    {stats?.system && (
+      <div className="card">
+        <h2 className="title-md mb-4">LLM Provider</h2>
+        <div className="flex gap-4 flex-wrap">
+          {Object.entries(stats.system).map(([k, v]: any) => (
+            <div key={k} className="chip">{k}: <strong>{String(v)}</strong></div>
+          ))}
+        </div>
+      </div>
+    )}
+  </div>
+);
+
+const UsersTab = ({ token }: { token: string | null }) => {
+  const [users, setUsers] = useState<any[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [msg, setMsg] = useState('');
+
+  const fetchUsers = useCallback(async () => {
+    setLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/admin/users`, { headers: { Authorization: `Bearer ${token}` } });
+      if (res.ok) {
+        const json = await res.json();
+        setUsers(json.users || []);
+      }
+    } finally { setLoading(false); }
+  }, [token]);
+
+  useEffect(() => { fetchUsers(); }, [fetchUsers]);
+
+  const updateRole = async (username: string, scopes: string) => {
+    const res = await fetch(`${API_BASE}/admin/users/${username}/role`, {
+      method: 'PUT',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ scopes: [scopes] })
+    });
+    if (res.ok) {
+      setUsers(u => u.map(usr => usr.username === username ? { ...usr, scopes: [scopes] } : usr));
+      setMsg(`Role updated for ${username}`);
+      setTimeout(() => setMsg(''), 3000);
+    } else {
+      setMsg(`Failed to update role for ${username}`);
+      setTimeout(() => setMsg(''), 3000);
+    }
+  };
+
+  return (
+    <div className="card">
+      <div className="flex justify-between items-center mb-4">
+        <h2 className="title-md">Registered Users</h2>
+        <button className="btn btn-outline py-1 px-3 text-xs" onClick={fetchUsers}>
+          <RefreshCw size={13}/> Refresh
+        </button>
+      </div>
+      {msg && <div className="bg-[#dcfce7] text-[#166534] py-2 px-3 mb-4 font-mono text-[0.8rem]">{msg}</div>}
+      {loading ? (
+        <div className="text-center p-8"><Spinner/></div>
+      ) : (
+        <div className="overflow-x-auto">
+          <table className="data-table">
+            <thead><tr><th>Username</th><th>Scope</th><th>Change Role</th></tr></thead>
+            <tbody>
+              {users.map(u => {
+                const isAdminUser = u.username === 'admin';
+                const currentScope = u.scopes?.includes('admin') ? 'admin' : (u.scopes?.includes('write') ? 'write' : 'read');
+                return (
+                  <tr key={u.username}>
+                    <td className="font-mono font-semibold">
+                      {u.username}
+                      {isAdminUser && <span className="chip filled ml-1.5 text-[0.62rem]">PROTECTED</span>}
+                    </td>
+                    <td><span className="chip">{u.scopes?.join(', ') || 'none'}</span></td>
+                    <td>
+                      {isAdminUser ? (
+                        <span className="font-mono text-xs text-[var(--muted-color)]">—</span>
+                      ) : (
+                        <select
+                          className="search-input w-auto py-1 px-2 text-[0.82rem]"
+                          value={currentScope}
+                          onChange={e => updateRole(u.username, e.target.value)}
+                        >
+                          <option value="read">Read Only</option>
+                          <option value="write">Read / Write</option>
+                          <option value="admin">Admin</option>
+                        </select>
+                      )}
+                    </td>
+                  </tr>
+                );
+              })}
+              {users.length === 0 && (
+                <tr><td colSpan={3} className="text-center p-8 text-[var(--muted-color)]">No users found.</td></tr>
+              )}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+};
+
+const DocumentsTab = ({ token }: { token: string | null }) => {
+  const [docs, setDocs] = useState<any[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [msg, setMsg] = useState('');
+
+  const fetchDocs = useCallback(async () => {
+    setLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/admin/documents`, { headers: { Authorization: `Bearer ${token}` } });
+      if (res.ok) {
+        const json = await res.json();
+        setDocs(json.documents || []);
+      }
+    } finally { setLoading(false); }
+  }, [token]);
+
+  useEffect(() => { fetchDocs(); }, [fetchDocs]);
+
+  const deleteDoc = async (id: string, filename: string) => {
+    if (!window.confirm(`Delete "${filename}" and all its graph data? This cannot be undone.`)) return;
+    const res = await fetch(`${API_BASE}/admin/documents/${id}`, { method: 'DELETE', headers: { Authorization: `Bearer ${token}` } });
+    if (res.ok) {
+      setDocs(d => d.filter(doc => doc.id !== id));
+      setMsg('Document deleted.');
+      setTimeout(() => setMsg(''), 3000);
+    }
+  };
+
+  const reIngestDoc = async (id: string, filename: string) => {
+    setMsg(`Re-ingesting "${filename}"...`);
+    try {
+      const res = await fetch(`${API_BASE}/admin/documents/${id}/reingest`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const data = await res.json();
+        setMsg(`Re-ingestion queued for "${filename}". Task: ${data.task_id?.slice(0,8)}…`);
+        setTimeout(() => { setMsg(''); fetchDocs(); }, 5000);
+      } else {
+        setMsg(`Failed to re-ingest "${filename}"`);
+        setTimeout(() => setMsg(''), 3000);
+      }
+    } catch {
+      setMsg('Network error during re-ingest.');
+      setTimeout(() => setMsg(''), 3000);
+    }
+  };
+
+  return (
+    <div className="card">
+      <div className="flex justify-between items-center mb-4">
+        <h2 className="title-md">Document Vault</h2>
+        <span className="font-mono text-xs text-[var(--muted-color)]">{docs.length} documents</span>
+      </div>
+      {msg && <div className={`py-2 px-3 mb-4 font-mono text-[0.8rem] ${(msg.includes('Failed') || msg.includes('error')) ? 'bg-[#fef2f2] text-[#dc2626]' : 'bg-[#dcfce7] text-[#166534]'}`}>{msg}</div>}
+      {loading ? (
+        <div className="text-center p-8"><Spinner/></div>
+      ) : (
+        <div className="overflow-x-auto">
+          <table className="data-table">
+            <thead><tr><th>ID</th><th>Filename</th><th>Status</th><th>Actions</th></tr></thead>
+            <tbody>
+              {docs.map(d => (
+                <tr key={d.id}>
+                  <td className="font-mono text-[0.78rem] text-[var(--muted-color)]">{d.id?.substring(0,12)}…</td>
+                  <td className="font-mono font-semibold">{d.filename}</td>
+                  <td>
+                    <span className={`chip ${d.status === 'completed' ? 'success' : d.status === 'failed' ? 'error' : 'warning'}`}>
+                      {d.status || 'unknown'}
+                    </span>
+                  </td>
+                  <td className="flex gap-1.5 flex-wrap">
+                    {(d.status === 'failed' || d.status === 'pending') && (
+                      <button className="btn text-[0.72rem] py-1 px-2 border-[#2563eb] text-[#2563eb] bg-[#eff6ff]"
+                        onClick={() => reIngestDoc(d.id, d.filename)}>
+                        <Play size={11}/> Re-Ingest
+                      </button>
+                    )}
+                    <button className="btn btn-danger text-xs py-1 px-2.5" onClick={() => deleteDoc(d.id, d.filename)}>
+                      <Trash2 size={12}/> Delete
+                    </button>
+                  </td>
+                </tr>
+              ))}
+              {docs.length === 0 && (
+                <tr><td colSpan={4} className="text-center p-8 text-[var(--muted-color)]">No documents uploaded yet.</td></tr>
+              )}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+};
+
+const GraphCRUDTab = ({ token }: { token: string | null }) => {
+  const [nodes, setNodes] = useState<any[]>([]);
+  const [query, setQuery] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [msg, setMsg] = useState('');
+
+  const search = async (e?: React.FormEvent) => {
+    e?.preventDefault();
+    setLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/admin/graph/nodes?query=${encodeURIComponent(query)}&limit=100`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) setNodes((await res.json()).nodes || []);
+    } finally { setLoading(false); }
+  };
+
+  const deleteNode = async (id: string) => {
+    if (!window.confirm('Detach and delete this node?')) return;
+    const res = await fetch(`${API_BASE}/admin/graph/nodes/${id}`, {
+      method: 'DELETE', headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.ok) {
+      setNodes(n => n.filter(nd => nd.id !== id));
+      setMsg('Node deleted.');
+      setTimeout(() => setMsg(''), 3000);
+    }
+  };
+
+  return (
+    <div className="card">
+      <h2 className="title-md mb-4">Graph Node Browser</h2>
+      <div className="page-info-bar">
+        <Info size={14}/>
+        <span>Search and inspect nodes directly in Neo4j. Use label names or property values. <strong>DELETE</strong> detaches all relationships before removing the node.</span>
+      </div>
+      {msg && <div className="bg-[#dcfce7] text-[#166534] py-2 px-3 mb-4 font-mono text-[0.8rem]">{msg}</div>}
+      <form onSubmit={search} className="flex gap-3 mb-6">
+        <input type="text" value={query} onChange={e => setQuery(e.target.value)}
+          placeholder="Search node labels or properties…" className="search-input flex-1"/>
+        <button type="submit" className="btn btn-primary" disabled={loading}>
+          {loading ? <Spinner/> : null} Search
+        </button>
+      </form>
+      <div className="overflow-x-auto max-h-[420px] overflow-y-auto">
+        <table className="data-table">
+          <thead><tr><th>ID</th><th>Labels</th><th>Properties</th><th>Action</th></tr></thead>
+          <tbody>
+            {nodes.map((n, i) => (
+              <tr key={i}>
+                <td className="font-mono text-[0.78rem] text-[var(--muted-color)]">{n.id}</td>
+                <td className="font-mono text-[#2563eb]">{n.labels?.join(', ')}</td>
+                <td className="font-mono text-[0.78rem] text-[var(--muted-color)] max-w-[260px] whitespace-nowrap overflow-hidden text-ellipsis">
+                  {JSON.stringify(n.properties)}
+                </td>
+                <td>
+                  <button className="btn btn-danger text-xs py-1 px-2.5" onClick={() => deleteNode(n.id)}>
+                    <Trash2 size={12}/> Delete
+                  </button>
+                </td>
+              </tr>
+            ))}
+            {nodes.length === 0 && (
+              <tr><td colSpan={4} className="text-center p-8 text-[var(--muted-color)]">
+                {loading ? 'Searching…' : 'Enter a search term above to browse nodes.'}
+              </td></tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+};
+
+const OntologyGovernanceTab = ({ token }: { token: string | null }) => {
+  const [proposals, setProposals] = useState<any[]>([]);
+  const [driftReports, setDriftReports] = useState<any[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [detectLoading, setDetectLoading] = useState(false);
+  const [msg, setMsg] = useState('');
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    try {
+      const [propRes, driftRes] = await Promise.all([
+        fetch(`${API_BASE}/admin/ontology/pending`, { headers: { Authorization: `Bearer ${token}` } }),
+        fetch(`${API_BASE}/ontology/drift`, { headers: { Authorization: `Bearer ${token}` } }),
+      ]);
+      if (propRes.ok) setProposals((await propRes.json()).proposals || []);
+      if (driftRes.ok) setDriftReports((await driftRes.json()).reports || []);
+    } finally { setLoading(false); }
+  }, [token]);
+
+  useEffect(() => { fetchData(); }, [fetchData]);
+
+  const handleProposal = async (id: string, action: 'approve' | 'reject') => {
+    const res = await fetch(`${API_BASE}/admin/ontology/${action}/${id}`, {
+      method: 'POST', headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.ok) {
+      setProposals(p => p.filter(o => o.id !== id));
+      setMsg(`Proposal ${action}d.`);
+      setTimeout(() => setMsg(''), 3000);
+    }
+  };
+
+  const handleDrift = async (id: string, action: 'approve' | 'reject') => {
+    const res = await fetch(`${API_BASE}/ontology/drift/${id}/${action}`, {
+      method: 'POST', headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.ok) {
+      setDriftReports(d => d.filter(r => r.id !== id));
+      setMsg(`Drift report ${action}d.`);
+      setTimeout(() => setMsg(''), 3000);
+    }
+  };
+
+  const detectDrift = async () => {
+    setDetectLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/ontology/drift/detect`, {
+        method: 'POST', headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        setMsg('Drift detection complete. Refreshing…');
+        await fetchData();
+      }
+    } finally {
+      setDetectLoading(false);
+      setTimeout(() => setMsg(''), 4000);
+    }
+  };
+
+  return (
+    <div>
+      {msg && <div className="bg-[#dcfce7] text-[#166534] py-2.5 px-3.5 mb-4 font-mono text-[0.8rem] border border-[#bbf7d0]">{msg}</div>}
+
+      {/* Drift detection */}
+      <div className="card mb-6">
+        <div className="flex justify-between items-center mb-3">
+          <h2 className="title-md">Ontology Drift Reports</h2>
+          <button className="btn btn-primary text-[0.8rem]" onClick={detectDrift} disabled={detectLoading}>
+            {detectLoading ? <Spinner/> : <Zap size={13}/>} Run Drift Detection
+          </button>
+        </div>
+        <p className="text-[var(--muted-color)] text-[0.85rem] mb-5 font-sans">
+          Drift detection samples recent data and suggests additions or changes to the graph schema.
+          Review and approve or reject proposals below.
+        </p>
+        {loading ? <div className="text-center p-6"><Spinner/></div> : (
+          <div className="grid gap-3">
+            {driftReports.map(r => (
+              <div key={r.id} className="border-2 border-black p-4 flex justify-between items-start gap-4">
+                <div className="flex-1">
+                  <div className="flex gap-2 mb-1.5 flex-wrap">
+                    <span className="chip">{r.status || 'pending'}</span>
+                    <span className="chip">{r.new_entity_types?.length || 0} new types</span>
+                  </div>
+                  <p className="font-mono text-[0.78rem] text-[#555] m-0">
+                    {r.summary || 'Drift report — review suggested schema changes.'}
+                  </p>
+                </div>
+                <div className="flex gap-2 shrink-0">
+                  <button className="btn bg-[#f0fdf4] text-[#16a34a] border-[#16a34a] py-1 px-3 text-[0.78rem]"
+                    onClick={() => handleDrift(r.id, 'approve')}><Check size={13}/> Apply</button>
+                  <button className="btn bg-[#fef2f2] text-[#dc2626] border-[#dc2626] py-1 px-3 text-[0.78rem]"
+                    onClick={() => handleDrift(r.id, 'reject')}><X size={13}/> Reject</button>
+                </div>
+              </div>
+            ))}
+            {driftReports.length === 0 && (
+              <div className="empty-state p-8">No pending drift reports. Run drift detection above.</div>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Manual proposals */}
+      <div className="card">
+        <h2 className="title-md mb-3">Manual Schema Proposals</h2>
+        <div className="grid gap-3">
+          {proposals.map(o => (
+            <div key={o.id} className="border-[1.5px] border-[#e5e5e5] p-3.5 flex justify-between items-center gap-4">
+              <div className="flex items-center gap-3">
+                <span className="chip">{o.type}</span>
+                <span className="font-mono text-[0.85rem]">{o.name}</span>
+              </div>
+              <div className="flex gap-2">
+                <button className="btn bg-[#f0fdf4] text-[#16a34a] border-[#16a34a] py-1 px-3 text-[0.78rem]"
+                  onClick={() => handleProposal(o.id, 'approve')}><Check size={13}/> Approve</button>
+                <button className="btn bg-[#fef2f2] text-[#dc2626] border-[#dc2626] py-1 px-3 text-[0.78rem]"
+                  onClick={() => handleProposal(o.id, 'reject')}><X size={13}/> Reject</button>
+              </div>
+            </div>
+          ))}
+          {proposals.length === 0 && (
+            <div className="empty-state p-6">No pending manual proposals.</div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+const WorkersTab = ({ token }: { token: string | null }) => {
+  const [tasks, setTasks] = useState<any>(null);
+  const [health, setHealth] = useState<any>(null);
+  const [loading, setLoading] = useState(true);
+
+  const fetchAll = useCallback(async () => {
+    setLoading(true);
+    try {
+      const [taskRes, healthRes] = await Promise.all([
+        fetch(`${API_BASE}/admin/tasks`, { headers: { Authorization: `Bearer ${token}` } }),
+        fetch(`${API_BASE}/system/health`, { headers: { Authorization: `Bearer ${token}` } }),
+      ]);
+      if (taskRes.ok) setTasks(await taskRes.json());
+      if (healthRes.ok) setHealth(await healthRes.json());
+    } finally { setLoading(false); }
+  }, [token]);
+
+  useEffect(() => { fetchAll(); }, [fetchAll]);
+
+  return (
+    <div>
+      <div className="card mb-5">
+        <div className="flex justify-between items-center mb-4">
+          <h2 className="title-md">Celery Worker Status</h2>
+          <button className="btn btn-outline text-xs py-1 px-3" onClick={fetchAll}>
+            <RefreshCw size={13}/> Refresh
+          </button>
+        </div>
+        {loading ? <div className="text-center p-6"><Spinner/></div> : (
+          <div className="grid grid-cols-[repeat(auto-fit,minmax(160px,1fr))] gap-3">
+            {[
+              { label:'Active Tasks', value: tasks?.active_tasks ?? tasks?.active ?? 0 },
+              { label:'Queued Tasks', value: tasks?.queued_tasks ?? tasks?.reserved ?? 0 },
+              { label:'Completed', value: tasks?.completed_tasks ?? tasks?.total ?? 0 },
+              { label:'Failed', value: tasks?.failed_tasks ?? 0 },
+            ].map(m => (
+              <div key={m.label} className="status-card">
+                <div className="status-label">{m.label}</div>
+                <div className="metric-value text-2xl">{m.value}</div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+      {health && (
+        <div className="card">
+          <h2 className="title-md mb-3">Service Health</h2>
+          <div className="grid grid-cols-[repeat(auto-fit,minmax(140px,1fr))] gap-2.5">
+            {Object.entries(health).map(([k, v]: any) => {
+              const ok = v === true || v === 'ok' || v === 'connected' || v === 'healthy';
+              return (
+                <div key={k} className="border-[1.5px] border-[#e5e5e5] py-2 px-3 flex items-center gap-2">
+                  <span className={`indicator ${ok ? 'online' : 'offline'}`}/>
+                  <div>
+                    <div className="status-label">{k}</div>
+                    <div className="font-mono text-[0.78rem] font-bold">{String(v)}</div>
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+const EnrichmentTab = ({ token }: { token: string | null }) => {
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState<any>(null);
+  const [batchSize, setBatchSize] = useState(20);
+  const [minConnections, setMinConnections] = useState(1);
+  const [driftLoading, setDriftLoading] = useState(false);
+  const [driftResult, setDriftResult] = useState<any>(null);
+
+  const runEnrichment = async () => {
+    setLoading(true); setResult(null);
+    try {
+      const res = await fetch(`${API_BASE}/entities/enrich`, {
+        method:'POST',
+        headers:{ Authorization:`Bearer ${token}`, 'Content-Type':'application/json' },
+        body: JSON.stringify({ batch_size: batchSize, min_connections: minConnections })
+      });
+      if (res.ok) setResult(await res.json());
+    } finally { setLoading(false); }
+  };
+
+  const runDrift = async () => {
+    setDriftLoading(true); setDriftResult(null);
+    try {
+      const res = await fetch(`${API_BASE}/ontology/drift/detect`, {
+        method:'POST', headers:{ Authorization:`Bearer ${token}` }
+      });
+      if (res.ok) setDriftResult(await res.json());
+    } finally { setDriftLoading(false); }
+  };
+
+  return (
+    <div>
+      {/* Entity Enrichment */}
+      <div className="card mb-6">
+        <h2 className="title-md mb-2">Entity Enrichment</h2>
+        <p className="text-[var(--muted-color)] text-[0.85rem] mb-5">
+          Synthesize rich LLM-generated profiles for all eligible entities by scanning their neighborhood context in the graph.
+        </p>
+        <div className="grid grid-cols-2 gap-4 mb-4 max-w-[360px]">
+          <div>
+            <label className="block font-mono text-[0.7rem] font-bold text-[#888] mb-1">BATCH SIZE</label>
+            <input type="number" min={1} max={100} value={batchSize} onChange={e => setBatchSize(Number(e.target.value))}
+              className="search-input w-full"/>
+          </div>
+          <div>
+            <label className="block font-mono text-[0.7rem] font-bold text-[#888] mb-1">MIN CONNECTIONS</label>
+            <input type="number" min={0} max={20} value={minConnections} onChange={e => setMinConnections(Number(e.target.value))}
+              className="search-input w-full"/>
+          </div>
+        </div>
+        <button className="btn btn-primary flex gap-2 items-center" onClick={runEnrichment} disabled={loading}>
+          {loading ? <Spinner/> : <Zap size={14}/>}
+          {loading ? 'Enriching…' : 'Run Entity Enrichment'}
+        </button>
+        {result && (
+          <div className="mt-4 bg-[#f0fdf4] border border-[#bbf7d0] p-3 font-mono text-[0.82rem] text-[#166534]">
+            ✓ {result.message || `Enriched ${result.enriched_count ?? '?'} entities`}
+          </div>
+        )}
+      </div>
+
+      {/* Drift Detection */}
+      <div className="card">
+        <h2 className="title-md mb-2">Ontology Drift Detection</h2>
+        <p className="text-[var(--muted-color)] text-[0.85rem] mb-5">
+          Analyse recent data samples to detect schema evolution and generate a drift report for admin review.
+        </p>
+        <button className="btn btn-primary flex gap-2 items-center" onClick={runDrift} disabled={driftLoading}>
+          {driftLoading ? <Spinner/> : <GitBranch size={14}/>}
+          {driftLoading ? 'Detecting…' : 'Run Drift Detection'}
+        </button>
+        {driftResult && (
+          <div className="mt-4 bg-[#eff6ff] border border-[#bfdbfe] p-3 font-mono text-[0.82rem] text-[#1d4ed8]">
+            ✓ Drift report created. ID: {driftResult.report_id || driftResult.id || '—'} → Review in Ontology Governance tab.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+const SandboxTab = ({ token }: { token: string | null }) => {
+  const [loading, setLoading] = useState(false);
+  const [msg, setMsg] = useState('');
+
+  const trigger = async (endpoint: string, label: string) => {
+    setLoading(true); setMsg('');
+    try {
+      const res = await fetch(`${API_BASE}${endpoint}`, {
+        method:'POST', headers:{ Authorization:`Bearer ${token}` }
+      });
+      setMsg(res.ok ? `✓ ${label} dispatched to Celery worker.` : `✗ Failed to trigger ${label}.`);
+    } catch {
+      setMsg(`✗ Network error.`);
+    } finally { setLoading(false); }
+  };
+
+  return (
+    <div className="card">
+      <h2 className="title-md mb-2">MiroFish God-Mode Sandbox</h2>
+      <p className="text-[var(--muted-color)] text-[0.85rem] mb-6">
+        Control the simulation loops that connect Knowledge Graph entities into living agents.
+      </p>
+      {msg && (
+        <div className={`py-2.5 px-3.5 mb-4 font-mono text-[0.82rem] border ${msg.startsWith('✓') ? 'bg-[#dcfce7] text-[#166534] border-[#bbf7d0]' : 'bg-[#fef2f2] text-[#dc2626] border-[#fecaca]'}`}>
+          {msg}
+        </div>
+      )}
+      <div className="flex flex-col gap-4 max-w-[420px]">
+        {[
+          { endpoint:'/v1/simulation/generate_personas', label:'Generate Agent Personas', icon:<Users size={14}/>,
+            desc:'Converts raw graph nodes into living psychological profiles for agent simulation.' },
+          { endpoint:'/v1/simulation/tick', label:'Force Simulation Tick', icon:<Play size={14}/>,
+            desc:'Forces agents to read their local graph memory and output a new interaction edge.' },
+        ].map(item => (
+          <div key={item.endpoint} className="border-2 border-black p-4">
+            <button className="btn btn-primary flex gap-2 items-center w-full justify-center mb-2" onClick={() => trigger(item.endpoint, item.label)} disabled={loading}>
+              {loading ? <Spinner/> : item.icon} {item.label}
+            </button>
+            <p className="m-0 text-[0.78rem] text-[var(--muted-color)] font-sans">{item.desc}</p>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+// ─── Main Dashboard ───────────────────────────────────────────────────────────
+export default function AdminDashboard() {
+  const { token, user } = useAuth();
+  const [activeTab, setActiveTab] = useState('overview');
+  const [stats, setStats] = useState<any>(null);
+  const [health, setHealth] = useState<any>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchOverview = useCallback(async () => {
+    if (!token) return;
+    try {
+      const [statsRes, healthRes] = await Promise.all([
+        fetch(`${API_BASE}/admin/stats`, { headers: { Authorization: `Bearer ${token}` } }),
+        fetch(`${API_BASE}/system/health`, { headers: { Authorization: `Bearer ${token}` } }),
+      ]);
+      if (statsRes.ok) setStats(await statsRes.json());
+      if (healthRes.ok) setHealth(await healthRes.json());
+    } catch (err: any) {
+      setError(err.message);
+    }
+  }, [token]);
+
+  useEffect(() => { fetchOverview(); }, [fetchOverview]);
+
+  if (user && user.username !== 'admin' && !user.scopes?.includes('admin')) {
+    return (
+      <div className="container flex-center min-h-[60vh] flex-col gap-4">
+        <Shield size={48} className="opacity-30"/>
+        <h2 className="title-md">Access Denied</h2>
+        <p className="text-[var(--muted-color)]">You need administrative privileges to view this page.</p>
+      </div>
+    );
+  }
+
+  const TABS = [
+    { id:'overview',   label:'Overview',           icon:<BarChart2 size={14}/> },
+    { id:'users',      label:'Users',              icon:<Users size={14}/> },
+    { id:'documents',  label:'Documents',          icon:<Database size={14}/> },
+    { id:'graph',      label:'Graph CRUD',         icon:<GitBranch size={14}/> },
+    { id:'ontology',   label:'Ontology',           icon:<Settings size={14}/> },
+    { id:'workers',    label:'Workers',            icon:<Cpu size={14}/> },
+    { id:'enrichment', label:'Enrichment / Drift', icon:<Zap size={14}/> },
+    { id:'sandbox',    label:'God-Mode Sandbox',   icon:<Play size={14}/> },
+  ];
+
+  return (
+    <div className="container fade-in py-8 px-10 max-w-[1400px]">
+      {/* Header */}
+      <div className="flex justify-between items-start mb-6">
+        <div>
+          <h1 className="text-3xl font-bold font-display tracking-tight">Admin Control Center</h1>
+          <p className="text-[#666] mt-2 text-[0.95rem]">Manage graph data, workers, users, and platform configuration</p>
+        </div>
+        {error && (
+          <div className="bg-[#fef2f2] text-[#dc2626] py-2 px-4 border border-[#fecaca] font-mono text-[0.85rem] flex items-center gap-2 rounded shadow-sm">
+            <AlertTriangle size={15}/> {error}
+          </div>
+        )}
+      </div>
+
+      <div className="grid grid-cols-[240px_1fr] gap-8 mt-2">
+        {/* Sidebar nav */}
+        <div className="bg-white border-2 border-black p-3">
+          <nav className="flex flex-col gap-1.5">
+            {TABS.map(tab => (
+              <button
+                key={tab.id}
+                className={`flex items-center w-full justify-start gap-2.5 py-2 px-3 text-[0.85rem] font-medium border-[1.5px] transition-colors ${activeTab === tab.id ? 'bg-black text-white border-black' : 'bg-transparent text-black border-transparent hover:bg-gray-100'}`}
+                onClick={() => setActiveTab(tab.id)}
+              >
+                {tab.icon} {tab.label}
+              </button>
+            ))}
+          </nav>
+        </div>
+
+        {/* Main content */}
+        <div>
+          {activeTab === 'overview' && <OverviewTab stats={stats} health={health} onRefresh={fetchOverview}/>}
+          {activeTab === 'users' && <UsersTab token={token}/>}
+          {activeTab === 'documents' && <DocumentsTab token={token}/>}
+          {activeTab === 'graph' && <GraphCRUDTab token={token}/>}
+          {activeTab === 'ontology' && <OntologyGovernanceTab token={token}/>}
+          {activeTab === 'workers' && <WorkersTab token={token}/>}
+          {activeTab === 'enrichment' && <EnrichmentTab token={token}/>}
+          {activeTab === 'sandbox' && <SandboxTab token={token}/>}
+        </div>
+      </div>
+
+      <style>{`
+        @keyframes spin { 100% { transform: rotate(360deg); } }
+      `}</style>
+    </div>
+  );
+}

frontend-react/src/views/Home.tsx

@@ -0,0 +1,692 @@
+import React, { useEffect, useState, useRef } from 'react';
+import { useAuth } from '../context/AuthContext';
+import { Network, Server, Cpu, Database, Activity, ArrowRight, Zap, GitBranch, MessageSquare, TrendingUp, RefreshCw } from 'lucide-react';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000/api';
+
+// Animated counter hook
+function useCountUp(target: number, duration = 1200) {
+  const [val, setVal] = useState(0);
+  const prev = useRef(0);
+  useEffect(() => {
+    if (target === 0) { setVal(0); return; }
+    const start = prev.current;
+    const diff = target - start;
+    const startTime = performance.now();
+    const tick = (now: number) => {
+      const t = Math.min((now - startTime) / duration, 1);
+      const ease = 1 - Math.pow(1 - t, 3);
+      setVal(Math.round(start + diff * ease));
+      if (t < 1) requestAnimationFrame(tick);
+      else prev.current = target;
+    };
+    requestAnimationFrame(tick);
+  }, [target]);
+  return val;
+}
+
+const StatCounter: React.FC<{ value: number | string; label: string; suffix?: string }> = ({ value, label, suffix = '' }) => {
+  const numVal = typeof value === 'number' ? value : parseInt(String(value)) || 0;
+  const animated = useCountUp(numVal);
+  return (
+    <div className="hm-stat-block">
+      <div className="hm-stat-value">{typeof value === 'number' ? animated : value}{suffix}</div>
+      <div className="hm-stat-key">{label}</div>
+    </div>
+  );
+};
+
+const Home: React.FC = () => {
+  const { token, logout, user } = useAuth();
+  const [health, setHealth] = useState<any>(null);
+  const [stats, setStats] = useState<any>(null);
+  const [myStats, setMyStats] = useState<any>(null);
+  const [loading, setLoading] = useState(true);
+  const [lastRefresh, setLastRefresh] = useState<Date>(new Date());
+
+  const fetchData = async () => {
+    setLoading(true);
+    try {
+      const [healthRes, statsRes, myStatsRes] = await Promise.all([
+        fetch(`${API_BASE}/system/health`),
+        fetch(`${API_BASE}/system/stats`, { headers: { Authorization: `Bearer ${token}` } }),
+        fetch(`${API_BASE}/system/my-stats`, { headers: { Authorization: `Bearer ${token}` } }).catch(() => null),
+      ]);
+      if (statsRes.status === 401) { logout(); return; }
+      if (healthRes.ok) setHealth(await healthRes.json());
+      if (statsRes.ok) setStats(await statsRes.json());
+      if (myStatsRes?.ok) setMyStats(await myStatsRes.json());
+    } catch (err) {
+      console.error('Failed to fetch system data', err);
+    } finally {
+      setLoading(false);
+      setLastRefresh(new Date());
+    }
+  };
+
+  useEffect(() => {
+    fetchData();
+    const interval = setInterval(fetchData, 30000);
+    return () => clearInterval(interval);
+  }, [token]);
+
+  const isOnline = (v: boolean | undefined) => v === true;
+
+  const systemOk = health ? (isOnline(health.neo4j_connected) && isOnline(health.redis_connected)) : false;
+
+  return (
+    <div className="container fade-in max-w-[1300px] pb-12">
+
+      {/* ── Hero ─────────────────────────────────────── */}
+      <div className="hm-hero">
+        <div className="hm-hero-left">
+          <div className="hm-hero-label">CORTEX PLATFORM</div>
+          <h1 className="hm-hero-title">
+            Agentic Knowledge<br />
+            <span className="hm-hero-accent">Intelligence</span>
+          </h1>
+          <p className="hm-hero-sub">
+            Production-grade knowledge graph · Real-time extraction · Multi-hop reasoning
+          </p>
+          <div className="hm-hero-ctas">
+            <a href="/process" className="hm-cta-primary">
+              <Database size={16} /> Ingest Documents <ArrowRight size={14} />
+            </a>
+            <a href="/interact" className="hm-cta-secondary">
+              <Cpu size={16} /> Query Graph <ArrowRight size={14} />
+            </a>
+          </div>
+        </div>
+
+        <div className="hm-hero-right">
+          <div className={`hm-system-badge ${systemOk ? 'ok' : 'warn'}`}>
+            <span className={`hm-pulse-dot ${systemOk ? 'green' : 'yellow'}`} />
+            <span className="hm-badge-label">
+              {loading ? 'CHECKING...' : systemOk ? 'SYSTEM OPERATIONAL' : 'SYSTEM DEGRADED'}
+            </span>
+            <button className="hm-refresh-btn" onClick={fetchData} title="Refresh">
+              <RefreshCw size={13} className={loading ? 'animate-spin' : ''} />
+            </button>
+          </div>
+
+          <div className="hm-infra-stack">
+            {[
+              { label: 'NEO4J', ok: isOnline(health?.neo4j_connected) },
+              { label: 'REDIS', ok: isOnline(health?.redis_connected) },
+              { label: `${health?.workers_active ?? 0} WORKERS`, ok: true, neutral: true },
+              { label: 'API', ok: true },
+            ].map(s => (
+              <div key={s.label} className="hm-infra-row">
+                <span className={`hm-dot ${s.neutral ? 'neutral' : s.ok ? 'online' : 'offline'}`} />
+                <span className="hm-infra-name">{s.label}</span>
+                <span className={`hm-infra-badge ${s.neutral ? 'neutral' : s.ok ? 'ok' : 'fail'}`}>
+                  {s.neutral ? 'ACTIVE' : s.ok ? 'CONNECTED' : 'OFFLINE'}
+                </span>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      {/* ── Platform Metrics ─────────────────────────── */}
+      <div className="hm-section">
+        <div className="hm-section-label">PLATFORM METRICS</div>
+        <div className="hm-metrics-row">
+          <StatCounter value={stats?.documents_count ?? 0} label="DOCUMENTS" />
+          <div className="hm-metric-divider" />
+          <StatCounter value={stats?.entities_count ?? 0} label="ENTITIES" />
+          <div className="hm-metric-divider" />
+          <StatCounter value={stats?.relationships_count ?? 0} label="RELATIONSHIPS" />
+          <div className="hm-metric-divider" />
+          <StatCounter value={stats?.chunks_count ?? 0} label="CHUNKS" />
+          <div className="hm-metric-divider" />
+          <div className="hm-stat-block">
+            <div className="hm-stat-value text-2xl">
+              {stats?.ontology_version ?? '—'}
+            </div>
+            <div className="hm-stat-key">ONTOLOGY VER</div>
+          </div>
+        </div>
+      </div>
+
+      {/* ── Main Grid ────────────────────────────────── */}
+      <div className="hm-main-grid">
+
+        {/* Quick Actions */}
+        <div className="hm-card hm-actions-card">
+          <div className="hm-card-head">
+            <Activity size={16} /> QUICK ACTIONS
+          </div>
+          <div className="hm-action-list">
+            {[
+              { href: '/process',  icon: <Database size={18}/>,  label: 'INGEST DOCUMENTS',  desc: 'Upload PDFs, text, or crawl URLs' },
+              { href: '/interact', icon: <Cpu size={18}/>,       label: 'QUERY KNOWLEDGE',   desc: 'Ask questions across the graph' },
+              { href: '/simulate', icon: <Network size={18}/>,   label: 'EXPLORE NODES',     desc: 'Interactive D3 force visualization' },
+              { href: '/ontology', icon: <Server size={18}/>,    label: 'MANAGE ONTOLOGY',   desc: 'Edit schema & run AI refinement' },
+              { href: '/insights', icon: <TrendingUp size={18}/>,label: 'INSIGHTS',           desc: 'Quality metrics & AI reports' },
+            ].map(a => (
+              <a key={a.href} href={a.href} className="hm-action-item">
+                <span className="hm-action-icon">{a.icon}</span>
+                <div className="hm-action-text">
+                  <div className="hm-action-label">{a.label}</div>
+                  <div className="hm-action-desc">{a.desc}</div>
+                </div>
+                <ArrowRight size={14} className="hm-action-arrow" />
+              </a>
+            ))}
+          </div>
+        </div>
+
+        {/* Right column: My Activity + Feature cards */}
+        <div className="flex flex-col gap-6">
+
+          {/* User Activity */}
+          <div className="hm-card">
+            <div className="hm-card-head">
+              <MessageSquare size={16} /> MY ACTIVITY
+              {user && <span className="ml-auto font-mono text-[0.7rem] text-[#666666]">@{user.username}</span>}
+            </div>
+            <div className="hm-activity-grid">
+              <div className="hm-activity-chip">
+                <div className="hm-activity-val">{myStats?.conversation_count ?? '—'}</div>
+                <div className="hm-activity-key">CONVERSATIONS</div>
+              </div>
+              <div className="hm-activity-chip">
+                <div className="hm-activity-val">{myStats?.message_count ?? '—'}</div>
+                <div className="hm-activity-key">QUERIES SENT</div>
+              </div>
+              <div className="hm-activity-chip">
+                <div className="hm-activity-val">{myStats?.last_active ? new Date(myStats.last_active).toLocaleDateString() : '—'}</div>
+                <div className="hm-activity-key">LAST ACTIVE</div>
+              </div>
+            </div>
+            {!myStats && (
+              <div style={{ fontFamily: 'var(--font-mono)', fontSize: '0.78rem', color: 'var(--muted-color)', marginTop: '0.75rem' }}>
+                Start querying the graph to build your activity history.
+              </div>
+            )}
+          </div>
+
+          {/* Graph intelligence card */}
+          <div className="hm-card hm-graph-card">
+            <div className="hm-card-head">
+              <GitBranch size={16} /> KNOWLEDGE GRAPH
+            </div>
+            <div style={{ fontSize: '0.85rem', lineHeight: 1.7, color: 'var(--muted-color)', marginBottom: '1rem' }}>
+              Neo4j-powered semantic knowledge graph. Multi-hop reasoning, entity enrichment, and community detection built in.
+            </div>
+            <div style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap' }}>
+              {['Entities', 'Relationships', 'Communities', 'Graph Export'].map(tag => (
+                <span key={tag} className="hm-tag">{tag}</span>
+              ))}
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* ── Feature Showcase ─────────────────────────── */}
+      <div className="hm-features-section">
+        <div className="hm-section-label" style={{ marginBottom: '1.5rem' }}>PLATFORM CAPABILITIES</div>
+        <div className="hm-features-grid">
+          {[
+            {
+              icon: <Database size={24}/>,
+              title: 'DOCUMENT INGESTION',
+              desc: 'Ingest PDFs, text files, Markdown, and web URLs. Celery workers extract entities and relationships into the knowledge graph automatically via LLM pipelines.',
+              color: '#2563eb',
+            },
+            {
+              icon: <Network size={24}/>,
+              title: 'GRAPH INTELLIGENCE',
+              desc: 'Neo4j-powered knowledge graph with rich entity relationships. Query across documents globally or per-source with full ontology control.',
+              color: '#7c3aed',
+            },
+            {
+              icon: <Cpu size={24}/>,
+              title: 'AGENTIC LOGIC',
+              desc: 'Multi-step ReACT reasoning agent that searches the graph, retrieves relevant chunks, and streams answers with confidence scoring in real time.',
+              color: '#059669',
+            },
+            {
+              icon: <Zap size={24}/>,
+              title: 'LLM-AS-JUDGE',
+              desc: 'Inline faithfulness evaluation using heuristic scoring. Detects hallucination risk, context precision, and answer quality on every response.',
+              color: '#d97706',
+            },
+            {
+              icon: <Activity size={24}/>,
+              title: 'LIVE SIMULATION',
+              desc: 'Interactive D3 force graph with color-coded entity types, physics controls, fullscreen mode, PNG export, and node detail modals.',
+              color: '#dc2626',
+            },
+            {
+              icon: <TrendingUp size={24}/>,
+              title: 'ONTOLOGY DRIFT',
+              desc: 'Automated schema drift detection that spots when new data no longer fits the current ontology. Propose and approve schema expansions.',
+              color: '#0891b2',
+            },
+          ].map(f => (
+            <div key={f.title} className="hm-feature-card" style={{ '--feature-color': f.color } as any}>
+              <div className="hm-feature-icon" style={{ color: f.color }}>{f.icon}</div>
+              <div className="hm-feature-title">{f.title}</div>
+              <div className="hm-feature-desc">{f.desc}</div>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* Footer bar */}
+      <div className="hm-footer-bar">
+        <span className="hm-footer-brand">CORTEX_PLATFORM</span>
+        <span style={{ color: 'var(--muted-color)', fontSize: '0.72rem', fontFamily: 'var(--font-mono)' }}>
+          Last refreshed: {lastRefresh.toLocaleTimeString()}
+        </span>
+        <span style={{ color: 'var(--muted-color)', fontSize: '0.72rem', fontFamily: 'var(--font-mono)' }}>
+          v{health ? '1.0' : '—'} · Neo4j + Redis + Celery
+        </span>
+      </div>
+
+      <style>{`
+        /* ── Hero ── */
+        .hm-hero {
+          display: grid;
+          grid-template-columns: 1fr 320px;
+          gap: 2rem;
+          padding: 2.5rem 0 2rem;
+          border-bottom: 3px solid #000;
+          margin-bottom: 2.5rem;
+          align-items: center;
+        }
+        .hm-hero-label {
+          font-family: var(--font-mono);
+          font-size: 0.72rem;
+          font-weight: 700;
+          letter-spacing: 3px;
+          color: var(--muted-color);
+          margin-bottom: 0.75rem;
+        }
+        .hm-hero-title {
+          font-family: var(--font-display);
+          font-size: clamp(2rem, 4vw, 3rem);
+          font-weight: 800;
+          line-height: 1.1;
+          margin-bottom: 0.75rem;
+          letter-spacing: -0.5px;
+        }
+        .hm-hero-accent {
+          position: relative;
+          display: inline-block;
+        }
+        .hm-hero-accent::after {
+          content: '';
+          position: absolute;
+          left: 0; bottom: 2px;
+          width: 100%; height: 4px;
+          background: #000;
+        }
+        .hm-hero-sub {
+          color: var(--muted-color);
+          font-size: 0.95rem;
+          line-height: 1.6;
+          margin-bottom: 1.5rem;
+          max-width: 480px;
+        }
+        .hm-hero-ctas {
+          display: flex;
+          gap: 0.75rem;
+          flex-wrap: wrap;
+        }
+        .hm-cta-primary {
+          display: inline-flex;
+          align-items: center;
+          gap: 0.5rem;
+          background: #000;
+          color: #fff;
+          padding: 0.65rem 1.25rem;
+          font-family: var(--font-mono);
+          font-size: 0.8rem;
+          font-weight: 700;
+          letter-spacing: 0.5px;
+          text-decoration: none;
+          transition: background 0.15s, transform 0.15s;
+          border: 2px solid #000;
+        }
+        .hm-cta-primary:hover {
+          background: #333;
+          color: #fff;
+          transform: translateY(-1px);
+          box-shadow: 3px 3px 0 rgba(0,0,0,0.2);
+        }
+        .hm-cta-secondary {
+          display: inline-flex;
+          align-items: center;
+          gap: 0.5rem;
+          background: transparent;
+          color: #000;
+          padding: 0.65rem 1.25rem;
+          font-family: var(--font-mono);
+          font-size: 0.8rem;
+          font-weight: 700;
+          letter-spacing: 0.5px;
+          text-decoration: none;
+          border: 2px solid #000;
+          transition: background 0.15s, transform 0.15s;
+        }
+        .hm-cta-secondary:hover {
+          background: #000;
+          color: #fff;
+          transform: translateY(-1px);
+        }
+
+        /* System badge */
+        .hm-system-badge {
+          display: flex;
+          align-items: center;
+          gap: 0.6rem;
+          border: 2px solid #000;
+          padding: 0.5rem 0.85rem;
+          margin-bottom: 1rem;
+          font-family: var(--font-mono);
+          font-size: 0.72rem;
+          font-weight: 700;
+          letter-spacing: 1px;
+        }
+        .hm-system-badge.warn { border-color: #d97706; color: #d97706; }
+        .hm-pulse-dot {
+          width: 8px; height: 8px;
+          border-radius: 50%;
+          flex-shrink: 0;
+          animation: pulseGlow 2s ease-in-out infinite;
+        }
+        .hm-pulse-dot.green { background: #16a34a; box-shadow: 0 0 0 0 rgba(22,163,74,0.4); }
+        .hm-pulse-dot.yellow { background: #d97706; box-shadow: 0 0 0 0 rgba(217,119,6,0.4); }
+        @keyframes pulseGlow {
+          0%, 100% { box-shadow: 0 0 0 0 rgba(22,163,74,0.4); }
+          50% { box-shadow: 0 0 0 5px rgba(22,163,74,0); }
+        }
+        .hm-badge-label { flex: 1; }
+        .hm-refresh-btn {
+          background: none;
+          border: none;
+          cursor: pointer;
+          padding: 0;
+          color: var(--muted-color);
+          display: flex;
+          align-items: center;
+          transition: color 0.15s;
+        }
+        .hm-refresh-btn:hover { color: #000; background: none; }
+
+        /* Infra stack */
+        .hm-infra-stack { display: flex; flex-direction: column; gap: 0.5rem; }
+        .hm-infra-row {
+          display: flex;
+          align-items: center;
+          gap: 0.5rem;
+          padding: 0.4rem 0.6rem;
+          border: 1.5px solid #e5e5e5;
+          font-family: var(--font-mono);
+          font-size: 0.78rem;
+        }
+        .hm-dot { width: 7px; height: 7px; border-radius: 50%; flex-shrink: 0; }
+        .hm-dot.online { background: #16a34a; }
+        .hm-dot.offline { background: #dc2626; }
+        .hm-dot.neutral { background: #9ca3af; }
+        .hm-infra-name { flex: 1; font-weight: 600; color: var(--muted-color); }
+        .hm-infra-badge {
+          font-size: 0.65rem;
+          font-weight: 700;
+          padding: 1px 6px;
+          letter-spacing: 0.5px;
+        }
+        .hm-infra-badge.ok { background: #dcfce7; color: #16a34a; }
+        .hm-infra-badge.fail { background: #fee2e2; color: #dc2626; }
+        .hm-infra-badge.neutral { background: #f3f4f6; color: #6b7280; }
+
+        /* ── Section label ── */
+        .hm-section { margin-bottom: 2.5rem; }
+        .hm-section-label {
+          font-family: var(--font-mono);
+          font-size: 0.68rem;
+          font-weight: 700;
+          letter-spacing: 3px;
+          color: var(--muted-color);
+          margin-bottom: 1rem;
+        }
+
+        /* ── Metrics row ── */
+        .hm-metrics-row {
+          display: flex;
+          align-items: center;
+          border: 3px solid #000;
+          overflow: hidden;
+        }
+        .hm-stat-block {
+          flex: 1;
+          min-width: 0;
+          padding: 1.25rem 1.5rem;
+          text-align: center;
+        }
+        .hm-stat-value {
+          font-family: var(--font-mono);
+          font-size: 2.2rem;
+          font-weight: 900;
+          line-height: 1;
+          margin-bottom: 0.3rem;
+        }
+        .hm-stat-key {
+          font-family: var(--font-mono);
+          font-size: 0.6rem;
+          color: var(--muted-color);
+          letter-spacing: 1.5px;
+          font-weight: 700;
+        }
+        .hm-metric-divider {
+          width: 1px;
+          height: 60px;
+          background: #000;
+          flex-shrink: 0;
+        }
+
+        /* ── Main grid ── */
+        .hm-main-grid {
+          display: grid;
+          grid-template-columns: 1fr 360px;
+          gap: 1.5rem;
+          margin-bottom: 3rem;
+        }
+
+        /* ── Card base ── */
+        .hm-card {
+          border: 2px solid #000;
+          padding: 1.5rem;
+          background: #fff;
+          transition: transform 0.15s, box-shadow 0.15s;
+        }
+        .hm-card:hover {
+          transform: translateY(-2px);
+          box-shadow: 4px 4px 0 #000;
+        }
+        .hm-card-head {
+          display: flex;
+          align-items: center;
+          gap: 0.5rem;
+          font-family: var(--font-mono);
+          font-size: 0.72rem;
+          font-weight: 700;
+          letter-spacing: 1.5px;
+          margin-bottom: 1.25rem;
+          padding-bottom: 0.75rem;
+          border-bottom: 2px solid #000;
+        }
+
+        /* ── Actions ── */
+        .hm-actions-card {
+          background: #fafafa;
+        }
+        .hm-action-list { display: flex; flex-direction: column; gap: 0.4rem; }
+        .hm-action-item {
+          display: flex;
+          align-items: center;
+          gap: 0.75rem;
+          padding: 0.7rem 0.75rem;
+          border: 1.5px solid #e5e5e5;
+          text-decoration: none;
+          color: #000;
+          transition: all 0.15s;
+          background: #fff;
+        }
+        .hm-action-item:hover {
+          background: #000;
+          color: #fff;
+          border-color: #000;
+          transform: translateX(3px);
+          box-shadow: -3px 3px 0 rgba(0,0,0,0.1);
+        }
+        .hm-action-icon {
+          width: 36px; height: 36px;
+          display: flex; align-items: center; justify-content: center;
+          background: #000;
+          color: #fff;
+          flex-shrink: 0;
+          transition: background 0.15s;
+        }
+        .hm-action-item:hover .hm-action-icon { background: #fff; color: #000; }
+        .hm-action-text { flex: 1; min-width: 0; }
+        .hm-action-label {
+          font-family: var(--font-mono);
+          font-size: 0.8rem;
+          font-weight: 700;
+          letter-spacing: 0.5px;
+        }
+        .hm-action-desc {
+          font-size: 0.75rem;
+          color: var(--muted-color);
+          margin-top: 0.1rem;
+        }
+        .hm-action-item:hover .hm-action-desc { color: rgba(255,255,255,0.7); }
+        .hm-action-arrow { flex-shrink: 0; transition: transform 0.15s; }
+        .hm-action-item:hover .hm-action-arrow { transform: translateX(3px); }
+
+        /* ── Activity ── */
+        .hm-activity-grid {
+          display: grid;
+          grid-template-columns: repeat(3, 1fr);
+          gap: 0.75rem;
+        }
+        .hm-activity-chip {
+          border: 1.5px solid #e5e5e5;
+          padding: 0.75rem 0.5rem;
+          text-align: center;
+        }
+        .hm-activity-val {
+          font-family: var(--font-mono);
+          font-size: 1.3rem;
+          font-weight: 900;
+          line-height: 1;
+          margin-bottom: 0.25rem;
+        }
+        .hm-activity-key {
+          font-family: var(--font-mono);
+          font-size: 0.58rem;
+          color: var(--muted-color);
+          letter-spacing: 1px;
+          font-weight: 700;
+        }
+
+        /* ── Graph card ── */
+        .hm-graph-card {}
+        .hm-tag {
+          display: inline-block;
+          background: #f3f4f6;
+          border: 1.5px solid #e5e5e5;
+          font-family: var(--font-mono);
+          font-size: 0.68rem;
+          font-weight: 700;
+          padding: 2px 8px;
+          letter-spacing: 0.5px;
+        }
+
+        /* ── Features ── */
+        .hm-features-section {
+          border-top: 3px solid #000;
+          padding-top: 2.5rem;
+          margin-bottom: 2rem;
+        }
+        .hm-features-grid {
+          display: grid;
+          grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+          gap: 1rem;
+        }
+        .hm-feature-card {
+          border: 2px solid #e5e5e5;
+          padding: 1.5rem;
+          transition: border-color 0.2s, box-shadow 0.2s, transform 0.2s;
+          position: relative;
+          overflow: hidden;
+        }
+        .hm-feature-card::before {
+          content: '';
+          position: absolute;
+          left: 0; top: 0; bottom: 0;
+          width: 3px;
+          background: var(--feature-color, #000);
+          opacity: 0;
+          transition: opacity 0.2s;
+        }
+        .hm-feature-card:hover {
+          border-color: #000;
+          box-shadow: 4px 4px 0 #000;
+          transform: translateY(-2px);
+        }
+        .hm-feature-card:hover::before { opacity: 1; }
+        .hm-feature-icon {
+          margin-bottom: 0.85rem;
+          transition: transform 0.2s;
+        }
+        .hm-feature-card:hover .hm-feature-icon { transform: scale(1.1); }
+        .hm-feature-title {
+          font-family: var(--font-mono);
+          font-size: 0.72rem;
+          font-weight: 700;
+          letter-spacing: 1px;
+          margin-bottom: 0.5rem;
+        }
+        .hm-feature-desc {
+          font-size: 0.82rem;
+          color: var(--muted-color);
+          line-height: 1.65;
+        }
+
+        /* ── Footer ── */
+        .hm-footer-bar {
+          display: flex;
+          align-items: center;
+          gap: 1.5rem;
+          border-top: 1px solid #e5e5e5;
+          padding-top: 1.25rem;
+          margin-top: 1rem;
+        }
+        .hm-footer-brand {
+          font-family: var(--font-mono);
+          font-size: 0.72rem;
+          font-weight: 700;
+          letter-spacing: 2px;
+          margin-right: auto;
+        }
+
+        /* ── Responsive ── */
+        @media (max-width: 900px) {
+          .hm-hero { grid-template-columns: 1fr; }
+          .hm-hero-right { order: -1; }
+          .hm-main-grid { grid-template-columns: 1fr; }
+          .hm-metrics-row { flex-wrap: wrap; }
+          .hm-metric-divider { display: none; }
+          .hm-stat-block { flex: 0 0 50%; border-bottom: 1px solid #000; }
+        }
+      `}</style>
+    </div>
+  );
+};
+
+export default Home;

frontend-react/src/views/InsightsView.tsx

@@ -0,0 +1,872 @@
+import React, { useState, useEffect, useCallback } from 'react';
+import { useAuth } from '../context/AuthContext';
+import { BarChart2, TrendingUp, AlertTriangle, CheckCircle, RefreshCw, Zap, FileText, GitCommit, MessageSquare } from 'lucide-react';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000/api';
+
+interface EvalDashboard {
+  total_evaluations: number;
+  avg_overall_score: number;
+  avg_faithfulness: number;
+  avg_relevancy: number;
+  hallucination_rate: number;
+  trend_data: TrendPoint[];
+}
+
+interface TrendPoint {
+  timestamp: string;
+  overall_score: number;
+  faithfulness: number;
+  answer_relevancy: number;
+  hallucination_detected: boolean;
+  document_id?: string;
+}
+
+interface EvalForm {
+  question: string;
+  answer: string;
+  contexts: string;
+}
+
+// Helper: build markdown from report result
+function buildReportMarkdown(result: any, topic: string): string {
+  const lines: string[] = [];
+  lines.push(`# ${result.topic || topic}`);
+  lines.push('');
+  if (result.confidence !== undefined) {
+    lines.push(`**Confidence:** ${(result.confidence * 100).toFixed(1)}%`);
+  }
+  if (result.tool_calls_made !== undefined) {
+    lines.push(`**Tool calls:** ${result.tool_calls_made}`);
+  }
+  lines.push(`**Generated:** ${new Date().toLocaleString()}`);
+  lines.push('');
+
+  if (result.executive_summary) {
+    lines.push('## Executive Summary');
+    lines.push('');
+    lines.push(result.executive_summary);
+    lines.push('');
+  }
+
+  if (result.sections && typeof result.sections === 'object' && !Array.isArray(result.sections)) {
+    Object.entries(result.sections).forEach(([title, content], i) => {
+      lines.push(`## ${i + 1}. ${title}`);
+      lines.push('');
+      lines.push(String(content));
+      lines.push('');
+    });
+  } else if (Array.isArray(result.sections)) {
+    result.sections.forEach((s: any, i: number) => {
+      lines.push(`## ${i + 1}. ${s.title || ''}`);
+      lines.push('');
+      lines.push(s.content || '');
+      lines.push('');
+    });
+  } else if (!result.sections) {
+    lines.push(result.report || result.content || result.markdown || JSON.stringify(result, null, 2));
+    lines.push('');
+  }
+
+  if (result.key_entities && result.key_entities.length > 0) {
+    lines.push('## Key Entities');
+    lines.push('');
+    lines.push(result.key_entities.join(', '));
+  }
+
+  return lines.join('\n');
+}
+
+const InsightsView: React.FC = () => {
+  const { token } = useAuth();
+  const [dashboard, setDashboard] = useState<EvalDashboard | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [evalForm, setEvalForm] = useState<EvalForm>({ question: '', answer: '', contexts: '' });
+  const [evalResult, setEvalResult] = useState<any>(null);
+  const [evalLoading, setEvalLoading] = useState(false);
+  const [communities, setCommunities] = useState<any[]>([]);
+  const [communityLoading, setCommunityLoading] = useState(false);
+  const [activeTab, setActiveTab] = useState<'metrics' | 'evaluate' | 'communities' | 'export' | 'report' | 'graph-update' | 'entity-chat'>('metrics');
+
+  // Report Agent state
+  const [reportTopic, setReportTopic] = useState('');
+  const [reportDepth, setReportDepth] = useState(3);
+  const [reportResult, setReportResult] = useState<any>(null);
+  const [reportLoading, setReportLoading] = useState(false);
+  const [reportTimestamp, setReportTimestamp] = useState<Date | null>(null);
+  const [copyDone, setCopyDone] = useState(false);
+
+  // Graph Update state
+  const [updateText, setUpdateText] = useState('');
+  const [updateResult, setUpdateResult] = useState<any>(null);
+  const [updateLoading, setUpdateLoading] = useState(false);
+
+  // Entity Chat state
+  const [entities, setEntities] = useState<any[]>([]);
+  const [selectedEntity, setSelectedEntity] = useState('');
+  const [entityContext, setEntityContext] = useState('');
+  const [chatMsg, setChatMsg] = useState('');
+  const [chatHistory, setChatHistory] = useState<{role: string; content: string}[]>([]);
+  const [chatLoading, setChatLoading] = useState(false);
+
+  const fetchDashboard = useCallback(async () => {
+    setLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/eval/dashboard?limit=200`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) setDashboard(await res.json());
+    } catch (e) { console.error(e); }
+    setLoading(false);
+  }, [token]);
+
+  const fetchCommunities = useCallback(async () => {
+    setCommunityLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/graph/communities?limit=30`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const data = await res.json();
+        setCommunities(data.communities || []);
+      }
+    } catch (e) { console.error(e); }
+    setCommunityLoading(false);
+  }, [token]);
+
+  const fetchEntities = useCallback(async () => {
+    try {
+      const res = await fetch(`${API_BASE}/admin/graph/nodes?query=&limit=200`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const data = await res.json();
+        setEntities((data.nodes || []).slice(0, 100));
+      }
+    } catch {}
+  }, [token]);
+
+  useEffect(() => {
+    fetchDashboard();
+    fetchCommunities();
+    fetchEntities();
+  }, [fetchDashboard, fetchCommunities, fetchEntities]);
+
+  const runEval = async () => {
+    if (!evalForm.question || !evalForm.answer || !evalForm.contexts) return;
+    setEvalLoading(true);
+    setEvalResult(null);
+    try {
+      const res = await fetch(`${API_BASE}/eval/score`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+          question: evalForm.question,
+          answer: evalForm.answer,
+          contexts: evalForm.contexts.split('\n---\n').map(c => c.trim()).filter(Boolean)
+        })
+      });
+      if (res.ok) {
+        setEvalResult(await res.json());
+        fetchDashboard(); // Refresh metrics
+      }
+    } catch (e) { console.error(e); }
+    setEvalLoading(false);
+  };
+
+  const runReport = async () => {
+    if (!reportTopic.trim()) return;
+    setReportLoading(true); setReportResult(null);
+    try {
+      const res = await fetch(`${API_BASE}/report`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ topic: reportTopic, depth: reportDepth })
+      });
+      if (res.ok) {
+        setReportResult(await res.json());
+        setReportTimestamp(new Date());
+      }
+    } catch (e) { console.error(e); }
+    setReportLoading(false);
+  };
+
+  const runGraphUpdate = async () => {
+    if (!updateText.trim()) return;
+    setUpdateLoading(true); setUpdateResult(null);
+    try {
+      const res = await fetch(`${API_BASE}/graph/update`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ text: updateText })
+      });
+      if (res.ok) setUpdateResult(await res.json());
+    } catch (e) { console.error(e); }
+    setUpdateLoading(false);
+  };
+
+  const sendEntityChat = async () => {
+    if (!selectedEntity || !chatMsg.trim()) return;
+    const userMsg = { role: 'user', content: chatMsg };
+    setChatHistory(h => [...h, userMsg]);
+    setChatMsg('');
+    setChatLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/entities/${encodeURIComponent(selectedEntity)}/chat`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ message: userMsg.content })
+      });
+      if (res.ok) {
+        const data = await res.json();
+        setChatHistory(h => [...h, { role: 'assistant', content: data.response || data.answer || JSON.stringify(data) }]);
+      }
+    } catch (e) { console.error(e); }
+    setChatLoading(false);
+  };
+
+  const assignCommunities = async () => {
+    setCommunityLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/graph/communities/assign`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const data = await res.json();
+        alert(`✓ ${data.message}`);
+        fetchCommunities();
+      }
+    } catch (e) { console.error(e); }
+    setCommunityLoading(false);
+  };
+
+  const exportGraph = async (fmt: string) => {
+    const res = await fetch(`${API_BASE}/graph/export?format=${fmt}`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!res.ok) return;
+    const blob = await res.blob();
+    const ext = fmt === 'json' ? 'json' : fmt === 'cypher' ? 'cypher' : 'graphml';
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url; a.download = `graph_export.${ext}`; a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  const handleCopyReport = () => {
+    if (!reportResult) return;
+    const text = buildReportMarkdown(reportResult, reportTopic);
+    navigator.clipboard.writeText(text).then(() => {
+      setCopyDone(true);
+      setTimeout(() => setCopyDone(false), 2000);
+    });
+  };
+
+  const handleDownloadReport = () => {
+    if (!reportResult) return;
+    const text = buildReportMarkdown(reportResult, reportTopic);
+    const blob = new Blob([text], { type: 'text/markdown' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `report_${reportTopic.slice(0, 30).replace(/\s+/g, '_')}.md`;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  const score2color = (s: number) => {
+    if (s >= 0.8) return '#16a34a';
+    if (s >= 0.6) return '#d97706';
+    return '#dc2626';
+  };
+  const score2label = (s: number) => s >= 0.8 ? 'HIGH' : s >= 0.6 ? 'MEDIUM' : 'LOW';
+
+  const ScoreBar: React.FC<{ label: string; value: number }> = ({ label, value }) => (
+    <div style={{ marginBottom: '1rem' }}>
+      <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '0.25rem', fontFamily: 'var(--font-mono)', fontSize: '0.8rem' }}>
+        <span>{label}</span>
+        <span style={{ color: score2color(value), fontWeight: 700 }}>{(value * 100).toFixed(1)}%</span>
+      </div>
+      <div style={{ height: '8px', background: '#e5e7eb', position: 'relative' }}>
+        <div style={{ position: 'absolute', left: 0, top: 0, height: '100%', width: `${value * 100}%`, background: score2color(value), transition: 'width 0.6s ease' }} />
+      </div>
+    </div>
+  );
+
+  const confidenceBadgeColor = (c: number) =>
+    c >= 0.8 ? '#16a34a' : c >= 0.6 ? '#d97706' : '#dc2626';
+
+  return (
+    <div className="container" style={{ maxWidth: '1100px', paddingBottom: '3rem' }}>
+      <div className="page-header flex-between" style={{ marginBottom: '2rem' }}>
+        <div>
+          <h1>INSIGHTS HQ</h1>
+          <p className="mono-text">QUALITY METRICS // EVAL DASHBOARD // GRAPH INTELLIGENCE</p>
+        </div>
+        <div style={{ display: 'flex', gap: '0.5rem' }}>
+          <button className="app-btn mono-text" onClick={fetchDashboard} disabled={loading} style={{ padding: '0.5rem 1rem', fontSize: '0.8rem' }}>
+            <RefreshCw size={14} style={{ display: 'inline', marginRight: '0.4rem' }} />
+            REFRESH
+          </button>
+        </div>
+      </div>
+
+      {/* Tab Nav */}
+      <div style={{ display: 'flex', borderBottom: '3px solid #000', marginBottom: '2rem', gap: 0, flexWrap: 'wrap' }}>
+        {([
+          { id: 'metrics', label: 'METRICS' },
+          { id: 'evaluate', label: 'EVALUATE' },
+          { id: 'communities', label: 'COMMUNITIES' },
+          { id: 'export', label: 'EXPORT' },
+          { id: 'report', label: '⚡ REPORT' },
+          { id: 'graph-update', label: '↑ LIVE UPDATE' },
+          { id: 'entity-chat', label: '💬 ENTITY CHAT' },
+        ] as const).map(t => (
+          <button
+            key={t.id}
+            onClick={() => setActiveTab(t.id as any)}
+            className="mono-text"
+            style={{
+              padding: '0.65rem 1.2rem', fontWeight: 700, fontSize: '0.78rem', letterSpacing: '0.8px',
+              border: 'none', borderBottom: activeTab === t.id ? '3px solid #000' : 'none',
+              background: activeTab === t.id ? '#000' : 'transparent',
+              color: activeTab === t.id ? '#fff' : '#000', cursor: 'pointer',
+              marginBottom: '-3px', textTransform: 'uppercase', whiteSpace: 'nowrap'
+            }}
+          >
+            {t.label}
+          </button>
+        ))}
+      </div>
+
+      {/* ── METRICS TAB ── */}
+      {activeTab === 'metrics' && (
+        <div>
+          {loading ? (
+            <div className="mono-text" style={{ textAlign: 'center', padding: '3rem', color: '#aaa' }}>LOADING METRICS...</div>
+          ) : !dashboard || dashboard.total_evaluations === 0 ? (
+            <div style={{ border: '3px solid #000', padding: '3rem', textAlign: 'center' }}>
+              <BarChart2 size={48} style={{ marginBottom: '1rem', opacity: 0.3 }} />
+              <p className="mono-text" style={{ color: '#777' }}>NO EVALUATION DATA YET</p>
+              <p className="mono-text" style={{ color: '#999', fontSize: '0.85rem', marginTop: '0.5rem' }}>
+                Use the EVALUATE tab to score Q&A pairs and build your quality history.
+              </p>
+            </div>
+          ) : (
+            <>
+              {/* KPI Cards */}
+              <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', gap: '1rem', marginBottom: '2rem' }}>
+                {[
+                  { label: 'TOTAL EVALS', value: dashboard.total_evaluations, raw: true, icon: <BarChart2 size={20} /> },
+                  { label: 'AVG QUALITY', value: dashboard.avg_overall_score, icon: <TrendingUp size={20} /> },
+                  { label: 'FAITHFULNESS', value: dashboard.avg_faithfulness, icon: <CheckCircle size={20} /> },
+                  { label: 'HALLUCINATION RATE', value: dashboard.hallucination_rate, invert: true, icon: <AlertTriangle size={20} /> },
+                ].map(card => (
+                  <div key={card.label} style={{ border: '3px solid #000', padding: '1.5rem', background: (card.invert ? dashboard.hallucination_rate > 0.3 : false) ? '#fff5f5' : '#fff' }}>
+                    <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', marginBottom: '1rem' }}>
+                      <span className="mono-text" style={{ fontSize: '0.7rem', fontWeight: 700, letterSpacing: '1px', color: '#666' }}>{card.label}</span>
+                      {card.icon}
+                    </div>
+                    <div className="mono-text" style={{
+                      fontSize: '2rem', fontWeight: 900,
+                      color: card.raw ? '#000' : score2color(card.invert ? 1 - (card.value as number) : (card.value as number))
+                    }}>
+                      {card.raw ? card.value : `${((card.value as number) * 100).toFixed(1)}%`}
+                    </div>
+                  </div>
+                ))}
+              </div>
+
+              {/* Score Breakdown */}
+              <div style={{ border: '3px solid #000', padding: '1.5rem', marginBottom: '2rem' }}>
+                <h3 className="mono-text" style={{ marginBottom: '1.5rem', borderBottom: '1px dotted #000', paddingBottom: '0.5rem' }}>METRIC BREAKDOWN</h3>
+                <ScoreBar label="Overall Quality Score" value={dashboard.avg_overall_score} />
+                <ScoreBar label="Faithfulness (grounding)" value={dashboard.avg_faithfulness} />
+                <ScoreBar label="Answer Relevancy" value={dashboard.avg_relevancy} />
+                <ScoreBar label="Non-hallucination Rate" value={1 - dashboard.hallucination_rate} />
+              </div>
+
+              {/* Trend Table */}
+              {dashboard.trend_data.length > 0 && (
+                <div style={{ border: '3px solid #000', padding: '1.5rem' }}>
+                  <h3 className="mono-text" style={{ marginBottom: '1.5rem', borderBottom: '1px dotted #000', paddingBottom: '0.5rem' }}>EVALUATION HISTORY (LATEST {Math.min(dashboard.trend_data.length, 20)})</h3>
+                  <div style={{ overflowX: 'auto' }}>
+                    <table style={{ width: '100%', borderCollapse: 'collapse', fontFamily: 'var(--font-mono)', fontSize: '0.8rem' }}>
+                      <thead>
+                        <tr style={{ borderBottom: '2px solid #000' }}>
+                          {['TIMESTAMP', 'QUALITY', 'FAITHFULNESS', 'RELEVANCY', 'HALLUCINATION'].map(h => (
+                            <th key={h} style={{ padding: '0.5rem', textAlign: 'left', fontWeight: 700 }}>{h}</th>
+                          ))}
+                        </tr>
+                      </thead>
+                      <tbody>
+                        {dashboard.trend_data.slice(0, 20).map((p, i) => (
+                          <tr key={i} style={{ borderBottom: '1px dotted #ddd', background: i % 2 === 0 ? '#fafafa' : '#fff' }}>
+                            <td style={{ padding: '0.5rem' }}>{p.timestamp}</td>
+                            <td style={{ padding: '0.5rem', color: score2color(p.overall_score), fontWeight: 700 }}>{(p.overall_score * 100).toFixed(1)}%</td>
+                            <td style={{ padding: '0.5rem', color: score2color(p.faithfulness) }}>{(p.faithfulness * 100).toFixed(1)}%</td>
+                            <td style={{ padding: '0.5rem', color: score2color(p.answer_relevancy) }}>{(p.answer_relevancy * 100).toFixed(1)}%</td>
+                            <td style={{ padding: '0.5rem' }}>
+                              <span style={{ background: p.hallucination_detected ? '#dc2626' : '#16a34a', color: '#fff', padding: '0.1rem 0.5rem', fontSize: '0.7rem', fontWeight: 700 }}>
+                                {p.hallucination_detected ? 'YES' : 'NO'}
+                              </span>
+                            </td>
+                          </tr>
+                        ))}
+                      </tbody>
+                    </table>
+                  </div>
+                </div>
+              )}
+            </>
+          )}
+        </div>
+      )}
+
+      {/* ── EVALUATE TAB ── */}
+      {activeTab === 'evaluate' && (
+        <div>
+          <div style={{ border: '3px solid #000', padding: '2rem', marginBottom: '2rem' }}>
+            <h3 className="mono-text" style={{ marginBottom: '1.5rem' }}>
+              <Zap size={16} style={{ display: 'inline', marginRight: '0.5rem' }} />
+              SCORE A Q&A PAIR
+            </h3>
+            <p className="mono-text" style={{ fontSize: '0.8rem', color: '#666', marginBottom: '1.5rem' }}>
+              Paste a question, its generated answer, and the retrieved context chunks (separate chunks with "---").
+            </p>
+
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+              <div>
+                <label className="mono-text" style={{ fontSize: '0.8rem', fontWeight: 700, display: 'block', marginBottom: '0.5rem' }}>QUESTION</label>
+                <textarea value={evalForm.question} onChange={e => setEvalForm(f => ({ ...f, question: e.target.value }))}
+                  rows={2} style={{ width: '100%', border: '2px solid #000', padding: '0.75rem', fontFamily: 'var(--font-mono)', fontSize: '0.9rem', resize: 'vertical', boxSizing: 'border-box' }} />
+              </div>
+              <div>
+                <label className="mono-text" style={{ fontSize: '0.8rem', fontWeight: 700, display: 'block', marginBottom: '0.5rem' }}>GENERATED ANSWER</label>
+                <textarea value={evalForm.answer} onChange={e => setEvalForm(f => ({ ...f, answer: e.target.value }))}
+                  rows={4} style={{ width: '100%', border: '2px solid #000', padding: '0.75rem', fontFamily: 'var(--font-mono)', fontSize: '0.9rem', resize: 'vertical', boxSizing: 'border-box' }} />
+              </div>
+              <div>
+                <label className="mono-text" style={{ fontSize: '0.8rem', fontWeight: 700, display: 'block', marginBottom: '0.5rem' }}>CONTEXT CHUNKS (separate with "---" on its own line)</label>
+                <textarea value={evalForm.contexts} onChange={e => setEvalForm(f => ({ ...f, contexts: e.target.value }))}
+                  rows={6} placeholder={'Context chunk 1 text...\n---\nContext chunk 2 text...'} style={{ width: '100%', border: '2px solid #000', padding: '0.75rem', fontFamily: 'var(--font-mono)', fontSize: '0.85rem', resize: 'vertical', boxSizing: 'border-box' }} />
+              </div>
+              <button className="app-btn mono-text" onClick={runEval} disabled={evalLoading || !evalForm.question || !evalForm.answer || !evalForm.contexts}
+                style={{ alignSelf: 'flex-start', padding: '0.75rem 2rem' }}>
+                {evalLoading ? 'EVALUATING...' : 'RUN EVALUATION'}
+              </button>
+            </div>
+          </div>
+
+          {evalResult && (
+            <div style={{ border: '3px solid #000', padding: '2rem', background: evalResult.hallucination_detected ? '#fff5f5' : '#f0fdf4' }}>
+              <h3 className="mono-text" style={{ marginBottom: '1.5rem' }}>
+                {evalResult.hallucination_detected
+                  ? <><AlertTriangle size={16} style={{ display: 'inline', marginRight: '0.5rem', color: '#dc2626' }} />HALLUCINATION RISK DETECTED</>
+                  : <><CheckCircle size={16} style={{ display: 'inline', marginRight: '0.5rem', color: '#16a34a' }} />EVALUATION RESULTS</>
+                }
+              </h3>
+              <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(150px, 1fr))', gap: '1rem', marginBottom: '1.5rem' }}>
+                {[
+                  { label: 'OVERALL', value: evalResult.overall_score },
+                  { label: 'FAITHFULNESS', value: evalResult.faithfulness },
+                  { label: 'RELEVANCY', value: evalResult.answer_relevancy },
+                  { label: 'PRECISION', value: evalResult.context_precision },
+                ].map(m => (
+                  <div key={m.label} style={{ border: `2px solid ${score2color(m.value)}`, padding: '1rem', textAlign: 'center' }}>
+                    <div className="mono-text" style={{ fontSize: '0.7rem', fontWeight: 700, color: '#666', marginBottom: '0.5rem' }}>{m.label}</div>
+                    <div className="mono-text" style={{ fontSize: '1.8rem', fontWeight: 900, color: score2color(m.value) }}>
+                      {(m.value * 100).toFixed(0)}%
+                    </div>
+                    <div className="mono-text" style={{ fontSize: '0.65rem', color: score2color(m.value), marginTop: '0.25rem' }}>{score2label(m.value)}</div>
+                  </div>
+                ))}
+              </div>
+              <div className="mono-text" style={{ fontSize: '0.75rem', color: '#777', borderTop: '1px dotted #ccc', paddingTop: '0.75rem' }}>
+                Saved to Neo4j for trending. Eval ID: {evalResult.eval_id || 'N/A'}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* ── COMMUNITIES TAB ── */}
+      {activeTab === 'communities' && (
+        <div>
+          <div style={{ display: 'flex', gap: '1rem', marginBottom: '2rem', alignItems: 'center' }}>
+            <button className="app-btn mono-text" onClick={assignCommunities} disabled={communityLoading} style={{ padding: '0.75rem 1.5rem' }}>
+              {communityLoading ? 'DETECTING...' : '⚡ DETECT COMMUNITIES'}
+            </button>
+            <span className="mono-text" style={{ fontSize: '0.8rem', color: '#666' }}>
+              Run after ingesting documents to cluster entities into related groups (enables community search).
+            </span>
+          </div>
+
+          {communities.length === 0 ? (
+            <div style={{ border: '3px solid #000', padding: '3rem', textAlign: 'center' }}>
+              <p className="mono-text" style={{ color: '#777' }}>NO COMMUNITIES DETECTED YET</p>
+              <p className="mono-text" style={{ color: '#999', fontSize: '0.85rem', marginTop: '0.5rem' }}>Click "Detect Communities" above to cluster your knowledge graph entities.</p>
+            </div>
+          ) : (
+            <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))', gap: '1rem' }}>
+              {communities.map((c, i) => (
+                <div key={i} style={{ border: '2px solid #000', padding: '1.25rem' }}>
+                  <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '0.75rem' }}>
+                    <span className="mono-text" style={{ fontWeight: 700, fontSize: '0.85rem' }}>CLUSTER #{c.community_id}</span>
+                    <span className="mono-text" style={{ fontSize: '0.75rem', background: '#000', color: '#fff', padding: '0.15rem 0.5rem' }}>
+                      {c.entity_count} entities
+                    </span>
+                  </div>
+                  <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.35rem' }}>
+                    {(c.sample_entities || []).map((e: string, ei: number) => (
+                      <span key={ei} style={{ background: '#f3f4f6', border: '1px solid #d1d5db', padding: '0.15rem 0.5rem', fontSize: '0.75rem', fontFamily: 'var(--font-mono)' }}>{e}</span>
+                    ))}
+                    {c.entity_count > (c.sample_entities || []).length && (
+                      <span style={{ color: '#666', fontSize: '0.75rem', fontFamily: 'var(--font-mono)', padding: '0.15rem 0' }}>
+                        +{c.entity_count - (c.sample_entities || []).length} more
+                      </span>
+                    )}
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* ── EXPORT TAB ── */}
+      {activeTab === 'export' && (
+        <div>
+          <div style={{ border: '3px solid #000', padding: '2rem', marginBottom: '2rem' }}>
+            <h3 className="mono-text" style={{ marginBottom: '1.5rem' }}>EXPORT KNOWLEDGE GRAPH</h3>
+            <p className="mono-text" style={{ fontSize: '0.85rem', color: '#555', marginBottom: '2rem', lineHeight: '1.6' }}>
+              Export your knowledge graph for use in external tools, backups, or further analysis.
+            </p>
+            <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))', gap: '1rem' }}>
+              {[
+                { fmt: 'json', label: 'JSON', desc: 'Nodes & edges as JSON. For custom processing or visualization.' },
+                { fmt: 'cypher', label: 'CYPHER', desc: 'Cypher CREATE statements. Re-import to any Neo4j instance.' },
+                { fmt: 'graphml', label: 'GRAPHML', desc: 'GraphML XML. Compatible with Gephi, yEd, and most graph tools.' },
+              ].map(e => (
+                <div key={e.fmt} style={{ border: '2px solid #000', padding: '1.5rem' }}>
+                  <div className="mono-text" style={{ fontWeight: 900, fontSize: '1.1rem', marginBottom: '0.5rem' }}>.{e.label}</div>
+                  <p style={{ fontSize: '0.82rem', color: '#555', marginBottom: '1.25rem', fontFamily: 'var(--font-sans)', lineHeight: '1.5' }}>{e.desc}</p>
+                  <button className="app-btn mono-text" onClick={() => exportGraph(e.fmt)} style={{ width: '100%', textAlign: 'center' }}>
+                    DOWNLOAD .{e.label}
+                  </button>
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* ── REPORT AGENT TAB ── */}
+      {activeTab === 'report' && (
+        <div>
+          <div className="page-info-bar">
+            <FileText size={14}/>
+            <span><strong>REPORT AGENT</strong> — Enter any topic or question. The ReACT agent autonomously queries the knowledge graph using multiple retrieval strategies and synthesizes a deep multi-section report. More <strong>depth</strong> = more reasoning steps.</span>
+          </div>
+
+          {/* Input form */}
+          <div style={{ border: '3px solid #000', padding: '2rem', marginBottom: '2rem' }}>
+            <h3 className="mono-text" style={{ marginBottom: '1.5rem' }}>
+              <Zap size={16} style={{ display: 'inline', marginRight: '0.5rem' }}/>GENERATE ANALYTICAL REPORT
+            </h3>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+              <div>
+                <label className="mono-text" style={{ fontSize: '0.8rem', fontWeight: 700, display: 'block', marginBottom: '0.5rem' }}>TOPIC OR QUESTION</label>
+                <textarea value={reportTopic} onChange={e => setReportTopic(e.target.value)}
+                  rows={3} placeholder="e.g. 'Summarize all relationships between Company X and its investors'"
+                  style={{ width: '100%', border: '2px solid #000', padding: '0.75rem', fontFamily: 'var(--font-mono)', fontSize: '0.9rem', resize: 'vertical', boxSizing: 'border-box' }}/>
+              </div>
+              <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
+                <div>
+                  <label className="mono-text" style={{ fontSize: '0.8rem', fontWeight: 700, display: 'block', marginBottom: '0.5rem' }}>DEPTH (REASONING STEPS)</label>
+                  <select value={reportDepth} onChange={e => setReportDepth(Number(e.target.value))}
+                    style={{ border: '2px solid #000', padding: '0.5rem 0.75rem', fontFamily: 'var(--font-mono)', fontSize: '0.9rem' }}>
+                    {[1, 2, 3, 4, 5].map(n => <option key={n} value={n}>{n} {n === 1 ? '(fast)' : n === 5 ? '(deep)' : ''}</option>)}
+                  </select>
+                </div>
+                <button className="app-btn mono-text" onClick={runReport} disabled={reportLoading || !reportTopic.trim()}
+                  style={{ alignSelf: 'flex-end', padding: '0.75rem 2rem' }}>
+                  {reportLoading ? 'GENERATING...' : 'GENERATE REPORT'}
+                </button>
+              </div>
+            </div>
+          </div>
+
+          {/* Empty state */}
+          {!reportResult && !reportLoading && (
+            <div style={{ border: '3px dashed #e5e5e5', padding: '4rem 2rem', textAlign: 'center' }}>
+              <FileText size={44} style={{ opacity: 0.18, marginBottom: '1rem' }} />
+              <p className="mono-text" style={{ color: '#aaa', fontSize: '0.85rem', letterSpacing: '1px' }}>NO REPORT GENERATED YET</p>
+              <p style={{ color: '#bbb', fontSize: '0.8rem', marginTop: '0.5rem', fontFamily: 'var(--font-sans)' }}>
+                Enter a topic above and click Generate to produce an AI-powered analytical report from the knowledge graph.
+              </p>
+            </div>
+          )}
+
+          {/* Loading state */}
+          {reportLoading && (
+            <div style={{ border: '3px solid #000', padding: '2.5rem', textAlign: 'center' }}>
+              <div style={{ fontFamily: 'var(--font-mono)', fontWeight: 700, fontSize: '0.9rem', marginBottom: '0.75rem' }}>
+                ⚡ AGENT REASONING…
+              </div>
+              <div style={{ fontFamily: 'var(--font-sans)', fontSize: '0.82rem', color: 'var(--muted-color)' }}>
+                Querying knowledge graph with depth {reportDepth}. This may take 20–60 seconds.
+              </div>
+            </div>
+          )}
+
+          {/* Report output */}
+          {reportResult && (
+            <div style={{ border: '3px solid #000' }}>
+              {/* Report header bar */}
+              <div style={{ background: '#000', color: '#fff', padding: '0.85rem 1.5rem', display: 'flex', alignItems: 'center', gap: '0.75rem', flexWrap: 'wrap' }}>
+                <span style={{ fontFamily: 'var(--font-mono)', fontWeight: 700, fontSize: '0.82rem', flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                  📄 {(reportResult.topic || reportTopic).toUpperCase()}
+                </span>
+                {/* Confidence badge */}
+                {reportResult.confidence !== undefined && (
+                  <span style={{
+                    background: confidenceBadgeColor(reportResult.confidence),
+                    color: '#fff',
+                    padding: '2px 10px',
+                    fontFamily: 'var(--font-mono)',
+                    fontSize: '0.72rem',
+                    fontWeight: 700,
+                    letterSpacing: '0.5px',
+                    flexShrink: 0,
+                  }}>
+                    CONF: {(reportResult.confidence * 100).toFixed(0)}%
+                  </span>
+                )}
+                {reportResult.tool_calls_made !== undefined && (
+                  <span style={{ background: '#333', color: '#fff', padding: '2px 10px', fontFamily: 'var(--font-mono)', fontSize: '0.72rem', fontWeight: 700, flexShrink: 0 }}>
+                    {reportResult.tool_calls_made} CALLS
+                  </span>
+                )}
+                {/* Actions */}
+                <button
+                  onClick={handleCopyReport}
+                  style={{ background: copyDone ? '#16a34a' : 'transparent', color: '#fff', border: '1px solid #555', padding: '3px 10px', fontFamily: 'var(--font-mono)', fontSize: '0.72rem', cursor: 'pointer', flexShrink: 0 }}
+                >
+                  {copyDone ? '✓ COPIED' : '📋 COPY'}
+                </button>
+                <button
+                  onClick={handleDownloadReport}
+                  style={{ background: 'transparent', color: '#fff', border: '1px solid #555', padding: '3px 10px', fontFamily: 'var(--font-mono)', fontSize: '0.72rem', cursor: 'pointer', flexShrink: 0 }}
+                >
+                  ⬇ .MD
+                </button>
+              </div>
+
+              <div style={{ padding: '2rem' }}>
+                {/* Meta info row */}
+                <div style={{ display: 'flex', gap: '1.5rem', flexWrap: 'wrap', marginBottom: '2rem', paddingBottom: '1rem', borderBottom: '1px dotted #ddd', fontFamily: 'var(--font-mono)', fontSize: '0.72rem', color: '#888' }}>
+                  {reportTimestamp && <div>Generated: {reportTimestamp.toLocaleString()}</div>}
+                  {reportResult.tool_calls_made !== undefined && (
+                    <div>Depth: {reportDepth} · Tool calls: {reportResult.tool_calls_made}</div>
+                  )}
+                  {reportResult.confidence !== undefined && (
+                    <div style={{ color: confidenceBadgeColor(reportResult.confidence), fontWeight: 700 }}>
+                      Confidence: {(reportResult.confidence * 100).toFixed(1)}%
+                    </div>
+                  )}
+                </div>
+
+                {/* Executive summary */}
+                {reportResult.executive_summary && (
+                  <div style={{ marginBottom: '2.5rem', borderLeft: '4px solid #f59e0b', paddingLeft: '1.25rem' }}>
+                    <h4 className="mono-text" style={{ fontSize: '0.72rem', marginBottom: '0.75rem', color: '#d97706', letterSpacing: '1.5px' }}>
+                      EXECUTIVE SUMMARY
+                    </h4>
+                    <p style={{ fontFamily: 'var(--font-sans)', lineHeight: 1.9, fontSize: '1rem', fontWeight: 500, whiteSpace: 'pre-wrap', color: '#111' }}>
+                      {reportResult.executive_summary}
+                    </p>
+                  </div>
+                )}
+
+                {/* Sections */}
+                {reportResult.sections && typeof reportResult.sections === 'object' && !Array.isArray(reportResult.sections) ? (
+                  Object.entries(reportResult.sections).map(([title, content], i) => (
+                    <div key={i} style={{ marginBottom: '2rem', paddingBottom: '1.5rem', borderBottom: '1px dotted #e5e5e5' }}>
+                      <h4 className="mono-text" style={{ fontSize: '0.8rem', marginBottom: '1rem', color: '#000', display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+                        <span style={{ background: '#000', color: '#fff', padding: '2px 8px', fontSize: '0.65rem', flexShrink: 0 }}>{i + 1}</span>
+                        {title.toUpperCase()}
+                      </h4>
+                      <p style={{ fontFamily: 'var(--font-sans)', lineHeight: 1.85, fontSize: '0.92rem', whiteSpace: 'pre-wrap', color: '#333' }}>
+                        {String(content)}
+                      </p>
+                    </div>
+                  ))
+                ) : (
+                  reportResult.sections?.map?.((s: any, i: number) => (
+                    <div key={i} style={{ marginBottom: '2rem', paddingBottom: '1.5rem', borderBottom: '1px dotted #e5e5e5' }}>
+                      <h4 className="mono-text" style={{ fontSize: '0.8rem', marginBottom: '1rem', color: '#000', display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+                        <span style={{ background: '#000', color: '#fff', padding: '2px 8px', fontSize: '0.65rem', flexShrink: 0 }}>{i + 1}</span>
+                        {s.title?.toUpperCase()}
+                      </h4>
+                      <p style={{ fontFamily: 'var(--font-sans)', lineHeight: 1.85, fontSize: '0.92rem', whiteSpace: 'pre-wrap', color: '#333' }}>
+                        {s.content}
+                      </p>
+                    </div>
+                  ))
+                )}
+
+                {!reportResult.sections && (
+                  <p style={{ fontFamily: 'var(--font-sans)', lineHeight: 1.85, whiteSpace: 'pre-wrap', color: '#333' }}>
+                    {reportResult.report || reportResult.content || reportResult.markdown || JSON.stringify(reportResult, null, 2)}
+                  </p>
+                )}
+
+                {/* Key entities */}
+                {reportResult.key_entities && reportResult.key_entities.length > 0 && (
+                  <div style={{ marginTop: '2rem', paddingTop: '1rem', borderTop: '1px dotted #ccc' }}>
+                    <h4 className="mono-text" style={{ fontSize: '0.68rem', color: '#888', marginBottom: '0.5rem', letterSpacing: '1.5px' }}>
+                      KEY ENTITIES REFERENCED
+                    </h4>
+                    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.4rem' }}>
+                      {reportResult.key_entities.map((e: string, i: number) => (
+                        <span key={i} style={{ background: '#f3f4f6', border: '1.5px solid #e5e5e5', padding: '2px 8px', fontSize: '0.75rem', fontFamily: 'var(--font-mono)', fontWeight: 600 }}>
+                          {e}
+                        </span>
+                      ))}
+                    </div>
+                  </div>
+                )}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* ── LIVE GRAPH UPDATE TAB ── */}
+      {activeTab === 'graph-update' && (
+        <div>
+          <div className="page-info-bar">
+            <GitCommit size={14}/>
+            <span><strong>LIVE GRAPH UPDATE</strong> — Paste any text (news article, note, policy). The system extracts entities and relationships and merges them into the live knowledge graph without re-running ingestion. Uses <strong>MERGE</strong> to prevent duplicates.</span>
+          </div>
+          <div style={{ border: '3px solid #000', padding: '2rem', marginBottom: '2rem' }}>
+            <h3 className="mono-text" style={{ marginBottom: '1.5rem' }}><GitCommit size={16} style={{ display: 'inline', marginRight: '0.5rem' }}/>INJECT KNOWLEDGE INTO GRAPH</h3>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+              <div>
+                <label className="mono-text" style={{ fontSize: '0.8rem', fontWeight: 700, display: 'block', marginBottom: '0.5rem' }}>TEXT TO INJECT</label>
+                <textarea value={updateText} onChange={e => setUpdateText(e.target.value)}
+                  rows={8} placeholder="Paste any text — news, reports, notes, or raw facts..."
+                  style={{ width: '100%', border: '2px solid #000', padding: '0.75rem', fontFamily: 'var(--font-mono)', fontSize: '0.88rem', resize: 'vertical', boxSizing: 'border-box' }}/>
+              </div>
+              <button className="app-btn mono-text" onClick={runGraphUpdate} disabled={updateLoading || !updateText.trim()}
+                style={{ alignSelf: 'flex-start', padding: '0.75rem 2rem' }}>
+                {updateLoading ? 'INJECTING...' : 'INJECT INTO GRAPH'}
+              </button>
+            </div>
+          </div>
+          {updateResult && (
+            <div style={{ border: '3px solid #000', padding: '1.5rem', background: '#f0fdf4' }}>
+              <h3 className="mono-text" style={{ marginBottom: '1rem', color: '#166534' }}>✓ GRAPH UPDATED</h3>
+              <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(140px,1fr))', gap: '0.75rem', marginBottom: '1rem' }}>
+                {[
+                  ['Entities Added', updateResult.entities_added ?? updateResult.nodes_created],
+                  ['Relationships Added', updateResult.relationships_added ?? updateResult.edges_created],
+                  ['Merged Existing', updateResult.entities_merged ?? '—'],
+                ].map(([label, val]) => (
+                  <div key={label as string} style={{ border: '2px solid #000', padding: '1rem', textAlign: 'center' }}>
+                    <div className="mono-text" style={{ fontSize: '0.68rem', color: '#888', marginBottom: '0.35rem' }}>{label}</div>
+                    <div className="mono-text" style={{ fontSize: '1.6rem', fontWeight: 900 }}>{val ?? '—'}</div>
+                  </div>
+                ))}
+              </div>
+              {updateResult.message && (
+                <p className="mono-text" style={{ fontSize: '0.82rem', color: '#555' }}>{updateResult.message}</p>
+              )}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* ── ENTITY CHAT TAB ── */}
+      {activeTab === 'entity-chat' && (
+        <div>
+          <div className="page-info-bar">
+            <MessageSquare size={14}/>
+            <span><strong>ENTITY CHAT</strong> — Select an entity from the graph and interview it. The agent synthesizes answers from its neighborhood context, relationships, and LLM-generated profile.</span>
+          </div>
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 2fr', gap: '1.5rem' }}>
+            {/* Config panel */}
+            <div style={{ border: '3px solid #000', padding: '1.5rem' }}>
+              <h3 className="mono-text" style={{ marginBottom: '1.25rem', fontSize: '0.9rem' }}>SELECT ENTITY</h3>
+              <div style={{ marginBottom: '1rem' }}>
+                <label className="mono-text" style={{ fontSize: '0.75rem', fontWeight: 700, color: '#888', display: 'block', marginBottom: '0.4rem' }}>ENTITY NAME</label>
+                <select value={selectedEntity} onChange={e => { setSelectedEntity(e.target.value); setChatHistory([]); }}
+                  style={{ width: '100%', border: '2px solid #000', padding: '0.5rem', fontFamily: 'var(--font-mono)', fontSize: '0.85rem' }}>
+                  <option value="">— Select entity —</option>
+                  {entities.map((n: any) => (
+                    <option key={n.id} value={n.properties?.name || n.properties?.label || n.id}>
+                      {n.labels?.[0]} · {n.properties?.name || n.properties?.label || n.id}
+                    </option>
+                  ))}
+                </select>
+              </div>
+              <div style={{ marginBottom: '1rem' }}>
+                <label className="mono-text" style={{ fontSize: '0.75rem', fontWeight: 700, color: '#888', display: 'block', marginBottom: '0.4rem' }}>EXTRA CONTEXT (OPTIONAL)</label>
+                <textarea value={entityContext} onChange={e => setEntityContext(e.target.value)}
+                  rows={3} placeholder="Add any additional context or constraints..."
+                  style={{ width: '100%', border: '2px solid #000', padding: '0.5rem', fontFamily: 'var(--font-mono)', fontSize: '0.82rem', resize: 'vertical' }}/>
+              </div>
+              <button className="app-btn mono-text" style={{ width: '100%', justifyContent: 'center' }}
+                onClick={() => setChatHistory([])}>CLEAR CHAT</button>
+            </div>
+            {/* Chat window */}
+            <div style={{ border: '3px solid #000', display: 'flex', flexDirection: 'column', minHeight: 400 }}>
+              <div style={{ background: '#000', color: '#fff', padding: '0.5rem 1rem', fontFamily: 'var(--font-mono)', fontSize: '0.78rem', fontWeight: 700 }}>
+                {selectedEntity ? `CHATTING WITH: ${selectedEntity.toUpperCase()}` : 'SELECT AN ENTITY TO BEGIN'}
+              </div>
+              <div style={{ flex: 1, overflowY: 'auto', padding: '1rem', display: 'flex', flexDirection: 'column', gap: '0.75rem', minHeight: 280, maxHeight: 400 }}>
+                {chatHistory.length === 0 && (
+                  <div style={{ textAlign: 'center', padding: '2rem', color: '#ccc', fontFamily: 'var(--font-mono)', fontSize: '0.82rem' }}>
+                    {selectedEntity ? 'Ask this entity anything…' : 'Select an entity to start chatting'}
+                  </div>
+                )}
+                {chatHistory.map((m, i) => (
+                  <div key={i} style={{
+                    alignSelf: m.role === 'user' ? 'flex-end' : 'flex-start',
+                    background: m.role === 'user' ? '#000' : '#f3f4f6',
+                    color: m.role === 'user' ? '#fff' : '#000',
+                    padding: '0.6rem 1rem',
+                    maxWidth: '85%',
+                    fontFamily: 'var(--font-sans)', fontSize: '0.88rem', lineHeight: 1.6
+                  }}>
+                    {m.content}
+                  </div>
+                ))}
+                {chatLoading && (
+                  <div style={{ alignSelf: 'flex-start', background: '#f3f4f6', padding: '0.6rem 1rem', fontFamily: 'var(--font-mono)', fontSize: '0.82rem', color: '#888' }}>
+                    Thinking…
+                  </div>
+                )}
+              </div>
+              <div style={{ borderTop: '2px solid #000', display: 'flex', gap: 0 }}>
+                <input type="text" value={chatMsg} onChange={e => setChatMsg(e.target.value)}
+                  onKeyDown={e => e.key === 'Enter' && !e.shiftKey && sendEntityChat()}
+                  placeholder={selectedEntity ? 'Ask a question…' : 'Select an entity first'}
+                  disabled={!selectedEntity || chatLoading}
+                  style={{ flex: 1, border: 'none', padding: '0.75rem 1rem', fontFamily: 'var(--font-mono)', fontSize: '0.88rem', outline: 'none' }}/>
+                <button className="app-btn" onClick={sendEntityChat} disabled={!selectedEntity || !chatMsg.trim() || chatLoading}
+                  style={{ border: 'none', borderLeft: '2px solid #000', borderRadius: 0, minWidth: 80 }}>
+                  SEND
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default InsightsView;

frontend-react/src/views/InteractionView.tsx

@@ -0,0 +1,1396 @@
+import React, { useState, useRef, useEffect, useCallback } from 'react';
+import { useAuth } from '../context/AuthContext';
+import { Message, Conversation, DocumentInfo, GraphNode } from '../types/api';
+import {
+  MessageSquare, Send, Bot, User as UserIcon, Zap,
+  Menu, Info, X, ChevronDown, FileText, Plus
+} from 'lucide-react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000/api';
+
+/* ── confidence colour helper ─────────────────────────────────────────────── */
+const confColor = (c: number) => c >= 0.75 ? '#16a34a' : c >= 0.5 ? '#d97706' : '#dc2626';
+const riskColor = (r: string) =>
+  r.toLowerCase() === 'high' ? '#dc2626' : r.toLowerCase() === 'medium' ? '#d97706' : '#16a34a';
+
+/* ─────────────────────────────────────────────────────────────────────────── */
+
+const InteractionView: React.FC = () => {
+  const { token, logout } = useAuth();
+
+  // ── Core chat state ──────────────────────────────────────────────────────
+  const [query, setQuery] = useState('');
+  const [conversation, setConversation] = useState<Message[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  // ── Document / mode state ────────────────────────────────────────────────
+  const [documents, setDocuments] = useState<DocumentInfo[]>([]);
+  const [selectedDocId, setSelectedDocId] = useState('');
+  const [useGot, setUseGot] = useState(false);
+  const [mode, setMode] = useState<'rag' | 'simulation'>('rag');
+  const [agentId, setAgentId] = useState('');
+  const [agentNodes, setAgentNodes] = useState<GraphNode[]>([]);
+
+  // ── Thread history ────────────────────────────────────────────────────────
+  const [pastConversations, setPastConversations] = useState<Conversation[]>([]);
+  const [currentConversationId, setCurrentConversationId] = useState<string | null>(null);
+
+  // ── UI state ──────────────────────────────────────────────────────────────
+  const [sidebarOpen, setSidebarOpen] = useState(true);
+  const [drawerSource, setDrawerSource] = useState<any | null>(null);
+
+  const endOfChatRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  /* ── auto-scroll ─────────────────────────────────────────────────────── */
+  useEffect(() => {
+    endOfChatRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [conversation]);
+
+  /* ── initial data fetch ──────────────────────────────────────────────── */
+  useEffect(() => {
+    const fetchDocs = async () => {
+      try {
+        const res = await fetch(`${API_BASE}/documents`, {
+          headers: { Authorization: `Bearer ${token}` }
+        });
+        if (res.ok) setDocuments((await res.json()).documents);
+      } catch {}
+    };
+
+    const fetchConvs = async () => {
+      try {
+        const res = await fetch(`${API_BASE}/conversations`, {
+          headers: { Authorization: `Bearer ${token}` }
+        });
+        if (res.ok) setPastConversations((await res.json()).conversations);
+      } catch {}
+    };
+
+    const fetchAgents = async () => {
+      try {
+        const res = await fetch(`${API_BASE}/graph/visualization?limit=500`, {
+          headers: { Authorization: `Bearer ${token}` }
+        });
+        if (res.ok) setAgentNodes((await res.json()).nodes);
+      } catch {}
+    };
+
+    fetchDocs();
+    fetchConvs();
+    fetchAgents();
+  }, [token]);
+
+  /* ── load an archived thread ─────────────────────────────────────────── */
+  const loadConversation = useCallback(async (convId: string) => {
+    try {
+      const res = await fetch(`${API_BASE}/conversations/${convId}`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const data = await res.json();
+        setCurrentConversationId(data.id);
+        setConversation(
+          data.messages.map((m: any) => ({
+            role: m.role,
+            content: m.content,
+            reasoning: m.reasoning || [],
+            sources: m.sources || []
+          }))
+        );
+        // On mobile: close sidebar after selecting
+        if (window.innerWidth < 768) setSidebarOpen(false);
+      }
+    } catch {}
+  }, [token]);
+
+  const startNewConversation = useCallback(() => {
+    setCurrentConversationId(null);
+    setConversation([]);
+    if (window.innerWidth < 768) setSidebarOpen(false);
+    setTimeout(() => inputRef.current?.focus(), 100);
+  }, []);
+
+  /* ── submit query ────────────────────────────────────────────────────── */
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!query.trim() || loading) return;
+
+    const userMessage = { role: 'user', content: query };
+    const assistantPlaceholder = {
+      role: 'assistant', content: '', sources: [], reasoning: [],
+      confidence: null, drift_expanded: false
+    };
+
+    setConversation(prev => [...prev, userMessage, assistantPlaceholder]);
+    setQuery('');
+    setLoading(true);
+
+    try {
+      /* ── Simulation mode ──────────────────────────────────────────── */
+      if (mode === 'simulation') {
+        const res = await fetch(`${API_BASE}/v1/simulation/interview`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+          body: JSON.stringify({ agent_id: agentId, user_query: userMessage.content })
+        });
+        if (!res.ok) throw new Error('Simulation endpoint failed.');
+        const data = await res.json();
+        setConversation(prev => {
+          const next = [...prev];
+          next[next.length - 1] = {
+            role: 'assistant',
+            content: data.response,
+            sources: [],
+            reasoning: [`Simulated persona response for agent: ${data.agent_name || agentId}`],
+            confidence: null
+          };
+          return next;
+        });
+        setLoading(false);
+        return;
+      }
+
+      /* ── RAG streaming mode ─────────────────────────────────────────── */
+      const reqBody: any = {
+        query: userMessage.content,
+        streaming: true,
+        top_k: 5,
+        use_got: useGot
+      };
+      if (selectedDocId) reqBody.document_id = selectedDocId;
+      if (currentConversationId) reqBody.conversation_id = currentConversationId;
+
+      const res = await fetch(`${API_BASE}/query`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify(reqBody)
+      });
+
+      if (res.status === 401) { logout(); return; }
+      if (!res.body) throw new Error('ReadableStream not supported.');
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder('utf-8');
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const raw = decoder.decode(value);
+        const chunks = raw.split('\n\n');
+
+        for (const chunk of chunks) {
+          if (chunk.trim() === 'data: [DONE]') { setLoading(false); break; }
+          if (!chunk.startsWith('data: ')) continue;
+          try {
+            const data = JSON.parse(chunk.replace('data: ', ''));
+            if (data.type === 'meta') {
+              setCurrentConversationId(data.conversation_id);
+              // Refresh thread list so it shows up in sidebar
+              const convRes = await fetch(`${API_BASE}/conversations`, {
+                headers: { Authorization: `Bearer ${token}` }
+              });
+              if (convRes.ok) setPastConversations((await convRes.json()).conversations);
+              continue;
+            }
+            setConversation(prev => {
+              const next = [...prev];
+              const last = next.length - 1;
+              if (data.type === 'step') {
+                next[last] = { ...next[last], reasoning: [...(next[last].reasoning || []), data.content] };
+              } else if (data.type === 'answer') {
+                next[last] = {
+                  ...next[last],
+                  content: data.answer,
+                  sources: data.sources,
+                  confidence: data.confidence,
+                  drift_expanded: data.drift_expanded || false,
+                  hallucination_risk: data.hallucination_risk,
+                  confidence_reasoning: data.confidence_reasoning
+                };
+              }
+              return next;
+            });
+          } catch {}
+        }
+      }
+    } catch (err) {
+      console.error('Query error:', err);
+      // Show error in the placeholder message
+      setConversation(prev => {
+        const next = [...prev];
+        next[next.length - 1] = {
+          ...next[next.length - 1],
+          content: '⚠ An error occurred. Please check your connection or try again.'
+        };
+        return next;
+      });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  /* ── inline eval ─────────────────────────────────────────────────────── */
+  const runInlineEval = async (msgIndex: number) => {
+    const astMsg = conversation[msgIndex];
+    if (astMsg.role !== 'assistant') return;
+
+    let question = 'Contextual Query';
+    for (let i = msgIndex - 1; i >= 0; i--) {
+      if (conversation[i].role === 'user') { question = conversation[i].content; break; }
+    }
+
+    setConversation(prev => {
+      const next = [...prev];
+      next[msgIndex] = { ...next[msgIndex], evaluating: true };
+      return next;
+    });
+
+    try {
+      const contexts = (astMsg.sources || []).map((s: any) => s.text || JSON.stringify(s));
+      const res = await fetch(`${API_BASE}/eval/score`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ question, answer: astMsg.content, contexts })
+      });
+      const evalData = res.ok ? await res.json() : null;
+      setConversation(prev => {
+        const next = [...prev];
+        next[msgIndex] = { ...next[msgIndex], evaluating: false, ...(evalData ? { eval_result: evalData } : {}) };
+        return next;
+      });
+    } catch {
+      setConversation(prev => {
+        const next = [...prev]; next[msgIndex] = { ...next[msgIndex], evaluating: false }; return next;
+      });
+    }
+  };
+
+  /* ── keyboard shortcut: Ctrl+/ or Cmd+/ to focus input ─────────────── */
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.ctrlKey || e.metaKey) && e.key === '/') {
+        e.preventDefault();
+        inputRef.current?.focus();
+      }
+      if (e.key === 'Escape' && drawerSource) setDrawerSource(null);
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [drawerSource]);
+
+  /* ────────────────────────────────────────────────────────────────────── */
+  return (
+    <div className="iv-root">
+
+      {/* ── Top header bar ──────────────────────────────────────────────── */}
+      <div className="iv-header">
+        {/* left: title + breadcrumb */}
+        <div className="iv-header-left">
+          <button
+            className="iv-sidebar-toggle"
+            onClick={() => setSidebarOpen(o => !o)}
+            title={sidebarOpen ? 'Hide threads' : 'Show threads'}
+          >
+            <Menu size={18} />
+          </button>
+          <div>
+            <h1 className="iv-title">AGENTIC INTERACTION</h1>
+            <p className="mono-text iv-breadcrumb">TERMINAL // LOGIC QUERY INTERFACE</p>
+          </div>
+        </div>
+
+        {/* right: controls */}
+        <div className="iv-header-right">
+          {/* Document filter */}
+          <div className="iv-ctrl-group">
+            <label className="iv-ctrl-label">SCOPE</label>
+            <div className="iv-select-wrap">
+              <select
+                className="iv-select"
+                value={selectedDocId}
+                onChange={e => setSelectedDocId(e.target.value)}
+              >
+                <option value="">🌐 ALL DOCUMENTS</option>
+                {documents.length === 0 ? (
+                  <option disabled>No documents uploaded</option>
+                ) : (
+                  documents.map(doc => (
+                    <option key={doc.id} value={doc.id}>
+                      📄 {doc.filename.length > 32 ? doc.filename.substring(0, 30) + '…' : doc.filename}
+                    </option>
+                  ))
+                )}
+              </select>
+              <ChevronDown size={13} className="iv-select-chevron" />
+            </div>
+          </div>
+
+          {/* GoT toggle */}
+          <button
+            className={`iv-got-btn ${useGot ? 'active' : ''}`}
+            onClick={() => setUseGot(g => !g)}
+            title="Graph-of-Thought: runs all retrieval strategies in parallel for higher quality answers"
+          >
+            <Zap size={13} />
+            GoT {useGot ? 'ON' : 'OFF'}
+          </button>
+        </div>
+      </div>
+
+      {/* ── Info bar ────────────────────────────────────────────────────── */}
+      <div className="iv-info-bar">
+        <Info size={13} />
+        <span>
+          <strong>Standard (Graph Logic)</strong>: multi-hop retrieval over the knowledge graph. &nbsp;
+          <strong>GoT</strong>: runs all search strategies in parallel, best for complex questions. &nbsp;
+          <strong>God-Mode</strong>: interviews a simulated AI persona by agent ID. &nbsp;
+          Press <kbd>Ctrl+/</kbd> to focus input.
+        </span>
+      </div>
+
+      {/* ── Main layout ─────────────────────────────────────────────────── */}
+      <div className="iv-body">
+
+        {/* ── Sidebar ────────────────────────────────────────────────────── */}
+        <div className={`iv-sidebar ${sidebarOpen ? 'open' : 'closed'}`}>
+          <button className="iv-new-thread" onClick={startNewConversation} style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+            <Plus size={16} /> NEW THREAD
+          </button>
+
+          <div className="iv-thread-list">
+            <div className="iv-thread-header">ARCHIVED THREADS</div>
+            {pastConversations.length === 0 ? (
+              <div className="iv-empty-threads">No prior sequences</div>
+            ) : (
+              pastConversations.map(conv => (
+                <div
+                  key={conv.id}
+                  className={`iv-thread-item ${currentConversationId === conv.id ? 'active' : ''}`}
+                  onClick={() => loadConversation(conv.id)}
+                >
+                  <div className="iv-thread-title">
+                    <MessageSquare size={12} style={{ display: 'inline', marginRight: '6px', verticalAlign: '-1px' }} />
+                    {conv.title || 'Untitled thread'}
+                  </div>
+                  <div className="iv-thread-date">
+                    {new Date(conv.created_at).toLocaleDateString()}
+                  </div>
+                </div>
+              ))
+            )}
+          </div>
+        </div>
+
+        {/* ── Chat panel ──────────────────────────────────────────────────── */}
+        <div className="iv-chat-panel">
+
+          {/* messages */}
+          <div className="iv-messages">
+            {conversation.length === 0 ? (
+              <div className="iv-empty-chat">
+                <Bot size={40} style={{ opacity: 0.15 }} />
+                <span>INITIALIZE QUERY SEQUENCE TO BEGIN GRAPH ANALYSIS…</span>
+                <div className="iv-empty-hints">
+                  <span>Try: "Summarize the main entities in this document"</span>
+                  <span>Try: "What relationships exist between X and Y?"</span>
+                  <span>Try: "Find all mentions of [topic] and their context"</span>
+                </div>
+              </div>
+            ) : (
+              conversation.map((msg, idx) => (
+                <div key={idx} className={`iv-msg-row ${msg.role}`}>
+                  <div className="iv-msg-avatar">
+                    {msg.role === 'user' ? <UserIcon size={18} /> : <Bot size={18} />}
+                  </div>
+
+                  <div className="iv-msg-card">
+                    {/* message header */}
+                    <div className="iv-msg-header">
+                      <span className="iv-msg-role">
+                        {msg.role === 'user' ? 'YOU' : 'GRAPH REASONING SYSTEM'}
+                      </span>
+
+                      {msg.role === 'assistant' && msg.confidence != null && (
+                        <div className="iv-msg-badges">
+                          {msg.drift_expanded && (
+                            <span className="iv-badge" style={{ background: '#3b82f6' }}>
+                              DRIFT EXPANDED
+                            </span>
+                          )}
+                          <span
+                            className="iv-badge"
+                            style={{ background: confColor(msg.confidence) }}
+                            title={`Confidence: ${(msg.confidence * 100).toFixed(1)}%`}
+                          >
+                            {(msg.confidence * 100).toFixed(0)}% CONF
+                          </span>
+                          {msg.hallucination_risk && (
+                            <span
+                              className="iv-badge-outline"
+                              style={{ color: riskColor(msg.hallucination_risk), borderColor: riskColor(msg.hallucination_risk) }}
+                              title={msg.confidence_reasoning}
+                            >
+                              RISK: {msg.hallucination_risk.toUpperCase()}
+                            </span>
+                          )}
+                        </div>
+                      )}
+                    </div>
+
+                    {/* reasoning steps */}
+                    {msg.role === 'assistant' && msg.reasoning?.length > 0 && (
+                      <div className="iv-reasoning">
+                        {msg.reasoning.map((step: string, si: number) => (
+                          <div key={si} className="iv-reasoning-step">
+                            <span className="iv-step-idx">{si + 1}</span>
+                            <span>{step}</span>
+                          </div>
+                        ))}
+                      </div>
+                    )}
+
+                    {/* content */}
+                    <div className="iv-msg-content">
+                      {msg.role === 'assistant' && msg.content === '' && loading && idx === conversation.length - 1 ? (
+                        <span className="iv-cursor">██</span>
+                      ) : (
+                        <div className="iv-markdown">
+                          <ReactMarkdown remarkPlugins={[remarkGfm]}>{msg.content}</ReactMarkdown>
+                        </div>
+                      )}
+                    </div>
+
+                    {/* sources */}
+                    {msg.sources?.length > 0 && (
+                      <div className="iv-sources">
+                        <div className="iv-sources-top">
+                          <div className="iv-sources-label">
+                            SOURCES:
+                            <div className="iv-source-chips">
+                              {msg.sources
+                                .filter((v: any, i: number, a: any[]) =>
+                                  a.findIndex(t => (t.metadata?.file_name || t.document_id) === (v.metadata?.file_name || v.document_id)) === i
+                                )
+                                .map((s: any, si: number) => (
+                                  <button
+                                    key={si}
+                                    className="iv-source-chip"
+                                    onClick={() => setDrawerSource(s)}
+                                    title="Click to view source text"
+                                  >
+                                    {s.metadata?.file_name || s.document_id}
+                                  </button>
+                                ))}
+                            </div>
+                          </div>
+
+                          {msg.role === 'assistant' && !msg.eval_result && (
+                            <button
+                              className="iv-eval-btn"
+                              onClick={() => runInlineEval(idx)}
+                              disabled={msg.evaluating}
+                            >
+                              {msg.evaluating ? 'EVALUATING…' : 'EVALUATE QUALITY'}
+                            </button>
+                          )}
+                        </div>
+
+                        {/* eval results */}
+                        {msg.eval_result && (
+                          <div className="iv-eval-result">
+                            <div className="iv-eval-title">EVALUATION RESULTS</div>
+                            <div className="iv-eval-grid">
+                              {[
+                                { label: 'OVERALL', value: msg.eval_result.overall_score ?? (msg.eval_result.faithfulness * 0.5 + (msg.eval_result.answer_relevancy || msg.eval_result.relevancy || 0) * 0.3 + (msg.eval_result.context_precision || msg.eval_result.precision || 0) * 0.2) },
+                                { label: 'FAITHFULNESS', value: msg.eval_result.faithfulness },
+                                { label: 'RELEVANCY', value: msg.eval_result.answer_relevancy ?? msg.eval_result.relevancy },
+                                { label: 'PRECISION', value: msg.eval_result.context_precision ?? msg.eval_result.precision }
+                              ].map((m, mi) => {
+                                const val = typeof m.value === 'number' ? m.value : 0;
+                                const pct = Math.round(val * 100);
+                                return (
+                                  <div key={mi} className="iv-eval-metric">
+                                    <div className="iv-eval-label">{m.label}</div>
+                                    <div className="iv-eval-bar-wrap">
+                                      <div className="iv-eval-bar" style={{ width: `${pct}%`, background: confColor(val) }} />
+                                    </div>
+                                    <div className="iv-eval-pct" style={{ color: confColor(val) }}>{pct}%</div>
+                                  </div>
+                                );
+                              })}
+                            </div>
+                          </div>
+                        )}
+                      </div>
+                    )}
+                  </div>
+                </div>
+              ))
+            )}
+            <div ref={endOfChatRef} />
+          </div>
+
+          {/* ── Input area ─────────────────────────────────────────────── */}
+          <form className="iv-input-area" onSubmit={handleSubmit}>
+            {/* Mode + agent ID row */}
+            <div className="iv-input-controls">
+              <div className="iv-ctrl-group">
+                <label className="iv-ctrl-label">INTERACTION MODE</label>
+                <div className="iv-select-wrap">
+                  <select
+                    className="iv-select iv-select-dark"
+                    value={mode}
+                    onChange={e => setMode(e.target.value as 'rag' | 'simulation')}
+                  >
+                    <option value="rag">STANDARD (GRAPH LOGIC)</option>
+                    <option value="simulation">GOD-MODE (PERSONA INTERVIEW)</option>
+                  </select>
+                  <ChevronDown size={13} className="iv-select-chevron" />
+                </div>
+              </div>
+
+              {mode === 'simulation' && (
+                <div className="iv-ctrl-group">
+                  <label className="iv-ctrl-label" style={{ color: '#f59e0b' }}>TARGET PERSONA (GOD MODE)</label>
+                  <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
+                    <div className="iv-select-wrap">
+                      <select
+                        className="iv-select iv-select-dark"
+                        style={{ borderColor: '#f59e0b', width: '200px' }}
+                        value={agentNodes.some(n => n.id === agentId) ? agentId : ""}
+                        onChange={e => setAgentId(e.target.value)}
+                      >
+                        <option value="" disabled>Select from graph...</option>
+                        {agentNodes.map(n => (
+                          <option key={n.id} value={n.id}>
+                            [{n.type}] {n.label.length > 20 ? n.label.substring(0, 18) + '…' : n.label}
+                          </option>
+                        ))}
+                      </select>
+                      <ChevronDown size={13} className="iv-select-chevron" />
+                    </div>
+                    <span style={{ color: '#666', fontSize: '0.65rem', fontFamily: 'var(--font-mono)' }}>OR</span>
+                    <input
+                      type="text"
+                      value={agentId}
+                      onChange={e => setAgentId(e.target.value)}
+                      placeholder="Paste UUID..."
+                      className="iv-agent-input"
+                      style={{ width: '120px' }}
+                    />
+                  </div>
+                </div>
+              )}
+
+              {/* Document scope chip (shows when doc selected) */}
+              {selectedDocId && (
+                <div className="iv-scope-chip">
+                  <FileText size={12} />
+                  <span>{documents.find(d => d.id === selectedDocId)?.filename?.substring(0, 24) || 'Filtered'}</span>
+                  <button type="button" onClick={() => setSelectedDocId('')} title="Clear filter">
+                    <X size={11} />
+                  </button>
+                </div>
+              )}
+            </div>
+
+            {/* Text input row */}
+            <div className="iv-input-row">
+              <span className="iv-prompt-marker">&gt;</span>
+              <input
+                ref={inputRef}
+                type="text"
+                value={query}
+                onChange={e => setQuery(e.target.value)}
+                disabled={loading || (mode === 'simulation' && !agentId)}
+                placeholder={
+                  mode === 'simulation'
+                    ? agentId ? 'INTERVIEW AGENT…' : 'ENTER AGENT ID ABOVE FIRST…'
+                    : 'ENTER QUERY DIRECTIVE…'
+                }
+                className="iv-text-input"
+                autoComplete="off"
+              />
+              <button
+                type="submit"
+                className="iv-send-btn"
+                disabled={!query.trim() || loading || (mode === 'simulation' && !agentId)}
+                title="Send (Enter)"
+              >
+                {loading ? (
+                  <span className="iv-spinner" />
+                ) : (
+                  <Send size={18} />
+                )}
+              </button>
+            </div>
+          </form>
+        </div>
+      </div>
+
+      {/* ── Source detail drawer ─────────────────────────────────────────── */}
+      {drawerSource && (
+        <div className="iv-drawer-overlay" onClick={() => setDrawerSource(null)}>
+          <div className="iv-drawer" onClick={e => e.stopPropagation()}>
+            <div className="iv-drawer-header">
+              <h3 className="mono-text">SOURCE DETAIL</h3>
+              <button className="iv-drawer-close" onClick={() => setDrawerSource(null)}>
+                <X size={16} />
+              </button>
+            </div>
+            <div className="iv-drawer-body">
+              <div className="iv-drawer-meta">
+                <div className="iv-meta-row">
+                  <span className="iv-meta-key">DOCUMENT</span>
+                  <span>{drawerSource.metadata?.file_name || drawerSource.document_id || '—'}</span>
+                </div>
+                <div className="iv-meta-row">
+                  <span className="iv-meta-key">RELEVANCE</span>
+                  <span>{drawerSource.score != null ? (drawerSource.score * 100).toFixed(1) + '%' : 'N/A'}</span>
+                </div>
+                <div className="iv-meta-row">
+                  <span className="iv-meta-key">CHUNK ID</span>
+                  <span style={{ wordBreak: 'break-all' }}>{drawerSource.id || '—'}</span>
+                </div>
+              </div>
+              <hr className="iv-drawer-divider" />
+              <div className="iv-drawer-text">{drawerSource.text || 'No text available.'}</div>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* ── Scoped styles ────────────────────────────────────────────────── */}
+      <style>{`
+        /* ── Root layout ───────────────────────────────────────────── */
+        .iv-root {
+          height: calc(100vh - 62px);
+          display: flex;
+          flex-direction: column;
+          background: var(--bg-color);
+          overflow: hidden;
+        }
+
+        /* ── Header ───────────────────────────────────────────────── */
+        .iv-header {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: 1rem;
+          padding: 0.65rem 1.5rem;
+          border-bottom: 3px solid var(--border-color);
+          flex-shrink: 0;
+          flex-wrap: wrap;
+        }
+
+        .iv-header-left {
+          display: flex;
+          align-items: center;
+          gap: 0.75rem;
+          min-width: 0;
+        }
+
+        .iv-title {
+          font-size: 1rem;
+          letter-spacing: 2px;
+          margin: 0;
+          line-height: 1.1;
+        }
+
+        .iv-breadcrumb {
+          font-size: 0.7rem;
+          color: var(--muted-color);
+          margin: 0;
+        }
+
+        .iv-sidebar-toggle {
+          border: 2px solid var(--border-color);
+          background: var(--bg-color);
+          color: var(--text-color);
+          width: 34px;
+          height: 34px;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          cursor: pointer;
+          flex-shrink: 0;
+          transition: all 0.13s;
+        }
+        .iv-sidebar-toggle:hover { background: var(--text-color); color: var(--bg-color); }
+
+        .iv-header-right {
+          display: flex;
+          align-items: flex-end;
+          gap: 0.75rem;
+          flex-wrap: wrap;
+        }
+
+        /* ── Control group ─────────────────────────────────────────── */
+        .iv-ctrl-group {
+          display: flex;
+          flex-direction: column;
+          gap: 2px;
+        }
+        .iv-ctrl-label {
+          font-family: var(--font-mono);
+          font-size: 0.6rem;
+          font-weight: 700;
+          color: var(--muted-color);
+          letter-spacing: 1px;
+          text-transform: uppercase;
+        }
+
+        /* ── Uniform select ────────────────────────────────────────── */
+        .iv-select-wrap {
+          position: relative;
+          display: inline-flex;
+          align-items: center;
+        }
+        .iv-select-chevron {
+          position: absolute;
+          right: 8px;
+          pointer-events: none;
+          color: var(--muted-color);
+        }
+        .iv-select {
+          font-family: var(--font-mono);
+          font-size: 0.82rem;
+          font-weight: 700;
+          border: 2px solid var(--border-color);
+          background: var(--bg-color);
+          color: var(--text-color);
+          padding: 0.32rem 2rem 0.32rem 0.65rem;
+          cursor: pointer;
+          appearance: none;
+          -webkit-appearance: none;
+          outline: none;
+          max-width: 260px;
+        }
+        .iv-select:focus { box-shadow: 2px 2px 0 var(--border-color); }
+
+        /* Dark variant (input area) */
+        .iv-select-dark {
+          background: #111;
+          color: #e5e7eb;
+          border-color: #333;
+        }
+        .iv-select-dark option { background: #111; color: #e5e7eb; }
+
+        /* ── GoT button ────────────────────────────────────────────── */
+        .iv-got-btn {
+          display: inline-flex;
+          align-items: center;
+          gap: 5px;
+          border: 2px solid var(--border-color);
+          background: var(--bg-color);
+          color: var(--text-color);
+          font-family: var(--font-mono);
+          font-size: 0.75rem;
+          font-weight: 700;
+          padding: 0.32rem 0.75rem;
+          cursor: pointer;
+          transition: all 0.13s;
+          white-space: nowrap;
+        }
+        .iv-got-btn.active { background: #000; color: #fff; border-color: #000; }
+        .iv-got-btn:hover:not(.active) { background: #f3f4f6; }
+
+        /* ── Info bar ──────────────────────────────────────────────── */
+        .iv-info-bar {
+          display: flex;
+          align-items: flex-start;
+          gap: 0.5rem;
+          padding: 0.45rem 1.5rem;
+          background: var(--surface-color);
+          border-bottom: 1px solid #e5e5e5;
+          font-size: 0.75rem;
+          color: var(--muted-color);
+          line-height: 1.5;
+          flex-shrink: 0;
+        }
+        .iv-info-bar strong { color: var(--text-color); }
+        .iv-info-bar kbd {
+          background: #e5e7eb; border: 1px solid #d1d5db;
+          border-radius: 3px; padding: 0 4px;
+          font-family: var(--font-mono); font-size: 0.7rem;
+        }
+
+        /* ── Body: sidebar + chat ──────────────────────────────────── */
+        .iv-body {
+          display: flex;
+          flex: 1;
+          min-height: 0;
+          overflow: hidden;
+        }
+
+        /* ── Sidebar ───────────────────────────────────────────────── */
+        .iv-sidebar {
+          display: flex;
+          flex-direction: column;
+          border-right: 3px solid var(--border-color);
+          background: var(--bg-color);
+          flex-shrink: 0;
+          overflow: hidden;
+          transition: width 0.22s ease;
+        }
+        .iv-sidebar.open  { width: 220px; }
+        .iv-sidebar.closed { width: 0; border-right: none; }
+
+        .iv-new-thread {
+          width: 100%;
+          border: none;
+          border-bottom: 3px solid var(--border-color);
+          padding: 0.9rem 1rem;
+          background: #000;
+          color: #fff;
+          font-family: var(--font-mono);
+          font-size: 0.82rem;
+          font-weight: 700;
+          letter-spacing: 1px;
+          cursor: pointer;
+          flex-shrink: 0;
+          text-align: left;
+          transition: background 0.13s;
+          white-space: nowrap;
+        }
+        .iv-new-thread:hover { background: #222; }
+
+        .iv-thread-list {
+          flex: 1;
+          overflow-y: auto;
+          padding: 0.75rem;
+        }
+
+        .iv-thread-header {
+          font-family: var(--font-mono);
+          font-size: 0.6rem;
+          font-weight: 700;
+          color: var(--muted-color);
+          letter-spacing: 1px;
+          border-bottom: 1px dotted var(--border-color);
+          padding-bottom: 0.4rem;
+          margin-bottom: 0.6rem;
+          white-space: nowrap;
+        }
+
+        .iv-thread-item {
+          padding: 0.6rem 0.7rem;
+          border: 1.5px solid var(--border-color);
+          cursor: pointer;
+          margin-bottom: 0.4rem;
+          transition: background 0.13s;
+        }
+        .iv-thread-item:hover, .iv-thread-item.active {
+          background: var(--text-color);
+          color: var(--bg-color);
+          border-color: var(--text-color);
+        }
+        .iv-thread-title {
+          font-family: var(--font-mono);
+          font-size: 0.78rem;
+          font-weight: 600;
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+        }
+        .iv-thread-date {
+          font-family: var(--font-mono);
+          font-size: 0.65rem;
+          opacity: 0.65;
+          margin-top: 3px;
+        }
+        .iv-empty-threads {
+          font-family: var(--font-mono);
+          color: #bbb;
+          font-size: 0.78rem;
+          text-align: center;
+          padding: 1.5rem 0;
+        }
+
+        /* ── Chat panel ────────────────────────────────────────────── */
+        .iv-chat-panel {
+          flex: 1;
+          min-width: 0;
+          display: flex;
+          flex-direction: column;
+          overflow: hidden;
+        }
+
+        /* ── Messages ──────────────────────────────────────────────── */
+        .iv-messages {
+          flex: 1;
+          overflow-y: auto;
+          padding: 1.5rem;
+          display: flex;
+          flex-direction: column;
+          gap: 1.5rem;
+          scroll-behavior: smooth;
+        }
+
+        .iv-empty-chat {
+          flex: 1;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          gap: 1rem;
+          color: var(--muted-color);
+          font-family: var(--font-mono);
+          font-size: 0.88rem;
+          letter-spacing: 1.5px;
+          text-align: center;
+          padding: 3rem;
+        }
+        .iv-empty-hints {
+          display: flex;
+          flex-direction: column;
+          gap: 0.4rem;
+          margin-top: 0.75rem;
+          font-size: 0.72rem;
+          opacity: 0.6;
+        }
+
+        /* ── Message row ─────────────────────────────────────────── */
+        .iv-msg-row {
+          display: flex;
+          gap: 1rem;
+          align-items: flex-start;
+          max-width: 90%;
+        }
+        .iv-msg-row.user {
+          align-self: flex-end;
+          flex-direction: row-reverse;
+          max-width: 72%;
+        }
+        .iv-msg-row.assistant { align-self: flex-start; max-width: 90%; }
+
+        .iv-msg-avatar {
+          width: 36px;
+          height: 36px;
+          border: 2px solid var(--border-color);
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          flex-shrink: 0;
+          background: var(--bg-color);
+        }
+        .iv-msg-row.assistant .iv-msg-avatar {
+          background: #000;
+          color: #fff;
+          border-color: #000;
+        }
+
+        .iv-msg-card {
+          flex: 1;
+          border: 2px solid var(--border-color);
+          background: var(--bg-color);
+          min-width: 0;
+          box-shadow: 4px 4px 0 rgba(0,0,0,0.05);
+        }
+        .iv-msg-row.assistant .iv-msg-card {
+          border-left: 4px solid #000;
+        }
+        .iv-msg-row.user .iv-msg-card {
+          border-color: #000;
+          background: #f8f8f8;
+          border-right: 4px solid #000;
+        }
+
+        .iv-msg-header {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          flex-wrap: wrap;
+          gap: 0.5rem;
+          padding: 0.5rem 0.85rem;
+          border-bottom: 1px dotted var(--border-color);
+          background: var(--surface-color);
+        }
+        .iv-msg-role {
+          font-family: var(--font-mono);
+          font-size: 0.68rem;
+          font-weight: 700;
+          letter-spacing: 1px;
+          color: var(--muted-color);
+        }
+
+        .iv-msg-badges {
+          display: flex;
+          align-items: center;
+          gap: 0.4rem;
+          flex-wrap: wrap;
+        }
+        .iv-badge {
+          font-family: var(--font-mono);
+          font-size: 0.65rem;
+          font-weight: 700;
+          color: #fff;
+          padding: 1px 7px;
+          letter-spacing: 0.3px;
+        }
+        .iv-badge-outline {
+          font-family: var(--font-mono);
+          font-size: 0.65rem;
+          font-weight: 700;
+          padding: 1px 6px;
+          border: 1.5px solid;
+          cursor: help;
+        }
+
+        /* ── Reasoning chain ─────────────────────────────────────── */
+        .iv-reasoning {
+          padding: 0.75rem 0.85rem;
+          background: #fafafa;
+          border-bottom: 1px dotted var(--border-color);
+          display: flex;
+          flex-direction: column;
+          gap: 3px;
+        }
+        .iv-reasoning-step {
+          display: flex;
+          gap: 0.5rem;
+          font-family: var(--font-mono);
+          font-size: 0.75rem;
+          color: #555;
+          line-height: 1.5;
+        }
+        .iv-step-idx {
+          background: #000;
+          color: #fff;
+          font-size: 0.6rem;
+          font-weight: 700;
+          width: 16px;
+          height: 16px;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          flex-shrink: 0;
+          margin-top: 2px;
+        }
+
+        /* ── Message content ─────────────────────────────────────── */
+        .iv-msg-content {
+          padding: 0.85rem;
+        }
+
+        .iv-markdown { font-family: var(--font-sans); font-size: 0.97rem; line-height: 1.8; }
+        .iv-markdown p { margin-bottom: 0.75rem; }
+        .iv-markdown p:last-child { margin-bottom: 0; }
+        .iv-markdown ul, .iv-markdown ol { margin-bottom: 0.75rem; padding-left: 1.5rem; }
+        .iv-markdown li { margin-bottom: 0.2rem; }
+        .iv-markdown h1, .iv-markdown h2, .iv-markdown h3 { font-family: var(--font-display); margin: 1rem 0 0.5rem; }
+        .iv-markdown code { font-family: var(--font-mono); background: #f3f4f6; padding: 1px 5px; font-size: 0.85em; }
+        .iv-markdown pre { background: #1e293b; color: #e2e8f0; padding: 1rem; overflow-x: auto; margin-bottom: 0.75rem; }
+        .iv-markdown pre code { background: transparent; color: inherit; padding: 0; }
+        .iv-markdown table { border-collapse: collapse; width: 100%; margin-bottom: 0.75rem; font-size: 0.9rem; }
+        .iv-markdown th, .iv-markdown td { border: 1px solid var(--border-color); padding: 0.4rem 0.6rem; }
+        .iv-markdown th { background: var(--surface-color); font-family: var(--font-mono); font-size: 0.75rem; }
+        .iv-markdown blockquote { border-left: 3px solid #000; margin: 0 0 0.75rem; padding: 0.5rem 0.75rem; color: #555; background: #fafafa; }
+
+        .iv-cursor { animation: blink 0.9s step-end infinite; font-size: 1.1rem; }
+        @keyframes blink { 50% { opacity: 0; } }
+
+        /* ── Sources ──────────────────────────────────────────────── */
+        .iv-sources {
+          padding: 0.65rem 0.85rem;
+          border-top: 1px dashed var(--border-color);
+          background: #fafafa;
+        }
+        .iv-sources-top {
+          display: flex;
+          align-items: flex-start;
+          justify-content: space-between;
+          gap: 0.75rem;
+          flex-wrap: wrap;
+        }
+        .iv-sources-label {
+          font-family: var(--font-mono);
+          font-size: 0.7rem;
+          font-weight: 700;
+          color: var(--muted-color);
+          display: flex;
+          align-items: center;
+          gap: 0.5rem;
+          flex-wrap: wrap;
+        }
+        .iv-source-chips { display: flex; flex-wrap: wrap; gap: 4px; }
+        .iv-source-chip {
+          background: var(--bg-color);
+          border: 1px solid var(--border-color);
+          padding: 2px 8px;
+          cursor: pointer;
+          font-family: var(--font-mono);
+          font-size: 0.7rem;
+          transition: all 0.12s;
+        }
+        .iv-source-chip:hover { background: #000; color: #fff; border-color: #000; }
+
+        .iv-eval-btn {
+          font-family: var(--font-mono);
+          font-size: 0.68rem;
+          font-weight: 700;
+          border: 2px solid #000;
+          background: var(--bg-color);
+          color: var(--text-color);
+          padding: 2px 10px;
+          cursor: pointer;
+          letter-spacing: 0.5px;
+          white-space: nowrap;
+          transition: all 0.12s;
+          flex-shrink: 0;
+        }
+        .iv-eval-btn:hover:not(:disabled) { background: #000; color: #fff; }
+        .iv-eval-btn:disabled { opacity: 0.4; cursor: not-allowed; }
+
+        /* ── Eval results ─────────────────────────────────────────── */
+        .iv-eval-result {
+          margin-top: 0.65rem;
+          padding: 0.75rem;
+          border: 1px solid var(--border-color);
+          background: var(--bg-color);
+        }
+        .iv-eval-title {
+          font-family: var(--font-mono);
+          font-size: 0.65rem;
+          font-weight: 700;
+          color: var(--muted-color);
+          letter-spacing: 1px;
+          margin-bottom: 0.6rem;
+        }
+        .iv-eval-grid { display: flex; flex-direction: column; gap: 0.4rem; }
+        .iv-eval-metric { display: flex; align-items: center; gap: 0.6rem; }
+        .iv-eval-label { font-family: var(--font-mono); font-size: 0.65rem; color: #666; width: 80px; flex-shrink: 0; }
+        .iv-eval-bar-wrap { flex: 1; height: 5px; background: #e5e7eb; }
+        .iv-eval-bar { height: 100%; transition: width 0.4s ease; }
+        .iv-eval-pct { font-family: var(--font-mono); font-size: 0.72rem; font-weight: 700; width: 36px; text-align: right; }
+
+        /* ── Input area ───────────────────────────────────────────── */
+        .iv-input-area {
+          border-top: 3px solid var(--border-color);
+          background: #000;
+          flex-shrink: 0;
+          display: flex;
+          flex-direction: column;
+        }
+
+        .iv-input-controls {
+          display: flex;
+          align-items: flex-end;
+          gap: 1rem;
+          padding: 0.55rem 1rem 0.45rem;
+          border-bottom: 1px dotted #333;
+          flex-wrap: wrap;
+        }
+        .iv-input-controls .iv-ctrl-label { color: #888; }
+        .iv-input-controls .iv-select-chevron { color: #888; }
+
+        .iv-agent-input {
+          font-family: var(--font-mono);
+          font-size: 0.82rem;
+          font-weight: 600;
+          border: 2px solid #444;
+          background: #111;
+          color: #fff;
+          padding: 0.32rem 0.65rem;
+          width: 160px;
+          outline: none;
+        }
+        .iv-agent-input:focus { border-color: #f59e0b; box-shadow: 2px 2px 0 #f59e0b; }
+        .iv-agent-input::placeholder { color: #888; }
+
+        .iv-scope-chip {
+          display: inline-flex;
+          align-items: center;
+          gap: 5px;
+          border: 1.5px solid #444;
+          background: #111;
+          color: #aaa;
+          font-family: var(--font-mono);
+          font-size: 0.7rem;
+          padding: 3px 8px;
+          align-self: flex-end;
+          margin-bottom: 2px;
+        }
+        .iv-scope-chip button {
+          background: none;
+          border: none;
+          color: #aaa;
+          cursor: pointer;
+          padding: 0;
+          display: flex;
+          align-items: center;
+        }
+        .iv-scope-chip button:hover { color: #ef4444; }
+
+        /* ── Text input row ───────────────────────────────────────── */
+        .iv-input-row {
+          display: flex;
+          align-items: center;
+          padding: 0 0.5rem 0 1rem;
+          gap: 0.5rem;
+          min-height: 56px;
+        }
+
+        .iv-prompt-marker {
+          font-family: var(--font-mono);
+          font-size: 1.3rem;
+          font-weight: 700;
+          color: #fff;
+          flex-shrink: 0;
+          user-select: none;
+        }
+
+        .iv-text-input {
+          flex: 1;
+          background: transparent;
+          border: none;
+          outline: none;
+          font-family: var(--font-mono);
+          font-size: 1rem;
+          color: #fff;
+          padding: 0.75rem 0.5rem;
+          caret-color: #fff;
+        }
+        .iv-text-input::placeholder { color: #666; }
+        .iv-text-input:disabled { opacity: 0.4; cursor: not-allowed; }
+
+        .iv-send-btn {
+          width: 44px;
+          height: 44px;
+          border: 2px solid #444;
+          background: #111;
+          color: #888;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          cursor: pointer;
+          flex-shrink: 0;
+          transition: all 0.13s;
+        }
+        .iv-send-btn:hover:not(:disabled) { background: #fff; color: #000; border-color: #fff; }
+        .iv-send-btn:disabled { opacity: 0.35; cursor: not-allowed; pointer-events: none; }
+
+        .iv-spinner {
+          width: 18px;
+          height: 18px;
+          border: 2px solid #444;
+          border-top-color: #fff;
+          border-radius: 50%;
+          animation: spin 0.8s linear infinite;
+        }
+        @keyframes spin { 100% { transform: rotate(360deg); } }
+
+        /* ── Source drawer (modal style) ─────────────────────────── */
+        .iv-drawer-overlay {
+          position: fixed;
+          inset: 0;
+          background: rgba(0,0,0,0.4);
+          z-index: 999;
+          display: flex;
+          align-items: stretch;
+          justify-content: flex-end;
+        }
+
+        .iv-drawer {
+          width: min(420px, 95vw);
+          background: var(--bg-color);
+          border-left: 3px solid var(--border-color);
+          display: flex;
+          flex-direction: column;
+          animation: slideIn 0.22s ease-out;
+          box-shadow: -8px 0 32px rgba(0,0,0,0.15);
+        }
+        @keyframes slideIn { from { transform: translateX(100%); } to { transform: translateX(0); } }
+
+        .iv-drawer-header {
+          padding: 1rem 1.25rem;
+          border-bottom: 3px solid var(--border-color);
+          background: var(--surface-color);
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          flex-shrink: 0;
+        }
+        .iv-drawer-header h3 { margin: 0; font-size: 0.85rem; }
+
+        .iv-drawer-close {
+          width: 32px;
+          height: 32px;
+          border: 2px solid var(--border-color);
+          background: var(--bg-color);
+          color: var(--text-color);
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          cursor: pointer;
+          transition: all 0.12s;
+        }
+        .iv-drawer-close:hover { background: #000; color: #fff; border-color: #000; }
+
+        .iv-drawer-body {
+          flex: 1;
+          overflow-y: auto;
+          padding: 1.25rem;
+        }
+
+        .iv-drawer-meta { margin-bottom: 1rem; }
+        .iv-meta-row {
+          display: flex;
+          gap: 0.75rem;
+          margin-bottom: 0.5rem;
+          font-family: var(--font-mono);
+          font-size: 0.8rem;
+          align-items: flex-start;
+        }
+        .iv-meta-key { font-weight: 700; color: var(--muted-color); min-width: 80px; flex-shrink: 0; }
+
+        .iv-drawer-divider {
+          border: none;
+          border-top: 1px dashed var(--border-color);
+          margin: 0.75rem 0 1rem;
+        }
+
+        .iv-drawer-text {
+          font-family: var(--font-mono);
+          font-size: 0.82rem;
+          line-height: 1.7;
+          white-space: pre-wrap;
+          color: #444;
+        }
+
+        /* ── Responsive ──────────────────────────────────────────── */
+        @media (max-width: 768px) {
+          .iv-header { padding: 0.5rem 0.75rem; }
+          .iv-title { font-size: 0.88rem; letter-spacing: 1px; }
+          .iv-info-bar { display: none; }
+          .iv-sidebar.open { width: 200px; }
+          .iv-messages { padding: 1rem 0.75rem; }
+          .iv-msg-row { max-width: 100% !important; }
+          .iv-msg-avatar { width: 28px; height: 28px; }
+          .iv-msg-card { font-size: 0.9rem; }
+          .iv-msg-content { padding: 0.6rem; }
+          .iv-input-controls { padding: 0.4rem 0.75rem; gap: 0.5rem; }
+          .iv-input-row { min-height: 46px; }
+          .iv-text-input { font-size: 0.9rem; }
+          .iv-select { max-width: 200px; }
+        }
+
+        @media (max-width: 480px) {
+          .iv-sidebar.open { 
+            position: absolute;
+            left: 0; top: 0; bottom: 0;
+            z-index: 50;
+            border-right: 3px solid #000;
+            box-shadow: 4px 0 20px rgba(0,0,0,0.2);
+          }
+          .iv-msg-row.user { max-width: 90% !important; }
+        }
+      `}</style>
+    </div>
+  );
+};
+
+export default InteractionView;

frontend-react/src/views/Login.tsx

@@ -0,0 +1,644 @@
+import React, { useState, useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useAuth } from '../context/AuthContext';
+import { LogIn, UserPlus, Eye, EyeOff } from 'lucide-react';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000/api';
+
+/* ─── Typewriter ─── */
+const useTypewriter = (words: string[], speed = 80, pause = 2200) => {
+  const [index, setIndex] = useState(0);
+  const [sub, setSub] = useState(0);
+  const [deleting, setDeleting] = useState(false);
+  const [text, setText] = useState('');
+  useEffect(() => {
+    const word = words[index % words.length];
+    const timer = setTimeout(() => {
+      if (!deleting) {
+        setText(word.slice(0, sub + 1));
+        setSub(s => s + 1);
+        if (sub + 1 === word.length) setTimeout(() => setDeleting(true), pause);
+      } else {
+        setText(word.slice(0, sub - 1));
+        setSub(s => s - 1);
+        if (sub - 1 === 0) { setDeleting(false); setIndex(i => i + 1); }
+      }
+    }, deleting ? speed / 2 : speed);
+    return () => clearTimeout(timer);
+  }, [sub, deleting, index]);
+  return text;
+};
+
+const Login: React.FC = () => {
+  const [isRegistering, setIsRegistering] = useState(false);
+  const [username, setUsername] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [showPassword, setShowPassword] = useState(false);
+
+  const { login } = useAuth();
+  const navigate = useNavigate();
+
+  const rotatingWords = ['Knowledge Graphs.', 'Logic Engines.', 'LLM Reasoning.', 'Entity Networks.', 'Semantic Search.'];
+  const rotating = useTypewriter(rotatingWords);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError('');
+    setLoading(true);
+    try {
+      if (isRegistering) {
+        const regRes = await fetch(`${API_BASE}/auth/register`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ username, password, scopes: ['read', 'write', 'admin'] }),
+        });
+        if (!regRes.ok) {
+          const errData = await regRes.json();
+          throw new Error(errData.detail || 'Registration failed');
+        }
+      }
+      const loginRes = await fetch(`${API_BASE}/auth/login`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ username, password }),
+      });
+      if (!loginRes.ok) {
+        const errData = await loginRes.json();
+        throw new Error(errData.detail || 'Login failed');
+      }
+      const { access_token } = await loginRes.json();
+      const userRes = await fetch(`${API_BASE}/auth/me`, {
+        headers: { Authorization: `Bearer ${access_token}` },
+      });
+      if (!userRes.ok) throw new Error('Failed to fetch user profile');
+      const user = await userRes.json();
+      login(access_token, user);
+      navigate('/');
+    } catch (err: any) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="lp-root">
+
+      {/* ── Brand mark top-left ── */}
+      <div className="lp-brand">
+        <span className="lp-brand-dot" />
+        CORTEX
+      </div>
+
+      {/* ── Version badge top-right ── */}
+      <div className="lp-version">v1.0 · PRODUCTION</div>
+
+      {/* ── Giant background wordmark ── */}
+      <div className="lp-bg-word" aria-hidden>COR</div>
+      <div className="lp-bg-word lp-bg-word-2" aria-hidden>TEX</div>
+
+      {/* ── Hero headline, top-center area ── */}
+      <div className="lp-headline">
+        <div className="lp-headline-super">AGENTIC KNOWLEDGE PLATFORM</div>
+        <h1 className="lp-headline-h1">
+          Enterprise-grade<br/>
+          <span className="lp-headline-rotating">
+            {rotating}<span className="lp-cursor">|</span>
+          </span>
+        </h1>
+      </div>
+
+      {/* ── Floating stat chips ── */}
+      <div className="lp-stat lp-stat-1">
+        <div className="lp-stat-num">Neo4j</div>
+        <div className="lp-stat-key">GRAPH ENGINE</div>
+      </div>
+      <div className="lp-stat lp-stat-2">
+        <div className="lp-stat-num">ReACT</div>
+        <div className="lp-stat-key">AGENT LOOP</div>
+      </div>
+      <div className="lp-stat lp-stat-3">
+        <div className="lp-stat-num">EVAL</div>
+        <div className="lp-stat-key">SCORING</div>
+      </div>
+      <div className="lp-stat lp-stat-4">
+        <div className="lp-stat-num">Multi-hop</div>
+        <div className="lp-stat-key">REASONING</div>
+      </div>
+
+      {/* ── Vertical feature list bottom-left ── */}
+      <div className="lp-features">
+        <div className="lp-features-label">CAPABILITIES</div>
+        {[
+          'Document ingestion → Knowledge graph',
+          'LLM entity & relationship extraction',
+          'Agentic multi-step query reasoning',
+          'Hallucination risk scoring',
+          'Ontology drift detection & governance',
+          'Entity enrichment & deduplication',
+          'Interactive D3 force visualization',
+          'Export: JSON · Cypher · GraphML',
+        ].map((f, i) => (
+          <div key={i} className="lp-feature-row">
+            <span className="lp-feature-tick">→</span>
+            <span>{f}</span>
+          </div>
+        ))}
+      </div>
+
+      {/* ── Horizontal tech stack bottom-center ── */}
+      <div className="lp-stack">
+        {['FastAPI', 'Neo4j', 'Redis', 'Celery', 'Gemini', 'LangChain'].map(t => (
+          <span key={t} className="lp-stack-tag">{t}</span>
+        ))}
+      </div>
+
+      {/* ── Bottom-right quote ── */}
+      <div className="lp-quote">
+        "Knowledge is only useful<br/>when it can be reasoned over."
+      </div>
+
+      {/* ── Decorative rule lines ── */}
+      <div className="lp-rule lp-rule-h1" aria-hidden />
+      <div className="lp-rule lp-rule-h2" aria-hidden />
+      <div className="lp-rule lp-rule-v1" aria-hidden />
+
+      {/* ── LOGIN CARD (right side, vertically centered) ── */}
+      <div className="lp-card-wrap">
+        <div className="login-card">
+          <h2 className="login-title">
+            {isRegistering ? 'INITIALIZE ACCESS' : 'SYSTEM AUTH'}
+          </h2>
+
+          {error && <div className="error-banner">{error}</div>}
+
+          <form onSubmit={handleSubmit} className="login-form">
+            <div className="input-group">
+              <label>IDENTIFIER [USER]</label>
+              <input
+                type="text"
+                value={username}
+                onChange={(e) => setUsername(e.target.value)}
+                required
+                className="mono-text"
+                autoComplete="username"
+              />
+            </div>
+
+            <div className="input-group">
+              <label>KEY [PASS]</label>
+              <div className="password-wrapper">
+                <input
+                  type={showPassword ? 'text' : 'password'}
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                  required
+                  className="mono-text"
+                  autoComplete="current-password"
+                />
+                <button
+                  type="button"
+                  className="eye-btn"
+                  onClick={() => setShowPassword(!showPassword)}
+                  tabIndex={-1}
+                  title="Toggle visibility"
+                >
+                  {showPassword ? <EyeOff size={16} /> : <Eye size={16} />}
+                </button>
+              </div>
+            </div>
+
+            <button type="submit" className="app-btn auth-btn" disabled={loading}>
+              {loading
+                ? 'PROCESSING...'
+                : isRegistering
+                  ? <><UserPlus size={16} /> REGISTER</>
+                  : <><LogIn size={16} /> AUTHENTICATE →</>
+              }
+            </button>
+          </form>
+
+          <p className="toggle-mode">
+            <button type="button" className="text-btn" onClick={() => setIsRegistering(!isRegistering)}>
+              {isRegistering ? 'RETURN TO LOGIN' : 'REQUEST ACCESS (REGISTER)'}
+            </button>
+          </p>
+
+          <div className="lp-card-footer">
+            <span>CORTEX PLATFORM</span>
+            <span>SECURED · ENCRYPTED</span>
+          </div>
+        </div>
+      </div>
+
+      <style>{`
+        /* ── Root ── */
+        .lp-root {
+          position: fixed;
+          inset: 0;
+          background: #fff;
+          overflow: hidden;
+          font-family: var(--font-sans);
+        }
+
+        /* ── Brand top-left ── */
+        .lp-brand {
+          position: absolute;
+          top: 2rem;
+          left: 2.5rem;
+          font-family: var(--font-mono);
+          font-size: 0.75rem;
+          font-weight: 900;
+          letter-spacing: 3px;
+          display: flex;
+          align-items: center;
+          gap: 0.5rem;
+          z-index: 10;
+        }
+        .lp-brand-dot {
+          width: 8px; height: 8px;
+          background: #000;
+          border-radius: 50%;
+          animation: brandPulse 2.5s ease-in-out infinite;
+        }
+        @keyframes brandPulse {
+          0%, 100% { transform: scale(1); }
+          50% { transform: scale(1.4); }
+        }
+
+        /* ── Version badge ── */
+        .lp-version {
+          position: absolute;
+          top: 2rem;
+          right: 420px;
+          font-family: var(--font-mono);
+          font-size: 0.65rem;
+          font-weight: 700;
+          letter-spacing: 2px;
+          color: #aaa;
+          z-index: 10;
+        }
+
+        /* ── Giant background wordmarks ── */
+        .lp-bg-word {
+          position: absolute;
+          top: -0.15em;
+          left: -0.05em;
+          font-family: var(--font-display);
+          font-size: clamp(200px, 28vw, 380px);
+          font-weight: 900;
+          line-height: 1;
+          color: transparent;
+          -webkit-text-stroke: 1.5px #ebebeb;
+          letter-spacing: -0.04em;
+          pointer-events: none;
+          user-select: none;
+          z-index: 0;
+        }
+        .lp-bg-word-2 {
+          top: auto;
+          bottom: -0.1em;
+          left: auto;
+          right: 360px;
+          -webkit-text-stroke: 1.5px #f0f0f0;
+          font-size: clamp(160px, 22vw, 300px);
+        }
+
+        /* ── Hero headline ── */
+        .lp-headline {
+          position: absolute;
+          top: 5rem;
+          left: 2.5rem;
+          right: 420px;
+          z-index: 5;
+        }
+        .lp-headline-super {
+          font-family: var(--font-mono);
+          font-size: 0.65rem;
+          font-weight: 700;
+          letter-spacing: 4px;
+          color: #999;
+          margin-bottom: 0.75rem;
+        }
+        .lp-headline-h1 {
+          font-family: var(--font-display);
+          font-size: clamp(2rem, 3.8vw, 3.4rem);
+          font-weight: 800;
+          line-height: 1.15;
+          letter-spacing: -0.5px;
+        }
+        .lp-headline-rotating {
+          display: inline-block;
+          border-bottom: 4px solid #000;
+          min-width: 2ch;
+        }
+        .lp-cursor {
+          display: inline-block;
+          width: 2px;
+          animation: blink 0.9s step-end infinite;
+          font-weight: 300;
+          margin-left: 1px;
+        }
+        @keyframes blink { 50% { opacity: 0; } }
+
+        /* ── Floating stat chips ── */
+        .lp-stat {
+          position: absolute;
+          border: 2px solid #000;
+          padding: 0.6rem 0.9rem;
+          z-index: 5;
+          background: #fff;
+          transition: transform 0.2s, box-shadow 0.2s;
+        }
+        .lp-stat:hover {
+          transform: translateY(-3px);
+          box-shadow: 4px 4px 0 #000;
+        }
+        .lp-stat-num {
+          font-family: var(--font-mono);
+          font-size: 0.88rem;
+          font-weight: 900;
+          line-height: 1;
+          margin-bottom: 0.2rem;
+        }
+        .lp-stat-key {
+          font-family: var(--font-mono);
+          font-size: 0.58rem;
+          color: #888;
+          letter-spacing: 1px;
+          font-weight: 700;
+        }
+        .lp-stat-1 { top: 36%;  left: 2.5rem; }
+        .lp-stat-2 { top: 37%;  left: 9rem; }
+        .lp-stat-3 { top: 44%;  left: 2.5rem; }
+        .lp-stat-4 { top: 44%;  left: 9rem; }
+
+        /* ── Feature list ── */
+        .lp-features {
+          position: absolute;
+          bottom: 5rem;
+          left: 2.5rem;
+          width: 340px;
+          z-index: 5;
+        }
+        .lp-features-label {
+          font-family: var(--font-mono);
+          font-size: 0.6rem;
+          font-weight: 700;
+          letter-spacing: 3px;
+          color: #bbb;
+          margin-bottom: 0.6rem;
+        }
+        .lp-feature-row {
+          display: flex;
+          gap: 0.5rem;
+          font-family: var(--font-sans);
+          font-size: 0.78rem;
+          color: #333;
+          padding: 0.22rem 0;
+          border-bottom: 1px solid #f0f0f0;
+          line-height: 1.5;
+        }
+        .lp-feature-tick {
+          font-family: var(--font-mono);
+          font-size: 0.72rem;
+          font-weight: 700;
+          color: #000;
+          flex-shrink: 0;
+          margin-top: 1px;
+        }
+
+        /* ── Tech stack ── */
+        .lp-stack {
+          position: absolute;
+          bottom: 1.75rem;
+          left: 2.5rem;
+          right: 420px;
+          display: flex;
+          gap: 0.5rem;
+          flex-wrap: wrap;
+          z-index: 5;
+        }
+        .lp-stack-tag {
+          font-family: var(--font-mono);
+          font-size: 0.65rem;
+          font-weight: 700;
+          letter-spacing: 0.5px;
+          border: 1.5px solid #000;
+          padding: 2px 8px;
+          background: #fff;
+        }
+
+        /* ── Bottom-right quote ── */
+        .lp-quote {
+          position: absolute;
+          bottom: 4rem;
+          right: 420px;
+          width: 240px;
+          font-family: var(--font-display);
+          font-size: 0.82rem;
+          font-style: italic;
+          color: #bbb;
+          text-align: right;
+          line-height: 1.6;
+          z-index: 5;
+        }
+
+        /* ── Decorative rules ── */
+        .lp-rule {
+          position: absolute;
+          background: #e8e8e8;
+          z-index: 4;
+          pointer-events: none;
+        }
+        .lp-rule-h1 {
+          top: 4rem;
+          left: 0; right: 0;
+          height: 1px;
+        }
+        .lp-rule-h2 {
+          bottom: 3.5rem;
+          left: 0; right: 0;
+          height: 1px;
+        }
+        .lp-rule-v1 {
+          top: 0; bottom: 0;
+          right: 400px;
+          width: 2px;
+          background: #000;
+        }
+
+        /* ── Login card ── */
+        .lp-card-wrap {
+          position: absolute;
+          top: 0; bottom: 0;
+          right: 0;
+          width: 400px;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          background: #fff;
+          z-index: 20;
+          padding: 2rem 2.5rem;
+        }
+
+        .login-card {
+          width: 100%;
+          animation: slideUp 0.45s ease both;
+        }
+        @keyframes slideUp {
+          from { transform: translateY(16px); opacity: 0; }
+          to   { transform: translateY(0);    opacity: 1; }
+        }
+
+        .login-title {
+          font-family: var(--font-display);
+          font-size: 1.15rem;
+          font-weight: 800;
+          letter-spacing: 2px;
+          margin-bottom: 2rem;
+          text-transform: uppercase;
+          border-bottom: 3px solid #000;
+          padding-bottom: 1rem;
+        }
+
+        .input-group {
+          margin-bottom: 1.25rem;
+        }
+        .input-group label {
+          display: block;
+          font-family: var(--font-mono);
+          font-size: 0.72rem;
+          font-weight: 700;
+          letter-spacing: 1px;
+          margin-bottom: 0.4rem;
+          color: #555;
+        }
+        .input-group input {
+          width: 100%;
+          border: 2px solid #000;
+          padding: 0.75rem;
+          font-size: 0.95rem;
+          background: #fafafa;
+          transition: box-shadow 0.15s;
+        }
+        .input-group input:focus {
+          outline: none;
+          box-shadow: 3px 3px 0 #000;
+          background: #fff;
+        }
+        .password-wrapper {
+          position: relative;
+          display: flex;
+          align-items: center;
+        }
+        .password-wrapper input { padding-right: 2.5rem; }
+        .eye-btn {
+          position: absolute;
+          right: 0.5rem;
+          background: none !important;
+          border: none !important;
+          cursor: pointer;
+          color: #888;
+          display: flex;
+          align-items: center;
+          transition: color 0.15s !important;
+        }
+        .eye-btn:hover { background: none !important; color: #000 !important; }
+
+        .auth-btn {
+          width: 100%;
+          padding: 0.9rem;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          gap: 0.5rem;
+          margin-top: 0.5rem;
+          font-size: 0.85rem;
+          letter-spacing: 1px;
+          background: #000;
+          color: #fff;
+          border: 2px solid #000;
+          transition: background 0.15s, transform 0.15s;
+        }
+        .auth-btn:hover:not(:disabled) {
+          background: #222;
+          transform: translateY(-1px);
+          box-shadow: 3px 3px 0 rgba(0,0,0,0.2);
+        }
+        .auth-btn:disabled { opacity: 0.5; }
+
+        .error-banner {
+          background: #000;
+          color: #fff;
+          padding: 0.6rem 0.75rem;
+          margin-bottom: 1.25rem;
+          font-family: var(--font-mono);
+          font-size: 0.78rem;
+          border-left: 4px solid #dc2626;
+        }
+
+        .toggle-mode {
+          text-align: center;
+          margin-top: 1.25rem;
+        }
+        .text-btn {
+          background: none;
+          border: none;
+          color: #555;
+          text-decoration: underline;
+          text-underline-offset: 4px;
+          cursor: pointer;
+          font-family: var(--font-mono);
+          font-size: 0.72rem;
+          letter-spacing: 0.5px;
+          transition: color 0.15s;
+        }
+        .text-btn:hover { color: #000; background: none; }
+
+        .lp-card-footer {
+          display: flex;
+          justify-content: space-between;
+          margin-top: 2rem;
+          padding-top: 1rem;
+          border-top: 1px solid #e5e5e5;
+          font-family: var(--font-mono);
+          font-size: 0.6rem;
+          color: #bbb;
+          letter-spacing: 0.5px;
+        }
+
+        /* ── Responsive ── */
+        @media (max-width: 800px) {
+          .lp-headline { right: 2rem; }
+          .lp-version { right: 2rem; }
+          .lp-rule-v1 { display: none; }
+          .lp-card-wrap {
+            position: fixed;
+            inset: 0;
+            width: 100%;
+            background: rgba(255,255,255,0.95);
+            backdrop-filter: blur(8px);
+          }
+          .lp-bg-word, .lp-bg-word-2, .lp-features, .lp-stack, .lp-quote,
+          .lp-stat-1, .lp-stat-2, .lp-stat-3, .lp-stat-4 { display: none; }
+        }
+
+        @media (max-height: 750px) {
+          .lp-headline { top: 4rem; }
+          .lp-headline-h1 { font-size: clamp(1.8rem, 3.5vw, 2.8rem); }
+          .lp-stat-1 { top: 32%; }
+          .lp-stat-2 { top: 33%; }
+          .lp-stat-3 { top: 41%; }
+          .lp-stat-4 { top: 41%; }
+          .lp-features { bottom: 4rem; transform: scale(0.9); transform-origin: left bottom; }
+          .lp-stack { display: none; }
+        }
+      `}</style>
+    </div>
+  );
+};
+
+export default Login;

frontend-react/src/views/Ontology.tsx

@@ -0,0 +1,803 @@
+import React, { useState, useEffect } from 'react';
+import { useAuth } from '../context/AuthContext';
+import { DriftReport, DocumentInfo } from '../types/api';
+import { Database, GitMerge, Settings, Sparkles, Save, Info, Zap, AlertTriangle, Check, X, FileText } from 'lucide-react';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000/api';
+
+const Ontology: React.FC = () => {
+  const { token, logout } = useAuth();
+  
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [refining, setRefining] = useState(false);
+  const [deduping, setDeduping] = useState(false);
+  const [enriching, setEnriching] = useState(false);
+  const [detectingDrift, setDetectingDrift] = useState(false);
+  const [driftReports, setDriftReports] = useState<DriftReport[]>([]);
+  
+  const [version, setVersion] = useState('');
+  const [entityTypes, setEntityTypes] = useState('');
+  const [relationshipTypes, setRelationshipTypes] = useState('');
+  const [properties, setProperties] = useState('');
+  const [feedback, setFeedback] = useState('');
+  
+  // "Global" baseline so we can restore when switching back to global mode
+  const [globalEntityTypes, setGlobalEntityTypes] = useState('');
+  const [globalRelationshipTypes, setGlobalRelationshipTypes] = useState('');
+  const [globalProperties, setGlobalProperties] = useState('');
+  
+  const [documents, setDocuments] = useState<DocumentInfo[]>([]);
+  const [selectedDocId, setSelectedDocId] = useState<string>('');
+  const [stats, setStats] = useState<any>(null);
+  const [docSchemaLoading, setDocSchemaLoading] = useState(false);
+  
+  const [message, setMessage] = useState('');
+
+  /* ── Fetch global ontology ─────────────────────────────────────── */
+  const fetchOntology = async () => {
+    setLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/ontology`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.status === 401) { logout(); return; }
+      if (res.ok) {
+        const data = await res.json();
+        setVersion(data.version || '1.0');
+        const ent = data.entity_types?.join(', ') || '';
+        const rel = data.relationship_types?.join(', ') || '';
+        const props = JSON.stringify(data.properties || {}, null, 2);
+        setEntityTypes(ent);
+        setRelationshipTypes(rel);
+        setProperties(props);
+        // Save as global baseline
+        setGlobalEntityTypes(ent);
+        setGlobalRelationshipTypes(rel);
+        setGlobalProperties(props);
+      } else {
+        setMessage('No active ontology found. Please upload documents first.');
+      }
+    } catch (err) {
+      console.error(err);
+      setMessage('FAILED TO LOAD ONTOLOGY API');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const fetchDocuments = async () => {
+    try {
+      const res = await fetch(`${API_BASE}/documents`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const data = await res.json();
+        setDocuments(data.documents);
+      }
+    } catch (err) {
+      console.error('Failed to fetch docs for dropdown', err);
+    }
+  };
+
+  const fetchStats = async (docId: string) => {
+    try {
+      const url = new URL(`${API_BASE}/ontology/stats`);
+      if (docId) url.searchParams.append('document_id', docId);
+      const res = await fetch(url.toString(), {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) setStats(await res.json());
+      else setStats(null);
+    } catch { setStats(null); }
+  };
+
+  /* ── Fetch document-specific schema ─────────────────────────────── */
+  const fetchDocSchema = async (docId: string) => {
+    if (!docId) {
+      // Restore global schema
+      setEntityTypes(globalEntityTypes);
+      setRelationshipTypes(globalRelationshipTypes);
+      setProperties(globalProperties);
+      return;
+    }
+    setDocSchemaLoading(true);
+    try {
+      const url = new URL(`${API_BASE}/ontology/stats`);
+      url.searchParams.append('document_id', docId);
+      const res = await fetch(url.toString(), {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const data = await res.json();
+        // Populate editor with document-specific entity types and relationships
+        const docEntityTypes = (data.entity_stats || [])
+          .map((s: any) => s.type)
+          .filter(Boolean)
+          .join(', ');
+        const docRelTypes = (data.relationship_stats || [])
+          .map((s: any) => s.type)
+          .filter(Boolean)
+          .join(', ');
+        
+        setEntityTypes(docEntityTypes || globalEntityTypes);
+        setRelationshipTypes(docRelTypes || globalRelationshipTypes);
+        // Properties: keep global properties since per-doc isn't tracked separately
+        setProperties(globalProperties);
+      }
+    } catch (err) {
+      console.error('Failed to fetch doc schema', err);
+    } finally {
+      setDocSchemaLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchOntology();
+    fetchDocuments();
+    fetchStats('');
+  }, [token]);
+
+  useEffect(() => {
+    fetchStats(selectedDocId);
+    fetchDocSchema(selectedDocId);
+  }, [selectedDocId]);
+
+  const handleSave = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSaving(true);
+    setMessage('');
+    
+    let parsedProps = {};
+    try {
+      parsedProps = JSON.parse(properties);
+    } catch (e) {
+      setMessage('ERROR: PROPERTIES MUST BE VALID JSON');
+      setSaving(false);
+      return;
+    }
+
+    try {
+      const res = await fetch(`${API_BASE}/ontology`, {
+        method: 'PUT',
+        headers: { 
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${token}` 
+        },
+        body: JSON.stringify({
+          entity_types: entityTypes.split(',').map(s => s.trim()).filter(Boolean),
+          relationship_types: relationshipTypes.split(',').map(s => s.trim()).filter(Boolean),
+          properties: parsedProps,
+          approved: true
+        })
+      });
+      
+      if (res.status === 401) { logout(); return; }
+      
+      if (res.ok) {
+        setMessage('ONTOLOGY SCHEMA UPDATED');
+        fetchOntology();
+        setSelectedDocId(''); // reset to global after save
+      } else {
+        setMessage('FAILED TO SAVE SCHEMA');
+      }
+    } catch (err) {
+      console.error(err);
+      setMessage('API ERROR DURING SAVE');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleRefine = async () => {
+    setRefining(true);
+    setMessage('ANALYZING GRAPH FOR UPGRADES... (THIS MAY TAKE 30s+)');
+    try {
+      const res = await fetch(`${API_BASE}/ontology/refine`, {
+        method: 'POST',
+        headers: { 
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${token}` 
+        },
+        body: JSON.stringify({ 
+          feedback: feedback || undefined,
+          document_id: selectedDocId || undefined
+        })
+      });
+      
+      if (res.status === 401) { logout(); return; }
+      
+      if (res.ok) {
+        const data = await res.json();
+        setMessage(`SUCCESS: ${data.changes}`);
+        fetchOntology();
+      } else {
+        setMessage('FAILED TO REFINE SCHEMA');
+      }
+    } catch (err) {
+      console.error(err);
+      setMessage('API ERROR DURING REFINE');
+    } finally {
+      setRefining(false);
+    }
+  };
+
+  const handleDeduplicate = async () => {
+    if (!window.confirm("Run semantic merging? This cannot be undone.")) return;
+    setDeduping(true);
+    setMessage('SCANNING GRAPH FOR DUPLICATE ENTITIES... (THIS MAY TAKE AWHILE)');
+    try {
+      const res = await fetch(`${API_BASE}/entities/deduplicate`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.status === 401) { logout(); return; }
+      if (res.ok) {
+        const data = await res.json();
+        setMessage(`DEDUPLICATION COMPLETE: Merged ${data.merged_count} entities.`);
+      } else {
+        setMessage('FAILED TO DEDUPLICATE ENTITIES');
+      }
+    } catch (err) {
+      console.error(err);
+      setMessage('API ERROR DURING DEDUPLICATION');
+    } finally {
+      setDeduping(false);
+    }
+  };
+
+  const handleEnrichEntities = async () => {
+    setEnriching(true);
+    setMessage('GENERATING ENTITY PROFILES FROM GRAPH NEIGHBORHOODS...');
+    try {
+      const res = await fetch(`${API_BASE}/entities/enrich`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ batch_size: 20, min_connections: 1 })
+      });
+      if (res.status === 401) { logout(); return; }
+      if (res.ok) {
+        const data = await res.json();
+        setMessage(`ENRICHMENT COMPLETE: ${data.message || `${data.enriched_count ?? '?'} entities profiled.`}`);
+      } else {
+        setMessage('FAILED TO ENRICH ENTITIES');
+      }
+    } catch {
+      setMessage('API ERROR DURING ENRICHMENT');
+    } finally {
+      setEnriching(false);
+    }
+  };
+
+  const handleDetectDrift = async () => {
+    setDetectingDrift(true);
+    setMessage('ANALYZING GRAPH DATA FOR SCHEMA DRIFT...');
+    try {
+      const res = await fetch(`${API_BASE}/ontology/drift/detect`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.status === 401) { logout(); return; }
+      if (res.ok) {
+        const data = await res.json();
+        setMessage(`DRIFT REPORT CREATED: ID ${data.report_id || data.id || '—'}`);
+        fetchDriftReports();
+      } else {
+        setMessage('FAILED TO DETECT DRIFT');
+      }
+    } catch {
+      setMessage('API ERROR DURING DRIFT DETECTION');
+    } finally {
+      setDetectingDrift(false);
+    }
+  };
+
+  const fetchDriftReports = async () => {
+    try {
+      const res = await fetch(`${API_BASE}/ontology/drift`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const data = await res.json();
+        setDriftReports(data.reports || []);
+      }
+    } catch {}
+  };
+
+  const handleDriftAction = async (id: string, action: 'approve' | 'reject') => {
+    const res = await fetch(`${API_BASE}/ontology/drift/${id}/${action}`, {
+      method: 'POST', headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.ok) {
+      setDriftReports(d => d.filter(r => r.id !== id));
+      setMessage(`Drift report ${action}d.`);
+    }
+  };
+
+  const selectedDoc = documents.find(d => d.id === selectedDocId);
+
+  return (
+    <div className="container" style={{ animation: 'fadeIn 0.5s ease' }}>
+      <div className="page-header flex-between">
+        <div>
+          <h1>ONTOLOGY MANAGEMENT</h1>
+          <p className="mono-text">SCHEMA CONTROL &amp; GRAPH REFINEMENT</p>
+        </div>
+        <Database size={32} />
+      </div>
+
+      {/* Help info bar */}
+      <div className="page-info-bar">
+        <Info size={14}/>
+        <span>
+          <strong>ENTITY TYPES</strong> define what kinds of nodes exist in your graph.
+          <strong> RELATIONSHIP TYPES</strong> define how they connect.
+          Use <strong>LLM REFINEMENT</strong> to auto-suggest schema improvements from your data.
+          Use <strong>DRIFT DETECTION</strong> to detect when new data doesn't fit the current schema.
+          Use <strong>ENTITY ENRICHMENT</strong> to synthesize rich profiles for all graph nodes.
+        </span>
+      </div>
+
+      <div className="ontology-layout">
+        {/* Schema Editor */}
+        <div className="card editor-card">
+          <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: '1.5rem' }}>
+            <h2 className="mono-text flex-center" style={{ gap: '0.5rem', margin: 0 }}>
+              <Settings size={20}/> EDIT SCHEMA {version ? `v${version}` : ''}
+            </h2>
+            {selectedDocId && (
+              <div style={{ display: 'flex', alignItems: 'center', gap: '0.4rem', background: '#000', color: '#fff', padding: '3px 10px', fontFamily: 'var(--font-mono)', fontSize: '0.68rem', fontWeight: 700, letterSpacing: '0.5px' }}>
+                <FileText size={11} />
+                DOC SCOPE: {selectedDoc?.filename?.slice(0, 22) ?? selectedDocId.slice(0, 12)}…
+              </div>
+            )}
+          </div>
+
+          {/* Document selector in editor header */}
+          <div style={{ marginBottom: '1.25rem', padding: '0.75rem', background: '#f5f5f5', border: '1.5px solid #e5e5e5' }}>
+            <label className="control-label" style={{ display: 'block', marginBottom: '0.4rem' }}>
+              POPULATE FROM DOCUMENT
+            </label>
+            <select
+              className="mono-text doc-dropdown"
+              value={selectedDocId}
+              onChange={(e) => setSelectedDocId(e.target.value)}
+              style={{ width: '100%' }}
+            >
+              <option value="">🌐 GLOBAL — Full Ontology Schema</option>
+              {documents.map(doc => (
+                <option key={doc.id} value={doc.id}>📄 {doc.filename}</option>
+              ))}
+            </select>
+            {docSchemaLoading && (
+              <div style={{ fontFamily: 'var(--font-mono)', fontSize: '0.72rem', color: 'var(--muted-color)', marginTop: '0.4rem' }}>
+                ↻ Loading document schema…
+              </div>
+            )}
+            {selectedDocId && !docSchemaLoading && (
+              <div style={{ fontFamily: 'var(--font-mono)', fontSize: '0.68rem', color: '#16a34a', marginTop: '0.4rem', display: 'flex', alignItems: 'center', gap: '0.3rem' }}>
+                <Check size={11}/> Schema populated from "{selectedDoc?.filename ?? selectedDocId}"
+              </div>
+            )}
+          </div>
+          
+          {loading ? (
+            <div className="mono-text" style={{ padding: '2rem', textAlign: 'center' }}>LOADING SCHEMA...</div>
+          ) : (
+            <form onSubmit={handleSave} className="schema-form">
+              <div className="form-group">
+                <label className="mono-text">ENTITY TYPES (COMMA-SEPARATED)</label>
+                <textarea 
+                  value={entityTypes} 
+                  onChange={(e) => setEntityTypes(e.target.value)}
+                  className="mono-text"
+                  rows={3}
+                  placeholder="Person, Organization, Location, Event…"
+                />
+              </div>
+
+              <div className="form-group">
+                <label className="mono-text">RELATIONSHIP TYPES (COMMA-SEPARATED)</label>
+                <textarea 
+                  value={relationshipTypes} 
+                  onChange={(e) => setRelationshipTypes(e.target.value)}
+                  className="mono-text"
+                  rows={3}
+                  placeholder="WORKS_FOR, LOCATED_IN, RELATED_TO…"
+                />
+              </div>
+
+              <div className="form-group">
+                <label className="mono-text">PROPERTIES BINDING (JSON FORMAT)</label>
+                <textarea 
+                  value={properties} 
+                  onChange={(e) => setProperties(e.target.value)}
+                  className="mono-text dict-editor"
+                  rows={8}
+                />
+              </div>
+
+              <button 
+                type="submit" 
+                className="app-btn full-width" 
+                disabled={saving}
+                style={{ display: 'flex', justifyContent: 'center', gap: '8px' }}
+              >
+                <Save size={18} /> {saving ? 'SAVING...' : 'COMMIT SCHEMA CHANGES'}
+              </button>
+            </form>
+          )}
+
+        </div>
+
+        {/* AI Tools */}
+        <div className="tools-card-container">
+          <div className="card tools-card">
+            <h2 className="mono-text flex-center" style={{ gap: '0.5rem' }}>
+              <Sparkles size={20}/> LLM REFINEMENT
+            </h2>
+            <p style={{ marginTop: '1rem', marginBottom: '0.75rem', fontSize: '0.88rem', lineHeight: 1.6 }}>
+              Use the LLM Agent to scan existing document chunks and automatically suggest expansions or restructuring to the current ontology schema.
+            </p>
+
+            <div className="refine-info-box">
+              <Info size={13} />
+              <span>
+                <strong>Global mode:</strong> samples random chunks from all documents.<br/>
+                <strong>Targeted mode:</strong> only scans chunks from the selected document — useful for domain-specific refinement.
+              </span>
+            </div>
+
+            <label className="control-label" style={{ display: 'block', marginBottom: '0.4rem', marginTop: '1rem' }}>REFINEMENT SCOPE</label>
+            <select 
+              className="mono-text doc-dropdown" 
+              value={selectedDocId} 
+              onChange={(e) => setSelectedDocId(e.target.value)}
+              style={{ width: '100%', marginBottom: '1rem' }}
+            >
+              <option value="">🌐 GLOBAL — ALL DOCUMENTS (RANDOM CHUNKS)</option>
+              {documents.map(doc => (
+                <option key={doc.id} value={doc.id}>📄 TARGET: {doc.filename}</option>
+              ))}
+            </select>
+            <label className="control-label" style={{ display: 'block', marginBottom: '0.4rem' }}>OPTIONAL CRITERIA</label>
+            <textarea 
+              placeholder="e.g., 'Focus heavily on extracting medical symptoms and treatment names'"
+              value={feedback}
+              onChange={(e) => setFeedback(e.target.value)}
+              className="mono-text"
+              rows={3}
+              style={{ width: '100%', marginBottom: '1rem' }}
+            />
+            <button 
+              onClick={handleRefine}
+              className="app-btn outline-btn full-width" 
+              disabled={refining || loading}
+              style={{ display: 'flex', justifyContent: 'center', gap: '8px' }}
+            >
+              <Sparkles size={18} /> {refining ? 'ANALYZING GRAPH...' : 'REFINE SCHEMA'}
+            </button>
+          </div>
+
+          <div className="card tools-card" style={{ marginTop: '2rem' }}>
+            <h2 className="mono-text flex-center" style={{ gap: '0.5rem' }}>
+              <GitMerge size={20}/> IDENTITY RESOLUTION
+            </h2>
+            <p style={{ marginTop: '1rem', marginBottom: '1rem', fontSize: '0.9rem', lineHeight: 1.5 }}>
+              Scan the entire Knowledge Graph and use Semantic Embedding comparisons to detect and permanently merge duplicated entities.
+            </p>
+            <button
+              onClick={handleDeduplicate}
+              className="app-btn outline-btn full-width"
+              disabled={deduping || loading}
+              style={{ display: 'flex', justifyContent: 'center', gap: '8px' }}
+            >
+              <GitMerge size={18} /> {deduping ? 'MERGING...' : 'DEDUPLICATE ENTITIES'}
+            </button>
+          </div>
+
+          {/* Entity Enrichment */}
+          <div className="card tools-card" style={{ marginTop: '2rem' }}>
+            <h2 className="mono-text flex-center" style={{ gap: '0.5rem' }}>
+              <Zap size={20}/> ENTITY ENRICHMENT
+            </h2>
+            <p style={{ marginTop: '1rem', marginBottom: '1rem', fontSize: '0.9rem', lineHeight: 1.5 }}>
+              Generate rich LLM-synthesized profiles for all eligible entities using their graph neighborhood context. Profiles power the Entity Chat feature.
+            </p>
+            <button
+              onClick={handleEnrichEntities}
+              className="app-btn outline-btn full-width"
+              disabled={enriching || loading}
+              style={{ display: 'flex', justifyContent: 'center', gap: '8px' }}
+            >
+              <Zap size={18} /> {enriching ? 'ENRICHING...' : 'ENRICH ALL ENTITIES'}
+            </button>
+          </div>
+
+          {/* Drift Detection */}
+          <div className="card tools-card" style={{ marginTop: '2rem' }}>
+            <h2 className="mono-text flex-center" style={{ gap: '0.5rem' }}>
+              <AlertTriangle size={20}/> ONTOLOGY DRIFT
+            </h2>
+            <p style={{ marginTop: '1rem', marginBottom: '1rem', fontSize: '0.9rem', lineHeight: 1.5 }}>
+              Detect when new incoming data no longer fits the current schema. The drift detector proposes additions for review.
+            </p>
+            <button
+              onClick={handleDetectDrift}
+              className="app-btn outline-btn full-width"
+              disabled={detectingDrift || loading}
+              style={{ display: 'flex', justifyContent: 'center', gap: '8px', marginBottom: driftReports.length > 0 ? '1rem' : 0 }}
+            >
+              <AlertTriangle size={18} /> {detectingDrift ? 'DETECTING...' : 'DETECT DRIFT'}
+            </button>
+            {driftReports.length > 0 && (
+              <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem', marginTop: '0.5rem' }}>
+                <div className="control-label" style={{ marginBottom: '0.25rem' }}>PENDING DRIFT REPORTS</div>
+                {driftReports.slice(0, 3).map(r => (
+                  <div key={r.id} style={{ border: '1px solid #e5e5e5', padding: '0.6rem 0.75rem', display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: '0.5rem' }}>
+                    <span style={{ fontFamily: 'var(--font-mono)', fontSize: '0.72rem', flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                      {r.summary || r.id}
+                    </span>
+                    <div style={{ display: 'flex', gap: '4px', flexShrink: 0 }}>
+                      <button onClick={() => handleDriftAction(r.id, 'approve')}
+                        style={{ background: '#f0fdf4', color: '#16a34a', border: '1px solid #16a34a', padding: '2px 8px', cursor: 'pointer', fontSize: '0.72rem' }}>
+                        <Check size={10}/>
+                      </button>
+                      <button onClick={() => handleDriftAction(r.id, 'reject')}
+                        style={{ background: '#fef2f2', color: '#dc2626', border: '1px solid #dc2626', padding: '2px 8px', cursor: 'pointer', fontSize: '0.72rem' }}>
+                        <X size={10}/>
+                      </button>
+                    </div>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+
+          {/* ── Live Stats Panel ── */}
+          {stats && (
+            <div className="card tools-card stats-panel" style={{ marginTop: '2rem' }}>
+              <h2 className="mono-text flex-center" style={{ gap: '0.5rem', marginBottom: '1rem' }}>
+                <Database size={20}/> GRAPH STATISTICS
+                {selectedDocId && <span className="scope-badge">DOC FILTERED</span>}
+              </h2>
+
+              <div className="stats-summary">
+                <div className="sum-chip">
+                  <div className="sum-val">{stats.total_entities}</div>
+                  <div className="sum-key">TOTAL ENTITIES</div>
+                </div>
+                <div className="sum-chip">
+                  <div className="sum-val">{stats.total_relationships}</div>
+                  <div className="sum-key">RELATIONSHIPS</div>
+                </div>
+              </div>
+
+              {stats.entity_stats?.length > 0 && (
+                <>
+                  <div className="stat-section-lbl">ENTITY TYPES</div>
+                  {stats.entity_stats.slice(0, 8).map((s: any) => (
+                    <div key={s.type} className="stat-bar-row">
+                      <span className="stat-bar-label">{s.type}</span>
+                      <div className="stat-bar-track">
+                        <div
+                          className="stat-bar-fill"
+                          style={{ width: `${Math.min(100, (s.count / stats.total_entities) * 100)}%` }}
+                        />
+                      </div>
+                      <span className="stat-bar-count">{s.count}</span>
+                    </div>
+                  ))}
+                </>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+
+      {message && (
+        <div className={`status-toast ${message.includes('ERROR') || message.includes('FAILED') ? 'error' : ''}`}>
+          <Info size={20} /> {message}
+          <button 
+            onClick={() => setMessage('')} 
+            className="toast-dismiss-btn"
+          >
+            &times;
+          </button>
+        </div>
+      )}
+
+      <style>{`
+        .doc-dropdown {
+          background: var(--bg-color);
+          color: var(--text-color);
+          border: 2px solid var(--border-color);
+          padding: 0.5rem;
+          font-size: 0.9rem;
+          font-weight: bold;
+          outline: none;
+          max-width: 100%;
+          text-overflow: ellipsis;
+        }
+
+        .ontology-layout {
+          display: grid;
+          grid-template-columns: 3fr 2fr;
+          gap: 2rem;
+          margin-top: 1rem;
+        }
+        
+        @media (max-width: 768px) {
+          .ontology-layout {
+            grid-template-columns: 1fr;
+          }
+        }
+
+        .form-group {
+          margin-bottom: 1.5rem;
+        }
+
+        .form-group label {
+          display: block;
+          margin-bottom: 0.5rem;
+          font-weight: bold;
+          font-size: 0.85rem;
+          color: #555;
+        }
+
+        .form-group textarea {
+          width: 100%;
+          padding: 1rem;
+          border: 2px solid var(--border-color);
+          background: var(--bg-color);
+          color: var(--text-color);
+          resize: vertical;
+          font-size: 0.9rem;
+        }
+
+        .form-group textarea:focus {
+          outline: none;
+          border-color: #555;
+        }
+
+        .dict-editor {
+          font-family: var(--font-mono);
+          white-space: pre;
+          background-color: #fafafa !important;
+        }
+
+        .status-toast {
+          position: fixed;
+          bottom: 2rem;
+          right: 2rem;
+          background: var(--text-color);
+          color: var(--bg-color);
+          padding: 1rem 1.5rem;
+          border-left: 6px solid var(--text-color);
+          box-shadow: 4px 4px 0 var(--border-color);
+          display: flex;
+          align-items: center;
+          gap: 1rem;
+          z-index: 9999;
+          font-family: var(--font-mono);
+          font-weight: bold;
+          font-size: 0.9rem;
+          animation: slideUp 0.3s ease-out;
+          max-width: 400px;
+        }
+
+        .status-toast.error {
+          border-left-color: #ff0000;
+        }
+
+        .refine-info-box {
+          background: #f5f5f5;
+          border-left: 3px solid #000;
+          padding: 0.5rem 0.75rem;
+          font-size: 0.78rem;
+          line-height: 1.6;
+          display: flex;
+          gap: 0.5rem;
+          align-items: flex-start;
+        }
+
+        .control-label {
+          font-family: var(--font-mono);
+          font-size: 0.7rem;
+          font-weight: 700;
+          color: #666;
+          letter-spacing: 1px;
+          text-transform: uppercase;
+        }
+
+        .outline-btn {
+          background: transparent !important;
+          color: var(--text-color) !important;
+          border: 2px solid var(--text-color) !important;
+        }
+        .outline-btn:hover:not(:disabled) {
+          background: var(--text-color) !important;
+          color: var(--bg-color) !important;
+        }
+
+        /* ── Stats panel ── */
+        .stats-summary {
+          display: grid;
+          grid-template-columns: 1fr 1fr;
+          gap: 0.75rem;
+          margin-bottom: 1rem;
+        }
+        .sum-chip {
+          border: 1.5px solid #e5e5e5;
+          padding: 0.6rem 0.75rem;
+          text-align: center;
+        }
+        .sum-val {
+          font-family: var(--font-mono);
+          font-size: 1.4rem;
+          font-weight: 700;
+          line-height: 1;
+        }
+        .sum-key {
+          font-family: var(--font-mono);
+          font-size: 0.62rem;
+          color: #888;
+          letter-spacing: 1px;
+          margin-top: 0.2rem;
+        }
+        .stat-section-lbl {
+          font-family: var(--font-mono);
+          font-size: 0.65rem;
+          font-weight: 700;
+          color: #888;
+          letter-spacing: 1px;
+          margin-bottom: 0.5rem;
+        }
+        .stat-bar-row {
+          display: flex;
+          align-items: center;
+          gap: 0.5rem;
+          margin-bottom: 0.35rem;
+          font-family: var(--font-mono);
+          font-size: 0.75rem;
+        }
+        .stat-bar-label {
+          width: 90px;
+          flex-shrink: 0;
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          color: #444;
+        }
+        .stat-bar-track {
+          flex: 1;
+          height: 6px;
+          background: #e5e5e5;
+          border-radius: 2px;
+          overflow: hidden;
+        }
+        .stat-bar-fill {
+          height: 100%;
+          background: #000;
+          transition: width 0.4s ease;
+        }
+        .stat-bar-count {
+          width: 28px;
+          text-align: right;
+          color: #666;
+          font-size: 0.72rem;
+        }
+        .scope-badge {
+          font-size: 0.6rem;
+          background: #000;
+          color: #fff;
+          padding: 2px 6px;
+          letter-spacing: 0.5px;
+          margin-left: 0.4rem;
+        }
+      `}</style>
+    </div>
+  );
+};
+
+export default Ontology;

frontend-react/src/views/Process.tsx

@@ -0,0 +1,763 @@
+import React, { useState, useEffect } from 'react';
+import { useAuth } from '../context/AuthContext';
+import { DocumentInfo } from '../types/api';
+import { Upload, FilePlus, Activity, Trash2, Eye, Globe, X, FileText, Link, Hash, BookOpen } from 'lucide-react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000/api';
+
+interface PreviewData {
+  filename: string;
+  file_type: string;
+  word_count: number;
+  char_count: number;
+  content: string;
+}
+
+const Process: React.FC = () => {
+  const { token, logout } = useAuth();
+  const [documents, setDocuments] = useState<DocumentInfo[]>([]);
+  const [loadingDocs, setLoadingDocs] = useState(true);
+  const [uploading, setUploading] = useState(false);
+  const [file, setFile] = useState<File | null>(null);
+  const [url, setUrl] = useState('');
+  const [message, setMessage] = useState('');
+
+  // Preview modal state
+  const [previewOpen, setPreviewOpen] = useState(false);
+  const [previewData, setPreviewData] = useState<PreviewData | null>(null);
+  const [previewLoading, setPreviewLoading] = useState(false);
+
+  interface TaskState {
+    status: string;
+    progress?: {
+      current_chunk?: number;
+      total_chunks?: number;
+      file?: string;
+    };
+  }
+
+  const [tasks, setTasks] = useState<Record<string, TaskState>>({});
+
+  const fetchDocuments = async () => {
+    setLoadingDocs(true);
+    try {
+      const res = await fetch(`${API_BASE}/documents`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.status === 401) { logout(); return; }
+      if (res.ok) {
+        const data = await res.json();
+        setDocuments(data.documents);
+      }
+    } catch (err) {
+      console.error('Failed to fetch docs', err);
+    } finally {
+      setLoadingDocs(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchDocuments();
+    const interval = setInterval(fetchDocuments, 10000);
+    return () => clearInterval(interval);
+  }, [token]);
+
+  useEffect(() => {
+    const activeTasks = Object.keys(tasks).filter(
+      tid => tasks[tid].status !== 'completed' && tasks[tid].status !== 'failure'
+    );
+    if (activeTasks.length === 0) return;
+
+    const interval = setInterval(() => {
+      activeTasks.forEach(async (tid) => {
+        try {
+          const res = await fetch(`${API_BASE}/documents/status/${tid}`, {
+            headers: { Authorization: `Bearer ${token}` }
+          });
+          if (res.status === 401) { logout(); return; }
+          if (res.ok) {
+            const data = await res.json();
+            setTasks(prev => ({ ...prev, [tid]: { status: data.status, progress: data.progress } }));
+            if (data.status === 'completed' || data.status === 'failure') fetchDocuments();
+          }
+        } catch (e) {}
+      });
+    }, 2000);
+
+    return () => clearInterval(interval);
+  }, [tasks, token]);
+
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    if (e.target.files && e.target.files.length > 0) setFile(e.target.files[0]);
+  };
+
+  const handleUpload = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!file) return;
+    setUploading(true);
+    setMessage('');
+    const formData = new FormData();
+    formData.append('file', file);
+    try {
+      const res = await fetch(`${API_BASE}/documents/upload`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` },
+        body: formData
+      });
+      if (res.status === 401) { logout(); return; }
+      const data = await res.json();
+      if (!res.ok) {
+        setMessage(`UPLOAD FAILED: ${data.detail}`);
+      } else {
+        setMessage('FILE UPLOADED. INGESTION TASK QUEUED.');
+        if (data.task_id) setTasks(prev => ({ ...prev, [data.task_id]: { status: 'pending' } }));
+        setFile(null);
+        fetchDocuments();
+      }
+    } catch (err: any) {
+      setMessage(`ERROR: ${err.message}`);
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  const handleUrlScrape = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!url.trim()) return;
+    setUploading(true);
+    setMessage('');
+    try {
+      const res = await fetch(`${API_BASE}/documents/scrape`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ url: url.trim() })
+      });
+      if (res.status === 401) { logout(); return; }
+      const data = await res.json();
+      if (!res.ok) {
+        setMessage(`SCRAPE FAILED: ${data.detail}`);
+      } else {
+        setMessage('URL SCRAPED. INGESTION TASK QUEUED.');
+        if (data.task_id) setTasks(prev => ({ ...prev, [data.task_id]: { status: 'pending' } }));
+        setUrl('');
+        fetchDocuments();
+      }
+    } catch (err: any) {
+      setMessage(`ERROR: ${err.message}`);
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  const handleDelete = async (docId: string) => {
+    if (!window.confirm('WARNING: Delete this document and all its graph data?')) return;
+    try {
+      const res = await fetch(`${API_BASE}/documents/${docId}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.status === 401) { logout(); return; }
+      fetchDocuments();
+    } catch (err) {
+      console.error(err);
+    }
+  };
+
+  const handleView = async (doc: any) => {
+    const fileType = (doc.file_type || '').toLowerCase();
+
+    // Text/scraped files → use inline preview modal
+    if (fileType === '.txt' || fileType === '.md' || fileType === '') {
+      setPreviewOpen(true);
+      setPreviewLoading(true);
+      setPreviewData(null);
+      try {
+        const res = await fetch(`${API_BASE}/documents/${doc.id}/preview`, {
+          headers: { Authorization: `Bearer ${token}` }
+        });
+        if (res.status === 401) { logout(); return; }
+        if (res.ok) {
+          const data = await res.json();
+          setPreviewData(data);
+        } else {
+          const err = await res.json();
+          setMessage(`PREVIEW ERROR: ${err.detail}`);
+          setPreviewOpen(false);
+        }
+      } catch (err) {
+        setMessage('ERROR: Failed to load preview.');
+        setPreviewOpen(false);
+      } finally {
+        setPreviewLoading(false);
+      }
+      return;
+    }
+
+    // Binary files (PDF) → open in new tab as before
+    const newTab = window.open('', '_blank');
+    if (!newTab) { setMessage('ERROR: Please allow popups to view PDFs.'); return; }
+    newTab.document.write('<div style="font-family:monospace;padding:20px;">Fetching secure document...</div>');
+    try {
+      const res = await fetch(`${API_BASE}/documents/${doc.id}/download`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.status === 401) { newTab.close(); logout(); return; }
+      if (res.ok) {
+        const contentType = res.headers.get('content-type') || 'application/pdf';
+        const blob = await res.blob();
+        const fileBlob = new Blob([blob], { type: contentType });
+        const blobUrl = window.URL.createObjectURL(fileBlob);
+        newTab.location.href = blobUrl;
+      } else {
+        newTab.close();
+        setMessage('ERROR: Document file not found on server.');
+      }
+    } catch (err) {
+      newTab.close();
+      setMessage('ERROR: Failed to open document.');
+    }
+  };
+
+  const isTxtDoc = (doc: any) => {
+    const ft = (doc.file_type || '').toLowerCase();
+    return ft === '.txt' || ft === '.md' || ft === '';
+  };
+
+  return (
+    <div className="container" style={{ animation: 'fadeIn 0.5s ease' }}>
+      <div className="page-header flex-between">
+        <div>
+          <h1>INGESTION PIPELINE</h1>
+          <p className="mono-text">DATA PROCESSING &amp; GRAPH CONSTRUCTION</p>
+        </div>
+        <Activity size={32} />
+      </div>
+
+      <div className="process-layout">
+        {/* Upload / Scrape Section */}
+        <div className="card upload-card">
+          <h2 className="mono-text flex-center"><FilePlus style={{ marginRight: '0.5rem' }}/> ADD DOCUMENT</h2>
+
+          <form onSubmit={handleUpload} className="upload-form">
+            <div className="file-input-wrapper">
+              <input type="file" id="file-upload" onChange={handleFileChange} accept=".pdf,.txt,.md" />
+              <label htmlFor="file-upload" className="file-label">
+                {file ? file.name : 'SELECT FILE FOR INGESTION'}
+              </label>
+            </div>
+            <button
+              type="submit"
+              className="app-btn full-width"
+              disabled={!file || uploading}
+              style={{ marginTop: '1rem', display: 'flex', justifyContent: 'center', gap: '8px' }}
+            >
+              {uploading && file ? 'UPLOADING...' : <><Upload size={18} /> INITIALIZE FILE INGESTION</>}
+            </button>
+          </form>
+
+          <hr style={{ margin: '2rem 0', borderColor: 'var(--border-color)', borderStyle: 'dotted' }} />
+
+          <h2 className="mono-text flex-center"><Globe style={{ marginRight: '0.5rem' }}/> SCRAPE URL</h2>
+          <p style={{ fontSize: '0.85rem', color: '#666', marginBottom: '1rem', lineHeight: 1.5 }}>
+            Paste any public URL — articles, docs, Wikipedia pages — to scrape and ingest the content into your knowledge graph.
+          </p>
+          <form onSubmit={handleUrlScrape} className="upload-form">
+            <input
+              type="url"
+              className="query-input mono-text"
+              placeholder="https://example.com/article"
+              value={url}
+              onChange={(e) => setUrl(e.target.value)}
+              required
+              style={{ width: '100%', marginBottom: '1rem' }}
+            />
+            <button
+              type="submit"
+              className="app-btn full-width"
+              disabled={!url || uploading}
+              style={{ display: 'flex', justifyContent: 'center', gap: '8px' }}
+            >
+              {uploading && url ? 'SCRAPING...' : <><Activity size={18} /> INGEST FROM URL</>}
+            </button>
+          </form>
+
+          {Object.keys(tasks).length > 0 && (
+            <div className="task-tracker" style={{ marginTop: '1rem' }}>
+              <h4 className="mono-text">ACTIVE TASKS</h4>
+              {Object.entries(tasks).map(([tid, taskObj]) => {
+                const pct = (taskObj.progress?.current_chunk && taskObj.progress?.total_chunks)
+                  ? Math.round((taskObj.progress.current_chunk / taskObj.progress.total_chunks) * 100)
+                  : 0;
+                return (
+                  <div key={tid} className="task-row" style={{ flexDirection: 'column', alignItems: 'flex-start', gap: '8px' }}>
+                    <div style={{ display: 'flex', justifyContent: 'space-between', width: '100%' }}>
+                      <span title={tid}>{tid.substring(0,8)}...</span>
+                      <span className={`status-badge ${taskObj.status}`}>
+                        {taskObj.status.toUpperCase()}{taskObj.status === 'processing' && pct > 0 ? ` ${pct}%` : ''}
+                      </span>
+                    </div>
+                    {taskObj.status === 'processing' && taskObj.progress?.total_chunks && (
+                      <div style={{ width: '100%', height: '4px', background: '#e0e0e0', borderRadius: '2px', overflow: 'hidden' }}>
+                        <div style={{ width: `${pct}%`, height: '100%', background: '#000', transition: 'width 0.3s ease' }}></div>
+                      </div>
+                    )}
+                  </div>
+                );
+              })}
+            </div>
+          )}
+        </div>
+
+        {/* Corpus Table */}
+        <div className="card documents-card">
+          <h2 className="mono-text">CORPUS INDEX</h2>
+          <div className="table-wrapper">
+            <table className="docs-table">
+              <thead>
+                <tr>
+                  <th>DOCUMENT NAME</th>
+                  <th>TYPE</th>
+                  <th>SIZE</th>
+                  <th>INGESTED</th>
+                  <th>ACTIONS</th>
+                </tr>
+              </thead>
+              <tbody>
+                {documents.length === 0 && !loadingDocs ? (
+                  <tr><td colSpan={5} style={{ textAlign: 'center', padding: '3rem' }} className="mono-text">
+                    <p style={{ marginBottom: '1rem' }}>NO DOCUMENTS INDEXED IN GRAPH DATABASE</p>
+                    <p style={{ color: '#666', fontSize: '0.85rem' }}>Upload a file or scrape a URL above to begin.</p>
+                  </td></tr>
+                ) : loadingDocs ? (
+                  <tr><td colSpan={5} style={{ textAlign: 'center', padding: '3rem' }} className="mono-text">
+                    FETCHING CORPUS DATA...
+                  </td></tr>
+                ) : (
+                  documents.map((doc: any) => (
+                    <tr key={doc.id}>
+                      <td className="mono-text" style={{ maxWidth: '220px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                        <span style={{ display: 'flex', alignItems: 'center', gap: '6px' }}>
+                          {isTxtDoc(doc) ? <Link size={14} /> : <FileText size={14} />}
+                          {doc.filename}
+                        </span>
+                      </td>
+                      <td>
+                        <span className={`type-badge ${isTxtDoc(doc) ? 'scraped' : 'pdf'}`}>
+                          {isTxtDoc(doc) ? 'WEB / TXT' : (doc.file_type || 'PDF').toUpperCase()}
+                        </span>
+                      </td>
+                      <td className="mono-text">{(doc.size_bytes / 1024).toFixed(1)} KB</td>
+                      <td className="mono-text" style={{ fontSize: '0.8rem' }}>{doc.upload_date?.substring(0,19) || '—'}</td>
+                      <td style={{ whiteSpace: 'nowrap' }}>
+                        <button
+                          className="icon-btn"
+                          onClick={() => handleView(doc)}
+                          title={isTxtDoc(doc) ? 'Preview Content' : 'Open PDF'}
+                          style={{ marginRight: '10px' }}
+                        >
+                          <Eye size={16} />
+                        </button>
+                        <button className="icon-btn" onClick={() => handleDelete(doc.id)} title="Delete Document">
+                          <Trash2 size={16} />
+                        </button>
+                      </td>
+                    </tr>
+                  ))
+                )}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </div>
+
+      {/* Document Preview Modal */}
+      {previewOpen && (
+        <div className="preview-overlay" onClick={() => setPreviewOpen(false)}>
+          <div className="preview-modal" onClick={(e) => e.stopPropagation()}>
+            {/* Modal Header */}
+            <div className="preview-header">
+              <div className="preview-header-left">
+                <BookOpen size={20} />
+                <div>
+                  <div className="preview-title">{previewData?.filename || 'Loading...'}</div>
+                  {previewData && (
+                    <div className="preview-meta-row">
+                      <span className="preview-meta-chip"><Hash size={12} /> {previewData.word_count.toLocaleString()} words</span>
+                      <span className="preview-meta-chip"><FileText size={12} /> {(previewData.char_count / 1000).toFixed(1)}K chars</span>
+                      <span className="type-badge scraped">WEB SCRAPE</span>
+                    </div>
+                  )}
+                </div>
+              </div>
+              <button className="icon-btn" onClick={() => setPreviewOpen(false)} style={{ fontSize: '1.5rem' }}>
+                <X size={22} />
+              </button>
+            </div>
+
+            {/* Modal Body */}
+            <div className="preview-body">
+              {previewLoading ? (
+                <div className="loading-spinner"><Activity size={32} style={{ animation: 'pulse 1.5s infinite' }} /> Fetching Content...</div>
+              ) : previewData ? (
+                <div className="markdown-content formatted">
+                  <ReactMarkdown remarkPlugins={[remarkGfm]}>{previewData.content}</ReactMarkdown>
+                </div>
+              ) : (
+                <div className="error-text">Failed to load content.</div>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+
+      {message && (
+        <div className={`status-toast ${message.includes('ERROR') || message.includes('FAILED') ? 'error' : ''}`}>
+          <Activity size={20} /> {message}
+          <button
+            onClick={() => setMessage('')}
+            className="toast-dismiss-btn"
+          >
+            &times;
+          </button>
+        </div>
+      )}
+
+      <style>{`
+        .process-layout {
+          display: grid;
+          grid-template-columns: 1fr 2fr;
+          gap: 2rem;
+        }
+
+        @media (max-width: 900px) {
+          .process-layout { grid-template-columns: 1fr; }
+        }
+
+        .file-input-wrapper {
+          position: relative;
+          overflow: hidden;
+          display: inline-block;
+          width: 100%;
+          border: 2px dashed var(--border-color);
+          text-align: center;
+          background: var(--hover-bg);
+          transition: var(--transition-speed);
+        }
+
+        .file-input-wrapper:hover { background: #e0e0e0; }
+
+        .file-input-wrapper input[type=file] {
+          font-size: 100px;
+          position: absolute;
+          left: 0; top: 0;
+          opacity: 0;
+          cursor: pointer;
+        }
+
+        .file-label {
+          display: block;
+          padding: 2rem;
+          font-family: var(--font-mono);
+          font-weight: 600;
+          cursor: pointer;
+        }
+
+        .task-tracker {
+          margin-top: 2rem;
+          border-top: 2px solid var(--border-color);
+          padding-top: 1rem;
+        }
+
+        .task-row {
+          display: flex;
+          justify-content: space-between;
+          padding: 0.5rem 0;
+          font-family: var(--font-mono);
+          font-size: 0.85rem;
+          border-bottom: 1px dotted var(--border-color);
+        }
+
+        .status-badge {
+          padding: 0.1rem 0.5rem;
+          background: var(--text-color);
+          color: var(--bg-color);
+          font-weight: 700;
+          font-size: 0.75rem;
+          font-family: var(--font-mono);
+        }
+        .status-badge.processing { background: #666; }
+        .status-badge.completed { background: #000; }
+        .status-badge.failure { background: #990000; color: white; }
+
+        .type-badge {
+          display: inline-block;
+          padding: 0.15rem 0.5rem;
+          font-size: 0.7rem;
+          font-family: var(--font-mono);
+          font-weight: 700;
+          letter-spacing: 0.5px;
+          border: 1.5px solid var(--border-color);
+        }
+        .type-badge.scraped { background: #000; color: #fff; border-color: #000; }
+        .type-badge.pdf { background: transparent; color: #444; }
+
+        .table-wrapper {
+          overflow-x: auto;
+          margin-top: 1rem;
+          width: 100%;
+          -webkit-overflow-scrolling: touch;
+        }
+
+        .docs-table {
+          width: 100%;
+          border-collapse: collapse;
+          border: 2px solid var(--border-color);
+        }
+
+        .docs-table th, .docs-table td {
+          border: 1px solid var(--border-color);
+          padding: 0.75rem;
+          text-align: left;
+          font-size: 0.9rem;
+        }
+
+        .docs-table th {
+          background-color: var(--text-color);
+          color: var(--bg-color);
+          font-family: var(--font-display);
+          letter-spacing: 1px;
+          white-space: nowrap;
+        }
+
+        .docs-table tr:hover { background-color: var(--hover-bg); }
+
+        .icon-btn {
+          background: none;
+          border: none;
+          cursor: pointer;
+          color: var(--text-color);
+          padding: 4px;
+        }
+        .icon-btn:hover { color: #ff0000; }
+
+        /* Preview Modal */
+        .preview-overlay {
+          position: fixed;
+          inset: 0;
+          background: rgba(0, 0, 0, 0.65);
+          z-index: 5000;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          padding: 2rem;
+          animation: fadeIn 0.2s ease;
+        }
+
+        .preview-modal {
+          background: var(--bg-color);
+          border: 3px solid var(--border-color);
+          box-shadow: 8px 8px 0 var(--border-color);
+          width: 100%;
+          max-width: 860px;
+          max-height: 85vh;
+          display: flex;
+          flex-direction: column;
+          animation: scaleIn 0.2s ease;
+        }
+
+        @keyframes scaleIn {
+          from { transform: scale(0.95); opacity: 0; }
+          to { transform: scale(1); opacity: 1; }
+        }
+
+        .preview-header {
+          display: flex;
+          align-items: flex-start;
+          justify-content: space-between;
+          padding: 1.25rem 1.5rem;
+          border-bottom: 2px solid var(--border-color);
+          background: var(--text-color);
+          color: var(--bg-color);
+          gap: 1rem;
+        }
+
+        .preview-header-left {
+          display: flex;
+          align-items: flex-start;
+          gap: 1rem;
+          flex: 1;
+          min-width: 0;
+        }
+
+        .preview-title {
+          font-family: var(--font-mono);
+          font-weight: 700;
+          font-size: 0.95rem;
+          word-break: break-all;
+          margin-bottom: 0.4rem;
+        }
+
+        .preview-meta-row {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 0.5rem;
+          align-items: center;
+        }
+
+        .preview-meta-chip {
+          display: inline-flex;
+          align-items: center;
+          gap: 4px;
+          background: rgba(255,255,255,0.15);
+          padding: 0.15rem 0.5rem;
+          font-size: 0.75rem;
+          font-family: var(--font-mono);
+          border-radius: 2px;
+        }
+
+        .preview-header .icon-btn { color: var(--bg-color); }
+        .preview-header .icon-btn:hover { color: #ffaaaa; }
+
+        .preview-body {
+          flex: 1;
+          overflow-y: auto;
+          padding: 0;
+        }
+
+        .markdown-content.formatted {
+          padding: 2rem;
+          font-family: var(--font-sans);
+          line-height: 1.6;
+          color: #333;
+          font-size: 1rem;
+        }
+
+        .markdown-content.formatted h1,
+        .markdown-content.formatted h2,
+        .markdown-content.formatted h3 {
+          font-family: var(--font-mono);
+          color: #000;
+          margin-top: 1.5em;
+          margin-bottom: 0.5em;
+          border-bottom: 2px solid #eaeaea;
+          padding-bottom: 0.3em;
+        }
+
+        .markdown-content.formatted p {
+          margin-bottom: 1em;
+        }
+
+        .markdown-content.formatted ul,
+        .markdown-content.formatted ol {
+          margin-bottom: 1em;
+          padding-left: 2em;
+        }
+
+        .markdown-content.formatted a {
+          color: #0056b3;
+          text-decoration: underline;
+        }
+
+        .markdown-content.formatted code {
+          font-family: var(--font-mono);
+          background: #f4f4f4;
+          padding: 0.1em 0.3em;
+          border-radius: 3px;
+          font-size: 0.9em;
+        }
+
+        .markdown-content.formatted pre {
+          background: #111;
+          color: #fff;
+          padding: 1em;
+          overflow-x: auto;
+          border-radius: 4px;
+        }
+
+        .markdown-content.formatted pre code {
+          background: transparent;
+          color: inherit;
+          padding: 0;
+        }
+
+        .markdown-content.formatted blockquote {
+          border-left: 4px solid #ccc;
+          margin: 0;
+          padding-left: 1em;
+          color: #666;
+          font-style: italic;
+        }
+
+        .preview-loading {
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          gap: 1rem;
+          height: 300px;
+          font-family: var(--font-mono);
+          font-weight: bold;
+          letter-spacing: 2px;
+          color: #666;
+        }
+
+        .preview-content {
+          font-family: var(--font-mono);
+          font-size: 0.82rem;
+          line-height: 1.7;
+          white-space: pre-wrap;
+          word-break: break-word;
+          padding: 2rem;
+          margin: 0;
+          color: #111;
+          border: none;
+          background: #fafafa;
+        }
+
+        .spin-slow {
+          animation: spin 1.5s linear infinite;
+        }
+
+        @keyframes spin {
+          100% { transform: rotate(360deg); }
+        }
+
+        .status-toast {
+          position: fixed;
+          bottom: 2rem;
+          right: 2rem;
+          background: var(--text-color);
+          color: var(--bg-color);
+          padding: 1rem 1.5rem;
+          border-left: 6px solid var(--text-color);
+          box-shadow: 4px 4px 0 var(--border-color);
+          display: flex;
+          align-items: center;
+          gap: 1rem;
+          z-index: 9999;
+          font-family: var(--font-mono);
+          font-weight: bold;
+          font-size: 0.9rem;
+          animation: slideUp 0.3s ease-out;
+          max-width: 420px;
+        }
+
+        .status-toast.error { border-left-color: #ff0000; }
+
+        @keyframes slideUp {
+          from { transform: translateY(100px); opacity: 0; }
+          to { transform: translateY(0); opacity: 1; }
+        }
+
+        @keyframes fadeIn {
+          from { opacity: 0; }
+          to { opacity: 1; }
+        }
+      `}</style>
+    </div>
+  );
+};
+
+export default Process;

frontend-react/src/views/SimulationRunView.tsx

@@ -0,0 +1,690 @@
+import React, { useEffect, useState, useCallback, useRef } from 'react';
+import { useAuth } from '../context/AuthContext';
+import { GraphNode, GraphEdge, DocumentInfo } from '../types/api';
+import GraphCanvas, { DEFAULT_OPTIONS } from '../components/GraphCanvas';
+import type { GraphOptions, GraphCanvasHandle } from '../components/GraphCanvas';
+import {
+  RefreshCw, Play, Database, Info, Maximize2, Minimize2,
+  Download, SlidersHorizontal, X, Layers, Tag, Search,
+  Image, GitBranch, HelpCircle
+} from 'lucide-react';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000/api';
+
+const TYPE_COLORS = [
+  '#e63946','#457b9d','#2a9d8f','#e9c46a','#f4a261',
+  '#6a4c93','#1982c4','#8ac926','#ff595e','#6a994e',
+  '#bc4749','#a8dadc'
+];
+
+const SimulationRunView: React.FC = () => {
+  const { token, logout } = useAuth();
+  const [graphData, setGraphData] = useState<{ nodes: GraphNode[]; edges: GraphEdge[] }>({ nodes: [], edges: [] });
+  const [loading, setLoading] = useState(false);
+  const [limit, setLimit] = useState(100);
+  const [documents, setDocuments] = useState<DocumentInfo[]>([]);
+  const [selectedDocId, setSelectedDocId] = useState('');
+  const [nodeCount, setNodeCount] = useState(0);
+  const [edgeCount, setEdgeCount] = useState(0);
+
+  // UI state
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const [showPanel, setShowPanel] = useState(false);
+  const [showHelp, setShowHelp] = useState(false);
+  const [showSearch, setShowSearch] = useState(false);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [highlightNodeIds, setHighlightNodeIds] = useState<Set<string>>(new Set());
+
+  // Graph options
+  const [options, setOptions] = useState<GraphOptions>({ ...DEFAULT_OPTIONS });
+
+  // Canvas handle
+  const canvasRef = useRef<GraphCanvasHandle>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Derived legend
+  const typeLegend = React.useMemo(() => {
+    const types = [...new Set(graphData.nodes.map(n => n.type || 'Unknown'))];
+    return types.map((t, i) => ({ type: t, color: TYPE_COLORS[i % TYPE_COLORS.length] }));
+  }, [graphData.nodes]);
+
+  // Graph stats
+  const degreeStats = React.useMemo(() => {
+    if (!graphData.nodes.length) return null;
+    const degMap = new Map<string, number>();
+    graphData.nodes.forEach(n => degMap.set(n.id, 0));
+    graphData.edges.forEach(e => {
+      degMap.set(e.source, (degMap.get(e.source) || 0) + 1);
+      degMap.set(e.target, (degMap.get(e.target) || 0) + 1);
+    });
+    const degrees = [...degMap.values()];
+    const avg = degrees.reduce((a, b) => a + b, 0) / degrees.length;
+    const max = Math.max(...degrees);
+    const hubs = graphData.nodes.filter(n => (degMap.get(n.id) || 0) >= avg * 2);
+    return { avg: avg.toFixed(1), max, hubs: hubs.slice(0, 5) };
+  }, [graphData]);
+
+  // ── Data fetching ──────────────────────────────────────────────────────
+  const fetchDocuments = useCallback(async () => {
+    try {
+      const res = await fetch(`${API_BASE}/documents`, { headers: { Authorization: `Bearer ${token}` } });
+      if (res.ok) setDocuments((await res.json()).documents);
+    } catch {}
+  }, [token]);
+
+  const fetchGraph = useCallback(async (docId: string, nodeLimit: number) => {
+    setLoading(true);
+    try {
+      const url = new URL(`${API_BASE}/graph/visualization`);
+      url.searchParams.append('limit', nodeLimit.toString());
+      if (docId) url.searchParams.append('document_id', docId);
+      const res = await fetch(url.toString(), { headers: { Authorization: `Bearer ${token}` } });
+      if (res.status === 401) { logout(); return; }
+      if (res.ok) {
+        const data = await res.json();
+        setGraphData(data);
+        setNodeCount(data.nodes?.length ?? 0);
+        setEdgeCount(data.edges?.length ?? 0);
+        setHighlightNodeIds(new Set());
+        setSearchQuery('');
+      }
+    } catch (err) {
+      console.error('Graph fetch error:', err);
+    } finally {
+      setLoading(false);
+    }
+  }, [token, logout]);
+
+  const handleNodeUpdate = useCallback(async (nodeId: string, newName: string) => {
+    try {
+      const res = await fetch(`${API_BASE}/entities/${nodeId}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ name: newName })
+      });
+      if (res.status === 401) { logout(); return; }
+      if (res.ok) {
+        setGraphData(prev => ({
+          ...prev,
+          nodes: prev.nodes.map(n => n.id === nodeId ? { ...n, label: newName } : n)
+        }));
+      }
+    } catch {}
+  }, [token, logout]);
+
+  useEffect(() => { fetchDocuments(); }, [fetchDocuments]);
+  useEffect(() => { fetchGraph(selectedDocId, limit); }, [fetchGraph, selectedDocId, limit]);
+
+  // Search handler
+  const handleSearch = useCallback((q: string) => {
+    setSearchQuery(q);
+    if (!q.trim()) {
+      setHighlightNodeIds(new Set());
+      return;
+    }
+    const lower = q.toLowerCase();
+    const matched = new Set(
+      graphData.nodes
+        .filter(n =>
+          n.label?.toLowerCase().includes(lower) ||
+          n.type?.toLowerCase().includes(lower)
+        )
+        .map(n => n.id)
+    );
+    setHighlightNodeIds(matched);
+    // Zoom to first match
+    if (matched.size > 0) {
+      const firstId = [...matched][0];
+      canvasRef.current?.highlightNode(firstId);
+    }
+  }, [graphData.nodes]);
+
+  // ── Fullscreen ─────────────────────────────────────────────────────────
+  const toggleFullscreen = useCallback(() => {
+    if (!isFullscreen) {
+      containerRef.current?.requestFullscreen?.().catch(() => setIsFullscreen(true));
+    } else {
+      document.exitFullscreen?.().catch(() => setIsFullscreen(false));
+    }
+    setIsFullscreen(f => !f);
+  }, [isFullscreen]);
+
+  useEffect(() => {
+    const handler = () => setIsFullscreen(!!document.fullscreenElement);
+    document.addEventListener('fullscreenchange', handler);
+    return () => document.removeEventListener('fullscreenchange', handler);
+  }, []);
+
+  // ── Option helpers ─────────────────────────────────────────────────────
+  const setOpt = <K extends keyof GraphOptions>(key: K, val: GraphOptions[K]) =>
+    setOptions(prev => ({ ...prev, [key]: val }));
+
+  const selectedDocName = documents.find(d => d.id === selectedDocId)?.filename || '';
+
+  return (
+    <div ref={containerRef} className={`simulation-root${isFullscreen ? ' fullscreen' : ''}`}>
+
+      {/* ── Top bar ──────────────────────────────────────────────────────── */}
+      <div className="sim-topbar">
+        <div className="sim-title-group">
+          <h2>GRAPH VISUALIZATION</h2>
+          <div className="sim-chips">
+            <span className="s-chip"><Database size={11}/> {nodeCount} nodes</span>
+            <span className="s-chip">{edgeCount} edges</span>
+            {degreeStats && <span className="s-chip" title="Average connections per node">avg° {degreeStats.avg}</span>}
+            {selectedDocId && (
+              <span className="s-chip active" title={selectedDocName}>
+                {selectedDocName.length > 22 ? selectedDocName.substring(0,20)+'…' : selectedDocName}
+              </span>
+            )}
+          </div>
+        </div>
+
+        <div className="sim-controls">
+          {/* Doc filter */}
+          <div className="ctrl-grp">
+            <label className="ctrl-lbl">DOCUMENT</label>
+            <select className="sim-sel" value={selectedDocId} onChange={e => setSelectedDocId(e.target.value)}>
+              <option value="">🌐 ALL</option>
+              {documents.map(doc => (
+                <option key={doc.id} value={doc.id}>📄 {doc.filename.length > 28 ? doc.filename.substring(0,26)+'…' : doc.filename}</option>
+              ))}
+            </select>
+          </div>
+
+          {/* Limit */}
+          <div className="ctrl-grp">
+            <label className="ctrl-lbl">NODES</label>
+            <select className="sim-sel" value={limit} onChange={e => setLimit(Number(e.target.value))}>
+              {[50, 100, 200, 500, 1000].map(v => <option key={v} value={v}>{v}</option>)}
+            </select>
+          </div>
+
+          {/* Action buttons */}
+          <div className="sim-actions">
+            <button className="sim-icon-btn" title="Refresh graph" onClick={() => fetchGraph(selectedDocId, limit)} disabled={loading}>
+              {loading ? <RefreshCw className="spin" size={15}/> : <Play size={15}/>}<span>REFRESH</span>
+            </button>
+
+            <button className="sim-icon-btn" title="Fit to view" onClick={() => canvasRef.current?.fitView()}>
+              <Layers size={15}/><span>FIT</span>
+            </button>
+
+            {/* Edge labels quick toggle */}
+            <button
+              className={`sim-icon-btn${options.showEdgeLabels ? ' active' : ''}`}
+              title={options.showEdgeLabels ? 'Hide edge labels' : 'Show edge labels'}
+              onClick={() => setOpt('showEdgeLabels', !options.showEdgeLabels)}
+            >
+              <Tag size={15}/><span>LABELS</span>
+            </button>
+
+            {/* Search */}
+            <button
+              className={`sim-icon-btn${showSearch ? ' active' : ''}`}
+              title="Search nodes"
+              onClick={() => { setShowSearch(s => !s); if (showSearch) { setSearchQuery(''); setHighlightNodeIds(new Set()); } }}
+            >
+              <Search size={15}/><span>SEARCH</span>
+            </button>
+
+            {/* Export PNG */}
+            <button className="sim-icon-btn" title="Export as PNG" onClick={() => canvasRef.current?.exportPNG()}>
+              <Image size={15}/><span>PNG</span>
+            </button>
+
+            {/* Export SVG */}
+            <button className="sim-icon-btn" title="Export as SVG" onClick={() => canvasRef.current?.exportSVG()}>
+              <Download size={15}/><span>SVG</span>
+            </button>
+
+            {/* Options panel */}
+            <button className={`sim-icon-btn${showPanel ? ' active' : ''}`} title="Advanced options" onClick={() => setShowPanel(p => !p)}>
+              <SlidersHorizontal size={15}/><span>OPTIONS</span>
+            </button>
+
+            {/* Fullscreen */}
+            <button className="sim-icon-btn" title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} onClick={toggleFullscreen}>
+              {isFullscreen ? <Minimize2 size={15}/> : <Maximize2 size={15}/>}
+              <span>{isFullscreen ? 'EXIT' : 'FULL'}</span>
+            </button>
+
+            {/* Help */}
+            <button className={`sim-icon-btn${showHelp ? ' active' : ''}`} title="Keyboard shortcuts & help" onClick={() => setShowHelp(h => !h)}>
+              <HelpCircle size={15}/><span>?</span>
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {/* ── Node Search bar ──────────────────────────────────────────────── */}
+      {showSearch && (
+        <div className="search-bar-row">
+          <Search size={14}/>
+          <input
+            autoFocus
+            type="text"
+            className="sim-search-input"
+            placeholder="Search by node name or type…"
+            value={searchQuery}
+            onChange={e => handleSearch(e.target.value)}
+          />
+          {highlightNodeIds.size > 0 && (
+            <span className="search-result-badge">{highlightNodeIds.size} match{highlightNodeIds.size !== 1 ? 'es' : ''}</span>
+          )}
+          <button className="sim-icon-btn" style={{ padding: '0.2rem 0.5rem' }} onClick={() => { setSearchQuery(''); setHighlightNodeIds(new Set()); }}>
+            <X size={13}/>
+          </button>
+        </div>
+      )}
+
+      {/* ── Help modal ───────────────────────────────────────────────────── */}
+      {showHelp && (
+        <div className="advanced-panel">
+          <div className="panel-header">
+            <span>CONTROLS REFERENCE</span>
+            <button className="toast-dismiss-btn" onClick={() => setShowHelp(false)}><X size={15}/></button>
+          </div>
+          <div className="panel-body" style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))', gap: '1rem' }}>
+            <div>
+              <div className="opt-label">MOUSE / TOUCH</div>
+              <table className="help-table">
+                <tbody>
+                  {[
+                    ['Single click', 'Zoom to node'],
+                    ['Double click', 'Edit node name'],
+                    ['Drag node', 'Pin node position'],
+                    ['Hover', 'Highlight neighbors'],
+                    ['Scroll', 'Zoom in / out'],
+                    ['Drag canvas', 'Pan view'],
+                    ['Click canvas bg', 'Reset highlight'],
+                  ].map(([k, v]) => (
+                    <tr key={k}><td className="help-key">{k}</td><td className="help-val">{v}</td></tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+            <div>
+              <div className="opt-label">TOOLBAR BUTTONS</div>
+              <table className="help-table">
+                <tbody>
+                  {[
+                    ['REFRESH', 'Reload graph from Neo4j'],
+                    ['FIT', 'Reset zoom/pan to center'],
+                    ['LABELS', 'Toggle edge relation text'],
+                    ['SEARCH', 'Find & highlight nodes'],
+                    ['PNG/SVG', 'Export graph image'],
+                    ['OPTIONS', 'Physics & display settings'],
+                    ['FULL', 'Toggle fullscreen mode'],
+                  ].map(([k, v]) => (
+                    <tr key={k}><td className="help-key">{k}</td><td className="help-val">{v}</td></tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+            <div>
+              <div className="opt-label">TIPS</div>
+              <ul className="help-tips">
+                <li>Set <strong>NODES</strong> to 50 for better performance on large graphs</li>
+                <li>Enable <strong>Curved edges</strong> to reduce visual overlap</li>
+                <li><strong>Node size by degree</strong> makes hubs visually prominent</li>
+                <li>Use <strong>SEARCH</strong> to find entities by name or type</li>
+                <li>Increase <strong>Charge Strength</strong> to spread out dense clusters</li>
+              </ul>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* ── Advanced options panel ────────────────────────────────────────── */}
+      {showPanel && (
+        <div className="advanced-panel">
+          <div className="panel-header">
+            <span>ADVANCED GRAPH OPTIONS</span>
+            <button className="toast-dismiss-btn" onClick={() => setShowPanel(false)}><X size={15}/></button>
+          </div>
+          <div className="panel-body">
+            {/* Display toggles */}
+            <div className="opt-section">
+              <div className="opt-label">DISPLAY</div>
+              <div className="opt-row">
+                {([
+                  ['colorByType', 'Color nodes by entity type'],
+                  ['showLabels', 'Show node name labels'],
+                  ['showEdgeLabels', 'Show edge relation labels'],
+                  ['showCurvedEdges', 'Curved edges (arc routing)'],
+                  ['nodeSizeByDegree', 'Node size by connection count'],
+                ] as [keyof GraphOptions, string][]).map(([key, label]) => (
+                  <label key={key} className="opt-toggle">
+                    <input type="checkbox"
+                      checked={options[key] as boolean}
+                      onChange={e => setOpt(key, e.target.checked)}
+                    />
+                    <span>{label}</span>
+                  </label>
+                ))}
+              </div>
+            </div>
+
+            {/* Physics sliders */}
+            <div className="opt-section">
+              <div className="opt-label">PHYSICS</div>
+              <div className="opt-sliders">
+                {([
+                  ['nodeRadius', 'Node Radius', 8, 40, 1],
+                  ['linkDistance', 'Link Distance', 40, 500, 10],
+                  ['chargeStrength', 'Repulsion', -1200, -30, 10],
+                  ['centerGravity', 'Center Gravity', 0, 0.5, 0.01],
+                ] as [keyof GraphOptions, string, number, number, number][]).map(([key, label, min, max, step]) => (
+                  <div key={key} className="slider-row">
+                    <label>{label}: <strong>{typeof options[key] === 'number' ? (options[key] as number).toFixed(key === 'centerGravity' ? 2 : 0) : options[key]}</strong></label>
+                    <input type="range" min={min} max={max} step={step}
+                      value={options[key] as number}
+                      onChange={e => setOpt(key, Number(e.target.value))}
+                    />
+                  </div>
+                ))}
+              </div>
+            </div>
+
+            <button className="reset-btn" onClick={() => setOptions({ ...DEFAULT_OPTIONS })}>
+              ↺ RESET TO DEFAULTS
+            </button>
+          </div>
+        </div>
+      )}
+
+      {/* ── Canvas + Legend + Stats ───────────────────────────────────────── */}
+      <div className="canvas-area">
+        <div className="canvas-wrapper">
+          {loading && graphData.nodes.length === 0 ? (
+            <div className="loading-overlay">
+              <RefreshCw className="spin" size={28}/>
+              <span>INITIALIZING PHYSICS ENGINE...</span>
+            </div>
+          ) : graphData.nodes.length === 0 ? (
+            <div className="loading-overlay empty">
+              <Database size={40}/>
+              <span>
+                {selectedDocId
+                  ? 'No entities found for this document.\nTry a different document or re-ingest.'
+                  : 'No entity data in graph.\nIngest documents via the PROCESS tab first.'}
+              </span>
+            </div>
+          ) : (
+            <GraphCanvas
+              ref={canvasRef}
+              data={graphData}
+              onNodeUpdate={handleNodeUpdate}
+              options={options}
+              highlightNodeIds={highlightNodeIds}
+            />
+          )}
+
+          {loading && graphData.nodes.length > 0 && (
+            <div className="refresh-pill">
+              <RefreshCw className="spin" size={13}/> REFRESHING
+            </div>
+          )}
+        </div>
+
+        {/* ── Sidebar: Legend + Stats ─────────────────────────────────────── */}
+        <div className="sidebar-panels">
+          {/* Type Legend */}
+          {options.colorByType && typeLegend.length > 0 && (
+            <div className="legend-panel">
+              <div className="legend-title">ENTITY TYPES</div>
+              {typeLegend.map(({ type, color }) => (
+                <div key={type} className="legend-row">
+                  <span className="legend-dot" style={{ background: color }}/>
+                  <span className="legend-type">{type}</span>
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Graph stats */}
+          {degreeStats && (
+            <div className="stats-sidebar">
+              <div className="legend-title">NETWORK STATS</div>
+              <div className="stat-row"><span>Avg Degree</span><strong>{degreeStats.avg}</strong></div>
+              <div className="stat-row"><span>Max Degree</span><strong>{degreeStats.max}</strong></div>
+              {degreeStats.hubs.length > 0 && (
+                <>
+                  <div className="legend-title" style={{ marginTop: '0.6rem' }}>HUB NODES</div>
+                  {degreeStats.hubs.map((n: any) => (
+                    <div
+                      key={n.id}
+                      className="hub-node-row"
+                      title="Click to zoom to this node"
+                      onClick={() => canvasRef.current?.highlightNode(n.id)}
+                    >
+                      <GitBranch size={10}/>
+                      <span>{n.label?.length > 14 ? n.label.substring(0,12)+'…' : n.label}</span>
+                    </div>
+                  ))}
+                </>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* ── Hint bar ──────────────────────────────────────────────────────── */}
+      <div className="sim-hint">
+        <Info size={11}/>
+        <span>
+          <strong>Click</strong> node to zoom · <strong>Double-click</strong> to rename · <strong>Hover</strong> to highlight neighbors ·
+          <strong> Drag</strong> to pin · <strong>Scroll</strong> to zoom
+        </span>
+      </div>
+
+      <style>{`
+        .simulation-root {
+          height: calc(100vh - 62px);
+          display: flex;
+          flex-direction: column;
+          padding: 0.75rem 1.25rem 0.5rem;
+          background: var(--bg-color);
+          overflow: hidden;
+          gap: 0;
+        }
+        .simulation-root.fullscreen {
+          height: 100vh;
+          position: fixed;
+          inset: 0;
+          z-index: 9999;
+          background: #fff;
+          padding: 0.75rem 1.25rem 0.5rem;
+        }
+
+        /* Top bar */
+        .sim-topbar {
+          display: flex;
+          align-items: flex-start;
+          justify-content: space-between;
+          flex-wrap: wrap;
+          gap: 0.5rem;
+          border-bottom: 2px solid #000;
+          padding-bottom: 0.6rem;
+          margin-bottom: 0.5rem;
+        }
+        .sim-title-group h2 { margin: 0 0 0.2rem; font-size: 1rem; letter-spacing: 2px; }
+        .sim-chips { display: flex; flex-wrap: wrap; gap: 5px; }
+        .s-chip {
+          display: inline-flex; align-items: center; gap: 3px;
+          border: 1.5px solid #000; padding: 1px 7px;
+          font-family: var(--font-mono); font-size: 0.7rem; font-weight: 700;
+        }
+        .s-chip.active { background: #000; color: #fff; }
+
+        .sim-controls { display: flex; align-items: flex-end; flex-wrap: wrap; gap: 0.6rem; }
+        .ctrl-grp { display: flex; flex-direction: column; gap: 2px; }
+        .ctrl-lbl {
+          font-family: var(--font-mono); font-size: 0.62rem;
+          font-weight: 700; color: #888; letter-spacing: 1px;
+        }
+        .sim-sel {
+          font-family: var(--font-mono); font-size: 0.8rem;
+          border: 2px solid #000; background: #fff; color: #000;
+          padding: 0.28rem 0.55rem; cursor: pointer; min-width: 120px;
+          max-width: 180px;
+        }
+        .sim-sel:focus { outline: none; box-shadow: 2px 2px 0 #000; }
+
+        .sim-actions { display: flex; flex-wrap: wrap; gap: 5px; align-items: flex-end; }
+        .sim-icon-btn {
+          display: inline-flex; align-items: center; gap: 4px;
+          border: 2px solid #000; background: #fff; color: #000;
+          padding: 0.28rem 0.65rem; font-family: var(--font-mono);
+          font-size: 0.7rem; font-weight: 700; cursor: pointer;
+          letter-spacing: 0.5px; transition: all 0.13s ease;
+          white-space: nowrap;
+        }
+        .sim-icon-btn:hover, .sim-icon-btn.active { background: #000; color: #fff; }
+        .sim-icon-btn:disabled { opacity: 0.4; cursor: not-allowed; pointer-events: none; }
+
+        /* Search bar */
+        .search-bar-row {
+          display: flex; align-items: center; gap: 0.5rem;
+          border: 2px solid #000; padding: 0.3rem 0.75rem;
+          margin-bottom: 0.5rem; background: #fafafa;
+        }
+        .sim-search-input {
+          flex: 1; border: none; background: transparent;
+          font-family: var(--font-mono); font-size: 0.85rem;
+          color: #000; outline: none;
+        }
+        .search-result-badge {
+          font-family: var(--font-mono); font-size: 0.72rem; font-weight: 700;
+          background: #000; color: #fff; padding: 1px 8px;
+        }
+
+        /* Advanced panel */
+        .advanced-panel {
+          border: 2px solid #000; background: #fff;
+          margin-bottom: 0.5rem; box-shadow: 3px 3px 0 #000;
+        }
+        .panel-header {
+          display: flex; justify-content: space-between; align-items: center;
+          padding: 0.4rem 0.9rem;
+          background: #000; color: #fff;
+          font-family: var(--font-mono); font-size: 0.75rem; font-weight: 700;
+          letter-spacing: 1px;
+        }
+        .panel-body {
+          display: flex; flex-wrap: wrap; gap: 1.25rem; padding: 0.9rem 1rem;
+        }
+        .opt-section { flex: 1; min-width: 160px; }
+        .opt-label {
+          font-family: var(--font-mono); font-size: 0.62rem; font-weight: 700;
+          color: #888; letter-spacing: 1px; margin-bottom: 0.45rem;
+        }
+        .opt-row { display: flex; flex-direction: column; gap: 5px; }
+        .opt-toggle {
+          display: flex; align-items: center; gap: 7px;
+          font-family: var(--font-mono); font-size: 0.77rem; cursor: pointer;
+        }
+        .opt-toggle input { cursor: pointer; }
+        .opt-sliders { display: flex; flex-direction: column; gap: 0.55rem; }
+        .slider-row {
+          display: flex; flex-direction: column; gap: 3px;
+          font-family: var(--font-mono); font-size: 0.75rem;
+        }
+        .slider-row input[type=range] { width: 100%; cursor: pointer; }
+        .reset-btn {
+          align-self: flex-end;
+          border: 2px solid #000; background: #fff; color: #000;
+          font-family: var(--font-mono); font-size: 0.72rem; font-weight: 700;
+          padding: 0.3rem 0.9rem; cursor: pointer; letter-spacing: 0.5px;
+          transition: all 0.13s ease;
+        }
+        .reset-btn:hover { background: #000; color: #fff; }
+
+        /* Help table */
+        .help-table { width: 100%; border-collapse: collapse; }
+        .help-table td { vertical-align: top; padding: 2px 0; font-family: var(--font-mono); font-size: 0.74rem; }
+        .help-key { color: #000; font-weight: 700; white-space: nowrap; padding-right: 0.75rem; }
+        .help-val { color: #555; }
+        .help-tips { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 5px; }
+        .help-tips li { font-family: var(--font-mono); font-size: 0.74rem; color: #555; line-height: 1.4; }
+        .help-tips li::before { content: '→ '; color: #000; font-weight: 700; }
+        .help-tips strong { color: #000; }
+
+        /* Canvas area */
+        .canvas-area {
+          flex: 1; display: flex; gap: 0.6rem; min-height: 0; overflow: hidden;
+        }
+        .canvas-wrapper {
+          flex: 1; border: 2px solid #000;
+          background: #fafafa; position: relative; overflow: hidden; min-height: 0;
+        }
+        .loading-overlay {
+          position: absolute; inset: 0;
+          display: flex; flex-direction: column; align-items: center; justify-content: center;
+          gap: 1rem; background: rgba(255,255,255,0.92);
+          font-family: var(--font-mono); font-size: 0.88rem;
+          letter-spacing: 1.2px; color: #555;
+          white-space: pre-line; text-align: center; padding: 2rem; z-index: 10;
+        }
+        .loading-overlay.empty { color: #bbb; }
+        .refresh-pill {
+          position: absolute; top: 8px; right: 8px;
+          display: flex; align-items: center; gap: 5px;
+          background: rgba(0,0,0,0.85); color: #fff;
+          font-family: var(--font-mono); font-size: 0.7rem;
+          padding: 2px 9px; z-index: 20;
+        }
+
+        /* Sidebar panels */
+        .sidebar-panels {
+          display: flex; flex-direction: column; gap: 0.5rem;
+          width: 150px; flex-shrink: 0; overflow-y: auto;
+        }
+        .legend-panel, .stats-sidebar {
+          border: 2px solid #000; background: #fff; padding: 0.65rem 0.75rem; flex-shrink: 0;
+        }
+        .legend-title {
+          font-family: var(--font-mono); font-size: 0.6rem; font-weight: 700;
+          color: #888; letter-spacing: 1px; margin-bottom: 0.5rem; text-transform: uppercase;
+        }
+        .legend-row { display: flex; align-items: center; gap: 7px; margin-bottom: 4px; }
+        .legend-dot {
+          width: 11px; height: 11px; border-radius: 50%; flex-shrink: 0;
+          border: 1px solid rgba(0,0,0,0.15);
+        }
+        .legend-type {
+          font-family: var(--font-mono); font-size: 0.72rem; font-weight: 600;
+          white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+        }
+        .stat-row {
+          display: flex; justify-content: space-between; align-items: center;
+          font-family: var(--font-mono); font-size: 0.72rem;
+          color: #555; margin-bottom: 3px;
+        }
+        .stat-row strong { color: #000; font-weight: 700; }
+        .hub-node-row {
+          display: flex; align-items: center; gap: 5px;
+          font-family: var(--font-mono); font-size: 0.69rem;
+          color: #333; margin-bottom: 3px; cursor: pointer;
+          padding: 2px 4px; transition: background 0.12s;
+        }
+        .hub-node-row:hover { background: #f0f0f0; }
+
+        /* Hint bar */
+        .sim-hint {
+          display: flex; align-items: center; gap: 5px;
+          font-size: 0.69rem; color: #999; font-family: var(--font-mono);
+          padding: 0.25rem 0; border-top: 1px dashed #ccc; margin-top: 0.25rem;
+          flex-shrink: 0;
+        }
+        .sim-hint strong { color: #555; }
+
+        .spin { animation: spin 1.2s linear infinite; }
+        @keyframes spin { 100% { transform: rotate(360deg); } }
+      `}</style>
+    </div>
+  );
+};
+
+export default SimulationRunView;

frontend-react/tsconfig.app.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2023",
+    "useDefineForClassFields": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

frontend-react/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

frontend-react/tsconfig.node.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}

frontend-react/vite.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+  ],
+  server: {
+    host: true, // Listen on all network interfaces to allow LAN access
+  }
+})

main.py

@@ -0,0 +1,9 @@
+"""
+Entry point for the application
+You can run the API server using: uv run python main.py
+"""
+
+from src.graph_rag_service.main import main
+
+if __name__ == "__main__":
+    main()

package-lock.json

@@ -0,0 +1,373 @@
+{
+  "name": "graph-rag",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "graph-rag",
+      "version": "1.0.0",
+      "hasInstallScript": true,
+      "devDependencies": {
+        "concurrently": "^8.2.2"
+      }
+    },
+    "node_modules/@babel/runtime": {
+      "version": "7.29.2",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.2.tgz",
+      "integrity": "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/chalk": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
+      "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.1.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/chalk/node_modules/supports-color": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
+      "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.1",
+        "wrap-ansi": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/concurrently": {
+      "version": "8.2.2",
+      "resolved": "https://registry.npmjs.org/concurrently/-/concurrently-8.2.2.tgz",
+      "integrity": "sha512-1dP4gpXFhei8IOtlXRE/T/4H88ElHgTiUzh71YUmtjTEHMSRS2Z/fgOxHSxxusGHogsRfxNq1vyAwxSC+EVyDg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "chalk": "^4.1.2",
+        "date-fns": "^2.30.0",
+        "lodash": "^4.17.21",
+        "rxjs": "^7.8.1",
+        "shell-quote": "^1.8.1",
+        "spawn-command": "0.0.2",
+        "supports-color": "^8.1.1",
+        "tree-kill": "^1.2.2",
+        "yargs": "^17.7.2"
+      },
+      "bin": {
+        "conc": "dist/bin/concurrently.js",
+        "concurrently": "dist/bin/concurrently.js"
+      },
+      "engines": {
+        "node": "^14.13.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/open-cli-tools/concurrently?sponsor=1"
+      }
+    },
+    "node_modules/date-fns": {
+      "version": "2.30.0",
+      "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-2.30.0.tgz",
+      "integrity": "sha512-fnULvOpxnC5/Vg3NCiWelDsLiUc9bRwAPs/+LfTLNvetFCtCTN+yQz15C/fs4AwX1R9K5GLtLfn8QW+dWisaAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.21.0"
+      },
+      "engines": {
+        "node": ">=0.11"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/date-fns"
+      }
+    },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
+    "node_modules/has-flag": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
+      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/lodash": {
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/require-directory": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
+      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/rxjs": {
+      "version": "7.8.2",
+      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.2.tgz",
+      "integrity": "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "tslib": "^2.1.0"
+      }
+    },
+    "node_modules/shell-quote": {
+      "version": "1.8.3",
+      "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.3.tgz",
+      "integrity": "sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/spawn-command": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/spawn-command/-/spawn-command-0.0.2.tgz",
+      "integrity": "sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ==",
+      "dev": true
+    },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/supports-color": {
+      "version": "8.1.1",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz",
+      "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/supports-color?sponsor=1"
+      }
+    },
+    "node_modules/tree-kill": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz",
+      "integrity": "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "tree-kill": "cli.js"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD"
+    },
+    "node_modules/wrap-ansi": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/yargs": {
+      "version": "17.7.2",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
+      "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^8.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.3",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^21.1.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "21.1.1",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,16 @@
+{
+  "name": "graph-rag",
+  "version": "1.0.0",
+  "description": "Agentic Graph RAG Application",
+  "private": true,
+  "scripts": {
+    "rag": "concurrently -k -p \"[{name}]\" -n \"SERVER,WORKER,FRONTEND\" -c \"magenta,blue,cyan\" \"npm run run:server\" \"npm run run:worker\" \"npm run run:frontend\"",
+    "run:server": "uv run python main.py",
+    "run:worker": "uv run celery -A src.graph_rag_service.workers.celery_worker worker --loglevel=info --concurrency=4 --pool=threads",
+    "run:frontend": "npm --prefix frontend-react run dev",
+    "postinstall": "npm --prefix frontend-react install && uv sync && uv run playwright install chromium"
+  },
+  "devDependencies": {
+    "concurrently": "^8.2.2"
+  }
+}

pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "graph-rag"
+version = "0.1.0"
+description = "Agentic Graph RAG as a Service - Production-grade knowledge graph platform"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    {name = "Your Name", email = "your.email@example.com"}
+]
+keywords = ["graph", "rag", "llm", "knowledge-graph", "neo4j", "langgraph", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "fastapi[standard]>=0.129.0",
+    "uvicorn[standard]>=0.41.0",
+    "llama-index-core>=0.14.14",
+    "langgraph>=1.0.8",
+    "langchain-core>=1.2.13",
+    "neo4j>=5.28.0,<6.0.0",
+    "redis>=7.2.0",
+    "celery>=5.6.2",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.13.0",
+    "python-multipart>=0.0.22",
+    "httpx>=0.28.1",
+    "llama-index-llms-openai>=0.6.18",
+    "llama-index-llms-anthropic>=0.10.8",
+    "llama-index-llms-gemini>=0.6.2",
+    "llama-index-embeddings-gemini>=0.1.0",
+    "llama-index-llms-ollama>=0.9.1",
+    "llama-index-embeddings-ollama>=0.8.6",
+    "llama-index-graph-stores-neo4j>=0.5.1",
+    "llama-parse>=0.6.10",
+    "opentelemetry-api>=1.39.1",
+    "opentelemetry-sdk>=1.39.1",
+    "opentelemetry-instrumentation-fastapi>=0.60b1",
+    "python-jose[cryptography]>=3.5.0",
+    "passlib[bcrypt]>=1.7.4",
+    "aiofiles>=25.1.0",
+    "pypdf>=6.7.1",
+    "python-magic-bin>=0.4.14",
+    "openpyxl>=3.1.2",
+    "python-pptx>=0.6.23",
+    "beautifulsoup4>=4.12.3",
+    "crawl4ai>=0.4.0",
+    "markdownify>=1.2.2",
+    "flower>=2.0.1",
+    "bcrypt>=4.0.0",            # used directly in auth.py (not via passlib)
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "black>=24.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+graph-rag = "graph_rag_service.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/graph_rag_service"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 100
+target-version = ['py312']
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"

refactor_di.py

@@ -0,0 +1,33 @@
+import os
+import re
+
+target_dir = r"D:\Desktop_March_26\LYZR\graph-RAG\src\graph_rag_service\api\routers"
+
+import_statement = "from ..dependencies import get_graph_store, get_retrieval_agent, get_ingestion_pipeline, get_redis_client\n"
+
+for f in os.listdir(target_dir):
+    if not f.endswith(".py"): continue
+    p = os.path.join(target_dir, f)
+    with open(p, "r", encoding="utf-8") as file:
+        content = file.read()
+    
+    # Remove all definitions
+    content = re.sub(r'def get_graph_store\(.*?\).*?return.*?\n+', '', content, flags=re.DOTALL)
+    content = re.sub(r'def get_retrieval_agent\(.*?\).*?return.*?\n+', '', content, flags=re.DOTALL)
+    content = re.sub(r'def get_ingestion_pipeline\(.*?\).*?return.*?\n+', '', content, flags=re.DOTALL)
+    content = re.sub(r'def get_redis_client\(.*?\).*?return.*?\n+', '', content, flags=re.DOTALL)
+    content = re.sub(r'# Dependency injection for global state\n+', '', content)
+    
+    # Add import near the top if not present
+    if "from ..dependencies import" not in content and ("Depends(" in content or "Request" in content):
+        # find the last import
+        last_import = max((content.find("\nimport "), content.find("\nfrom ")))
+        if last_import != -1:
+            end_of_line = content.find("\n", last_import + 1)
+            content = content[:end_of_line+1] + import_statement + content[end_of_line+1:]
+        else:
+            content = import_statement + content
+            
+    with open(p, "w", encoding="utf-8") as file:
+        file.write(content)
+    print(f"Refactored {f}")