Initial deployment with frontend architecture

.dockerignore

@@ -0,0 +1,51 @@
+# ----------------------------------
+# 1. Sensitive Information & Secrets
+# ----------------------------------
+.env
+.env.*
+*.pem
+*.key
+secret*.json
+
+# ----------------------------------
+# 2. Virtual Environments 
+# ----------------------------------
+# CRITICAL: Do not copy your Windows environment into a Linux container!
+env/
+venv/
+.venv/
+env.bak/
+
+# ----------------------------------
+# 3. Local Databases
+# ----------------------------------
+# Prevents uploading your local test database. Let the container make a fresh one.
+*.db
+*.sqlite3
+halluciguard.db
+
+# ----------------------------------
+# 4. Python Caches & Build Artifacts
+# ----------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.pytest_cache/
+build/
+dist/
+*.egg-info/
+
+# ----------------------------------
+# 5. IDEs, Git, & Notebooks
+# ----------------------------------
+.vscode/
+.idea/
+.git/
+.gitignore
+*.swp
+.DS_Store
+
+# Jupyter (Ignore checkpoints and your research notebooks to keep the image small)
+.ipynb_checkpoints/
+*.ipynb

Dockerfile

@@ -0,0 +1,25 @@
+# Use an official Python runtime as a parent image
+FROM python:3.10-slim
+
+# Hugging Face requires the app to run as user '1000'
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# Set the working directory
+WORKDIR /app
+
+# Copy the current directory contents into the container
+COPY --chown=user . /app
+
+# Install dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Make the startup script executable
+RUN chmod +x run.sh
+
+# Expose the port Hugging Face looks for
+EXPOSE 7860
+
+# Command to run the dual-server script
+CMD ["./run.sh"]

api/database.py

@@ -0,0 +1,35 @@
+import os
+from dotenv import load_dotenv
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import declarative_base, sessionmaker
+
+# Load the .env file
+load_dotenv()
+
+# Grab the URL, with a fallback just in case
+# --- COMMENT OUT YOUR POSTGRES URL ---
+# DATABASE_URL = os.getenv("DATABASE_URL", "postgresql+asyncpg://postgres:postgres@localhost:5432/halluciguard")
+
+# --- ADD THE SQLITE URL ---
+DATABASE_URL = "sqlite+aiosqlite:///./halluciguard.db"
+
+# Update your engine to include connect_args for SQLite
+engine = create_async_engine(
+    DATABASE_URL, 
+    echo=False, 
+    connect_args={"check_same_thread": False} # Required for SQLite with FastAPI
+)
+
+# Create a session factory
+AsyncSessionLocal = sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False
+)
+
+Base = declarative_base()
+
+# Dependency to yield database sessions for our FastAPI routes
+async def get_db():
+    async with AsyncSessionLocal() as session:
+        yield session

api/detector.py

