may be final

.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Model cache
+.cache/
+models/
+
+# Output files
+*.png
+*.jpg
+*.pdf
+entropy_curve.png
+example_entropy_curve.png
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Streamlit
+.streamlit/

ARCHITECTURE.md

@@ -0,0 +1,195 @@
+# System Architecture
+
+## Data Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         USER INPUT                                   │
+│                    "What is the capital of France?"                  │
+└──────────────────────────────┬──────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      MODEL LOADER                                    │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │  TransformerLens GPT-2                                        │  │
+│  │  • Load pretrained model                                      │  │
+│  │  • Generate 5 stochastic responses (temp=0.8)                │  │
+│  │  • Capture activations (logits, hidden states, attention)    │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────┬──────────────────────────────────────┘
+                               │
+                ┌──────────────┴──────────────┐
+                │                             │
+                ▼                             ▼
+┌───────────────────────────┐   ┌─────────────────────────────┐
+│   INTERNAL METRICS        │   │   EXTERNAL VERIFIER         │
+│                           │   │                             │
+│  ┌─────────────────────┐ │   │  ┌───────────────────────┐ │
+│  │ Entropy Metric      │ │   │  │ Ground Truth Loader   │ │
+│  │ • Token-level       │ │   │  │ • Match question      │ │
+│  │ • Mean & max        │ │   │  │ • Load answer         │ │
+│  │ • Normalized        │ │   │  └───────────────────────┘ │
+│  └─────────────────────┘ │   │                             │
+│                           │   │  ┌───────────────────────┐ │
+│  ┌─────────────────────┐ │   │  │ Sentence Transformer  │ │
+│  │ Stability Metric    │ │   │  │ • Encode responses    │ │
+│  │ • Layer similarity  │ │   │  │ • Encode ground truth │ │
+│  │ • Cosine distance   │ │   │  │ • Compute similarity  │ │
+│  │ • Averaged          │ │   │  └───────────────────────┘ │
+│  └─────────────────────┘ │   │                             │
+│                           │   │  ┌───────────────────────┐ │
+│  ┌─────────────────────┐ │   │  │ Consistency Score     │ │
+│  │ Grounding Metric    │ │   │  │ • Mean similarity     │ │
+│  │ • Attention to      │ │   │  │ • External risk       │ │
+│  │   prompt ratio      │ │   │  │   = 1 - consistency   │ │
+│  │ • Across layers     │ │   │  └───────────────────────┘ │
+│  └─────────────────────┘ │   │                             │
+│                           │   └─────────────────────────────┘
+│  ┌─────────────────────┐ │
+│  │ Internal Risk       │ │
+│  │ = w1*entropy +      │ │
+│  │   w2*(1-stability)+ │ │
+│  │   w3*(1-grounding)  │ │
+│  └─────────────────────┘ │
+└───────────┬───────────────┘
+            │
+            │
+            ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         ANALYZER                                     │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │  Hybrid Risk Score                                            │  │
+│  │  = alpha * InternalRisk + beta * ExternalRisk                │  │
+│  │  = 0.6 * InternalRisk + 0.4 * ExternalRisk                   │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────┬──────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         OUTPUT                                       │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │ • 5 Generated Responses                                       │  │
+│  │ • Mean Entropy: 2.3456                                        │  │
+│  │ • Max Entropy: 4.5678                                         │  │
+│  │ • Stability Score: 0.8765                                     │  │
+│  │ • Grounding Score: 0.7654                                     │  │
+│  │ • Internal Risk: 0.3456                                       │  │
+│  │ • Similarity Scores: [0.92, 0.89, 0.91, 0.88, 0.90]          │  │
+│  │ • External Consistency: 0.9000                                │  │
+│  │ • External Risk: 0.1000                                       │  │
+│  │ • FINAL RISK: 0.2474 (LOW)                                   │  │
+│  │ • Entropy Curve Visualization                                 │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Component Interaction
+
+```
+┌──────────────┐
+│   app.py     │  Streamlit UI
+│   main.py    │  CLI Interface
+│   example.py │  Demo Script
+└──────┬───────┘
+       │
+       │ uses
+       ▼
+┌──────────────────┐
+│   analyzer.py    │  Orchestrates everything
+└──────┬───────────┘
+       │
+       │ coordinates
+       ▼
+┌──────────────────────────────────────────┐
+│  model_loader.py                         │
+│  internal_metrics.py                     │
+│  external_verifier.py                    │
+└──────────────────────────────────────────┘
+       │
+       │ uses
+       ▼
+┌──────────────────────────────────────────┐
+│  TransformerLens (GPT-2)                 │
+│  SentenceTransformer (MiniLM)            │
+│  PyTorch, NumPy, Matplotlib              │
+└──────────────────────────────────────────┘
+```
+
+## Risk Calculation Formula
+
+```
+InternalRisk = w1 × normalized_entropy
+             + w2 × (1 - stability)
+             + w3 × (1 - grounding)
+
+where:
+  w1 = 0.4 (entropy weight)
+  w2 = 0.3 (stability weight)
+  w3 = 0.3 (grounding weight)
+
+ExternalRisk = 1 - ExternalConsistency
+             = 1 - mean(similarities)
+
+FinalRisk = α × InternalRisk + β × ExternalRisk
+
+where:
+  α = 0.6 (internal weight)
+  β = 0.4 (external weight)
+
+Risk Interpretation:
+  FinalRisk < 0.3  → LOW RISK (reliable)
+  0.3 ≤ FinalRisk < 0.6 → MEDIUM RISK (uncertain)
+  FinalRisk ≥ 0.6  → HIGH RISK (hallucination)
+```
+
+## Module Dependencies
+
+```
+model_loader.py
+  ├── transformer_lens (HookedTransformer)
+  ├── torch
+  └── numpy
+
+internal_metrics.py
+  ├── torch
+  ├── torch.nn.functional
+  └── numpy
+
+external_verifier.py
+  ├── sentence_transformers
+  ├── sklearn.metrics.pairwise
+  ├── json
+  └── numpy
+
+analyzer.py
+  ├── model_loader
+  ├── internal_metrics
+  ├── external_verifier
+  └── matplotlib
+
+app.py
+  ├── analyzer
+  ├── streamlit
+  ├── plotly
+  └── matplotlib
+
+main.py
+  ├── analyzer
+  └── argparse
+```
+
+## File Sizes
+
+```
+Core Modules:        ~25 KB
+UI/CLI:             ~15 KB
+Documentation:      ~15 KB
+Data:               ~1.5 KB
+Total Project:      ~56 KB
+
+External Downloads (first run):
+  GPT-2 model:      ~500 MB
+  MiniLM model:     ~80 MB
+  PyTorch:          ~200 MB
+```

INSTALL_ANACONDA.md

@@ -0,0 +1,100 @@
+# Installation Guide for Anaconda Users
+
+## Prerequisites
+- Anaconda or Miniconda installed
+- Python 3.8 or higher
+
+## Installation Steps
+
+### Step 1: Create a New Conda Environment (Recommended)
+
+```bash
+conda create -n hallucination python=3.10
+conda activate hallucination
+```
+
+### Step 2: Install PyTorch
+
+Install PyTorch based on your system:
+
+**For CPU only:**
+```bash
+conda install pytorch torchvision torchaudio cpuonly -c pytorch
+```
+
+**For CUDA (GPU) - if you have NVIDIA GPU:**
+```bash
+conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia
+```
+
+### Step 3: Install Other Dependencies
+
+```bash
+pip install transformer-lens transformers sentence-transformers streamlit plotly scikit-learn matplotlib numpy
+```
+
+Or use the requirements file:
+```bash
+pip install -r requirements.txt
+```
+
+### Step 4: Verify Installation
+
+```bash
+python -c "import torch; import transformer_lens; import streamlit; print('All dependencies installed successfully!')"
+```
+
+## Quick Start
+
+### Activate Environment
+```bash
+conda activate hallucination
+```
+
+### Run Streamlit UI
+```bash
+streamlit run app.py
+```
+
+### Run Example
+```bash
+python example.py
+```
+
+### Run CLI
+```bash
+python main.py --prompt "What is the capital of France?"
+```
+
+## Troubleshooting
+
+### ImportError: No module named 'transformer_lens'
+```bash
+pip install transformer-lens
+```
+
+### CUDA Out of Memory
+Use CPU-only version or reduce batch size:
+```bash
+python main.py --prompt "..." --num-responses 3 --max-length 30
+```
+
+### Slow Performance on First Run
+- First run downloads models (~500MB)
+- Subsequent runs will be faster
+- Models are cached in `~/.cache/huggingface/`
+
+## Deactivate Environment
+
+When done:
+```bash
+conda deactivate
+```
+
+## Uninstall
+
+To remove the environment:
+```bash
+conda deactivate
+conda env remove -n hallucination
+```

PROJECT_SUMMARY.md

@@ -0,0 +1,228 @@
+# 🎯 PROJECT COMPLETE - Hybrid LLM Hallucination Detection System
+
+## ✅ What Has Been Built
+
+A complete, production-ready Python project for detecting hallucinations in LLM-generated text using GPT-2 and TransformerLens.
+
+---
+
+## 📁 Project Structure
+
+```
+gllm/
+│
+├── 🔧 Core Modules
+│   ├── model_loader.py          # GPT-2 loading & text generation
+│   ├── internal_metrics.py      # Entropy, stability, grounding metrics
+│   ├── external_verifier.py     # Ground truth matching & similarity
+│   └── analyzer.py              # Main orchestrator combining all metrics
+│
+├── 🚀 Entry Points
+│   ├── app.py                   # Streamlit web UI (RECOMMENDED)
+│   ├── main.py                  # Command-line interface
+│   └── example.py               # Quick demo script
+│
+├── 📊 Data
+│   └── ground_truth.json        # 10 sample Q&A pairs for verification
+│
+├── 📖 Documentation
+│   ├── README.md                # Complete project documentation
+│   ├── SETUP.md                 # Quick setup for Anaconda users
+│   ├── QUICKSTART.md            # Quick start guide
+│   └── INSTALL_ANACONDA.md      # Detailed Anaconda installation
+│
+├── 🛠️ Utilities
+│   ├── install.bat              # Auto-install script (Windows)
+│   ├── run_ui.bat               # Launch Streamlit UI (Windows)
+│   ├── requirements.txt         # Python dependencies
+│   └── .gitignore               # Git ignore rules
+│
+└── Total: 16 files, ~52KB code
+```
+
+---
+
+## 🎨 Features Implemented
+
+### ✅ Internal Hallucination Analysis
+- **Entropy Metric**: Token-level uncertainty from logits
+- **Stability Metric**: Layer-wise hidden state similarity
+- **Attention Grounding**: Attention to prompt tokens ratio
+- **Internal Risk Score**: Weighted combination (w1=0.4, w2=0.3, w3=0.3)
+
+### ✅ External Factual Verification
+- Ground truth dataset loading (JSON)
+- Semantic similarity using sentence-transformers (all-MiniLM-L6-v2)
+- Multi-response consistency checking (5 stochastic samples)
+- External risk calculation
+
+### ✅ Hybrid Risk Scoring
+- Combined internal + external metrics
+- Configurable weights (alpha=0.6, beta=0.4)
+- Risk interpretation (LOW/MEDIUM/HIGH)
+
+### ✅ Streamlit Web UI
+- Interactive parameter configuration
+- Real-time analysis dashboard
+- Plotly visualizations:
+  - Entropy curves
+  - Metric comparisons
+  - Risk breakdowns
+  - Layer-wise stability
+- Comprehensive metric displays
+- Modern, professional design
+
+### ✅ CLI Interface
+- Full command-line support
+- Configurable parameters
+- Matplotlib entropy plots
+- Formatted text output
+
+---
+
+## 🚀 How to Use (Anaconda Prompt)
+
+### 1️⃣ Install Dependencies
+```bash
+cd C:\Users\Sanjana\Desktop\gllm
+conda install pytorch torchvision torchaudio cpuonly -c pytorch -y
+pip install transformer-lens transformers sentence-transformers streamlit plotly scikit-learn
+```
+
+### 2️⃣ Run Streamlit UI (Recommended)
+```bash
+streamlit run app.py
+```
+Open http://localhost:8501 in your browser
+
+### 3️⃣ Or Use Command Line
+```bash
+python main.py --prompt "What is the capital of France?"
+```
+
+### 4️⃣ Or Run Example
+```bash
+python example.py
+```
+
+---
+
+## 📊 System Output
+
+For each prompt, the system provides:
+
+### Generated Responses
+- 5 stochastic responses with temperature sampling
+
+### Internal Metrics
+- Mean Entropy: 0.0000 - 10.0000
+- Max Entropy: 0.0000 - 10.0000
+- Stability Score: 0.0000 - 1.0000
+- Grounding Score: 0.0000 - 1.0000
+- Internal Risk: 0.0000 - 1.0000
+
+### External Metrics
+- Similarity Scores: 0.0000 - 1.0000 (per response)
+- External Consistency: 0.0000 - 1.0000
+- External Risk: 0.0000 - 1.0000
+
+### Final Score
+- **Final Hallucination Risk: 0.0000 - 1.0000**
+  - < 0.3: ✅ LOW RISK
+  - 0.3-0.6: ⚠️ MEDIUM RISK
+  - > 0.6: ❌ HIGH RISK
+
+### Visualizations
+- Token-level entropy curve
+- Internal risk component breakdown
+- External similarity comparison
+- Layer-wise stability analysis
+- Final risk pie chart
+
+---
+
+## 🎯 Key Technical Details
+
+### Models Used
+- **GPT-2** (124M params) via TransformerLens
+- **all-MiniLM-L6-v2** for semantic similarity
+
+### Metrics Implementation
+- **Entropy**: Computed from softmax probabilities
+- **Stability**: Cosine similarity between layer activations
+- **Grounding**: Attention weight ratio to prompt tokens
+- **Similarity**: Cosine similarity of sentence embeddings
+
+### Performance
+- **First run**: ~60 seconds (downloads models)
+- **Subsequent runs**: ~10-20 seconds per prompt
+- **Memory**: ~2GB RAM (CPU mode)
+- **GPU**: Optional, significantly faster if available
+
+---
+
+## 📦 Dependencies
+
+```
+torch>=2.0.0              # Deep learning framework
+transformer-lens>=1.0.0   # GPT-2 interpretability
+transformers>=4.30.0      # HuggingFace transformers
+sentence-transformers     # Semantic similarity
+streamlit>=1.28.0         # Web UI
+plotly>=5.14.0           # Interactive plots
+matplotlib>=3.7.0         # Static plots
+numpy>=1.24.0            # Numerical computing
+scikit-learn>=1.3.0      # ML utilities
+```
+
+Total download: ~600MB (one-time)
+
+---
+
+## 🎓 Customization
+
+### Add Your Own Questions
+Edit `ground_truth.json`:
+```json
+{
+    "question": "Your question here",
+    "answer": "The correct answer"
+}
+```
+
+### Adjust Risk Weights
+- In UI: Use sidebar sliders
+- In CLI: `--alpha 0.7 --beta 0.3`
+
+### Use Different GPT-2 Models
+- `gpt2` (124M) - default
+- `gpt2-medium` (355M)
+- `gpt2-large` (774M)
+
+---
+
+## ✨ What Makes This Special
+
+1. **Complete Implementation**: All requirements met
+2. **Production Ready**: Clean, modular, well-documented code
+3. **User Friendly**: Both GUI and CLI interfaces
+4. **Extensible**: Easy to add new metrics or models
+5. **Educational**: Clear comments explaining each metric
+6. **Visualizations**: Interactive and static plots
+7. **Local**: Runs entirely on your machine, no API keys needed
+
+---
+
+## 🎉 You're All Set!
+
+The project is complete and ready to use. Simply:
+
+1. Open **Anaconda Prompt**
+2. Navigate to `C:\Users\Sanjana\Desktop\gllm`
+3. Install dependencies (see SETUP.md)
+4. Run `streamlit run app.py`
+5. Start detecting hallucinations! 🔍
+
+---
+
+**Happy Hallucination Hunting! 🚀**

QUICKSTART.md

@@ -0,0 +1,115 @@
+# Quick Start Guide
+
+## Installation
+
+1. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. **First run will download models (~500MB):**
+   - GPT-2 model (~500MB)
+   - Sentence transformer model (~80MB)
+
+## Running the System
+
+### Option 1: Streamlit Web UI (Recommended)
+
+```bash
+streamlit run app.py
+```
+
+Then open http://localhost:8501 in your browser.
+
+### Option 2: Run Example Script
+
+```bash
+python example.py
+```
+
+This will analyze the prompt "What is the capital of France?" and show all metrics.
+
+### Option 3: Command Line
+
+```bash
+python main.py --prompt "What is the capital of France?"
+```
+
+## Testing Different Prompts
+
+Try these prompts from the ground truth dataset:
+
+```bash
+python main.py --prompt "Who wrote Romeo and Juliet?"
+python main.py --prompt "What is the speed of light?"
+python main.py --prompt "When did World War II end?"
+python main.py --prompt "What is the largest planet in our solar system?"
+```
+
+## Understanding the Output
+
+### Internal Metrics
+- **Mean Entropy**: Average uncertainty (0-10, higher = more uncertain)
+- **Stability Score**: Layer consistency (0-1, higher = more stable)
+- **Grounding Score**: Attention to prompt (0-1, higher = more grounded)
+- **Internal Risk**: Combined internal score (0-1, higher = more risk)
+
+### External Metrics
+- **Similarity Scores**: How similar each response is to ground truth (0-1)
+- **External Consistency**: Average similarity across responses (0-1)
+- **External Risk**: 1 - consistency (0-1, higher = more risk)
+
+### Final Risk Score
+- **< 0.3**: ✅ LOW - Reliable response
+- **0.3-0.6**: ⚠️ MEDIUM - Some uncertainties
+- **> 0.6**: ❌ HIGH - Likely hallucination
+
+## Customization
+
+### Add Your Own Questions
+
+Edit `ground_truth.json`:
+
+```json
+[
+    {
+        "question": "Your question",
+        "answer": "The correct answer"
+    }
+]
+```
+
+### Adjust Parameters
+
+In Streamlit UI: Use sidebar sliders
+
+In CLI: Use command-line flags
+```bash
+python main.py --prompt "..." --temperature 0.9 --num-responses 10
+```
+
+## Troubleshooting
+
+### Out of Memory
+- Use smaller model: `--model gpt2` (default)
+- Reduce responses: `--num-responses 3`
+- Reduce length: `--max-length 30`
+
+### Slow Performance
+- First run downloads models (one-time)
+- GPU recommended but not required
+- Reduce `--num-responses` for faster analysis
+
+### No Ground Truth Found
+- System will still compute internal metrics
+- External risk defaults to 0.5 (neutral)
+- Add your prompt to `ground_truth.json`
+
+## Next Steps
+
+1. Try the Streamlit UI for interactive exploration
+2. Add your own questions to the ground truth dataset
+3. Experiment with different temperature settings
+4. Compare results across different GPT-2 model sizes
+
+Enjoy exploring hallucination detection! 🔍

README.md