@@ -0,0 +1,177 @@
+import torch
+import re
+from transformers import AutoTokenizer, AutoModelForSequenceClassification
+
+# ── Configuration Constants ──
+TEMPERATURE = 1.5           # Logit smoothing factor (higher = softer distribution)
+CONFIDENCE_THRESHOLD = 0.60 # Minimum raw probability to trust a classification
+CHUNK_SIZE = 400            # Words per chunk
+CHUNK_OVERLAP = 50          # Overlapping words between chunks
+
+
+def sliding_window_chunker(text: str, chunk_size: int = CHUNK_SIZE, overlap: int = CHUNK_OVERLAP) -> list[str]:
+    """Splits a large text into overlapping chunks of a specific word count."""
+    words = text.split()
+    chunks = []
+    
+    if not words:
+        return chunks
+        
+    step = chunk_size - overlap
+    if step <= 0:
+        step = 1
+        
+    for i in range(0, len(words), step):
+        chunk_words = words[i:i + chunk_size]
+        chunks.append(" ".join(chunk_words))
+        
+        if i + chunk_size >= len(words):
+            break
+            
+    return chunks
+
+def split_into_claims(text: str) -> list[str]:
+    """Splits the LLM output into individual sentences/claims to prevent conversational filler from ruining factual scores."""
+    raw_sentences = re.split(r'(?<=[.!?])\s+', text.strip())
+    
+    valid_claims = []
+    for s in raw_sentences:
+        clean = s.strip()
+        # Only keep substantial claims to avoid evaluating numbering fragments (like "1.")
+        if len(clean.split()) >= 3:
+            valid_claims.append(clean)
+            
+    if not valid_claims and text.strip():
+        valid_claims = [text.strip()]
+        
+    return valid_claims
+
+def normalize_scores(contradiction: float, entailment: float, neutral: float) -> tuple[float, float, float]:
+    """Ensures the three scores sum to exactly 100.0%."""
+    total = contradiction + entailment + neutral
+    if total == 0:
+        return (0.0, 0.0, 100.0)
+    
+    c = round((contradiction / total) * 100.0, 2)
+    e = round((entailment / total) * 100.0, 2)
+    n = round(100.0 - c - e, 2)  # Assign remainder to neutral to guarantee sum = 100
+    return (c, e, n)
+
+
+class HallucinationDetector:
+    def __init__(self):
+        """Initializes the model and tokenizer only once when the class is created."""
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        self.model_name = "cross-encoder/nli-deberta-v3-base"
+        
+        print(f"Initializing Detector on {self.device.type.upper()}...")
+        self.tokenizer = AutoTokenizer.from_pretrained(self.model_name)
+        self.model = AutoModelForSequenceClassification.from_pretrained(self.model_name).to(self.device)
+        print("Detector Ready!")
+
+    def _infer_chunk(self, chunk: str, claim: str) -> dict:
+        """Runs NLI inference on a single chunk against a single claim."""
+        inputs = self.tokenizer(
+            chunk, claim, 
+            return_tensors="pt", truncation=True, max_length=512
+        ).to(self.device)
+        
+        with torch.no_grad():
+            outputs = self.model(**inputs)
+            # Temperature Scaling
+            scaled_logits = outputs.logits / TEMPERATURE
+            probs = torch.nn.functional.softmax(scaled_logits, dim=-1)
+            
+        c_raw = probs[0][0].item()
+        e_raw = probs[0][1].item()
+        n_raw = probs[0][2].item()
+        
+        # Confidence Thresholding
+        max_score = max(c_raw, e_raw, n_raw)
+        if max_score < CONFIDENCE_THRESHOLD:
+            c_raw, e_raw, n_raw = 0.0, 0.0, 1.0  # Default to Neutral
+            
+        return {
+            "contradiction": c_raw,
+            "entailment": e_raw,
+            "neutral": n_raw,
+            "spans": []  # Placeholder for Captum
+        }
+
+    def analyze(self, context: str, llm_response: str) -> dict:
+        """
+        Hyper-Accurate Claim-by-Claim Analysis:
+        Splits LLM output into sentences, evaluates each sentence against context chunks,
+        and aggregates the results logically.
+        """
+        chunks = sliding_window_chunker(context)
+        if not chunks:
+            chunks = [""]
+            
+        claims = split_into_claims(llm_response)
+        sentence_scores = []
+        best_attribution_spans = []
+        
+        for claim in claims:
+            # Score this claim against all context chunks
+            chunk_results = [self._infer_chunk(chunk, claim) for chunk in chunks]
+            
+            s_max_e = max(r["entailment"] for r in chunk_results)
+            s_max_c = max(r["contradiction"] for r in chunk_results)
+            s_max_n = max(r["neutral"] for r in chunk_results)
+            
+            # Priority Resolution ("Truth Wins") for THIS specific claim
+            if s_max_e >= CONFIDENCE_THRESHOLD and s_max_e >= s_max_c:
+                final_s_e = s_max_e
+                final_s_c = s_max_c * 0.25
+                final_s_n = max(0.0, 1.0 - final_s_e - final_s_c)
+                winning_spans = max(chunk_results, key=lambda x: x["entailment"])["spans"]
+            elif s_max_c >= CONFIDENCE_THRESHOLD and s_max_c > s_max_e:
+                final_s_c = s_max_c
+                final_s_e = s_max_e * 0.25
+                final_s_n = max(0.0, 1.0 - final_s_c - final_s_e)
+                winning_spans = max(chunk_results, key=lambda x: x["contradiction"])["spans"]
+            else:
+                final_s_c = s_max_c
+                final_s_e = s_max_e
+                final_s_n = s_max_n
+                winning_spans = []
+                
+            sentence_scores.append({
+                "c": final_s_c,
+                "e": final_s_e,
+                "n": final_s_n,
+                "spans": winning_spans
+            })
+            
+        # ── Document-level Aggregation ──
+        # 1. Contradiction runs on a "One Strike" rule: If ANY claim contradicts, the output is flawed.
+        doc_c = max(s["c"] for s in sentence_scores)
+        
+        # 2. Entailment and Neutral run on an Average: Reflects the ratio of "Facts" vs "Neutral conversational filler".
+        doc_e = sum(s["e"] for s in sentence_scores) / len(sentence_scores)
+        doc_n = sum(s["n"] for s in sentence_scores) / len(sentence_scores)
+        
+        # Clamp negatives and purely normalize
+        doc_c = max(doc_c, 0.0)
+        doc_e = max(doc_e, 0.0)
+        doc_n = max(doc_n, 0.0)
+        
+        c_pct, e_pct, n_pct = normalize_scores(doc_c, doc_e, doc_n)
+        
+        # Grab spans from the claim that scored the highest severity 
+        if doc_c > doc_e:
+            best_spans = max(sentence_scores, key=lambda x: x["c"])["spans"]
+        else:
+            best_spans = max(sentence_scores, key=lambda x: x["e"])["spans"]
+            
+        # True Hallucination criteria
+        is_hallucination = (c_pct > e_pct) and (doc_c >= CONFIDENCE_THRESHOLD)
+            
+        return {
+            "contradiction_score": c_pct,
+            "entailment_score": e_pct,
+            "neutral_score": n_pct,
+            "is_hallucination": is_hallucination,
+            "attribution_spans": best_spans
+        }