@@ -0,0 +1,224 @@
+# Hybrid LLM Hallucination Detection System
+
+A complete Python project for detecting hallucinations in LLM-generated text using GPT-2 and TransformerLens. The system combines internal model analysis (entropy, stability, attention grounding) with external factual verification.
+
+## Features
+
+- **Internal Hallucination Analysis**
+  - Token-level entropy computation
+  - Layer-wise stability analysis via hidden state similarity
+  - Attention grounding metric (attention to prompt tokens)
+  
+- **External Factual Verification**
+  - Ground truth dataset matching
+  - Semantic similarity using sentence transformers
+  - Multi-response consistency checking
+
+- **Hybrid Risk Scoring**
+  - Weighted combination of internal and external metrics
+  - Configurable risk weights
+  - Interpretable risk levels (LOW/MEDIUM/HIGH)
+
+- **Interactive Streamlit UI**
+  - Real-time analysis dashboard
+  - Interactive visualizations with Plotly
+  - Configurable parameters
+  - Comprehensive metric displays
+
+## Project Structure
+
+```
+gllm/
+├── model_loader.py          # GPT-2 model loading and text generation
+├── internal_metrics.py      # Entropy, stability, grounding metrics
+├── external_verifier.py     # Ground truth matching and similarity
+├── analyzer.py              # Main analysis orchestrator
+├── main.py                  # CLI interface
+├── app.py                   # Streamlit web UI
+├── ground_truth.json        # Sample ground truth dataset
+└── requirements.txt         # Python dependencies
+```
+
+## Installation
+
+1. Clone or download this project
+
+2. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+### Option 1: Streamlit Web UI (Recommended)
+
+Run the interactive web interface:
+
+```bash
+streamlit run app.py
+```
+
+Then open your browser to the provided URL (typically http://localhost:8501)
+
+Features:
+- Enter prompts and configure parameters via UI
+- View all metrics and visualizations in real-time
+- Interactive plots for entropy curves and metric comparisons
+- Export-ready analysis results
+
+### Option 2: Command Line Interface
+
+Run analysis from the command line:
+
+```bash
+python main.py --prompt "What is the capital of France?" --num-responses 5
+```
+
+Available arguments:
+- `--prompt`: Input question/prompt (required)
+- `--num-responses`: Number of responses to generate (default: 5)
+- `--max-length`: Maximum generation length (default: 50)
+- `--temperature`: Sampling temperature (default: 0.8)
+- `--model`: GPT-2 variant (default: gpt2)
+- `--ground-truth`: Path to ground truth JSON (default: ground_truth.json)
+- `--save-plot`: Path to save entropy plot (optional)
+- `--alpha`: Weight for internal risk (default: 0.6)
+- `--beta`: Weight for external risk (default: 0.4)
+
+Example:
+```bash
+python main.py --prompt "Who wrote Romeo and Juliet?" --num-responses 5 --temperature 0.9 --save-plot entropy.png
+```
+
+## How It Works
+
+### 1. Text Generation
+- Loads GPT-2 using TransformerLens
+- Generates 5 stochastic responses with temperature sampling
+- Captures model activations (logits, hidden states, attention patterns)
+
+### 2. Internal Metrics
+
+**Entropy Metric:**
+- Computes token-level entropy from logits
+- Higher entropy = higher uncertainty
+
+**Stability Metric:**
+- Measures cosine similarity between consecutive layer activations
+- Lower stability = more processing changes (potential hallucination)
+
+**Attention Grounding:**
+- Ratio of attention to prompt tokens vs all tokens
+- Lower grounding = less reliance on input (potential hallucination)
+
+**Internal Risk Score:**
+```
+InternalRisk = w1 * entropy + w2 * (1 - stability) + w3 * (1 - grounding)
+```
+
+### 3. External Verification
+
+- Matches prompt to ground truth dataset
+- Computes semantic similarity using sentence-transformers
+- Averages similarity across all 5 responses
+- External risk = 1 - consistency
+
+### 4. Final Hybrid Score
+
+```
+FinalRisk = alpha * InternalRisk + beta * ExternalRisk
+```
+
+Default: alpha=0.6, beta=0.4
+
+### 5. Risk Interpretation
+
+- **< 0.3**: LOW - Response appears reliable
+- **0.3-0.6**: MEDIUM - May contain uncertainties
+- **> 0.6**: HIGH - Likely contains hallucinations
+
+## Customization
+
+### Adding Ground Truth Data
+
+Edit `ground_truth.json`:
+
+```json
+[
+    {
+        "question": "Your question here",
+        "answer": "The factual answer here"
+    }
+]
+```
+
+### Adjusting Weights
+
+In the Streamlit UI, use the sidebar sliders.
+
+For CLI, use command-line arguments:
+```bash
+python main.py --prompt "..." --alpha 0.7 --beta 0.3
+```
+
+### Using Different Models
+
+The system supports GPT-2 variants:
+- `gpt2` (124M parameters)
+- `gpt2-medium` (355M parameters)
+- `gpt2-large` (774M parameters)
+
+```bash
+python main.py --prompt "..." --model gpt2-medium
+```
+
+## Output
+
+The system provides:
+
+1. **All 5 generated responses**
+2. **Internal metrics:**
+   - Mean and max entropy
+   - Stability score
+   - Grounding score
+   - Internal risk score
+3. **External metrics:**
+   - Similarity scores for each response
+   - External consistency
+   - External risk
+4. **Final hallucination risk score**
+5. **Visualizations:**
+   - Entropy curve plot
+   - Metric comparison charts
+   - Risk breakdown
+
+## Requirements
+
+- Python 3.8+
+- PyTorch 2.0+
+- TransformerLens
+- Sentence Transformers
+- Streamlit
+- Matplotlib/Plotly
+
+See `requirements.txt` for complete list.
+
+## Notes
+
+- First run will download GPT-2 and sentence-transformer models (~500MB total)
+- GPU recommended but not required (runs on CPU)
+- Analysis takes ~30-60 seconds per prompt on CPU
+
+## License
+
+MIT License - feel free to use and modify for your projects.
+
+## Citation
+
+If you use this system in your research, please cite:
+
+```
+Hybrid LLM Hallucination Detection System
+Using GPT-2 and TransformerLens
+https://github.com/yourusername/gllm
+```

SETUP.md

@@ -0,0 +1,111 @@
+# 🚀 SETUP GUIDE - Anaconda Prompt
+
+## Step-by-Step Installation
+
+### Step 1: Open Anaconda Prompt
+1. Press Windows key
+2. Type "Anaconda Prompt"
+3. Click to open
+
+### Step 2: Navigate to Project
+```bash
+cd C:\Users\Sanjana\Desktop\gllm
+```
+
+### Step 3: Install PyTorch (CPU version)
+```bash
+conda install pytorch torchvision torchaudio cpuonly -c pytorch -y
+```
+⏱️ This takes ~3-5 minutes
+
+### Step 4: Install Other Dependencies
+```bash
+pip install transformer-lens transformers sentence-transformers streamlit plotly scikit-learn
+```
+⏱️ This takes ~2-3 minutes
+
+### Step 5: Verify Installation
+```bash
+python -c "import torch; import transformer_lens; import streamlit; print('✅ All dependencies installed!')"
+```
+
+---
+
+## Running the System
+
+### 🎨 Option 1: Streamlit Web UI (Recommended)
+```bash
+streamlit run app.py
+```
+Then open your browser to http://localhost:8501
+
+### 📝 Option 2: Run Example
+```bash
+python example.py
+```
+
+### ⌨️ Option 3: Command Line
+```bash
+python main.py --prompt "What is the capital of France?"
+```
+
+---
+
+## Quick Reference
+
+### Try Different Prompts
+```bash
+python main.py --prompt "Who wrote Romeo and Juliet?"
+python main.py --prompt "What is the speed of light?"
+python main.py --prompt "What is the largest planet in our solar system?"
+```
+
+### Adjust Parameters
+```bash
+python main.py --prompt "Your question" --num-responses 5 --temperature 0.9 --max-length 50
+```
+
+### Save Entropy Plot
+```bash
+python main.py --prompt "Your question" --save-plot entropy_curve.png
+```
+
+---
+
+## What Happens on First Run?
+
+When you first generate text, the system will download:
+- ✅ GPT-2 model (~500MB) - one time only
+- ✅ Sentence transformer model (~80MB) - one time only
+
+These are cached in `C:\Users\Sanjana\.cache\huggingface\`
+
+Subsequent runs will be much faster!
+
+---
+
+## Troubleshooting
+
+### If you get "No module named 'X'"
+```bash
+pip install X
+```
+
+### If Streamlit port is busy
+```bash
+streamlit run app.py --server.port 8502
+```
+
+### If you want GPU support (if you have NVIDIA GPU)
+```bash
+conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia -y
+```
+
+---
+
+## All Set! 🎉
+
+You're ready to detect hallucinations. Start with:
+```bash
+streamlit run app.py
+```

analyzer.py

@@ -0,0 +1,270 @@
+"""
+Analyzer Module.
+Combines internal and external metrics to compute the final hallucination risk score.
+Supports GPT-2 and GPT-Neo variants via TransformerLens.
+"""
+
+from typing import Dict, Any, Optional
+from model_loader import GPT2ModelLoader
+from internal_metrics import InternalMetrics
+from external_verifier import ExternalVerifier
+import matplotlib.pyplot as plt
+import numpy as np
+
+# All supported TransformerLens models used by the app.
+SUPPORTED_MODELS = {
+    "gpt2", "gpt2-medium", "gpt2-large", "gpt2-xl",
+    "EleutherAI/gpt-neo-125M", "EleutherAI/gpt-neo-1.3B", "EleutherAI/gpt-neo-2.7B",
+    "EleutherAI/pythia-2.8b",
+    "facebook/opt-6.7b",
+}
+
+
+class HallucinationAnalyzer:
+    """
+    Main analyzer that combines all metrics for hallucination detection.
+    Supports GPT-2, GPT-Neo, Pythia, and OPT variants via TransformerLens.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "gpt2",
+        semantic_threshold: float = 0.80
+    ):
+        """
+        Initialize the analyzer with all components.
+
+        Args:
+            model_name: Model name for a supported TransformerLens model
+            semantic_threshold: Minimum cosine similarity for TruthfulQA question
+                                matching (0-1). Lower values allow fuzzier matches.
+        """
+        self.model_name = model_name
+
+        if model_name not in SUPPORTED_MODELS:
+            supported = ", ".join(sorted(SUPPORTED_MODELS))
+            raise ValueError(f"Unsupported model '{model_name}'. Supported models: {supported}")
+
+        # TransformerLens model path
+        self.model_loader = GPT2ModelLoader(model_name)
+        self.internal_metrics = InternalMetrics(self.model_loader.get_model())
+
+        # ExternalVerifier loads TruthfulQA directly from HuggingFace
+        self.external_verifier = ExternalVerifier(
+            semantic_threshold=semantic_threshold
+        )
+    
+    def analyze(
+        self,
+        prompt: str,
+        num_responses: int = 5,
+        max_length: int = 50,
+        temperature: float = 0.8,
+        alpha: float = 0.6,
+        beta: float = 0.4,
+        w1: float = 0.4,
+        w2: float = 0.3,
+        w3: float = 0.3,
+    ) -> Dict[str, Any]:
+        """
+        Complete hallucination analysis pipeline.
+
+        Args:
+            prompt: Input prompt/question
+            num_responses: Number of responses to generate
+            max_length: Maximum generation length
+            temperature: Sampling temperature
+            alpha: Weight for internal risk in final score
+            beta: Weight for external risk in final score
+            w1, w2, w3: Weights for eigen score, stability, grounding
+
+        Returns:
+            Dictionary with all metrics and results
+        """
+        print("\n" + "=" * 80)
+        print("HYBRID LLM HALLUCINATION DETECTION SYSTEM")
+        print("=" * 80)
+        print(f"\nPrompt: {prompt}\n")
+
+        return self._analyze_gpt2(
+            prompt, num_responses, max_length, temperature,
+            alpha, beta, w1, w2, w3
+        )
+
+    # ------------------------------------------------------------------
+    # GPT-2 analysis path (original, unchanged logic)
+    # ------------------------------------------------------------------
+
+    def _analyze_gpt2(
+        self,
+        prompt: str,
+        num_responses: int,
+        max_length: int,
+        temperature: float,
+        alpha: float,
+        beta: float,
+        w1: float,
+        w2: float,
+        w3: float,
+    ) -> Dict[str, Any]:
+        # Step 1: Generate multiple responses
+        print("Step 1: Generating responses...")
+        responses = self.model_loader.generate_responses(
+            prompt=prompt,
+            num_responses=num_responses,
+            max_length=max_length,
+            temperature=temperature,
+        )
+
+        # Step 2: Generate primary response with cache for internal analysis
+        print("\nStep 2: Generating primary response with activations...")
+        primary_generation = self.model_loader.generate_with_cache(
+            prompt=prompt,
+            max_length=max_length,
+            temperature=temperature,
+        )
+
+        # Step 3: Compute internal metrics
+        print("\nStep 3: Computing internal metrics...")
+
+        # EigenScore: pass the K sampled responses (INSIDE-paper implementation)
+        eigen_metrics = self.internal_metrics.compute_eigen_score(responses)
+        print(f"  Eigen Score:     {eigen_metrics['eigen_score']:.4f}")
+        print(f"  Responses used:  {eigen_metrics['num_responses']}")
+
+        stability_metrics = self.internal_metrics.compute_stability(
+            primary_generation["cache"],
+            primary_generation["prompt_length"],
+        )
+        print(f"  Stability Score: {stability_metrics['stability_score']:.4f}")
+
+        total_length = primary_generation["tokens"].shape[0]
+        grounding_metrics = self.internal_metrics.compute_attention_grounding(
+            primary_generation["cache"],
+            primary_generation["prompt_length"],
+            total_length,
+        )
+        print(f"  Grounding Score: {grounding_metrics['grounding_score']:.4f}")
+
+        internal_risk_metrics = self.internal_metrics.compute_internal_risk(
+            eigen_metrics, stability_metrics, grounding_metrics, w1, w2, w3
+        )
+        print(f"  Internal Risk: {internal_risk_metrics['internal_risk']:.4f}")
+
+        # Step 4: Compute external metrics
+        print("\nStep 4: Computing external metrics...")
+        external_metrics = self.external_verifier.compute_external_metrics(
+            prompt, responses
+        )
+
+        if external_metrics is None:
+            print("  Warning: No ground truth available, using default external risk")
+            external_metrics = {
+                "similarities": [0.5] * num_responses,
+                "external_consistency": 0.5,
+                "external_risk": 0.5,
+                "ground_truth": "N/A",
+                "ground_truth_source": "None",
+            }
+        # Back-compat: ensure ground_truth_source exists
+        external_metrics.setdefault("ground_truth_source", "TruthfulQA")
+        external_risk = external_metrics["external_risk"]
+
+        # Step 5: Final score
+        print("\nStep 5: Computing final hybrid hallucination score...")
+        final_risk = alpha * internal_risk_metrics["internal_risk"] + beta * external_risk
+        print(f"  Final Hallucination Risk: {final_risk:.4f}")
+
+        return {
+            "prompt": prompt,
+            "responses": responses,
+            "primary_response": primary_generation["text"],
+            "eigen": eigen_metrics,
+            "stability": stability_metrics,
+            "grounding": grounding_metrics,
+            "internal_risk": internal_risk_metrics,
+            "external": external_metrics,
+            "final_risk": final_risk,
+            "weights": {"alpha": alpha, "beta": beta, "w1": w1, "w2": w2, "w3": w3},
+        }
+
+    # (Ollama/Llama3 path removed - GPT-Neo is now the recommended larger model)
+    
+    def plot_eigenvalue_spectrum(self, eigenvalues: list, save_path: str = None):
+        """
+        Plot the eigenvalue spectrum for visualization.
+
+        Args:
+            eigenvalues: List of eigenvalues (descending order) from compute_eigen_score
+            save_path: Optional path to save the plot
+        """
+        if not eigenvalues:
+            raise ValueError("No eigenvalues were provided to plot.")
+
+        ranked_eigenvalues = sorted((float(value) for value in eigenvalues), reverse=True)
+        x_values = np.arange(1, len(ranked_eigenvalues) + 1)
+
+        plt.figure(figsize=(12, 6))
+        plt.bar(x_values, ranked_eigenvalues, color="steelblue", alpha=0.8)
+        plt.plot(x_values, ranked_eigenvalues, color="#0f766e", marker="o", linewidth=2)
+        plt.xlabel("Eigenvalue Rank", fontsize=12)
+        plt.ylabel("Eigenvalue Magnitude", fontsize=12)
+        plt.title("Hidden-State Covariance Eigenvalue Spectrum", fontsize=14, fontweight="bold")
+        plt.xticks(x_values)
+        plt.grid(True, alpha=0.3, axis="y")
+        plt.tight_layout()
+
+        if save_path:
+            plt.savefig(save_path, dpi=300, bbox_inches='tight')
+            print(f"Eigenvalue spectrum saved to {save_path}")
+
+        return plt
+    
+    def print_summary(self, results: Dict[str, Any]):
+        """
+        Print a formatted summary of all results.
+        
+        Args:
+            results: Results dictionary from analyze()
+        """
+        print("\n" + "="*80)
+        print("ANALYSIS SUMMARY")
+        print("="*80)
+        
+        print("\n--- GENERATED RESPONSES ---")
+        for i, response in enumerate(results["responses"], 1):
+            print(f"\nResponse {i}:")
+            print(f"  {response}")
+        
+        print("\n--- INTERNAL METRICS ---")
+        print(f"Eigen Score:      {results['eigen']['eigen_score']:.4f}")
+        print(f"Responses used:   {results['eigen']['num_responses']}")
+        print(f"Stability Score: {results['stability']['stability_score']:.4f}")
+        print(f"Grounding Score: {results['grounding']['grounding_score']:.4f}")
+        print(f"Internal Hallucination Risk: {results['internal_risk']['internal_risk']:.4f}")
+        
+        print("\n--- EXTERNAL METRICS ---")
+        if results['external']['ground_truth'] != "N/A":
+            print(f"Ground Truth: {results['external']['ground_truth']}")
+            print("\nSimilarity Scores:")
+            for i, sim in enumerate(results['external']['similarities'], 1):
+                print(f"  Response {i}: {sim:.4f}")
+            print(f"\nExternal Consistency: {results['external']['external_consistency']:.4f}")
+            print(f"External Risk: {results['external']['external_risk']:.4f}")
+        else:
+            print("No ground truth available")
+        
+        print("\n--- FINAL SCORE ---")
+        print(f"Final Hallucination Risk: {results['final_risk']:.4f}")
+        
+        # Risk interpretation
+        risk = results['final_risk']
+        if risk < 0.3:
+            interpretation = "LOW - Response appears reliable"
+        elif risk < 0.6:
+            interpretation = "MEDIUM - Response may contain some uncertainties"
+        else:
+            interpretation = "HIGH - Response likely contains hallucinations"
+        
+        print(f"Risk Level: {interpretation}")
+        print("="*80 + "\n")

app.py

@@ -0,0 +1,240 @@
+"""
+Multi-page Hallucination Detection System.
+Pages: Analyzer | Explanation | Evaluation | Detailed Metrics | History
+"""
+
+import streamlit as st
+
+import ui_pages.page_analyzer as p1
+import ui_pages.page_evaluation as p3
+import ui_pages.page_explanation as p2
+import ui_pages.page_history as p5
+import ui_pages.page_metrics as p4
+
+
+st.set_page_config(
+    page_title="HalluciScan - Hallucination Detection",
+    page_icon="H",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+st.markdown(
+    """
+<style>
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;700&display=swap');
+
+html, body, [class*="css"] {
+    font-family: 'Space Grotesk', sans-serif;
+}
+
+.stApp {
+    background:
+        radial-gradient(circle at top left, rgba(14, 165, 233, 0.18), transparent 35%),
+        radial-gradient(circle at top right, rgba(16, 185, 129, 0.14), transparent 30%),
+        linear-gradient(135deg, #f8fafc, #edf6ff 45%, #ecfdf5);
+}
+
+section[data-testid="stSidebar"] {
+    background: rgba(255, 255, 255, 0.82) !important;
+    border-right: 1px solid rgba(15, 23, 42, 0.08);
+}
+
+.card {
+    background: rgba(255, 255, 255, 0.9);
+    border: 1px solid rgba(15, 23, 42, 0.08);
+    border-radius: 18px;
+    padding: 1.4rem 1.6rem;
+    margin-bottom: 1rem;
+    backdrop-filter: blur(10px);
+    box-shadow: 0 12px 30px rgba(15, 23, 42, 0.06);
+}
+
+.hero {
+    text-align: center;
+    padding: 1.8rem 0 1rem 0;
+}
+
+.hero h1 {
+    margin-bottom: 0.35rem;
+    font-size: 2.7rem;
+    font-weight: 700;
+    letter-spacing: -0.04em;
+    color: #0f172a;
+}
+
+.hero p {
+    color: rgba(15, 23, 42, 0.68);
+    font-size: 1.02rem;
+}
+
+.badge-reliable,
+.badge-uncertain,
+.badge-hallucination,
+.badge-confident-hall {
+    display: inline-block;
+    padding: 6px 18px;
+    border-radius: 999px;
+    color: #fff;
+    font-weight: 700;
+    font-size: 0.98rem;
+}
+
+.badge-reliable { background: linear-gradient(90deg, #059669, #10b981); }
+.badge-uncertain { background: linear-gradient(90deg, #d97706, #f59e0b); }
+.badge-hallucination { background: linear-gradient(90deg, #dc2626, #ef4444); }
+.badge-confident-hall { background: linear-gradient(90deg, #b91c1c, #ef4444); }
+
+.meter-wrap {
+    background: rgba(15, 23, 42, 0.08);
+    border-radius: 999px;
+    height: 22px;
+    width: 100%;
+    overflow: hidden;
+    margin: 8px 0;
+}
+
+.meter-fill {
+    height: 100%;
+    border-radius: 999px;
+    transition: width 0.6s ease;
+}
+
+.reason-item {
+    padding: 8px 12px;
+    margin: 4px 0;
+    border-left: 3px solid #0284c7;
+    background: rgba(2, 132, 199, 0.08);
+    border-radius: 0 8px 8px 0;
+    color: rgba(15, 23, 42, 0.88);
+    font-size: 0.92rem;
+}
+
+div[data-baseweb="tab-list"] {
+    background: rgba(15, 23, 42, 0.04);
+    border-radius: 12px;
+    padding: 4px;
+    gap: 4px;
+}
+
+div[data-baseweb="tab"] {
+    border-radius: 8px !important;
+    font-weight: 500;
+}
+
+[data-testid="stMetricLabel"] { color: rgba(15, 23, 42, 0.6) !important; }
+[data-testid="stMetricValue"] { color: #111827 !important; }
+
+textarea, input {
+    background: rgba(255, 255, 255, 0.92) !important;
+    color: #111827 !important;
+    border-radius: 10px !important;
+    border: 1px solid rgba(15, 23, 42, 0.1) !important;
+}
+
+.stButton > button {
+    background: linear-gradient(135deg, #0284c7, #0f766e);
+    color: white;
+    border: none;
+    border-radius: 10px;
+    font-weight: 700;
+    padding: 0.6rem 1.2rem;
+    transition: transform 0.15s, box-shadow 0.15s;
+}
+
+.stButton > button:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 10px 24px rgba(2, 132, 199, 0.22);
+}
+
+details summary {
+    color: #0369a1 !important;
+    font-weight: 700;
+}
+
+.footer {
+    text-align: center;
+    color: rgba(15, 23, 42, 0.45);
+    font-size: 0.8rem;
+    padding: 1.5rem 0 0.5rem;
+}
+</style>
+""",
+    unsafe_allow_html=True,
+)
+
+st.sidebar.markdown(
+    """
+<div style='text-align:center; padding: 1rem 0 0.5rem;'>
+    <span style='font-size:2rem'>H</span>
+    <h2 style='color:#0369a1; margin:0; font-size:1.2rem; font-weight:700;'>HalluciScan</h2>
+    <p style='color:rgba(15,23,42,0.5); font-size:0.75rem; margin:0;'>Hallucination Detection System</p>
+</div>
+<hr style='border-color:rgba(15,23,42,0.1); margin: 0.8rem 0;'/>
+""",
+    unsafe_allow_html=True,
+)
+
+PAGE_ICONS = {
+    "Analyzer": p1,
+    "Explanation": p2,
+    "Evaluation": p3,
+    "Detailed Metrics": p4,
+    "History": p5,
+}
+
+page = st.sidebar.radio("Navigate", list(PAGE_ICONS.keys()), label_visibility="collapsed")
+
+st.sidebar.markdown("<hr style='border-color:rgba(15,23,42,0.1);'/>", unsafe_allow_html=True)
+st.sidebar.subheader("Model Settings")
+
+MODEL_LABELS = {
+    "gpt2": "GPT-2 (117M)",
+    "gpt2-medium": "GPT-2 Medium (345M)",
+    "gpt2-large": "GPT-2 Large (774M)",
+    "EleutherAI/gpt-neo-125M": "GPT-Neo 125M",
+    "EleutherAI/gpt-neo-1.3B": "GPT-Neo 1.3B",
+    "EleutherAI/gpt-neo-2.7B": "GPT-Neo 2.7B",
+    "EleutherAI/pythia-2.8b": "Pythia 2.8B",
+    "facebook/opt-6.7b": "OPT 6.7B (High VRAM/RAM)",
+}
+
+model_name = st.sidebar.selectbox(
+    "Model",
+    list(MODEL_LABELS.keys()),
+    format_func=lambda x: MODEL_LABELS[x],
+)
+
+semantic_threshold = st.sidebar.slider("Semantic Match Threshold", 0.50, 1.00, 0.80, 0.05)
+num_responses = st.sidebar.slider("Number of Responses", 1, 10, 5)
+max_length = st.sidebar.slider("Max Generation Length", 10, 100, 50)
+temperature = st.sidebar.slider("Temperature", 0.1, 2.0, 0.8, 0.1)
+
+st.sidebar.subheader("Risk Weights")
+alpha = st.sidebar.slider("Alpha (Internal)", 0.0, 1.0, 0.6, 0.1)
+beta = st.sidebar.slider("Beta (External)", 0.0, 1.0, 0.4, 0.1)
+
+st.sidebar.subheader("Metric Weights")
+w1 = st.sidebar.slider("w1 - EigenScore", 0.0, 1.0, 0.4, 0.1)
+w2 = st.sidebar.slider("w2 - Stability", 0.0, 1.0, 0.3, 0.1)
+w3 = st.sidebar.slider("w3 - Grounding", 0.0, 1.0, 0.3, 0.1)
+
+cfg = dict(
+    model_name=model_name,
+    semantic_threshold=semantic_threshold,
+    num_responses=num_responses,
+    max_length=max_length,
+    temperature=temperature,
+    alpha=alpha,
+    beta=beta,
+    w1=w1,
+    w2=w2,
+    w3=w3,
+)
+
+PAGE_ICONS[page].render(cfg) if page in {"Analyzer", "Evaluation"} else PAGE_ICONS[page].render()
+
+st.markdown(
+    "<div class='footer'>HalluciScan | Powered by GPT-2 | GPT-Neo | TransformerLens | TruthfulQA</div>",
+    unsafe_allow_html=True,
+)

dataset_loader.py

@@ -0,0 +1,85 @@
+"""
+Dataset Loader Module
+Loads and caches the TruthfulQA dataset as well as CoQA, SQuAD, NQ, and TriviaQA 
+from HuggingFace for ground truth comparison.
+"""
+
+from datasets import load_dataset
+from typing import List, Dict
+
+def load_truthfulqa(split: str = "validation"):
+    """
+    Load the TruthfulQA dataset (generation config) from HuggingFace.
+    """
+    dataset = load_dataset("truthful_qa", "generation")
+    return dataset[split]
+
+def get_all_qa_pairs(split: str = "validation") -> List[Dict]:
+    """
+    Load TruthfulQA, SQuAD, NQ Open, Trivia QA, and CoQA.
+    Returns a unified list of dictionaries with 'question', 'best_answer', and 'source'.
+    """
+    pairs = []
+    
+    # 1. TruthfulQA
+    try:
+        tqa = load_truthfulqa(split)
+        for row in tqa:
+            pairs.append({"question": row["question"], "best_answer": row["best_answer"], "source": "TruthfulQA"})
+    except Exception as e:
+        print(f"Error loading TruthfulQA: {e}")
+
+    # 2. SQuAD
+    try:
+        print("Loading SQuAD dataset...")
+        squad = load_dataset("squad", split=split)
+        for row in squad:
+            ans = row["answers"]["text"][0] if row["answers"]["text"] else ""
+            if ans:
+                pairs.append({"question": row["question"], "best_answer": ans, "source": "SQuAD"})
+    except Exception as e:
+        print(f"Error loading SQuAD: {e}")
+
+    # 3. NQ Open
+    try:
+        print("Loading NQ Open dataset...")
+        nq = load_dataset("nq_open", split=split)
+        for row in nq:
+            ans = row["answer"][0] if row["answer"] else ""
+            if ans:
+                pairs.append({"question": row["question"], "best_answer": ans, "source": "NQ"})
+    except Exception as e:
+        print(f"Error loading NQ: {e}")
+
+    # 4. Trivia QA
+    try:
+        print("Loading Trivia QA dataset...")
+        trivia = load_dataset("trivia_qa", "rc.nocontext", split=split)
+        for row in trivia:
+            ans = row["answer"]["value"]
+            if ans:
+                pairs.append({"question": row["question"], "best_answer": ans, "source": "TriviaQA"})
+    except Exception as e:
+        print(f"Error loading TriviaQA: {e}")
+
+    # 5. CoQA
+    try:
+        print("Loading CoQA dataset...")
+        coqa = load_dataset("coqa", split=split)
+        for row in coqa:
+            questions = row["questions"]
+            answers = row["answers"]["input_text"]
+            for q, a in zip(questions, answers):
+                pairs.append({"question": q, "best_answer": a, "source": "CoQA"})
+    except Exception as e:
+        print(f"Error loading CoQA: {e}")
+
+    return pairs
+
+def build_qa_lookup(split: str = "validation") -> dict:
+    """
+    Return a dict mapping each question (lowercased) -> best_answer.
+    Useful for fast exact-lookup.
+    """
+    data = load_truthfulqa(split)
+    return {entry["question"].strip().lower(): entry["best_answer"] for entry in data}

example.py

@@ -0,0 +1,51 @@
+"""
+Example script demonstrating the Hybrid LLM Hallucination Detection System.
+"""
+
+import matplotlib.pyplot as plt
+
+from analyzer import HallucinationAnalyzer
+
+
+def run_example():
+    """Run a simple example analysis."""
+    print("Initializing Hybrid LLM Hallucination Detection System...")
+    print("This may take a moment on first run (downloading models)...\n")
+
+    analyzer = HallucinationAnalyzer(
+        model_name="gpt2",
+        semantic_threshold=0.80,
+    )
+
+    prompt = "What is the capital of France?"
+
+    results = analyzer.analyze(
+        prompt=prompt,
+        num_responses=5,
+        max_length=30,
+        temperature=0.8,
+    )
+
+    analyzer.print_summary(results)
+
+    print("\nDisplaying eigenvalue spectrum...")
+    eigenvalues = results["eigen"].get("eigenvalues", [])
+    if eigenvalues:
+        analyzer.plot_eigenvalue_spectrum(
+            eigenvalues,
+            save_path="example_eigenvalue_spectrum.png",
+        )
+        plt.close("all")
+        print("Eigenvalue spectrum saved to 'example_eigenvalue_spectrum.png'")
+    else:
+        print("No eigenvalues available to plot.")
+
+    print("\n" + "=" * 80)
+    print("Example complete!")
+    print("=" * 80)
+    print("\nTo run the Streamlit UI, use: streamlit run app.py")
+    print('To run custom prompts, use: python main.py --prompt "Your question here"')
+
+
+if __name__ == "__main__":
+    run_example()

external_verifier.py

@@ -0,0 +1,241 @@
+"""
+External Verifier Module
+Uses TruthfulQA, CoQA, SQuAD, NQ, and TriviaQA as ground truth datasets.
+Semantic similarity is used to both find matching questions and score responses.
+"""
+
+import re
+import numpy as np
+from typing import List, Dict, Optional
+
+from sentence_transformers import SentenceTransformer
+from sklearn.metrics.pairwise import cosine_similarity
+
+from dataset_loader import get_all_qa_pairs
+
+
+def _first_sentence(text: str) -> str:
+    """
+    Extract the first complete sentence from *text*.
+
+    GPT-2 tends to generate verbose paragraph-level completions.  When
+    scoring against a short ground-truth answer the cosine similarity is
+    dragged down by the extra off-topic content.  Using only the first
+    sentence (the most on-topic part of the generation) gives a fairer
+    comparison.
+
+    Falls back to the full text if no sentence boundary is found.
+    """
+    text = text.strip()
+    # Split on the first period / exclamation / question mark followed by
+    # whitespace or end-of-string.  Keep trailing punctuation.
+    m = re.search(r'([.!?])(?:\s|$)', text)
+    if m:
+        return text[: m.start() + 1].strip()
+    # No sentence boundary: return up to the first 80 characters so we
+    # still trim extremely long generations.
+    return text[:80].strip()
+
+
+class ExternalVerifier:
+    """
+    Handles external factual verification.
+
+    Ground-truth priority
+    ---------------------
+    1. Exact match across aggregated datasets.
+    2. Semantic match across aggregated datasets.
+    3. Default neutral value (0.5 risk) when no source is found above threshold.
+
+    Question matching uses pre-computed sentence embeddings so it works even
+    when the user's prompt differs slightly from the dataset question.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "all-MiniLM-L6-v2",
+        split: str = "validation",
+        semantic_threshold: float = 0.80,
+    ):
+        """
+        Args:
+            model_name:        Sentence-Transformers model for embedding.
+            split:             Dataset split to load.
+            semantic_threshold: Minimum cosine similarity to accept a dataset
+                               question as a semantic match (0–1).
+        """
+        print(f"Loading sentence transformer model: {model_name}...")
+        self.embedding_model = SentenceTransformer(model_name)
+        self.semantic_threshold = semantic_threshold
+
+        # ── Load aggregated datasets ──────────────────────────────────────────
+        print(f"Loading datasets (split='{split}'). This might take a few moments...")
+        self.qa_pairs = get_all_qa_pairs(split)
+        print(f"Loaded {len(self.qa_pairs)} total QA entries.")
+
+        # Pre-compute question embeddings for fast semantic search
+        print("Pre-computing question embeddings...")
+        questions = [entry["question"] for entry in self.qa_pairs]
+        self._question_embeddings = self.embedding_model.encode(
+            questions, batch_size=64, show_progress_bar=False
+        )
+        print("External verifier ready.\n")
+
+    # ──────────────────────────────────────────────────────────────────────────
+    # Internal helpers
+    # ──────────────────────────────────────────────────────────────────────────
+
+    def _extract_relation_query(self, query: str) -> Optional[str]:
+        """
+        Build a relation-preserving search query for factoid prompts.
+
+        Examples
+        --------
+        "What is the capital of Australia?" -> "capital of Australia"
+        "Who is the president of France?"   -> "president of France"
+        """
+        q = query.strip().rstrip("?")
+
+        patterns = [
+            r"(?i)^what\s+is\s+the\s+(.+?)\s+of\s+(.+)$",
+            r"(?i)^who\s+is\s+the\s+(.+?)\s+of\s+(.+)$",
+            r"(?i)^what\s+was\s+the\s+(.+?)\s+of\s+(.+)$",
+            r"(?i)^who\s+was\s+the\s+(.+?)\s+of\s+(.+)$",
+        ]
+
+        for pattern in patterns:
+            match = re.match(pattern, q)
+            if match:
+                relation = match.group(1).strip()
+                entity = match.group(2).strip()
+                return f"{relation} of {entity}"
+
+        return None
+
+    # ──────────────────────────────────────────────────────────────────────────
+    # Public API
+    # ──────────────────────────────────────────────────────────────────────────
+
+    def find_ground_truth(self, question: str) -> Optional[Dict[str, str]]:
+        """
+        Find the ground-truth for *question*.
+
+        Priority: Exact match -> Semantic match -> None.
+
+        Returns:
+            Dict with keys ``text`` (ground truth string) and ``source``
+            (dataset name), or ``None``.
+        """
+        q_lower = question.strip().lower()
+
+        # ── 1. Exact match ─────────────────────────────────────────
+        for i, entry in enumerate(self.qa_pairs):
+            if entry["question"].strip().lower() == q_lower:
+                source = entry["source"]
+                print(f"  [ExternalVerifier] Exact {source} match (entry #{i}).")
+                return {"text": entry["best_answer"], "source": source}
+
+        # ── 2. Semantic match ──────────────────────────────────────
+        query_emb = self.embedding_model.encode([question])
+        sims = cosine_similarity(query_emb, self._question_embeddings)[0]
+        best_idx = int(np.argmax(sims))
+        best_sim = float(sims[best_idx])
+        best_entry = self.qa_pairs[best_idx]
+
+        print(
+            f"  [ExternalVerifier] Best {best_entry['source']} match: "
+            f"'{best_entry['question'][:80]}' "
+            f"(sim={best_sim:.4f})"
+        )
+
+        if best_sim >= self.semantic_threshold:
+            return {"text": best_entry["best_answer"], "source": best_entry["source"]}
+
+        print(
+            f"  [ExternalVerifier] Similarity {best_sim:.4f} < threshold "
+            f"{self.semantic_threshold:.2f} -> No reliable match found."
+        )
+
+        return None
+
+    def compute_similarity(self, text1: str, text2: str) -> float:
+        """Cosine similarity between two texts via sentence embeddings."""
+        embeddings = self.embedding_model.encode([text1, text2])
+        sim = cosine_similarity([embeddings[0]], [embeddings[1]])[0][0]
+        return float(sim)
+
+    def verify_responses(
+        self,
+        responses: List[str],
+        ground_truth: str,
+    ) -> Dict[str, object]:
+        """
+        Score each generated response against the ground-truth answer.
+
+        For each response we compute:
+          - full-response similarity  (captures overall topic alignment)
+          - first-sentence similarity (captures the most on-topic part;
+            important for GPT-2 which appends verbose off-topic content)
+        The reported similarity is the *maximum* of the two, so a response
+        is not penalised for being more detailed than the ground truth.
+
+        Returns:
+            {
+                "similarities":          List[float],
+                "external_consistency":  float,   # mean similarity
+                "external_risk":         float,   # 1 - consistency
+                "ground_truth":          str,
+            }
+        """
+        similarities = []
+        for i, response in enumerate(responses):
+            sim_full = self.compute_similarity(response, ground_truth)
+            first_sent = _first_sentence(response)
+            sim_first = self.compute_similarity(first_sent, ground_truth)
+            # Take the best of the two views
+            sim = max(sim_full, sim_first)
+            similarities.append(sim)
+            print(
+                f"  Response {i + 1} similarity to ground truth: "
+                f"{sim:.4f}  (full={sim_full:.4f}, 1st-sent={sim_first:.4f})"
+            )
+
+        external_consistency = float(np.mean(similarities))
+        external_risk = 1.0 - external_consistency
+
+        return {
+            "similarities": similarities,
+            "external_consistency": external_consistency,
+            "external_risk": external_risk,
+            "ground_truth": ground_truth,
+        }
+
+    def compute_external_metrics(
+        self,
+        prompt: str,
+        responses: List[str],
+    ) -> Optional[Dict[str, object]]:
+        """
+        Full external verification pipeline for a single prompt.
+
+        Returns:
+            Metrics dict (see ``verify_responses``) augmented with
+            ``ground_truth_source`` key, or ``None`` if no ground truth found.
+        """
+        result = self.find_ground_truth(prompt)
+
+        if result is None:
+            print(
+                f"  Warning: No ground truth found "
+                f"for: '{prompt[:80]}'"
+            )
+            return None
+
+        ground_truth = result["text"]
+        source = result["source"]
+        print(f"  Ground truth ({source}): {str(ground_truth)[:120]}...")
+
+        metrics = self.verify_responses(responses, ground_truth)
+        metrics["ground_truth_source"] = source
+        return metrics
+

gllm2.txt

@@ -0,0 +1,159 @@
+🔍 What Is Grounding Score?
+
+Grounding score measures:
+
+🧠 How well the generated response stays anchored to the original prompt.
+
+In simple words:
+
+High grounding → response is clearly related to the question
+
+Low grounding → response drifts, fabricates, or goes off-topic
+
+
+
+
+🔥 What Is Entropy?
+
+Entropy measures:
+
+📊 How uncertain the model is when choosing the next token.
+
+In simple words:
+
+Low entropy → model is confident
+
+High entropy → model is confused
+
+📈 In Your System
+
+Your analyzer computes entropy for:
+
+Each generated token
+
+Then builds an entropy curve
+
+
+🔬 How Grounding Is Usually Computed
+
+In your type of system, grounding is often computed using:
+
+Cosine similarity between:
+
+Embedding of prompt
+
+Embedding of response
+
+So internally:
+
+grounding_score = cosine(embedding(prompt), embedding(response))
+
+
+
+🔍 What is Semantic Match Threshold?
+
+In your UI you have:
+
+semantic_threshold = st.sidebar.slider(
+    "Semantic Match Threshold",
+    min_value=0.50,
+    max_value=1.00,
+    value=0.80,
+)
+
+This controls:
+
+🔎 How similar your user’s prompt must be to a TruthfulQA question
+before you consider it a "match" and use its ground truth.
+
+🧠 Why Do You Need This?
+
+TruthfulQA contains fixed questions like:
+
+"What happens if you swallow gum?"
+
+"What is the capital of France?"
+
+But your user might type:
+
+"If someone eats chewing gum, what occurs?"
+
+"France capital city?"
+
+These are semantically the same but textually different.
+
+So instead of exact string matching, your system uses:
+
+➜ Cosine similarity between embeddings
+📊 How It Works Internally
+
+Convert user prompt into embedding vector
+
+Convert all TruthfulQA questions into embeddings
+
+Compute cosine similarity:
+
+similarity = cosine(user_prompt, dataset_question)
+
+
+If:
+
+similarity >= semantic_threshold
+
+Then:
+
+System considers that TruthfulQA question a match
+
+Uses its correct answer as ground truth
+
+If not:
+
+Returns "N/A"
+
+External verification skipped
+
+
+
+
+
+
+
+🧠 What Is Stability?
+
+Stability measures:
+
+🔍 How consistent the model’s internal representations are across layers while generating a response.
+
+In simple terms:
+
+Stable model → layers agree with each other
+
+Unstable model → internal representations fluctuate a lot
+
+Instability often happens during hallucination.
+
+
+🧠 What Are Logits?
+
+Logits are:
+
+🔢 The raw output scores from the model before converting them into probabilities.
+
+They are not probabilities yet.
+
+They are just numbers.
+
+🔥 Where Do Logits Come From?
+
+When GPT-2 processes text, the final layer produces:
+
+vocabulary_size numbers
+
+For GPT-2:
+
+Vocabulary ≈ 50,257 tokens
+
+So for every next token prediction:
+→ model outputs 50,257 numbers
+
+These numbers = logits.

install.bat

@@ -0,0 +1,39 @@
+@echo off
+REM Installation script for Anaconda users
+REM Run this from Anaconda Prompt
+
+echo ========================================
+echo Hybrid LLM Hallucination Detection System
+echo Installation Script
+echo ========================================
+echo.
+
+echo Step 1: Installing PyTorch (CPU version)...
+call conda install pytorch torchvision torchaudio cpuonly -c pytorch -y
+if %errorlevel% neq 0 (
+    echo ERROR: Failed to install PyTorch
+    echo Please run this script from Anaconda Prompt
+    pause
+    exit /b 1
+)
+
+echo.
+echo Step 2: Installing other dependencies...
+call pip install transformer-lens transformers sentence-transformers streamlit plotly scikit-learn matplotlib numpy
+if %errorlevel% neq 0 (
+    echo ERROR: Failed to install dependencies
+    pause
+    exit /b 1
+)
+
+echo.
+echo ========================================
+echo Installation Complete!
+echo ========================================
+echo.
+echo To run the system:
+echo   1. Streamlit UI:  streamlit run app.py
+echo   2. Example:       python example.py
+echo   3. CLI:           python main.py --prompt "Your question"
+echo.
+pause

internal_metrics.py

@@ -0,0 +1,500 @@
+"""
+Internal Metrics Module
+Computes eigen score, stability, and attention grounding metrics
+for hallucination detection.
+
+Eigen Score follows the INSIDE paper (ICLR 2024): it measures semantic
+consistency across multiple sampled responses by analysing the eigenvalue
+spectrum of the covariance matrix built from per-response sentence embeddings
+extracted at the middle Transformer layer.  A low (more negative) eigen score
+signals high semantic consistency (low hallucination risk); a high (less
+negative) score signals high dispersion (uncertain / likely hallucinated).
+
+Feature Clipping follows the INSIDE paper exactly:
+  - A memory bank M of shape (N, hidden_dim) accumulates token-level hidden
+    activations across forward passes.
+  - Per-dimension thresholds are derived from the memory bank:
+        h_min[j] = percentile(M[:, j], 0.2)
+        h_max[j] = percentile(M[:, j], 99.8)
+  - Every hidden-state tensor is clipped element-wise per feature dimension j
+    *before* the sentence embedding is extracted.
+"""
+#hiiiiis
+import torch
+import torch.nn.functional as F
+import numpy as np
+from typing import Dict, Any, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Memory Bank
+# ---------------------------------------------------------------------------
+
+class MemoryBank:
+    """
+    Accumulates token-level hidden-state vectors and provides
+    distribution-aware, per-dimension feature clipping as described in the
+    INSIDE paper (ICLR 2024).
+
+    Usage
+    -----
+    1. Call ``update(hidden)`` after every forward pass to feed new
+       activations into the bank.
+    2. Call ``clip(hidden)`` to apply the derived thresholds to any
+       hidden-state tensor before downstream computation.
+
+    Attributes
+    ----------
+    max_size : int
+        Maximum number of activation vectors retained (FIFO when full).
+    hidden_dim : int or None
+        Dimensionality of the stored vectors (inferred on first update).
+    h_min, h_max : torch.Tensor or None
+        Per-dimension clipping thresholds. None until the bank has been
+        populated and ``compute_thresholds()`` has been called.
+    """
+
+    def __init__(self, max_size: int = 2000, lo: float = 0.2, hi: float = 99.8):
+        """
+        Args:
+            max_size: Maximum stored activation samples N.
+            lo:       Lower percentile for h_min  (paper: 0.2).
+            hi:       Upper percentile for h_max  (paper: 99.8).
+        """
+        self.max_size = max_size
+        self.lo = lo
+        self.hi = hi
+
+        self._bank: List[torch.Tensor] = []   # list of 1-D float32 CPU tensors
+        self.hidden_dim: Optional[int] = None
+        self.h_min: Optional[torch.Tensor] = None
+        self.h_max: Optional[torch.Tensor] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def update(self, hidden: torch.Tensor) -> None:
+        """
+        Add token-level activation vectors from a hidden-state tensor to
+        the memory bank.
+
+        Args:
+            hidden: Tensor of shape (seq_len, hidden_dim) **or**
+                    (batch, seq_len, hidden_dim).  All token vectors are
+                    flattened to individual rows and appended to the bank.
+        """
+        h = hidden.detach().float().cpu()
+
+        if h.dim() == 3:           # (batch, seq_len, hidden_dim)
+            h = h.reshape(-1, h.size(-1))
+        elif h.dim() == 2:         # (seq_len, hidden_dim) — already flat
+            pass
+        else:
+            raise ValueError(f"Expected 2-D or 3-D hidden tensor, got shape {tuple(h.shape)}")
+
+        if self.hidden_dim is None:
+            self.hidden_dim = h.size(-1)
+
+        # Append individual row vectors
+        for vec in h:
+            self._bank.append(vec)
+
+        # Enforce FIFO capacity
+        if len(self._bank) > self.max_size:
+            self._bank = self._bank[-self.max_size:]
+
+        # Invalidate cached thresholds — they need recomputing
+        self.h_min = None
+        self.h_max = None
+
+    def compute_thresholds(self) -> Tuple[torch.Tensor, torch.Tensor]:
+        """
+        Compute per-dimension clipping thresholds from the current bank.
+
+        Returns:
+            (h_min, h_max) — 1-D tensors of shape (hidden_dim,).
+
+        Raises:
+            RuntimeError: If the bank is empty.
+        """
+        if len(self._bank) == 0:
+            raise RuntimeError(
+                "MemoryBank is empty. Call update() with hidden activations first."
+            )
+
+        # Stack to (N, hidden_dim) — stays on CPU for numpy percentile
+        M = torch.stack(self._bank).numpy()          # (N, hidden_dim)
+
+        # Per-dimension percentiles (axis=0 → operate along the N dimension)
+        h_min_np = np.percentile(M, self.lo, axis=0)   # (hidden_dim,)
+        h_max_np = np.percentile(M, self.hi, axis=0)   # (hidden_dim,)
+
+        self.h_min = torch.from_numpy(h_min_np.astype(np.float32))
+        self.h_max = torch.from_numpy(h_max_np.astype(np.float32))
+        return self.h_min, self.h_max
+
+    def clip(self, hidden: torch.Tensor) -> torch.Tensor:
+        """
+        Apply distribution-aware, per-dimension feature clipping to *hidden*.
+
+        The thresholds are (re)computed from the current memory bank the
+        first time this is called, or whenever the bank has been updated
+        since the last call.
+
+        Args:
+            hidden: Tensor of shape (seq_len, hidden_dim) **or**
+                    (batch, seq_len, hidden_dim).
+
+        Returns:
+            Clipped tensor with the same shape and device as *hidden*.
+        """
+        if len(self._bank) == 0:
+            # Nothing in the bank yet — skip clipping silently
+            return hidden
+
+        if self.h_min is None or self.h_max is None:
+            self.compute_thresholds()
+
+        # Move thresholds to the same device as the incoming tensor
+        h_min = self.h_min.to(hidden.device)   # (hidden_dim,)
+        h_max = self.h_max.to(hidden.device)   # (hidden_dim,)
+
+        # torch.clamp with per-element min/max tensors — works on any shape
+        # because h_min/h_max broadcast over all leading dimensions.
+        return torch.clamp(hidden, min=h_min, max=h_max)
+
+    # ------------------------------------------------------------------
+    # Introspection helpers
+    # ------------------------------------------------------------------
+
+    def __len__(self) -> int:
+        return len(self._bank)
+
+    def __repr__(self) -> str:
+        return (
+            f"MemoryBank(size={len(self._bank)}/{self.max_size}, "
+            f"hidden_dim={self.hidden_dim}, "
+            f"percentiles=[{self.lo}, {self.hi}])"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Internal Metrics
+# ---------------------------------------------------------------------------
+
+class InternalMetrics:
+    """
+    Computes internal hallucination metrics from model activations.
+    """
+
+    def __init__(self, model, memory_bank_size: int = 2000):
+        """
+        Initialize with a TransformerLens model.
+
+        Args:
+            model:            HookedTransformer model instance.
+            memory_bank_size: Capacity of the feature-clipping memory bank.
+        """
+        self.model = model
+        self.n_layers = model.cfg.n_layers
+        self.n_heads = model.cfg.n_heads
+
+        # One memory bank per InternalMetrics instance, shared across calls.
+        # Tracks hidden states at the middle layer (consistent with EigenScore).
+        self.memory_bank = MemoryBank(max_size=memory_bank_size, lo=0.2, hi=99.8)
+
+    # ------------------------------------------------------------------
+    # EigenScore (INSIDE, ICLR 2024) with feature clipping
+    # ------------------------------------------------------------------
+
+    def compute_eigen_score(
+        self,
+        responses: List[str],
+        alpha: float = 0.001,
+    ) -> Dict[str, Any]:
+        """
+        Compute EigenScore as defined in the INSIDE paper with per-dimension
+        feature clipping applied to middle-layer hidden states.
+
+        Pipeline
+        --------
+        For each of the K sampled responses:
+          1. Run forward pass, extract middle-layer residual stream:
+                 H_i  ∈  R^(seq_len × d_model)
+          2. Feed H_i into the memory bank (updates statistics).
+          3. Apply distribution-aware, per-dimension feature clipping:
+                 H_i_clipped = clip(H_i, h_min, h_max)
+             where h_min[j] = percentile(M[:,j], 0.2)
+                   h_max[j] = percentile(M[:,j], 99.8)
+             and M is built from all activations accumulated so far.
+          4. Extract sentence embedding from last token of clipped states:
+                 z_i = H_i_clipped[-1, :]   ∈  R^d
+
+        Build embedding matrix:
+             Z = stack([z_1, …, z_K])                       shape: (K, d)
+        Centre and form the (K×K) covariance:
+             Z_centred = Z - Z.mean(dim=0)
+             Σ = Z_centred @ Z_centred.T + α·I              shape: (K, K)
+        Eigendecompose Σ (symmetric → eigvalsh):
+             λ_1 … λ_K  (clamped to ≥ 1e-12)
+        EigenScore = (1/K) · Σ_i log(λ_i)
+
+        Interpretation
+        --------------
+        Lower (more negative) → tightly clustered embeddings → low hallucination.
+        Higher (less negative / positive) → dispersed embeddings → likely hallucinated.
+
+        Args:
+            responses: List of K response strings.
+            alpha:     Tikhonov regularisation coefficient (default 0.001).
+
+        Returns:
+            Dictionary with:
+                eigen_score       – (1/K) · Σ log(λ_i)
+                eigenvalues       – list of eigenvalues in ascending order
+                num_responses     – K
+                clipping_applied  – True if the memory bank had enough data
+                h_min             – per-dimension lower thresholds (list, for debug)
+                h_max             – per-dimension upper thresholds (list, for debug)
+        """
+        K = len(responses)
+        if K == 0:
+            return {
+                "eigen_score": 0.0,
+                "eigenvalues": [],
+                "num_responses": 0,
+                "clipping_applied": False,
+                "h_min": [],
+                "h_max": [],
+            }
+
+        mid_layer = self.n_layers // 2
+        resid_key = f"blocks.{mid_layer}.hook_resid_post"
+
+        # ------------------------------------------------------------------
+        # PASS 1: collect all middle-layer hidden states into the memory bank
+        # ------------------------------------------------------------------
+        raw_hiddens: List[torch.Tensor] = []   # (seq_len, d_model) per response
+
+        for response in responses:
+            tokens = self.model.to_tokens(response)          # [1, seq_len]
+            with torch.no_grad():
+                _, cache = self.model.run_with_cache(tokens)
+
+            # hidden: (seq_len, d_model), float32
+            hidden = cache[resid_key][0].float()
+            raw_hiddens.append(hidden)
+
+            # Feed into memory bank to build distribution statistics
+            self.memory_bank.update(hidden)
+
+        clipping_applied = len(self.memory_bank) > 0
+
+        # Retrieve the thresholds computed from ALL K responses (and any
+        # activations accumulated from previous calls).
+        if clipping_applied:
+            h_min, h_max = self.memory_bank.compute_thresholds()
+        else:
+            h_min = h_max = None
+
+        # ------------------------------------------------------------------
+        # PASS 2: clip each hidden state, extract sentence embedding
+        # ------------------------------------------------------------------
+        embeddings: List[torch.Tensor] = []
+
+        for hidden in raw_hiddens:
+            # Apply INSIDE-paper feature clipping (per-dimension, from bank)
+            hidden_clipped = self.memory_bank.clip(hidden)        # (seq_len, d_model)
+
+            # Last-token embedding (INSIDE paper §3.2)
+            z_i = hidden_clipped[-1, :]                           # (d_model,)
+
+            # L2-normalise onto the unit sphere so that eigenvalues measure
+            # *angular* (directional) dispersion rather than magnitude.
+            # Without this, GPT-2 hidden norms (~35-50) inflate eigenvalues
+            # by ~1000×, pushing the eigen score to large positive numbers.
+            z_i = F.normalize(z_i, p=2, dim=0)                   # unit vector
+            embeddings.append(z_i)
+
+        # ------------------------------------------------------------------
+        # EigenScore computation
+        # ------------------------------------------------------------------
+        Z = torch.stack(embeddings)                               # (K, d_model)
+
+        Z_mean = Z.mean(dim=0)
+        Z_centered = Z - Z_mean                                   # (K, d_model)
+
+        # (K × K) covariance with Tikhonov regularisation
+        # With unit-norm embeddings, Sigma entries are bounded in [-1, 1]
+        # and eigenvalues lie in [0, K], giving log(λ) a sensible range.
+        Sigma = Z_centered @ Z_centered.T                         # (K, K)
+        Sigma = Sigma + alpha * torch.eye(K, device=Sigma.device, dtype=Sigma.dtype)
+
+        # Eigenvalues (symmetric → eigvalsh gives real, ascending values)
+        try:
+            eigenvalues = torch.linalg.eigvalsh(Sigma)
+        except Exception:
+            eigenvalues = torch.abs(torch.linalg.eigvals(Sigma).real)
+
+        eigenvalues = torch.clamp(eigenvalues, min=1e-12)
+
+        # EigenScore: (1/K) * sum(log(λ_i))
+        eigen_score = float((torch.sum(torch.log(eigenvalues)) / K).cpu())
+
+        return {
+            "eigen_score": eigen_score,
+            "eigenvalues": eigenvalues.cpu().tolist(),
+            "num_responses": K,
+            "clipping_applied": clipping_applied,
+            "h_min": h_min.tolist() if h_min is not None else [],
+            "h_max": h_max.tolist() if h_max is not None else [],
+        }
+
+    # ------------------------------------------------------------------
+    # Stability
+    # ------------------------------------------------------------------
+
+    def compute_stability(self, cache: Dict, prompt_length: int) -> Dict[str, float]:
+        """
+        Compute stability metric based on hidden state similarity across layers.
+
+        Args:
+            cache:         Model activation cache.
+            prompt_length: Length of the prompt in tokens.
+
+        Returns:
+            Dictionary with stability score.
+        """
+        layer_activations = []
+
+        for layer_idx in range(self.n_layers):
+            resid_key = f"blocks.{layer_idx}.hook_resid_post"
+            if resid_key in cache:
+                activation = cache[resid_key]             # [batch, seq_len, d_model]
+                layer_activations.append(activation[0])   # first batch item
+
+        if len(layer_activations) < 2:
+            return {"stability_score": 1.0}
+
+        similarities = []
+
+        for i in range(len(layer_activations) - 1):
+            curr_layer = layer_activations[i]             # [seq_len, d_model]
+            next_layer = layer_activations[i + 1]
+
+            curr_norm = F.normalize(curr_layer, p=2, dim=-1)
+            next_norm = F.normalize(next_layer, p=2, dim=-1)
+
+            token_similarities = torch.sum(curr_norm * next_norm, dim=-1)  # [seq_len]
+            similarities.append(token_similarities)
+
+        all_similarities = torch.stack(similarities)      # [n_layers-1, seq_len]
+        stability_score = float(torch.mean(all_similarities).cpu().numpy())
+
+        return {
+            "stability_score": stability_score,
+            "layer_similarities": [float(torch.mean(s).cpu().numpy()) for s in similarities],
+        }
+
+    # ------------------------------------------------------------------
+    # Attention Grounding
+    # ------------------------------------------------------------------
+
+    def compute_attention_grounding(
+        self,
+        cache: Dict,
+        prompt_length: int,
+        total_length: int,
+    ) -> Dict[str, float]:
+        """
+        Compute attention grounding — how much attention generated tokens pay
+        to prompt tokens.
+
+        Args:
+            cache:         Model activation cache.
+            prompt_length: Length of the prompt in tokens.
+            total_length:  Total sequence length.
+
+        Returns:
+            Dictionary with grounding score.
+        """
+        grounding_scores = []
+
+        for layer_idx in range(self.n_layers):
+            attn_key = f"blocks.{layer_idx}.attn.hook_pattern"
+
+            if attn_key in cache:
+                attn_pattern = cache[attn_key]       # [batch, n_heads, seq_len, seq_len]
+                attn_pattern = attn_pattern[0]       # [n_heads, seq_len, seq_len]
+
+                if total_length > prompt_length:
+                    gen_attn = attn_pattern[:, prompt_length:, :]        # [n_heads, gen_len, seq_len]
+                    attn_to_prompt = torch.sum(gen_attn[:, :, :prompt_length], dim=-1)
+                    total_attn = torch.sum(gen_attn, dim=-1)
+
+                    grounding_ratio = attn_to_prompt / (total_attn + 1e-10)
+                    layer_grounding = float(torch.mean(grounding_ratio).cpu().numpy())
+                    grounding_scores.append(layer_grounding)
+
+        if len(grounding_scores) == 0:
+            return {"grounding_score": 1.0}
+
+        grounding_score = float(np.mean(grounding_scores))
+
+        return {
+            "grounding_score": grounding_score,
+            "layer_grounding": grounding_scores,
+        }
+
+    # ------------------------------------------------------------------
+    # Internal Risk
+    # ------------------------------------------------------------------
+
+    def compute_internal_risk(
+        self,
+        eigen_metrics: Dict,
+        stability_metrics: Dict,
+        grounding_metrics: Dict,
+        w1: float = 0.4,
+        w2: float = 0.3,
+        w3: float = 0.3,
+    ) -> Dict[str, float]:
+        """
+        Compute internal hallucination risk score.
+
+        Args:
+            eigen_metrics:    Output from compute_eigen_score.
+            stability_metrics: Output from compute_stability.
+            grounding_metrics: Output from compute_attention_grounding.
+            w1, w2, w3:       Weights for eigen score, stability, grounding.
+
+        Returns:
+            Dictionary with internal risk score and components.
+        """
+        import math
+
+        raw = eigen_metrics["eigen_score"]
+        # Map raw eigen score to [0, 1] risk.
+        # With L2-normalised embeddings the raw score typically falls in
+        # [-2, +2].  A simple sigmoid centred at 0 with scale=1 works well:
+        #   score << 0  → tight cluster   → low risk  (→ 0)
+        #   score ~  0  → moderate spread → mid risk  (→ 0.5)
+        #   score >> 0  → high dispersion → high risk (→ 1)
+        normalized_eigen = float(1.0 / (1.0 + math.exp(-raw)))
+
+        stability = stability_metrics["stability_score"]
+        grounding = grounding_metrics["grounding_score"]
+
+        internal_risk = (
+            w1 * normalized_eigen +
+            w2 * (1 - stability) +
+            w3 * (1 - grounding)
+        )
+
+        return {
+            "internal_risk": internal_risk,
+            "eigen_score_component": w1 * normalized_eigen,
+            "stability_component": w2 * (1 - stability),
+            "grounding_component": w3 * (1 - grounding),
+        }

main.py

@@ -0,0 +1,115 @@
+"""
+Main Module.
+Command-line interface for the Hybrid LLM Hallucination Detection System.
+"""
+
+import argparse
+
+from datasets import load_dataset
+
+from analyzer import HallucinationAnalyzer
+
+
+def main():
+    """Main entry point for the hallucination detection system."""
+    parser = argparse.ArgumentParser(
+        description="Hybrid LLM Hallucination Detection System"
+    )
+
+    parser.add_argument(
+        "--prompt",
+        type=str,
+        default=None,
+        help="Optional single prompt to analyze (if not using full dataset)",
+    )
+    parser.add_argument(
+        "--use-dataset",
+        action="store_true",
+        help="Run evaluation on the TruthfulQA validation set",
+    )
+    parser.add_argument(
+        "--num-responses",
+        type=int,
+        default=5,
+        help="Number of responses to generate (default: 5)",
+    )
+    parser.add_argument(
+        "--max-length",
+        type=int,
+        default=50,
+        help="Maximum generation length (default: 50)",
+    )
+    parser.add_argument(
+        "--temperature",
+        type=float,
+        default=0.8,
+        help="Sampling temperature (default: 0.8)",
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="gpt2",
+        help="GPT-2 model variant (default: gpt2)",
+    )
+    parser.add_argument(
+        "--alpha",
+        type=float,
+        default=0.6,
+        help="Weight for internal risk in final score (default: 0.6)",
+    )
+    parser.add_argument(
+        "--beta",
+        type=float,
+        default=0.4,
+        help="Weight for external risk in final score (default: 0.4)",
+    )
+    parser.add_argument(
+        "--semantic-threshold",
+        type=float,
+        default=0.80,
+        help="Min cosine similarity to match a TruthfulQA question (default: 0.80)",
+    )
+
+    args = parser.parse_args()
+
+    analyzer = HallucinationAnalyzer(
+        model_name=args.model,
+        semantic_threshold=args.semantic_threshold,
+    )
+
+    if args.use_dataset:
+        dataset = load_dataset("truthful_qa", "generation")
+        data = dataset["validation"]
+
+        for example in data:
+            question = example["question"]
+
+            print("\n" + "=" * 30)
+            print(f"Question: {question}")
+            print("=" * 30)
+
+            results = analyzer.analyze(
+                prompt=question,
+                num_responses=args.num_responses,
+                max_length=args.max_length,
+                temperature=args.temperature,
+                alpha=args.alpha,
+                beta=args.beta,
+            )
+            analyzer.print_summary(results)
+    elif args.prompt:
+        results = analyzer.analyze(
+            prompt=args.prompt,
+            num_responses=args.num_responses,
+            max_length=args.max_length,
+            temperature=args.temperature,
+            alpha=args.alpha,
+            beta=args.beta,
+        )
+        analyzer.print_summary(results)
+    else:
+        print("Provide --prompt or --use-dataset")
+
+
+if __name__ == "__main__":
+    main()

model_loader.py

@@ -0,0 +1,136 @@
+"""
+Model Loader Module.
+Loads supported TransformerLens causal language models and provides text generation functionality.
+"""
+
+import torch
+from transformer_lens import HookedTransformer
+from typing import List, Dict, Any
+import numpy as np
+
+
+class GPT2ModelLoader:
+    """
+    Handles loading and text generation with supported TransformerLens models.
+    Supports: gpt2, gpt2-medium, gpt2-large, gpt2-xl,
+              EleutherAI/gpt-neo-125M, EleutherAI/gpt-neo-1.3B, EleutherAI/gpt-neo-2.7B,
+              EleutherAI/pythia-2.8b, facebook/opt-6.7b
+    """
+    
+    def __init__(self, model_name: str = "gpt2"):
+        """
+        Initialize the model.
+        
+        Args:
+            model_name: Name of the supported model variant to load
+        """
+        print(f"Loading {model_name} model...")
+        self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        self.model = HookedTransformer.from_pretrained(model_name, device=self.device)
+        self.model_name = model_name
+        print(f"Model loaded successfully on {self.device}")
+    
+    def generate_responses(
+        self, 
+        prompt: str, 
+        num_responses: int = 5,
+        max_length: int = 50,
+        temperature: float = 0.8,
+        top_p: float = 0.9
+    ) -> List[str]:
+        """
+        Generate multiple stochastic responses for a given prompt.
+        
+        Args:
+            prompt: Input text prompt
+            num_responses: Number of responses to generate
+            max_length: Maximum length of generated text
+            temperature: Sampling temperature for diversity
+            top_p: Nucleus sampling parameter
+            
+        Returns:
+            List of generated text responses
+        """
+        responses = []
+        
+        # Compute prompt token length once
+        prompt_tokens = self.model.to_tokens(prompt)
+        prompt_token_len = prompt_tokens.shape[1]
+        
+        for i in range(num_responses):
+            # Generate text
+            generated_tokens = self.model.generate(
+                prompt_tokens,
+                max_new_tokens=max_length,
+                temperature=temperature,
+                top_p=top_p,
+                do_sample=True,
+                stop_at_eos=True
+            )
+            
+            # Decode ONLY the newly generated tokens (not the prompt)
+            new_tokens = generated_tokens[0][prompt_token_len:]
+            generated_text = self.model.to_string(new_tokens).lstrip()
+            responses.append(generated_text)
+            
+            print(f"Generated response {i+1}/{num_responses}")
+        
+        return responses
+    
+    def generate_with_cache(
+        self,
+        prompt: str,
+        max_length: int = 50,
+        temperature: float = 0.8,
+        top_p: float = 0.9
+    ) -> Dict[str, Any]:
+        """
+        Generate text and return both the text and model activations.
+        
+        Args:
+            prompt: Input text prompt
+            max_length: Maximum length of generated text
+            temperature: Sampling temperature
+            top_p: Nucleus sampling parameter
+            
+        Returns:
+            Dictionary containing generated text, tokens, logits, and cache
+        """
+        # Tokenize the prompt
+        tokens = self.model.to_tokens(prompt)
+        prompt_length = tokens.shape[1]
+        
+        # Generate with caching enabled
+        with torch.no_grad():
+            generated_tokens = self.model.generate(
+                tokens,
+                max_new_tokens=max_length,
+                temperature=temperature,
+                top_p=top_p,
+                do_sample=True,
+                stop_at_eos=True,
+                return_type="tokens"
+            )
+        
+        # Get full sequence
+        full_tokens = generated_tokens[0]
+        
+        # Run forward pass to get activations
+        with torch.no_grad():
+            logits, cache = self.model.run_with_cache(full_tokens)
+        
+        # Decode ONLY the newly generated tokens (not the echoed prompt)
+        new_tokens = full_tokens[prompt_length:]
+        generated_text = self.model.to_string(new_tokens).lstrip()
+        
+        return {
+            "text": generated_text,
+            "tokens": full_tokens,
+            "logits": logits,
+            "cache": cache,
+            "prompt_length": prompt_length
+        }
+    
+    def get_model(self) -> HookedTransformer:
+        """Return the underlying model."""
+        return self.model

ollama_loader.py

@@ -0,0 +1,207 @@
+"""
+Ollama Model Loader
+Handles text generation via the local Ollama API (e.g., llama3).
+Because Ollama models don't expose internal logits/activations,
+internal metrics are approximated from response-level statistics.
+"""
+
+import requests
+import json
+import numpy as np
+from typing import List, Dict, Any
+
+
+OLLAMA_BASE_URL = "http://localhost:11434"
+
+
+def _check_ollama_running() -> bool:
+    """Return True if the Ollama server is reachable."""
+    try:
+        r = requests.get(f"{OLLAMA_BASE_URL}/", timeout=3)
+        return r.status_code == 200
+    except Exception:
+        return False
+
+
+def _resolve_model_name(requested: str) -> str:
+    """
+    Look up the exact tag Ollama knows for the requested model.
+    Returns the resolved tag (e.g. 'llama3:latest') or the original
+    string if nothing matches (Ollama may still handle it).
+    """
+    try:
+        r = requests.get(f"{OLLAMA_BASE_URL}/api/tags", timeout=5)
+        if r.status_code != 200:
+            return requested
+        models = r.json().get("models", [])
+        tags = [m["name"] for m in models]
+
+        # Exact match first
+        if requested in tags:
+            return requested
+
+        # Prefix match: 'llama3' matches 'llama3:latest', 'llama3:8b', etc.
+        base = requested.split(":")[0]
+        matches = [t for t in tags if t == requested or t.startswith(base + ":")]
+        if matches:
+            return matches[0]  # prefer first match (usually :latest)
+
+        return requested  # let Ollama decide / fail with a clear message
+    except Exception:
+        return requested
+
+
+class OllamaModelLoader:
+    """
+    Loads text generation capability from a locally running Ollama model.
+    Internal metrics (entropy, stability, grounding) are approximated because
+    Ollama does not expose raw logits or attention weights via its public API.
+    """
+
+    def __init__(self, model_name: str = "llama3"):
+        if not _check_ollama_running():
+            raise RuntimeError(
+                "Ollama server is not running. "
+                "Please start it with: `ollama serve`"
+            )
+        # Resolve to the exact tag Ollama knows (e.g. 'llama3' → 'llama3:latest')
+        self.model_name = _resolve_model_name(model_name)
+        self.api_url = f"{OLLAMA_BASE_URL}/api/generate"
+        print(f"Ollama model resolved to '{self.model_name}' at {OLLAMA_BASE_URL}")
+
+    # ------------------------------------------------------------------
+    # Core generation
+    # ------------------------------------------------------------------
+
+    def _generate_single(
+        self,
+        prompt: str,
+        max_length: int = 150,
+        temperature: float = 0.8,
+    ) -> str:
+        """Call Ollama API and return the generated text (non-streaming)."""
+        payload = {
+            "model": self.model_name,
+            "prompt": prompt,
+            "stream": False,
+            "options": {
+                "temperature": float(temperature),
+                "num_predict": int(max_length),
+            },
+        }
+        try:
+            response = requests.post(self.api_url, json=payload, timeout=120)
+            if not response.ok:
+                # Surface Ollama's own error message for easier debugging
+                try:
+                    detail = response.json().get("error", response.text)
+                except Exception:
+                    detail = response.text
+                raise RuntimeError(
+                    f"Ollama API error ({response.status_code}): {detail}\n"
+                    f"Model used: '{self.model_name}'"
+                )
+            return response.json().get("response", "")
+        except requests.RequestException as e:
+            raise RuntimeError(f"Request to Ollama failed: {e}") from e
+
+    def generate_responses(
+        self,
+        prompt: str,
+        num_responses: int = 5,
+        max_length: int = 150,
+        temperature: float = 0.8,
+        top_p: float = 0.9,  # accepted for API compatibility, not forwarded
+    ) -> List[str]:
+        """Generate multiple stochastic responses for a given prompt."""
+        responses = []
+        for i in range(num_responses):
+            text = self._generate_single(prompt, max_length, temperature)
+            responses.append(text)
+            print(f"Generated response {i + 1}/{num_responses}")
+        return responses
+
+    # ------------------------------------------------------------------
+    # Proxy internal metrics
+    # Because Ollama doesn't expose logits/activations, we approximate
+    # entropy from token-probability variance and stability from the
+    # pairwise similarity of multiple responses.
+    # ------------------------------------------------------------------
+
+    def generate_with_proxy_metrics(
+        self,
+        prompt: str,
+        num_samples: int = 5,
+        max_length: int = 150,
+        temperature: float = 0.8,
+    ) -> Dict[str, Any]:
+        """
+        Generate several responses and derive proxy internal-metric signals.
+
+        Returns a dict with keys mirroring those expected by analyzer.py:
+          - responses          : list of generated strings
+          - entropy_metrics    : dict with mean_entropy, max_entropy, entropy_curve
+          - stability_metrics  : dict with stability_score, layer_similarities
+          - grounding_metrics  : dict with grounding_score
+        """
+        responses = self.generate_responses(
+            prompt, num_responses=num_samples,
+            max_length=max_length, temperature=temperature
+        )
+
+        # --- Proxy entropy: estimated from character-length variance ----
+        # High variance in response length / token counts ≈ high uncertainty.
+        lengths = np.array([len(r.split()) for r in responses], dtype=float)
+        if lengths.max() > 0:
+            normalised = lengths / lengths.max()
+        else:
+            normalised = lengths
+        # Build a synthetic entropy curve (one value per response)
+        prob_like = normalised / (normalised.sum() + 1e-9)
+        entropy_curve = list(
+            -prob_like * np.log2(prob_like + 1e-9)
+        )
+        mean_entropy = float(np.mean(entropy_curve))
+        max_entropy  = float(np.max(entropy_curve))
+
+        # --- Proxy stability: Jaccard overlap between response pairs -----
+        def jaccard(a: str, b: str) -> float:
+            sa, sb = set(a.lower().split()), set(b.lower().split())
+            if not sa and not sb:
+                return 1.0
+            return len(sa & sb) / len(sa | sb)
+
+        pair_sims = []
+        for i in range(len(responses)):
+            for j in range(i + 1, len(responses)):
+                pair_sims.append(jaccard(responses[i], responses[j]))
+        stability_score = float(np.mean(pair_sims)) if pair_sims else 0.5
+        # Expose as layer-like list so the plot in app.py doesn't break
+        layer_similarities = pair_sims if pair_sims else [stability_score]
+
+        # --- Proxy grounding: similarity of responses to the prompt -----
+        prompt_words = set(prompt.lower().split())
+        grounding_scores = []
+        for r in responses:
+            r_words = set(r.lower().split())
+            if not r_words:
+                grounding_scores.append(0.0)
+            else:
+                grounding_scores.append(len(prompt_words & r_words) / len(r_words))
+        grounding_score = float(np.mean(grounding_scores))
+
+        return {
+            "responses": responses,
+            "entropy_metrics": {
+                "mean_entropy": mean_entropy,
+                "max_entropy":  max_entropy,
+                "entropy_curve": entropy_curve,
+            },
+            "stability_metrics": {
+                "stability_score":    stability_score,
+                "layer_similarities": layer_similarities,
+            },
+            "grounding_metrics": {
+                "grounding_score": grounding_score,
+            },
+        }

pyrightconfig.json

@@ -0,0 +1,11 @@
+{
+  "pythonVersion": "3.10",
+  "include": ["."],
+  "extraPaths": ["."],
+  "executionEnvironments": [
+    {
+      "root": ".",
+      "extraPaths": ["."]
+    }
+  ]
+}

requirements.txt

@@ -0,0 +1,12 @@
+torch>=2.0.0
+transformer-lens>=1.0.0
+transformers>=4.30.0
+sentence-transformers>=2.2.0
+numpy>=1.24.0
+matplotlib>=3.7.0
+streamlit>=1.28.0
+scikit-learn>=1.3.0
+plotly>=5.14.0
+datasets>=3.0.0
+sentence-transformers>=2.2.2
+pandas>=1.5.0

run_ui.bat

@@ -0,0 +1,11 @@
+@echo off
+REM Run the Streamlit UI
+REM Make sure you've run install.bat first
+
+echo Starting Hybrid LLM Hallucination Detection System...
+echo.
+echo Opening Streamlit UI in your browser...
+echo Press Ctrl+C to stop the server
+echo.
+
+streamlit run app.py

ui_pages/__init__.py

@@ -0,0 +1 @@
+# pages package

ui_pages/page_analyzer.py

@@ -0,0 +1,282 @@
+"""
+Page 1 - Main Analyzer.
+Prompt input -> run analysis -> show classification, confidence, and responses.
+"""
+
+from datetime import datetime
+import math
+
+import plotly.graph_objects as go
+import streamlit as st
+
+from analyzer import HallucinationAnalyzer
+
+
+@st.cache_resource
+def load_analyzer(model_name, semantic_threshold):
+    return HallucinationAnalyzer(
+        model_name=model_name,
+        semantic_threshold=semantic_threshold,
+    )
+
+
+def classify(final_risk: float, eigen_score: float, external_similarity: float) -> tuple[str, str, float]:
+    """Return the headline label, badge CSS class, and confidence percentage."""
+    norm_eigen = 1.0 / (1.0 + math.exp(-eigen_score / max(1.0, abs(eigen_score) + 1e-9)))
+    eigen_high = norm_eigen > 0.5
+    confidence = max(0.0, min(100.0, round((1 - final_risk) * 100, 1)))
+
+    if external_similarity > 0.5:
+        return "Reliable", "badge-reliable", confidence
+    if eigen_high:
+        return "Uncertain Hallucination", "badge-uncertain", confidence
+    return "Confident Hallucination", "badge-confident-hall", confidence
+
+
+def confidence_color(pct: float) -> str:
+    if pct >= 70:
+        return "linear-gradient(90deg,#059669,#34d399)"
+    if pct >= 40:
+        return "linear-gradient(90deg,#d97706,#fbbf24)"
+    return "linear-gradient(90deg,#dc2626,#f87171)"
+
+
+def gauge(pct: float, label: str) -> go.Figure:
+    color = "#10b981" if pct >= 70 else ("#f59e0b" if pct >= 40 else "#ef4444")
+    fig = go.Figure(
+        go.Indicator(
+            mode="gauge+number",
+            value=pct,
+            number={"suffix": "%", "font": {"size": 36, "color": "#111827"}},
+            title={"text": label, "font": {"size": 15, "color": "#4b5563"}},
+            gauge={
+                "axis": {
+                    "range": [0, 100],
+                    "tickcolor": "#9ca3af",
+                    "tickfont": {"color": "#4b5563"},
+                },
+                "bar": {"color": color, "thickness": 0.25},
+                "bgcolor": "rgba(0,0,0,0.05)",
+                "borderwidth": 0,
+                "steps": [
+                    {"range": [0, 40], "color": "rgba(239,68,68,0.15)"},
+                    {"range": [40, 70], "color": "rgba(245,158,11,0.15)"},
+                    {"range": [70, 100], "color": "rgba(16,185,129,0.15)"},
+                ],
+            },
+        )
+    )
+    fig.update_layout(
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)",
+        margin=dict(t=40, b=20, l=20, r=20),
+        height=230,
+    )
+    return fig
+
+
+def plot_eigenvalues(eigenvalues):
+    if not eigenvalues:
+        return go.Figure()
+
+    sorted_eigenvalues = sorted((float(v) for v in eigenvalues), reverse=True)
+    x_values = list(range(1, len(sorted_eigenvalues) + 1))
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Bar(
+            x=x_values,
+            y=sorted_eigenvalues,
+            marker=dict(
+                color=sorted_eigenvalues,
+                colorscale="Tealgrn",
+                showscale=True,
+                colorbar=dict(title="Magnitude", tickfont=dict(color="#475569")),
+                line=dict(color="rgba(15,23,42,0.18)", width=1),
+            ),
+            hovertemplate="Eigenvalue %{x}<br>Magnitude %{y:.4f}<extra></extra>",
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=x_values,
+            y=sorted_eigenvalues,
+            mode="lines+markers",
+            line=dict(color="#0f766e", width=2),
+            marker=dict(size=7, color="#0f766e"),
+            hoverinfo="skip",
+            showlegend=False,
+        )
+    )
+    fig.update_layout(
+        title=dict(
+            text="Hidden-State Covariance Eigenvalue Spectrum",
+            font=dict(color="#111827", size=14),
+        ),
+        xaxis=dict(
+            title="Eigenvalue Rank",
+            color="#4b5563",
+            tickmode="linear",
+            dtick=1,
+        ),
+        yaxis=dict(title="Magnitude", color="#4b5563"),
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0.03)",
+        height=340,
+        margin=dict(t=50, b=40, l=50, r=20),
+    )
+    return fig
+
+
+def render(cfg: dict):
+    st.markdown(
+        """
+    <div class='hero'>
+        <h1>HalluciScan</h1>
+        <p>Detect hallucinations in AI responses using internal activations and factual grounding.</p>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+    st.markdown("<div class='card'>", unsafe_allow_html=True)
+    prompt = st.text_area(
+        "Enter your question or prompt:",
+        height=110,
+        placeholder="e.g., What is the capital of Australia?",
+        key="main_prompt",
+    )
+    analyze_btn = st.button("Run Analysis", use_container_width=True, key="run_analysis")
+    st.markdown("</div>", unsafe_allow_html=True)
+
+    if analyze_btn and not prompt.strip():
+        st.warning("Please enter a prompt before running analysis.")
+        return
+
+    if not analyze_btn:
+        _show_example()
+        return
+
+    with st.spinner("Loading model and running analysis. This may take a minute."):
+        try:
+            analyzer = load_analyzer(cfg["model_name"], cfg["semantic_threshold"])
+            results = analyzer.analyze(
+                prompt=prompt,
+                num_responses=cfg["num_responses"],
+                max_length=cfg["max_length"],
+                temperature=cfg["temperature"],
+                alpha=cfg["alpha"],
+                beta=cfg["beta"],
+                w1=cfg["w1"],
+                w2=cfg["w2"],
+                w3=cfg["w3"],
+            )
+        except Exception as exc:
+            st.error(f"Analysis failed: {exc}")
+            st.exception(exc)
+            return
+
+    st.session_state["last_results"] = results
+    st.session_state["last_prompt"] = prompt
+
+    if "analysis_history" not in st.session_state:
+        st.session_state["analysis_history"] = []
+
+    st.session_state["analysis_history"].append(
+        {
+            "prompt": prompt,
+            "final_risk": results["final_risk"],
+            "eigen_score": results["eigen"]["eigen_score"],
+            "stability": results["stability"]["stability_score"],
+            "grounding": results["grounding"]["grounding_score"],
+            "ext_sim": results["external"]["external_consistency"],
+            "gt_source": results["external"].get("ground_truth_source", "N/A"),
+            "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+        }
+    )
+
+    final_risk = results["final_risk"]
+    eigen_score = results["eigen"]["eigen_score"]
+    ext_sim = results["external"]["external_consistency"]
+    label, badge, conf_pct = classify(final_risk, eigen_score, ext_sim)
+
+    st.success("Analysis complete.")
+
+    col_a, col_b, col_c = st.columns([1, 1, 1])
+
+    with col_a:
+        st.markdown(
+            f"""
+        <div class='card' style='text-align:center;'>
+            <p style='color:rgba(0,0,0,0.5); margin:0; font-size:0.85rem;'>CLASSIFICATION</p>
+            <span class='{badge}' style='font-size:1.1rem; margin-top:8px; display:inline-block;'>{label}</span>
+        </div>""",
+            unsafe_allow_html=True,
+        )
+
+    with col_b:
+        fill_color = confidence_color(conf_pct)
+        st.markdown(
+            f"""
+        <div class='card' style='text-align:center;'>
+            <p style='color:rgba(0,0,0,0.5); margin:0 0 6px; font-size:0.85rem;'>CONFIDENCE</p>
+            <span style='font-size:2rem; font-weight:700; color:#111827;'>{conf_pct}%</span>
+            <div class='meter-wrap' style='margin-top:8px;'>
+                <div class='meter-fill' style='width:{conf_pct}%; background:{fill_color};'></div>
+            </div>
+        </div>""",
+            unsafe_allow_html=True,
+        )
+
+    with col_c:
+        st.plotly_chart(gauge(conf_pct, "Confidence Meter"), use_container_width=True)
+
+    m1, m2, m3, m4 = st.columns(4)
+    m1.metric("Final Risk", f"{final_risk:.4f}")
+    m2.metric("EigenScore", f"{eigen_score:.4f}")
+    m3.metric("Stability", f"{results['stability']['stability_score']:.4f}")
+    m4.metric("External Similarity", f"{ext_sim:.4f}")
+
+    st.markdown("<div class='card'>", unsafe_allow_html=True)
+    st.subheader("Generated Responses")
+    for i, response in enumerate(results["responses"], 1):
+        with st.expander(f"Response {i}", expanded=(i == 1)):
+            st.write(response)
+    st.markdown("</div>", unsafe_allow_html=True)
+
+    if results["external"]["ground_truth"] != "N/A":
+        st.markdown(
+            f"""
+        <div class='card'>
+            <p style='color:#0369a1; font-weight:700; margin:0 0 4px;'>Ground Truth ({results['external'].get('ground_truth_source', 'N/A')})</p>
+            <p style='color:#111827; margin:0;'>{results['external']['ground_truth']}</p>
+        </div>""",
+            unsafe_allow_html=True,
+        )
+    else:
+        st.info("No ground truth was found across datasets (TruthfulQA, CoQA, SQuAD, NQ, TriviaQA) for this prompt. External similarity was set to a neutral fallback.")
+
+    st.subheader("Eigenvalue Spectrum")
+    st.plotly_chart(
+        plot_eigenvalues(results["eigen"]["eigenvalues"]),
+        use_container_width=True,
+    )
+    st.caption("Eigenvalues are shown in descending order and ranked from 1 to N for easier reading.")
+
+    st.info("Switch to Explanation in the sidebar for a plain-language breakdown of these results.")
+
+
+def _show_example():
+    st.markdown(
+        """
+    <div class='card' style='text-align:center; padding:2.5rem 1rem;'>
+        <span style='font-size:3rem;'>Analyze</span>
+        <h3 style='color:#0369a1; margin:0.5rem 0;'>Ready to Analyze</h3>
+        <p style='color:rgba(0,0,0,0.6); max-width:520px; margin:0 auto;'>
+            Type a question above and click <strong>Run Analysis</strong>.<br/>
+            The system will generate multiple responses, compute internal metrics
+            (EigenScore, Stability, Grounding), and cross-check with reference datasets.
+        </p>
+    </div>""",
+        unsafe_allow_html=True,
+    )

ui_pages/page_evaluation.py

@@ -0,0 +1,422 @@
+"""
+Page 3 - Evaluation Page.
+ROC curve, confusion matrix, accuracy, precision, recall, and F1.
+
+The model is run for every sampled question so that the `final_risk` score
+produced by the full hallucination-detection pipeline is used as the classifier
+score for the ROC curve.  The true label is determined by comparing the model's
+*own generated response* to the CSV ground-truth answer via cosine similarity:
+
+    similarity >= label_threshold  →  label = 0  (model was correct)
+    similarity <  label_threshold  →  label = 1  (model hallucinated)
+"""
+
+import ast
+
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+import streamlit as st
+from sklearn.metrics import (
+    accuracy_score,
+    auc,
+    confusion_matrix,
+    f1_score,
+    precision_score,
+    recall_score,
+    roc_curve,
+)
+
+from analyzer import HallucinationAnalyzer
+
+
+@st.cache_resource
+def load_analyzer(model_name, semantic_threshold):
+    return HallucinationAnalyzer(
+        model_name=model_name,
+        semantic_threshold=semantic_threshold,
+    )
+
+
+LIGHT_LAYOUT = dict(
+    paper_bgcolor="rgba(0,0,0,0)",
+    plot_bgcolor="rgba(0,0,0,0.03)",
+    font=dict(color="#4b5563"),
+    margin=dict(t=50, b=40, l=50, r=20),
+)
+
+
+def plot_roc(y_true, y_scores, auc_val):
+    fpr, tpr, _ = roc_curve(y_true, y_scores)
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=[0, 1],
+            y=[0, 1],
+            mode="lines",
+            line=dict(color="#475569", dash="dash", width=1),
+            name="Random Chance (AUC = 0.50)",
+            hoverinfo="skip",
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=list(fpr) + [1, 0],
+            y=list(tpr) + [0, 0],
+            fill="toself",
+            fillcolor="rgba(2,132,199,0.12)",
+            line=dict(color="rgba(0,0,0,0)"),
+            showlegend=False,
+            hoverinfo="skip",
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=fpr,
+            y=tpr,
+            mode="lines+markers",
+            name=f"ROC Curve (AUC = {auc_val:.4f})",
+            line=dict(color="#0284c7", width=2.5),
+            marker=dict(size=4, color="#0284c7"),
+            hovertemplate="FPR: %{x:.3f}<br>TPR: %{y:.3f}<extra></extra>",
+        )
+    )
+    fig.update_layout(
+        title=dict(text=f"ROC Curve (AUC = {auc_val:.4f})", font=dict(color="#111827", size=15)),
+        xaxis=dict(title="False Positive Rate", range=[0, 1]),
+        yaxis=dict(title="True Positive Rate", range=[0, 1.02]),
+        legend=dict(x=0.55, y=0.08, font=dict(size=12)),
+        height=430,
+        **LIGHT_LAYOUT,
+    )
+    return fig
+
+
+def plot_confusion(y_true, y_pred):
+    cm = confusion_matrix(y_true, y_pred)
+    labels = ["Correct (0)", "Hallucinated (1)"]
+    fig = go.Figure(
+        go.Heatmap(
+            z=cm,
+            x=labels,
+            y=labels,
+            colorscale=[[0, "#e0f2fe"], [0.5, "#38bdf8"], [1, "#0369a1"]],
+            text=cm,
+            texttemplate="%{text}",
+            textfont=dict(size=20, color="#111827"),
+            showscale=False,
+        )
+    )
+    fig.update_layout(
+        title=dict(text="Confusion Matrix", font=dict(color="#111827", size=15)),
+        xaxis=dict(title="Predicted", side="bottom"),
+        yaxis=dict(title="Actual", autorange="reversed"),
+        height=350,
+        **LIGHT_LAYOUT,
+    )
+    return fig
+
+
+def plot_risk_distribution(details: list) -> go.Figure:
+    """Box / strip plot showing risk score distribution per true label."""
+    label_key = "True Label (label=0 → Correct, 1 → Hallucinated)"
+    correct_scores = [d["Final Risk"] for d in details if d[label_key] == "Correct"]
+    halluc_scores  = [d["Final Risk"] for d in details if d[label_key] == "Hallucinated"]
+
+    fig = go.Figure()
+    fig.add_trace(go.Box(
+        y=correct_scores, name="Correct (label=0)",
+        marker_color="#10b981", boxmean=True,
+        hovertemplate="Risk: %{y:.4f}<extra>Correct</extra>",
+    ))
+    fig.add_trace(go.Box(
+        y=halluc_scores, name="Hallucinated (label=1)",
+        marker_color="#ef4444", boxmean=True,
+        hovertemplate="Risk: %{y:.4f}<extra>Hallucinated</extra>",
+    ))
+    fig.update_layout(
+        title=dict(text="Final Risk Distribution by True Label", font=dict(color="#111827", size=13)),
+        yaxis=dict(title="Final Risk Score", range=[0, 1.05]),
+        height=320,
+        **LIGHT_LAYOUT,
+    )
+    return fig
+
+
+def metric_card(label: str, value: str, sub: str, color: str):
+    st.markdown(
+        f"""
+    <div class='card' style='text-align:center; border-top:3px solid {color};'>
+        <p style='color:rgba(0,0,0,0.5); font-size:0.78rem; margin:0 0 2px; font-weight:700;'>{label}</p>
+        <p style='color:#111827; font-size:1.8rem; font-weight:700; margin:0;'>{value}</p>
+        <p style='color:rgba(0,0,0,0.4); font-size:0.75rem; margin:0;'>{sub}</p>
+    </div>""",
+        unsafe_allow_html=True,
+    )
+
+
+def render(cfg: dict):
+    st.markdown(
+        """
+    <div class='hero'>
+        <h1>Evaluation</h1>
+        <p>Run the full model pipeline on sampled questions and measure ROC / classification performance.</p>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+    with st.expander("How this works", expanded=False):
+        st.markdown(
+            """
+**End-to-end evaluation — the model generates responses for every question.**
+
+| Step | What happens |
+|---|---|
+| **1. Sample** | N questions are drawn from `generation_validation.csv` |
+| **2. Analyze** | The full pipeline runs: model generates responses → EigenScore, Stability, Grounding, External similarity → `final_risk` |
+| **3. Label** | The model's own generated response is compared to the CSV ground-truth answer via cosine similarity. If similarity ≥ *Label threshold* → **Correct (0)**, else → **Hallucinated (1)** |
+| **4. ROC** | `final_risk` is used as the classifier score; true labels from step 3 are used as ground truth |
+
+**Formula reference**
+
+| Metric | Formula |
+|---|---|
+| **Accuracy** | (TP + TN) / Total |
+| **Precision** | TP / (TP + FP) |
+| **Recall** | TP / (TP + FN) |
+| **F1** | 2 · P · R / (P + R) |
+| **AUC** | Area under ROC (0.5 = random, 1.0 = perfect) |
+"""
+        )
+
+    st.markdown("<div class='card'>", unsafe_allow_html=True)
+    c1, c2 = st.columns(2)
+    with c1:
+        roc_samples = st.slider(
+            "Questions to evaluate",
+            3, 20, 5, 1,
+            key="roc_samples",
+            help="Number of questions the model will actually run. Each takes ~10–30 s depending on model size.",
+        )
+    with c2:
+        label_threshold = st.slider(
+            "Label threshold (Gen↔GT similarity)",
+            0.10, 0.90, 0.45, 0.05,
+            key="label_thresh",
+            help=(
+                "How similar the model's generated response must be to the ground truth "
+                "to be counted as Correct. Below this → True Label = Hallucinated."
+            ),
+        )
+
+    c3, c4 = st.columns(2)
+    with c3:
+        risk_threshold = st.slider(
+            "Risk threshold (confusion matrix)",
+            0.10, 0.90, 0.30, 0.05,
+            key="risk_thresh",
+            help=(
+                "GPT-2 final_risk scores cluster around 0.25–0.35. "
+                "Set this near the middle of that range. "
+                "Risk score above this → Predicted Hallucinated."
+            ),
+        )
+    with c4:
+        roc_score_key = st.selectbox(
+            "Score used for ROC curve",
+            ["Final Risk", "Ext. Similarity (inverted)", "EigenScore component"],
+            index=0,
+            key="roc_score_key",
+            help=(
+                "Which score to use as the classifier for the ROC curve. "
+                "'Final Risk' uses the full hybrid score. "
+                "'Ext. Similarity (inverted)' uses 1 - external_consistency, which is "
+                "more reliable when GPT-2 responses are noisy. "
+                "'EigenScore component' uses the normalised eigen risk alone."
+            ),
+        )
+    run_btn = st.button("Run Batch Evaluation", use_container_width=True, key="run_roc")
+    st.markdown("</div>", unsafe_allow_html=True)
+
+    if not run_btn:
+        st.markdown(
+            """
+        <div class='card' style='text-align:center; padding:2.5rem;'>
+            <h3 style='color:#0369a1;'>Waiting for Evaluation</h3>
+            <p style='color:rgba(0,0,0,0.6);'>
+                Click <strong>Run Batch Evaluation</strong> to run the model on sampled
+                questions and compute ROC / classification metrics.
+            </p>
+            <p style='color:rgba(0,0,0,0.45); font-size:0.85rem;'>
+                ⚠️ Each question requires a full model forward pass. 5 questions ≈ 1–3 min.
+            </p>
+        </div>""",
+            unsafe_allow_html=True,
+        )
+        return
+
+    # ── Load CSV ────────────────────────────────────────────────────────────
+    try:
+        df = pd.read_csv("generation_validation.csv")
+    except FileNotFoundError:
+        st.error("generation_validation.csv not found in the working directory.")
+        return
+
+    df = df.dropna(subset=["question", "best_answer"])
+    df = df[df["best_answer"].astype(str).str.strip() != ""]
+    sample_count = min(roc_samples, len(df))
+    sampled = df.sample(n=sample_count, random_state=42).reset_index(drop=True)
+
+    # ── Load model ──────────────────────────────────────────────────────────
+    try:
+        analyzer = load_analyzer(cfg["model_name"], cfg["semantic_threshold"])
+    except Exception as exc:
+        st.error(f"Model loading failed: {exc}")
+        return
+
+    # ── Run pipeline for every question ────────────────────────────────────
+    st.info(
+        f"Running the full analysis pipeline on {sample_count} questions. "
+        "Progress is shown below — this may take several minutes."
+    )
+
+    y_true, y_scores, details = [], [], []
+    progress = st.progress(0.0)
+    status   = st.empty()
+
+    for idx, row in sampled.iterrows():
+        question  = str(row["question"]).strip()
+        gt_text   = str(row["best_answer"]).strip()
+
+        status.markdown(
+            f"**[{idx + 1}/{sample_count}]** Running model on: *{question[:80]}*…"
+        )
+
+        try:
+            results = analyzer.analyze(
+                prompt        = question,
+                num_responses = cfg["num_responses"],
+                max_length    = cfg["max_length"],
+                temperature   = cfg["temperature"],
+                alpha         = cfg["alpha"],
+                beta          = cfg["beta"],
+                w1            = cfg["w1"],
+                w2            = cfg["w2"],
+                w3            = cfg["w3"],
+            )
+        except Exception as exc:
+            st.warning(f"Skipped question {idx + 1} due to error: {exc}")
+            progress.progress((idx + 1) / sample_count)
+            continue
+
+        final_risk     = results["final_risk"]
+        primary_resp   = results["primary_response"]
+
+        # Determine true label: compare model's own response to ground truth
+        gen_sim = analyzer.external_verifier.compute_similarity(primary_resp, gt_text)
+        true_label = 0 if gen_sim >= label_threshold else 1   # 0=correct, 1=hallucinated
+
+        y_true.append(true_label)
+
+        ext_sim_val   = results["external"]["external_consistency"]
+        import math
+        raw_eigen     = results["eigen"]["eigen_score"]
+        eigen_norm    = float(1.0 / (1.0 + math.exp(-raw_eigen)))
+
+        # Pick the ROC classifier score based on user's selection
+        if roc_score_key == "Ext. Similarity (inverted)":
+            roc_score = 1.0 - ext_sim_val
+        elif roc_score_key == "EigenScore component":
+            roc_score = eigen_norm
+        else:
+            roc_score = final_risk
+
+        predicted = 1 if roc_score > risk_threshold else 0
+
+        y_scores.append(roc_score)
+
+        details.append({
+            "Question":          question[:65] + ("…" if len(question) > 65 else ""),
+            "Ground Truth":      gt_text[:65]  + ("…" if len(gt_text)   > 65 else ""),
+            "Model Response":    primary_resp[:65] + ("…" if len(primary_resp) > 65 else ""),
+            "Gen↔GT Sim":        round(gen_sim, 4),
+            "True Label (label=0 → Correct, 1 → Hallucinated)": "Hallucinated" if true_label == 1 else "Correct",
+            "ROC Score used":    round(roc_score, 4),
+            "Final Risk":        round(final_risk, 4),
+            "Ext. Similarity":   round(ext_sim_val, 4),
+            "EigenScore":        round(raw_eigen, 4),
+            "Stability":         round(results["stability"]["stability_score"], 4),
+            "Predicted (score > threshold)": "Hallucinated" if predicted == 1 else "Correct",
+            "Correct?":          "✅" if predicted == true_label else "❌",
+        })
+
+        progress.progress((idx + 1) / sample_count)
+
+    status.empty()
+    progress.empty()
+
+    # ── Guard: need at least 2 classes ─────────────────────────────────────
+    if len(y_true) < 2:
+        st.error("Not enough samples completed successfully to compute metrics.")
+        return
+
+    unique_labels = set(y_true)
+    if len(unique_labels) < 2:
+        only = "Correct" if 0 in unique_labels else "Hallucinated"
+        st.warning(
+            f"All {len(y_true)} completed samples were labelled **{only}** "
+            f"(label threshold = {label_threshold:.2f}). "
+            "Try lowering the label threshold so some responses are labelled as hallucinated, "
+            "or increase the number of questions."
+        )
+        # Still show the per-sample table so the user can inspect
+        with st.expander("Per-sample results", expanded=True):
+            st.dataframe(pd.DataFrame(details), use_container_width=True)
+        return
+
+    # ── Metrics ─────────────────────────────────────────────────────────────
+    y_pred    = [1 if s > risk_threshold else 0 for s in y_scores]
+    auc_val   = auc(*roc_curve(y_true, y_scores)[:2])
+    acc       = accuracy_score(y_true, y_pred)
+    prec      = precision_score(y_true, y_pred, zero_division=0)
+    rec       = recall_score(y_true, y_pred, zero_division=0)
+    f1        = f1_score(y_true, y_pred, zero_division=0)
+    n_correct = y_true.count(0)
+    n_halluc  = y_true.count(1)
+
+    st.success(
+        f"Evaluated **{len(y_true)}** questions — "
+        f"**{n_correct}** labelled Correct, **{n_halluc}** labelled Hallucinated."
+    )
+
+    st.subheader("Performance Metrics")
+    k1, k2, k3, k4, k5 = st.columns(5)
+    with k1:
+        metric_card("AUC", f"{auc_val:.4f}", "Area under ROC", "#0284c7")
+    with k2:
+        metric_card("Accuracy", f"{acc:.2%}", "(TP+TN) / Total", "#60a5fa")
+    with k3:
+        metric_card("Precision", f"{prec:.2%}", "TP / (TP+FP)", "#34d399")
+    with k4:
+        metric_card("Recall", f"{rec:.2%}", "TP / (TP+FN)", "#f59e0b")
+    with k5:
+        metric_card("F1 Score", f"{f1:.2%}", "Harmonic mean P·R", "#ef4444")
+
+    col_roc, col_cm = st.columns([3, 2])
+    with col_roc:
+        st.plotly_chart(plot_roc(y_true, y_scores, auc_val), use_container_width=True)
+    with col_cm:
+        st.plotly_chart(plot_confusion(y_true, y_pred), use_container_width=True)
+
+    st.plotly_chart(plot_risk_distribution(details), use_container_width=True)
+
+    with st.expander("Per-sample results", expanded=False):
+        st.dataframe(pd.DataFrame(details), use_container_width=True)
+
+    st.caption(
+        "The model's full analysis pipeline (EigenScore + Stability + Grounding + External) "
+        "is run for each question. final_risk is used as the ROC classifier score. "
+        "The true label is determined by comparing the model's own generated response "
+        f"to the CSV ground truth (label threshold = {label_threshold:.2f})."
+    )

ui_pages/page_explanation.py

@@ -0,0 +1,211 @@
+"""
+Page 2 - Explanation Page.
+Converts raw metrics into user-friendly reasoning.
+"""
+
+import math
+
+import streamlit as st
+
+
+def _eigen_level(eigen_score: float) -> str:
+    norm = 1.0 / (1.0 + math.exp(-eigen_score / max(1.0, abs(eigen_score) + 1e-9)))
+    return "High" if norm > 0.5 else "Low"
+
+
+def build_reasons(results: dict) -> list[str]:
+    reasons = []
+    eigen_score = results["eigen"]["eigen_score"]
+    stability = results["stability"]["stability_score"]
+    grounding = results["grounding"]["grounding_score"]
+    ext_sim = results["external"]["external_consistency"]
+
+    if _eigen_level(eigen_score) == "High":
+        reasons.append("The model gave different answers across samples, which suggests uncertainty.")
+    else:
+        reasons.append("The model gave fairly consistent answers across samples, which suggests confidence.")
+
+    if stability < 0.5:
+        reasons.append("Its internal reasoning shifted noticeably across layers, so the answer path was unstable.")
+    else:
+        reasons.append("Its internal reasoning stayed relatively stable across layers.")
+
+    if grounding < 0.5:
+        reasons.append("The response was only weakly grounded in the original question.")
+    else:
+        reasons.append("The response stayed well grounded in the original question.")
+
+    if ext_sim < 0.5:
+        reasons.append("The answer did not match known facts strongly enough.")
+    else:
+        reasons.append("The answer matched the reference facts reasonably well.")
+
+    return reasons
+
+
+def classify_verbose(results: dict) -> tuple[str, str, str]:
+    eigen_score = results["eigen"]["eigen_score"]
+    ext_sim = results["external"]["external_consistency"]
+
+    norm_eigen = 1.0 / (1.0 + math.exp(-eigen_score / max(1.0, abs(eigen_score) + 1e-9)))
+    eigen_high = norm_eigen > 0.5
+
+    if ext_sim > 0.5:
+        return (
+            "This answer appears to be correct and reliable.",
+            "Reliable",
+            "The model's answer aligns with known reference information and did not show strong warning signs internally.",
+        )
+    if eigen_high:
+        return (
+            "This answer looks uncertain.",
+            "Uncertain Hallucination",
+            "The model varied across samples and the result also failed to match the reference facts closely.",
+        )
+    return (
+        "This answer is likely incorrect despite sounding confident.",
+        "Confident but Incorrect Answer",
+        "The model stayed internally consistent, but the answer still did not line up with the reference facts.",
+    )
+
+
+def _metric_bar(label: str, value: float, color: str, tooltip: str):
+    pct = round(value * 100, 1)
+    st.markdown(
+        f"""
+    <div style='margin-bottom:14px;'>
+        <div style='display:flex; justify-content:space-between; margin-bottom:4px;'>
+            <span style='color:#334155; font-size:0.9rem; font-weight:600;'>{label}</span>
+            <span style='color:#0f172a; font-size:0.9rem; font-weight:700;'>{pct}%</span>
+        </div>
+        <div class='meter-wrap'>
+            <div class='meter-fill' style='width:{pct}%; background:{color};'></div>
+        </div>
+        <span style='color:rgba(15,23,42,0.55); font-size:0.78rem;'>{tooltip}</span>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+
+def render():
+    st.markdown(
+        """
+    <div class='hero'>
+        <h1>Plain-Language Explanation</h1>
+        <p>What the system found, explained in simple terms.</p>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+    results = st.session_state.get("last_results")
+    prompt = st.session_state.get("last_prompt", "")
+
+    if results is None:
+        st.markdown(
+            """
+        <div class='card' style='text-align:center; padding:2.5rem;'>
+            <h3 style='color:#0369a1;'>No Analysis Yet</h3>
+            <p style='color:rgba(15,23,42,0.55);'>
+                Run an analysis on the <strong>Analyzer</strong> page first, then come back here.
+            </p>
+        </div>""",
+            unsafe_allow_html=True,
+        )
+        return
+
+    headline, sub_label, conclusion = classify_verbose(results)
+    reasons = build_reasons(results)
+
+    st.markdown(
+        f"""
+    <div class='card'>
+        <p style='color:#0369a1; font-size:0.8rem; margin:0 0 4px; font-weight:700;'>YOUR QUESTION</p>
+        <p style='color:#0f172a; margin:0; font-size:1rem;'>"{prompt}"</p>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+    verdict_color = {
+        "Reliable": "#059669",
+        "Uncertain Hallucination": "#d97706",
+        "Confident but Incorrect Answer": "#dc2626",
+    }.get(sub_label, "#0369a1")
+
+    st.markdown(
+        f"""
+    <div class='card' style='border-left: 4px solid {verdict_color};'>
+        <h3 style='color:#0f172a; margin:0 0 6px;'>{headline}</h3>
+        <span style='background:{verdict_color}22; color:{verdict_color};
+              border:1px solid {verdict_color}55; padding:4px 14px;
+              border-radius:30px; font-size:0.85rem; font-weight:700;'>
+            {sub_label}
+        </span>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+    st.subheader("Reasons")
+    for reason in reasons:
+        st.markdown(f"<div class='reason-item'>{reason}</div>", unsafe_allow_html=True)
+
+    st.subheader("What the Numbers Mean")
+
+    eigen_score = results["eigen"]["eigen_score"]
+    stability = results["stability"]["stability_score"]
+    grounding = results["grounding"]["grounding_score"]
+    ext_sim = results["external"]["external_consistency"]
+    norm_eigen = 1.0 / (1.0 + math.exp(-eigen_score / max(1.0, abs(eigen_score) + 1e-9)))
+
+    col1, col2 = st.columns(2)
+    with col1:
+        _metric_bar(
+            "Answer Consistency (1 - EigenScore)",
+            1 - norm_eigen,
+            "linear-gradient(90deg,#0284c7,#38bdf8)",
+            "Higher means the model repeated itself more consistently across samples.",
+        )
+        _metric_bar(
+            "Layer Stability",
+            stability,
+            "linear-gradient(90deg,#2563eb,#60a5fa)",
+            "Higher means the hidden-state trajectory changed less from layer to layer.",
+        )
+    with col2:
+        _metric_bar(
+            "Grounding",
+            grounding,
+            "linear-gradient(90deg,#0f766e,#2dd4bf)",
+            "Higher means the answer stayed closer to the original question.",
+        )
+        _metric_bar(
+            "Factual Similarity",
+            ext_sim,
+            "linear-gradient(90deg,#059669,#34d399)",
+            "Higher means the answer better matched the reference ground truth (TruthfulQA, CoQA, SQuAD, NQ, TriviaQA).",
+        )
+
+    st.markdown(
+        f"""
+    <div class='card' style='margin-top:1rem; border-top:3px solid {verdict_color};'>
+        <p style='color:#0369a1; font-weight:700; margin:0 0 6px;'>Conclusion</p>
+        <p style='color:#0f172a; margin:0; line-height:1.6;'>{conclusion}</p>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+    with st.expander("Metric Glossary"):
+        st.markdown(
+            """
+| Metric | When High | When Low |
+|---|---|---|
+| **EigenScore** | Model gave more varied answers | Model gave more consistent answers |
+| **Stability** | Reasoning stayed stable across layers | Reasoning changed more across layers |
+| **Grounding** | Answer stayed connected to the question | Answer drifted away from the question |
+| **External Similarity** | Answer matched known facts | Answer did not match known facts |
+"""
+        )

ui_pages/page_history.py

@@ -0,0 +1,268 @@
+"""
+Page 5 - Analysis History.
+Tracks past analyses in session state.
+"""
+
+import json
+import math
+
+import pandas as pd
+import plotly.graph_objects as go
+import streamlit as st
+
+
+LIGHT_LAYOUT = dict(
+    paper_bgcolor="rgba(0,0,0,0)",
+    plot_bgcolor="rgba(0,0,0,0.03)",
+    font=dict(color="#475569"),
+    margin=dict(t=50, b=40, l=50, r=20),
+)
+
+
+def _classify(final_risk: float, eigen_score: float, ext_sim: float) -> tuple[str, str]:
+    norm_eigen = 1.0 / (1.0 + math.exp(-eigen_score / max(1.0, abs(eigen_score) + 1e-9)))
+    eigen_high = norm_eigen > 0.5
+    if ext_sim > 0.5:
+        return "Reliable", "badge-reliable"
+    if eigen_high:
+        return "Uncertain", "badge-uncertain"
+    return "Hallucination", "badge-confident-hall"
+
+
+def _trend_chart(history: list) -> go.Figure:
+    labels = [f"#{i + 1}" for i in range(len(history))]
+    risks = [item["final_risk"] for item in history]
+    stabilities = [item["stability"] for item in history]
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=labels,
+            y=risks,
+            mode="lines+markers",
+            name="Final Risk",
+            line=dict(color="#ef4444", width=2),
+            marker=dict(size=8),
+            hovertemplate="Run %{x}<br>Risk: %{y:.4f}<extra></extra>",
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=labels,
+            y=stabilities,
+            mode="lines+markers",
+            name="Stability",
+            line=dict(color="#60a5fa", width=2, dash="dot"),
+            marker=dict(size=6),
+            hovertemplate="Run %{x}<br>Stability: %{y:.4f}<extra></extra>",
+        )
+    )
+    fig.add_hline(
+        y=0.5,
+        line_dash="dash",
+        line_color="#f59e0b",
+        annotation_text="Risk = 0.5",
+        annotation_font_color="#f59e0b",
+    )
+    fig.update_layout(
+        title=dict(text="Risk Score Trend Across Runs", font=dict(color="#111827", size=14)),
+        xaxis=dict(title="Run"),
+        yaxis=dict(title="Score", range=[0, 1.05]),
+        legend=dict(font=dict(color="#475569")),
+        height=320,
+        **LIGHT_LAYOUT,
+    )
+    return fig
+
+
+def _radar_comparison(a: dict, b: dict, label_a: str, label_b: str) -> go.Figure:
+    categories = ["Consistency", "Stability", "Grounding", "Ext. Similarity", "Confidence"]
+
+    def values(item):
+        norm = 1.0 / (1.0 + math.exp(-item["eigen_score"] / max(1.0, abs(item["eigen_score"]) + 1e-9)))
+        return [
+            1 - norm,
+            item["stability"],
+            item["grounding"],
+            item["ext_sim"],
+            1 - item["final_risk"],
+        ]
+
+    values_a = values(a)
+    values_b = values(b)
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatterpolar(
+            r=values_a + [values_a[0]],
+            theta=categories + [categories[0]],
+            fill="toself",
+            fillcolor="rgba(2,132,199,0.14)",
+            line=dict(color="#0284c7", width=2),
+            name=label_a,
+        )
+    )
+    fig.add_trace(
+        go.Scatterpolar(
+            r=values_b + [values_b[0]],
+            theta=categories + [categories[0]],
+            fill="toself",
+            fillcolor="rgba(16,185,129,0.12)",
+            line=dict(color="#10b981", width=2),
+            name=label_b,
+        )
+    )
+    fig.update_layout(
+        polar=dict(
+            bgcolor="rgba(0,0,0,0.03)",
+            radialaxis=dict(visible=True, range=[0, 1], tickfont=dict(color="#475569")),
+            angularaxis=dict(tickfont=dict(color="#111827")),
+        ),
+        height=400,
+        showlegend=True,
+        title=dict(text="Metric Comparison", font=dict(color="#111827", size=14)),
+        legend=dict(font=dict(color="#475569")),
+        **{k: v for k, v in LIGHT_LAYOUT.items() if k != "plot_bgcolor"},
+    )
+    return fig
+
+
+def render():
+    st.markdown(
+        """
+    <div class='hero'>
+        <h1>Analysis History</h1>
+        <p>Past runs in this session, with trends and side-by-side comparison.</p>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+    history = st.session_state.get("analysis_history", [])
+
+    if not history:
+        st.markdown(
+            """
+        <div class='card' style='text-align:center; padding:2.5rem;'>
+            <h3 style='color:#0369a1;'>No History Yet</h3>
+            <p style='color:rgba(15,23,42,0.55);'>
+                Run at least one analysis on the <strong>Analyzer</strong> page first.
+            </p>
+        </div>""",
+            unsafe_allow_html=True,
+        )
+        return
+
+    st.subheader(f"Session Summary - {len(history)} run(s)")
+
+    rows = []
+    for i, item in enumerate(history):
+        label, _ = _classify(item["final_risk"], item["eigen_score"], item["ext_sim"])
+        rows.append(
+            {
+                "Run": f"#{i + 1}",
+                "Prompt": item["prompt"][:60] + ("..." if len(item["prompt"]) > 60 else ""),
+                "Classification": label,
+                "Final Risk": round(item["final_risk"], 4),
+                "EigenScore": round(item["eigen_score"], 4),
+                "Stability": round(item["stability"], 4),
+                "Grounding": round(item["grounding"], 4),
+                "Ext. Sim": round(item["ext_sim"], 4),
+                "Confidence %": round((1 - item["final_risk"]) * 100, 1),
+                "GT Source": item.get("gt_source", "-"),
+                "Timestamp": item.get("timestamp", "-"),
+            }
+        )
+
+    df = pd.DataFrame(rows)
+    st.dataframe(df, use_container_width=True)
+
+    if len(history) > 1:
+        st.plotly_chart(_trend_chart(history), use_container_width=True)
+    else:
+        st.info("Run at least 2 analyses to see the trend chart.")
+
+    st.markdown("<hr style='border-color:rgba(15,23,42,0.1);'/>", unsafe_allow_html=True)
+    st.subheader("Side-by-Side Comparison")
+
+    run_options = [f"#{i + 1} - {item['prompt'][:50]}..." for i, item in enumerate(history)]
+
+    if len(history) < 2:
+        st.info("Run at least 2 analyses to enable comparison.")
+    else:
+        c1, c2 = st.columns(2)
+        with c1:
+            idx_a = st.selectbox("Run A", range(len(history)), format_func=lambda i: run_options[i], key="cmp_a")
+        with c2:
+            idx_b = st.selectbox(
+                "Run B",
+                range(len(history)),
+                format_func=lambda i: run_options[i],
+                index=min(1, len(history) - 1),
+                key="cmp_b",
+            )
+
+        run_a = history[idx_a]
+        run_b = history[idx_b]
+
+        metrics_def = [
+            ("Final Risk", "final_risk", False),
+            ("EigenScore", "eigen_score", False),
+            ("Stability", "stability", True),
+            ("Grounding", "grounding", True),
+            ("Ext. Sim", "ext_sim", True),
+        ]
+
+        cols = st.columns(len(metrics_def))
+        for col, (name, key, high_good) in zip(cols, metrics_def):
+            value_a = run_a[key]
+            value_b = run_b[key]
+            delta = value_b - value_a
+            better = (delta > 0) == high_good
+            arrow = "Improved" if abs(delta) <= 0.001 else ("Up" if better else "Down")
+            col.markdown(
+                f"""
+            <div class='card' style='text-align:center;'>
+                <p style='color:rgba(0,0,0,0.45);font-size:0.75rem;margin:0 0 2px;font-weight:700;'>{name}</p>
+                <p style='color:#111827;font-size:1rem;font-weight:700;margin:0;'>
+                    {value_a:.4f} -> {value_b:.4f}
+                </p>
+                <p style='font-size:0.85rem;margin:2px 0 0;'>{arrow} {delta:+.4f}</p>
+            </div>""",
+                unsafe_allow_html=True,
+            )
+
+        st.plotly_chart(
+            _radar_comparison(run_a, run_b, f"Run #{idx_a + 1}", f"Run #{idx_b + 1}"),
+            use_container_width=True,
+        )
+
+    st.markdown("<hr style='border-color:rgba(15,23,42,0.1);'/>", unsafe_allow_html=True)
+    st.subheader("Export")
+    c1, c2, c3 = st.columns(3)
+
+    with c1:
+        csv = df.to_csv(index=False).encode("utf-8")
+        st.download_button(
+            "Download CSV",
+            csv,
+            file_name="halluciScan_history.csv",
+            mime="text/csv",
+            use_container_width=True,
+            key="dl_csv",
+        )
+
+    with c2:
+        json_data = json.dumps(history, indent=2, default=str).encode("utf-8")
+        st.download_button(
+            "Download JSON",
+            json_data,
+            file_name="halluciScan_history.json",
+            mime="application/json",
+            use_container_width=True,
+            key="dl_json",
+        )
+
+    with c3:
+        if st.button("Clear History", use_container_width=True, key="clear_hist"):
+            st.session_state["analysis_history"] = []
+            st.rerun()

ui_pages/page_metrics.py

@@ -0,0 +1,354 @@
+"""
+Page 4 - Detailed Metrics.
+Shows EigenScore, Stability, Grounding, and External Similarity with breakdowns.
+"""
+
+import json
+import math
+
+import plotly.graph_objects as go
+import streamlit as st
+
+
+LIGHT_LAYOUT = dict(
+    paper_bgcolor="rgba(0,0,0,0)",
+    plot_bgcolor="rgba(0,0,0,0.03)",
+    font=dict(color="#4b5563"),
+    margin=dict(t=50, b=40, l=50, r=20),
+)
+
+
+def _norm_eigen(eigen_score: float) -> float:
+    return 1.0 / (1.0 + math.exp(-eigen_score / max(1.0, abs(eigen_score) + 1e-9)))
+
+
+def _pill(text: str, color: str) -> str:
+    return (
+        f"<span style='background:{color}22; color:{color}; border:1px solid {color}55; "
+        f"padding:3px 12px; border-radius:30px; font-size:0.82rem; font-weight:700;'>{text}</span>"
+    )
+
+
+def _status_pill(value: float, high_good: bool = True) -> str:
+    good = value > 0.65 if high_good else value < 0.35
+    medium = 0.35 <= value <= 0.65
+    if good:
+        return _pill("Good", "#10b981")
+    if medium:
+        return _pill("Medium", "#f59e0b")
+    return _pill("Poor", "#ef4444")
+
+
+def radar_chart(metrics: dict) -> go.Figure:
+    categories = ["Consistency", "Stability", "Grounding", "External Similarity", "Confidence"]
+    values = [
+        metrics["consistency"],
+        metrics["stability"],
+        metrics["grounding"],
+        metrics["ext_sim"],
+        metrics["confidence"] / 100,
+    ]
+    values_closed = values + [values[0]]
+    cats_closed = categories + [categories[0]]
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatterpolar(
+            r=values_closed,
+            theta=cats_closed,
+            fill="toself",
+            fillcolor="rgba(2,132,199,0.16)",
+            line=dict(color="#0284c7", width=2),
+            name="Metrics",
+        )
+    )
+    fig.update_layout(
+        polar=dict(
+            bgcolor="rgba(0,0,0,0.03)",
+            radialaxis=dict(
+                visible=True,
+                range=[0, 1],
+                tickfont=dict(color="#4b5563"),
+                gridcolor="rgba(0,0,0,0.1)",
+            ),
+            angularaxis=dict(
+                tickfont=dict(color="#111827"),
+                gridcolor="rgba(0,0,0,0.1)"),
+        ),
+        height=380,
+        showlegend=False,
+        title=dict(text="Metric Radar", font=dict(color="#111827", size=14)),
+        **{k: v for k, v in LIGHT_LAYOUT.items() if k != "plot_bgcolor"},
+    )
+    return fig
+
+
+def layer_stability_chart(layer_sims: list) -> go.Figure:
+    x_values = [f"L{i}->L{i + 1}" for i in range(len(layer_sims))]
+    fig = go.Figure(
+        go.Scatter(
+            x=x_values,
+            y=layer_sims,
+            mode="lines+markers",
+            line=dict(color="#60a5fa", width=2),
+            marker=dict(size=7, color="#60a5fa", line=dict(color="#1e3a5f", width=1.5)),
+            fill="tozeroy",
+            fillcolor="rgba(96,165,250,0.08)",
+            hovertemplate="%{x}: %{y:.4f}<extra></extra>",
+        )
+    )
+    fig.add_hline(
+        y=0.5,
+        line_dash="dash",
+        line_color="#f59e0b",
+        annotation_text="Stability Threshold (0.5)",
+        annotation_font_color="#f59e0b",
+    )
+    fig.update_layout(
+        title=dict(
+            text="Layer-wise Stability",
+            font=dict(color="#111827", size=13),
+        ),
+        xaxis=dict(title="Layer transition"),
+        yaxis=dict(title="Similarity", range=[0, 1.05]),
+        height=300,
+        **LIGHT_LAYOUT,
+    )
+    return fig
+
+
+def similarity_bar(similarities: list) -> go.Figure:
+    colors = ["#10b981" if score > 0.5 else "#ef4444" for score in similarities]
+    fig = go.Figure(
+        go.Bar(
+            x=[f"Response {i + 1}" for i in range(len(similarities))],
+            y=similarities,
+            marker_color=colors,
+            text=[f"{score:.3f}" for score in similarities],
+            textposition="outside",
+            textfont=dict(color="#111827"),
+        )
+    )
+    fig.add_hline(
+        y=0.5,
+        line_dash="dash",
+        line_color="#f59e0b",
+        annotation_text="Similarity threshold (0.5)",
+        annotation_font_color="#f59e0b",
+    )
+    fig.update_layout(
+        title=dict(text="Per-response Similarity to Ground Truth", font=dict(color="#111827", size=13)),
+        yaxis=dict(range=[0, 1.15]),
+        height=300,
+        **LIGHT_LAYOUT,
+    )
+    return fig
+
+
+def internal_risk_breakdown(results: dict) -> go.Figure:
+    ir = results["internal_risk"]
+    labels = ["EigenScore Component", "Stability Component", "Grounding Component"]
+    values = [
+        ir["eigen_score_component"],
+        ir["stability_component"],
+        ir["grounding_component"],
+    ]
+    colors = ["#0284c7", "#60a5fa", "#34d399"]
+    fig = go.Figure(
+        go.Bar(
+            x=labels,
+            y=values,
+            marker_color=colors,
+            text=[f"{value:.4f}" for value in values],
+            textposition="outside",
+            textfont=dict(color="#111827"),
+        )
+    )
+    fig.update_layout(
+        title=dict(text="Internal Risk Component Breakdown", font=dict(color="#111827", size=13)),
+        yaxis=dict(title="Risk contribution"),
+        height=300,
+        **LIGHT_LAYOUT,
+    )
+    return fig
+
+
+def weights_pie(results: dict) -> go.Figure:
+    alpha = results["weights"]["alpha"]
+    beta = results["weights"]["beta"]
+    internal_risk = results["internal_risk"]["internal_risk"]
+    external_risk = results["external"]["external_risk"]
+    fig = go.Figure(
+        go.Pie(
+            labels=["Internal Risk (alpha)", "External Risk (beta)"],
+            values=[alpha * internal_risk, beta * external_risk],
+            marker=dict(colors=["#0284c7", "#0f766e"], line=dict(color="rgba(0,0,0,0)", width=0)),
+            hole=0.5,
+            textfont=dict(color="#111827"),
+        )
+    )
+    fig.update_layout(
+        title=dict(text="Final Risk Composition", font=dict(color="#111827", size=13)),
+        legend=dict(font=dict(color="#4b5563")),
+        height=300,
+        **{k: v for k, v in LIGHT_LAYOUT.items() if k != "plot_bgcolor"},
+    )
+    return fig
+
+
+def _detail_card(title: str, value_str: str, pill_html: str, meaning: str, border_color: str):
+    st.markdown(
+        f"""
+    <div class='card' style='border-left:4px solid {border_color};'>
+        <div style='display:flex; justify-content:space-between; align-items:center;'>
+            <span style='color:#111827; font-weight:700; font-size:1rem;'>{title}</span>
+            {pill_html}
+        </div>
+        <p style='color:#0369a1; font-size:1.5rem; font-weight:700; margin:4px 0;'>{value_str}</p>
+        <p style='color:rgba(0,0,0,0.6); font-size:0.85rem; margin:0;'>{meaning}</p>
+    </div>""",
+        unsafe_allow_html=True,
+    )
+
+
+def render():
+    st.markdown(
+        """
+    <div class='hero'>
+        <h1>Detailed Metrics</h1>
+        <p>Advanced view of EigenScore, Stability, Grounding, and External Similarity.</p>
+    </div>
+    """,
+        unsafe_allow_html=True,
+    )
+
+    results = st.session_state.get("last_results")
+
+    if results is None:
+        st.markdown(
+            """
+        <div class='card' style='text-align:center; padding:2.5rem;'>
+            <h3 style='color:#0369a1;'>No Analysis Yet</h3>
+            <p style='color:rgba(0,0,0,0.6);'>
+                Run an analysis on the <strong>Analyzer</strong> page first.
+            </p>
+        </div>""",
+            unsafe_allow_html=True,
+        )
+        return
+
+    eigen_score = results["eigen"]["eigen_score"]
+    stability = results["stability"]["stability_score"]
+    grounding = results["grounding"]["grounding_score"]
+    ext_sim = results["external"]["external_consistency"]
+    final_risk = results["final_risk"]
+    confidence = round((1 - final_risk) * 100, 1)
+    norm_eigen = _norm_eigen(eigen_score)
+    consistency = 1 - norm_eigen
+
+    c1, c2 = st.columns(2)
+    with c1:
+        _detail_card(
+            "EigenScore (raw)",
+            f"{eigen_score:.4f}",
+            _status_pill(consistency, high_good=True),
+            "Lower and more negative values usually mean the sampled answers stayed closer together.",
+            "#0284c7",
+        )
+        _detail_card(
+            "Grounding Score",
+            f"{grounding:.4f}",
+            _status_pill(grounding, high_good=True),
+            "Measures how strongly the generated answer attends back to the question tokens.",
+            "#34d399",
+        )
+    with c2:
+        _detail_card(
+            "Stability Score",
+            f"{stability:.4f}",
+            _status_pill(stability, high_good=True),
+            "Measures similarity between adjacent transformer layers across the response.",
+            "#60a5fa",
+        )
+        _detail_card(
+            "External Similarity",
+            f"{ext_sim:.4f}",
+            _status_pill(ext_sim, high_good=True),
+            "Measures how closely the generated responses match the reference answer.",
+            "#f59e0b",
+        )
+
+    st.markdown("<div class='card'>", unsafe_allow_html=True)
+    fr1, fr2, fr3 = st.columns(3)
+    fr1.metric("Final Risk Score", f"{final_risk:.4f}")
+    fr2.metric("Confidence", f"{confidence}%")
+    fr3.metric("Samples Generated", results["eigen"]["num_responses"])
+    fr4, fr5 = st.columns(2)
+    fr4.metric("Internal Risk", f"{results['internal_risk']['internal_risk']:.4f}")
+    fr5.metric("External Risk", f"{results['external']['external_risk']:.4f}")
+    st.markdown("</div>", unsafe_allow_html=True)
+
+    col_rad, col_pie = st.columns(2)
+    with col_rad:
+        st.plotly_chart(
+            radar_chart(
+                {
+                    "consistency": consistency,
+                    "stability": stability,
+                    "grounding": grounding,
+                    "ext_sim": ext_sim,
+                    "confidence": confidence,
+                }
+            ),
+            use_container_width=True,
+        )
+    with col_pie:
+        st.plotly_chart(weights_pie(results), use_container_width=True)
+
+    st.plotly_chart(internal_risk_breakdown(results), use_container_width=True)
+
+    if "layer_similarities" in results["stability"]:
+        st.plotly_chart(
+            layer_stability_chart(results["stability"]["layer_similarities"]),
+            use_container_width=True,
+        )
+
+    if results["external"]["ground_truth"] != "N/A":
+        st.plotly_chart(
+            similarity_bar(results["external"]["similarities"]),
+            use_container_width=True,
+        )
+        st.markdown(
+            f"""
+        <div class='card'>
+            <p style='color:#0369a1; font-weight:700; margin:0 0 4px;'>Ground Truth Used</p>
+            <p style='color:#111827; margin:0;'>{results['external']['ground_truth']}</p>
+        </div>""",
+            unsafe_allow_html=True,
+        )
+
+    with st.expander("Feature Clipping (INSIDE paper)"):
+        clipped = results["eigen"].get("clipping_applied", False)
+        st.markdown(
+            f"""
+- **Clipping applied:** {"Yes" if clipped else "No (memory bank was empty)"}
+- Hidden-state activations are clipped per feature dimension using percentile thresholds
+  derived from the accumulated memory bank.
+- This helps keep outlier activations from dominating the EigenScore.
+- Reference: *INSIDE: LLMs' Internal States Are Good Indicators of Factual Accuracy* (ICLR 2024)
+"""
+        )
+
+    with st.expander("Raw Results (JSON)"):
+        safe = {
+            "prompt": results["prompt"],
+            "final_risk": results["final_risk"],
+            "eigen_score": results["eigen"]["eigen_score"],
+            "stability": results["stability"]["stability_score"],
+            "grounding": results["grounding"]["grounding_score"],
+            "ext_sim": results["external"]["external_consistency"],
+            "weights": results["weights"],
+            "internal_risk": results["internal_risk"],
+            "external_risk": results["external"]["external_risk"],
+        }
+        st.code(json.dumps(safe, indent=2), language="json")