api/main.py

@@ -0,0 +1,65 @@
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Depends
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.detector import HallucinationDetector
+from api.database import engine, Base, get_db
+from api.models import HallucinationLog
+
+detector = HallucinationDetector()
+
+# Lifespan context to create tables automatically on startup
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with engine.begin() as conn:
+        # In a real production app you'd use Alembic migrations, 
+        # but this is perfect for our current phase.
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+
+app = FastAPI(
+    title="HalluciGuard API",
+    description="Async API for detecting LLM hallucinations using NLI.",
+    version="1.0.0",
+    lifespan=lifespan
+)
+
+class HallucinationRequest(BaseModel):
+    context: str
+    llm_output: str
+
+@app.get("/")
+async def root():
+    return {"status": "online", "message": "HalluciGuard API is running."}
+
+# Notice we added `db: AsyncSession = Depends(get_db)` here
+@app.post("/api/v1/score")
+async def score_hallucination(request: HallucinationRequest, db: AsyncSession = Depends(get_db)):
+    
+    # 1. Run the ML Model
+    results = detector.analyze(request.context, request.llm_output)
+    
+    # 2. Package the data for PostgreSQL
+    new_log = HallucinationLog(
+        context=request.context,
+        llm_output=request.llm_output,
+        contradiction_score=results["contradiction_score"],
+        entailment_score=results["entailment_score"],
+        neutral_score=results["neutral_score"],
+        is_hallucination=results["is_hallucination"]
+    )
+    
+    # 3. Async commit to the database
+    db.add(new_log)
+    await db.commit()
+    await db.refresh(new_log) # Grabs the auto-generated ID and Timestamp
+    
+    # 4. Return to the user
+    return {
+        "log_id": new_log.id,
+        "context": request.context,
+        "llm_output": request.llm_output,
+        "results": results,
+        "timestamp": new_log.created_at
+    }

api/models.py

@@ -0,0 +1,19 @@
+from sqlalchemy import Column, Integer, String, Float, Boolean, DateTime
+from sqlalchemy.sql import func
+from api.database import Base
+
+class HallucinationLog(Base):
+    __tablename__ = "hallucination_logs"
+
+    id = Column(Integer, primary_key=True, index=True)
+    context = Column(String, nullable=False)
+    llm_output = Column(String, nullable=False)
+    
+    # ML Scores
+    contradiction_score = Column(Float)
+    entailment_score = Column(Float)
+    neutral_score = Column(Float)
+    is_hallucination = Column(Boolean)
+    
+    # Auto-generate a timestamp when the record is created
+    created_at = Column(DateTime(timezone=True), server_default=func.now())

frontend/app.py

@@ -0,0 +1,231 @@
+import streamlit as st
+import requests
+import PyPDF2
+
+# 1. Configure the page settings
+st.set_page_config(page_title="HalluciGuard", page_icon="🛡️", layout="centered")
+
+# --- CUSTOM Premium CSS ---
+st.markdown("""
+<style>
+/* Global Font Import */
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800&display=swap');
+
+html, body, [class*="css"] {
+    font-family: 'Inter', sans-serif;
+}
+
+/* Glassmorphism for text areas */
+.stTextArea textarea {
+    background-color: rgba(22, 27, 34, 0.6) !important;
+    border-radius: 12px;
+    border: 1px solid rgba(255, 255, 255, 0.08) !important;
+    color: #ffffff !important;
+    padding: 12px !important;
+    transition: all 0.3s ease;
+}
+
+.stTextArea textarea:focus {
+    border-color: #6C63FF !important;
+    box-shadow: 0 0 0 2px rgba(108, 99, 255, 0.3) !important;
+}
+
+/* Beautiful Button Gradient */
+.stButton > button {
+    background: linear-gradient(135deg, #6C63FF 0%, #3B33D4 100%) !important;
+    color: white !important;
+    border-radius: 12px !important;
+    border: none !important;
+    padding: 0.6rem 1.5rem !important;
+    font-weight: 600 !important;
+    transition: all 0.3s ease !important;
+    box-shadow: 0 4px 15px rgba(108, 99, 255, 0.25) !important;
+}
+
+.stButton > button:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 6px 20px rgba(108, 99, 255, 0.4) !important;
+}
+
+/* Glassmorphism Metric Cards */
+div[data-testid="stMetric"] {
+    background-color: rgba(22, 27, 34, 0.7);
+    border: 1px solid rgba(255, 255, 255, 0.05);
+    padding: 1.5rem;
+    border-radius: 16px;
+    box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.2);
+    backdrop-filter: blur(12px);
+    -webkit-backdrop-filter: blur(12px);
+    transition: transform 0.2s ease;
+}
+
+div[data-testid="stMetric"]:hover {
+    transform: translateY(-4px);
+}
+
+/* Fancy Header Gradient */
+h1 {
+    background: -webkit-linear-gradient(45deg, #A78BFA, #6C63FF);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    font-weight: 800 !important;
+    margin-bottom: 0rem !important;
+    padding-bottom: 1rem;
+}
+
+/* File Uploader tweaking */
+div[data-testid="stFileUploader"] {
+    background-color: rgba(22, 27, 34, 0.4);
+    border-radius: 12px;
+    padding: 1.5rem;
+    border: 1px dashed rgba(255, 255, 255, 0.15);
+    transition: all 0.3s ease;
+}
+div[data-testid="stFileUploader"]:hover {
+    border-color: #6C63FF;
+    background-color: rgba(108, 99, 255, 0.05);
+}
+
+/* Subheaders */
+h3 {
+    color: #e6edf3 !important;
+    font-weight: 600 !important;
+}
+</style>
+""", unsafe_allow_html=True)
+
+st.title("🛡️ HalluciGuard")
+st.write("Research-grade LLM Hallucination Detection using NLI and Cross-Encoders.")
+
+# 2. Define the Backend URL
+API_URL = "http://127.0.0.1:8000/api/v1/score"
+
+# 3. Create the Input Forms
+st.subheader("Test an LLM Output")
+
+# Initialize session state for context text and uploaded file tracking
+if "context_text" not in st.session_state:
+    st.session_state.context_text = ""
+if "uploaded_filename" not in st.session_state:
+    st.session_state.uploaded_filename = None
+
+uploaded_file = st.file_uploader("Upload a document to use as Ground Truth (Optional)", type=["pdf"])
+
+if uploaded_file is not None:
+    # Only process the file if it's a new upload or newly selected
+    if st.session_state.uploaded_filename != uploaded_file.name:
+        try:
+            reader = PyPDF2.PdfReader(uploaded_file)
+            extracted_text = ""
+            for page in reader.pages:
+                text = page.extract_text()
+                if text:
+                    extracted_text += text + "\n"
+            
+            if not extracted_text.strip():
+                st.warning("Could not extract text. Please ensure the PDF is text-searchable and not a scanned image.")
+            else:
+                st.session_state.context_text = extracted_text.strip()
+                st.session_state.uploaded_filename = uploaded_file.name
+        except Exception as e:
+            st.error(f"Error reading PDF: {e}")
+
+context = st.text_area(
+    "Source Context (The factual ground truth):", 
+    key="context_text",
+    height=150, 
+    placeholder="e.g., The Q3 financial report states that the company's revenue grew by 15%, reaching $50 million."
+)
+
+llm_output = st.text_area(
+    "LLM Output (The generated response to evaluate):", 
+    height=100, 
+    placeholder="e.g., The company had a great Q3, bringing in $60 million in revenue."
+)
+
+# 4. The Action Button
+if st.button("Detect Hallucination", type="primary", use_container_width=True):
+    if not context or not llm_output:
+        st.warning("⚠️ Please provide both a context and an LLM output to test.")
+    else:
+        # Show a premium animated status indicator while the API processes
+        with st.status("🔍 Extracting text and structuring context...", expanded=False) as status:
+            st.write("⏳ Creating overlapping sequence chunks (evading 512-token limit)...")
+            st.write("🧠 Evaluating chunk semantics against DeBERTa-v3 cross-encoder...")
+            
+            try:
+                # Send data to our FastAPI backend
+                response = requests.post(
+                    API_URL, 
+                    json={"context": context, "llm_output": llm_output}
+                )
+                response.raise_for_status() # Throw an error if the API crashes
+                
+                status.update(label="✅ Analysis Complete & Scores Aggregated!", state="complete", expanded=True)
+                
+                data = response.json()
+                results = data.get("results", {})
+
+                # 5. Display the Results
+                st.markdown("---")
+                
+                # Big visual alert
+                if results.get("is_hallucination"):
+                    st.error("🚨 **HALLUCINATION DETECTED (Contradiction > 60%)**")
+                else:
+                    st.success("✅ **FACTUALLY CONSISTENT**")
+                    
+                # Display exact percentages cleanly
+                st.subheader("NLI Confidence Scores")
+                
+                contradiction_score = results.get('contradiction_score', 0)
+                entailment_score = results.get('entailment_score', 0)
+                neutral_score = results.get('neutral_score', 0)
+                
+                # Dynamic Plain-English Summary
+                if contradiction_score > 15:
+                    st.warning("🚨 Warning: The AI is explicitly contradicting the source material.")
+                elif neutral_score > 50:
+                    st.warning("⚠️ Note: The AI is going off-script. It is bringing in outside knowledge not found in your source context.")
+                elif entailment_score > 50 and contradiction_score < 5:
+                    st.success("✅ Excellent: The AI is sticking strictly to the facts provided.")
+                    
+                # Generate dynamic contextual captions based on percentages
+                if contradiction_score >= 60:
+                    c_text = "- Meaning: The AI is heavily contradicting the source facts. Critical hallucination risk."
+                elif contradiction_score > 10:
+                    c_text = "- Meaning: Some distinct parts of the output directly oppose the source material."
+                else:
+                    c_text = "- Meaning: The AI is largely staying true to the facts with zero serious contradictions."
+                
+                if entailment_score >= 80:
+                    e_text = "- Meaning: Excellent! The AI is strictly summarizing the facts given to it."
+                elif entailment_score > 40:
+                    e_text = "- Meaning: The AI includes a fair mix of factual summaries alongside some conversational filler."
+                else:
+                    e_text = "- Meaning: Very little of the output is strictly supported by the source text."
+                    
+                if neutral_score >= 60:
+                    n_text = "- Meaning: The AI is heavily going off-script and bringing in outside knowledge/questions."
+                elif neutral_score > 10:
+                    n_text = "- Meaning: The AI is adding a moderate amount of conversational filler or harmless additions."
+                else:
+                    n_text = "- Meaning: The AI is strictly sticking to the provided context with almost no unverified additions."
+                
+                col1, col2, col3 = st.columns(3)
+                with col1:
+                    st.metric("Contradiction", f"{contradiction_score}%")
+                    st.caption(c_text)
+                with col2:
+                    st.metric("Entailment", f"{entailment_score}%")
+                    st.caption(e_text)
+                with col3:
+                    st.metric("Neutral", f"{neutral_score}%")
+                    st.caption(n_text)
+                
+
+
+            except requests.exceptions.ConnectionError:
+                st.error("🔌 Failed to connect to the backend. Is your FastAPI server running on port 8000?")
+            except Exception as e:
+                st.error(f"An error occurred: {e}")

requirements.txt

@@ -0,0 +1,21 @@
+# --- Machine Learning & NLP Core ---
+torch>=2.0.0
+transformers>=4.30.0
+datasets>=2.13.0
+scikit-learn>=1.2.2
+numpy>=1.24.0
+pandas>=2.0.0
+
+# --- API Backend & Database ---
+fastapi>=0.100.0
+uvicorn[standard]>=0.22.0
+pydantic>=2.0.0
+sqlalchemy>=2.0.0
+asyncpg>=0.28.0
+
+# --- Frontend Dashboard ---
+streamlit>=1.25.0
+
+# --- Utilities & Testing ---
+python-dotenv>=1.0.0
+pytest>=7.4.0

run.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# Start the FastAPI backend in the background
+echo "Starting FastAPI Backend..."
+uvicorn api.main:app --host 127.0.0.1 --port 8000 &
+
+# Wait a few seconds to let the ML model load into memory
+sleep 10 
+
+# Start the Streamlit frontend on Hugging Face's required port
+echo "Starting Streamlit Frontend..."
+streamlit run frontend/app.py --server.port 7860 --server.address 0.0.0.0