Upload 8 files

DEPLOYMENT.md

@@ -0,0 +1,120 @@
+# DocuChat_AI Deployment Guide
+
+This guide covers deploying DocuChat_AI as a Streamlit app on Hugging Face Spaces, with optional private access, OCR support, and evaluation workflows.
+
+## 1. Recommended Hugging Face Setup
+
+For the standard app:
+
+```text
+SDK: Streamlit
+Python: 3.10
+Hardware: CPU Basic or higher
+```
+
+Required files:
+
+```text
+app.py
+README.md
+requirements.txt
+runtime.txt
+.gitattributes
+assets/
+```
+
+Required secret:
+
+```text
+GROQ_API_KEY=your_groq_key_here
+```
+
+Optional private access secret:
+
+```text
+APP_PASSWORD=your_private_app_password
+```
+
+If `APP_PASSWORD` is set, the app shows a password screen before users can access the workspace. If it is not set, the app runs in public demo mode.
+
+## 2. OCR Deployment Notes
+
+DocuChat_AI includes an OCR fallback for scanned PDFs using:
+
+```text
+pypdfium2
+pytesseract
+Pillow
+Tesseract OCR binary
+```
+
+Python packages are installed from `requirements.txt`, but the Tesseract system binary may not be available in a normal Streamlit Space.
+
+For best OCR support, deploy using the included `Dockerfile`, which installs:
+
+```text
+tesseract-ocr
+poppler-utils
+```
+
+Recommended OCR setup:
+
+```text
+SDK: Docker
+Hardware: CPU Upgrade if processing larger scanned PDFs
+```
+
+If OCR dependencies are missing, the app fails gracefully and still works for normal text-based PDFs, DOCX, and TXT files.
+
+## 3. Evaluation Dashboard
+
+The Evaluation tab supports labeled RAG testing with CSV files.
+
+Required CSV columns:
+
+```text
+question,expected_answer
+```
+
+Optional column:
+
+```text
+expected_source
+```
+
+Example:
+
+```csv
+question,expected_answer,expected_source
+What is the contract deadline?,The deadline is 15 June 2026.,contract.pdf page 3
+Who is the policy owner?,The policy owner is the HR department.,policy.pdf
+```
+
+Metrics shown:
+
+```text
+Correctness score
+Faithfulness score
+Confidence score
+Citation coverage
+Retrieved chunks
+```
+
+The correctness and faithfulness scores are LLM-judged and should be treated as practical evaluation signals, not formal benchmark results.
+
+## 4. Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `GROQ_API_KEY` | Yes | API key for Groq LLM inference |
+| `APP_PASSWORD` | No | Enables private password-protected app access |
+
+## 5. Production Recommendations
+
+- Use Hugging Face Secrets for all keys.
+- Use Docker mode if OCR is important.
+- Keep uploads temporary unless you add explicit user accounts and storage consent.
+- Add `APP_PASSWORD` for portfolio demos shared with recruiters.
+- Use the Evaluation tab with a small labeled test set before demos.
+- Use CPU Upgrade for larger PDFs or frequent OCR use.
+

Dockerfile

@@ -1,23 +1,36 @@
+# 1. Use an official lightweight Python image
 FROM python:3.10-slim
 
+# 2. Set the working directory inside the container
 WORKDIR /app
 
-ENV PYTHONDONTWRITEBYTECODE=1
-ENV PYTHONUNBUFFERED=1
-ENV PIP_NO_CACHE_DIR=1
-
-RUN apt-get update && apt-get install -y --no-install-recommends \
+# 3. Install system dependencies for FAISS and PDF processing
+RUN apt-get update && apt-get install -y \
     build-essential \
     curl \
+    software-properties-common \
+    git \
+    tesseract-ocr \
+    poppler-utils \
     && rm -rf /var/lib/apt/lists/*
 
+# 4. Copy only requirements first to leverage Docker caching
 COPY requirements.txt .
-RUN pip install --upgrade pip && pip install -r requirements.txt
 
+# 5. Install Python dependencies
+RUN pip3 install --no-cache-dir -r requirements.txt
+
+# 6. Copy the rest of your application code
 COPY . .
 
+# 7. Create the temporary directory for document uploads
+RUN mkdir -p temp_docs && chmod 777 temp_docs
+
+# 8. Expose the default Streamlit port
 EXPOSE 8501
 
-HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health || exit 1
+# 9. Healthcheck to ensure the app is running
+HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health
 
-CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]
+# 10. Start the application
+ENTRYPOINT ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

README.md

@@ -1,6 +1,6 @@
 ---
 title: DocuChat_AI
-emoji: 💻
+emoji: 📄
 colorFrom: blue
 colorTo: indigo
 sdk: streamlit
@@ -11,181 +11,358 @@ pinned: false
 license: mit
 ---
 
-# Document Intelligence RAG Assistant
+<div align="center">
 
-Upload documents, generate summaries, and ask grounded questions using Retrieval-Augmented Generation.
+<img src="https://capsule-render.vercel.app/api?type=waving&height=230&color=0:2563EB,100:14B8A6&text=DocuChat_AI&fontColor=ffffff&fontSize=56&fontAlignY=35&desc=Document%20Intelligence%20RAG%20Assistant&descAlignY=58&descSize=20&animation=fadeIn" />
 
-## Demo
+<p>
+  <img src="https://readme-typing-svg.herokuapp.com?font=Fira+Code&size=17&duration=2800&pause=1000&color=2563EB&center=true&vCenter=true&width=800&lines=Chat+with+PDF%2C+DOCX+and+TXT+documents;AI-powered+summaries+with+source-backed+answers;RAG+pipeline+using+LangChain%2C+FAISS+and+Groq;Built+with+Streamlit+for+fast+document+intelligence" alt="Typing SVG" />
+</p>
 
-[Live Demo](YOUR_HUGGING_FACE_SPACE_URL)
+<p>
+  <a href="https://huggingface.co/spaces/dineshb/DocuChat_AI">
+    <img src="https://img.shields.io/badge/Live_Demo-Hugging_Face-FFD21E?style=for-the-badge&logo=huggingface&logoColor=black" alt="Live Demo" />
+  </a>
+  <a href="https://github.com/dineshbarri/DocuChat_AI">
+    <img src="https://img.shields.io/badge/GitHub-Repository-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub Repository" />
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-2EA44F?style=for-the-badge" alt="MIT License" />
+  </a>
+</p>
 
-Screenshots:
+<p>
+  <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" />
+  <img src="https://img.shields.io/badge/Streamlit-FF4B4B?style=for-the-badge&logo=streamlit&logoColor=white" />
+  <img src="https://img.shields.io/badge/LangChain-1C3C3C?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/FAISS-Vector_Search-2563EB?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Groq-LLM_API-F55036?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/HuggingFace-Embeddings-FFD21E?style=for-the-badge&logo=huggingface&logoColor=black" />
+</p>
 
-- `assets/app_home.png`
-- `assets/document_processing.png`
-- `assets/chat_with_sources.png`
+**DocuChat_AI is a high-end AI document chatbot that lets users upload documents, generate summaries, extract insights, and ask grounded questions with source citations.**
 
-## Problem Statement
+</div>
 
-Professionals often need to quickly understand long PDFs, policies, resumes, contracts, research papers, reports, meeting notes, and business documents. Reading every page manually is slow, and generic chatbots can hallucinate when they are not grounded in the source material.
+---
 
-Document Intelligence RAG Assistant helps users upload documents, generate structured summaries, ask questions, inspect source citations, and export useful outputs from a clean Streamlit interface.
+## 🚀 Live Application
 
-## Key Features
+Try the app here:
 
-- PDF, TXT, and DOCX upload
-- Document summarization with multiple modes
-- Question answering over uploaded files
-- FAISS vector search
-- HuggingFace sentence-transformer embeddings
-- Groq / LLM-powered generation
-- Source citations with file, page, chunk, and preview text
-- Chat history within the current session
-- Export summary and chat history as Markdown
-- Streamlit user interface
-- Hugging Face Spaces deployment support
+### 👉 [Launch DocuChat_AI on Hugging Face](https://huggingface.co/spaces/dineshb/DocuChat_AI)
 
-## Architecture
+DocuChat_AI is designed for students, analysts, recruiters, researchers, founders, and professionals who need to understand long documents quickly without manually reading every page.
 
-The app follows a lightweight RAG pipeline:
+---
 
-Document Upload -> Text Extraction -> Chunking -> Embeddings -> FAISS Vector Store -> Retriever -> LLM -> Grounded Answer with Sources
+## 🖼️ Application Screenshots
 
-```mermaid
-flowchart LR
-    A[Upload Documents] --> B[Extract Text]
-    B --> C[Split into Chunks]
-    C --> D[Generate Embeddings]
-    D --> E[FAISS Vector Store]
-    E --> F[Retriever]
-    F --> G[LLM]
-    G --> H[Answer with Citations]
-```
+> Add your screenshots inside the `assets/` folder using the exact filenames below. GitHub will automatically render them in this README.
+
+<div align="center">
+
+### 1. Premium Home Workspace
+<img src="assets/app_home.png" width="90%" alt="DocuChat_AI home workspace" />
+
+### 2. Document Processing and Indexing
+<img src="assets/document_processing.png" width="90%" alt="Document upload and processing workflow" />
+
+### 3. Chat with Source Citations
+<img src="assets/chat_with_sources.png" width="90%" alt="Document question answering with citations" />
+
+### 4. Summary and Analysis Tools
+<img src="assets/summary_tools.png" width="90%" alt="Summary and analysis tabs" />
+
+</div>
+
+---
 
-## Tech Stack
+## 📌 Project Overview
 
-- Python
-- Streamlit
-- LangChain
-- FAISS
-- HuggingFace sentence-transformers
-- Groq API / LLM provider
-- PyPDF and document loaders
-- Docker / Hugging Face Spaces
+Most professionals deal with long PDFs, reports, resumes, policy documents, contracts, research papers, business notes, and technical files. Reading everything manually takes time, and generic chatbots can hallucinate when they are not grounded in the source document.
+
+**DocuChat_AI solves this using Retrieval-Augmented Generation (RAG).**
+
+The app extracts text from uploaded documents, splits it into searchable chunks, converts those chunks into embeddings, stores them in a FAISS vector index, retrieves the most relevant context for each question, and generates answers using an LLM while keeping responses grounded in the uploaded content.
+
+---
+
+## ✨ Key Features
+
+| Feature | Description |
+| --- | --- |
+| 📄 Multi-document upload | Supports PDF, DOCX, and TXT files |
+| 🧠 RAG-based Q&A | Ask natural-language questions about uploaded documents |
+| 📋 Smart summaries | Generate executive summaries, study notes, email briefs, and key takeaways |
+| 🔎 Source citations | View retrieved document chunks used to answer each question |
+| 🧩 Workflow tabs | Chat, Summaries, Extract, Analyze, and Deliverables |
+| ⚡ Quick action buttons | One-click prompts for risks, decisions, action items, FAQs, and presentation outlines |
+| 📊 Index stats | Track processed files, pages, chunks, and processing time |
+| 🧾 Document classification | LLM-based classification into Research Paper, Contract, CV, Invoice, Policy, Report, or Other |
+| 🧬 Entity extraction | Extract people, organizations, dates, money values, and locations |
+| ⚠️ Risk detection | Surface legal risks, missing information, deadlines, and action items |
+| 📈 RAG quality metrics | Show retrieved chunks, confidence score, citation coverage, and context usage |
+| 🧪 Evaluation dashboard | Upload labeled test questions and score correctness, faithfulness, and citation coverage |
+| 🔍 OCR-ready processing | Optional scanned PDF OCR support for Docker deployments |
+| 🔐 Optional authentication | Protect demos with an `APP_PASSWORD` environment secret |
+| 💬 Chat history | Maintains conversation context during the active session |
+| ⬇️ Export support | Export chat history as Markdown |
+| 🔐 Secure key input | Uses Hugging Face Secrets, environment variables, or password input |
+
+---
+
+## 🧠 What Users Can Do
+
+- Upload a long PDF and ask: **"What are the main risks in this document?"**
+- Turn a document into an **executive summary**
+- Extract **names, dates, metrics, definitions, and action items**
+- Generate **meeting notes, FAQs, email briefs, and presentation outlines**
+- Ask follow-up questions using conversation history
+- Inspect citations to understand where the answer came from
+
+---
 
-## Local Setup
+## 🏗️ RAG Architecture
 
-1. Clone the repository:
+<div align="center">
+  <img src="assets/rag_architecture.svg" width="100%" alt="DocuChat AI RAG architecture diagram" />
+</div>
+
+### Pipeline Flow
+
+1. **Document Upload** - User uploads PDF, DOCX, or TXT files.
+2. **Text Extraction** - The app extracts readable text using document loaders.
+3. **Chunking** - Text is split into manageable chunks with overlap.
+4. **Embedding Generation** - Chunks are converted into vector embeddings.
+5. **Vector Search** - FAISS retrieves the most relevant chunks for each query.
+6. **LLM Generation** - Groq-powered models generate answers using retrieved context.
+7. **Citation Display** - The app shows source previews used for the answer.
+
+---
+
+## 🛠️ Tech Stack
+
+| Layer | Tools |
+| --- | --- |
+| Frontend | Streamlit |
+| LLM | Groq API |
+| RAG Framework | LangChain |
+| Vector Database | FAISS |
+| Embeddings | Hugging Face Sentence Transformers |
+| Document Loading | PyPDF, DOCX2TXT, LangChain loaders |
+| Text Splitting | LangChain text splitters + tiktoken |
+| Deployment | Hugging Face Spaces |
+| Language | Python |
+
+---
+
+## 📁 Repository Structure
+
+```text
+DocuChat_AI/
+│
+├── app.py                         # Main Streamlit application
+├── README.md                      # Project documentation
+├── requirements.txt               # Python dependencies
+├── runtime.txt                    # Python runtime version for Hugging Face
+├── Dockerfile                     # Optional container deployment file
+├── DEPLOYMENT.md                  # Deployment, auth, OCR, and evaluation guide
+├── eval_sample.csv                # Sample labeled evaluation file
+├── LICENSE                        # MIT License
+├── .gitignore                     # Local files and secrets ignored by Git
+├── .gitattributes                 # Hugging Face / Git file handling
+│
+└── assets/
+    ├── app_home.png               # Home UI screenshot
+    ├── document_processing.png    # Upload and processing screenshot
+    ├── chat_with_sources.png      # Chat answer and citations screenshot
+    └── summary_tools.png          # Summary / analysis tools screenshot
+```
+
+---
+
+## ⚙️ Local Setup
+
+### 1. Clone the Repository
 
 ```bash
-git clone YOUR_REPOSITORY_URL
-cd YOUR_REPOSITORY_NAME
+git clone https://github.com/dineshbarri/DocuChat_AI.git
+cd DocuChat_AI
 ```
 
-2. Create and activate a virtual environment:
+### 2. Create a Virtual Environment
 
 ```bash
 python -m venv .venv
-.venv\Scripts\activate
 ```
 
-On macOS/Linux:
+Activate it:
 
 ```bash
-python -m venv .venv
+# Windows
+.venv\Scripts\activate
+
+# macOS / Linux
 source .venv/bin/activate
 ```
 
-3. Install dependencies:
+### 3. Install Dependencies
 
 ```bash
 pip install -r requirements.txt
 ```
 
-4. Create a `.env` file:
+### 4. Add Your Groq API Key
+
+Create a `.env` file:
 
 ```env
-GROQ_API_KEY=your_api_key_here
+GROQ_API_KEY=your_groq_api_key_here
 ```
 
-5. Run the app:
+You can create a Groq API key from:
+
+👉 [https://console.groq.com/](https://console.groq.com/)
+
+### 5. Run the App
 
 ```bash
 streamlit run app.py
 ```
 
-## Hugging Face Spaces Deployment
+Open the local URL shown in your terminal.
+
+---
+
+## 🔑 How to Get a Groq API Key
+
+1. Go to [Groq Console](https://console.groq.com/)
+2. Sign in or create an account
+3. Open **API Keys**
+4. Create a new API key
+5. Copy the key
+6. Paste it into the app sidebar or save it in `.env`
+
+For Hugging Face Spaces, add it as a secret:
+
+```text
+GROQ_API_KEY = your_key_here
+```
+
+---
+
+## 🚢 Hugging Face Deployment
 
 1. Create a new Hugging Face Space.
-2. Choose Streamlit as the Space SDK.
-3. Upload `app.py`, `README.md`, `requirements.txt`, `runtime.txt`, `.gitattributes`, and the `assets/` folder. `Dockerfile` is included for GitHub/Docker users, but a normal Streamlit Space does not require it.
-4. Add `GROQ_API_KEY` under Space Settings -> Secrets.
-5. Confirm `app.py` is the entry point.
-6. Restart the Space if dependencies are updated.
+2. Choose **Streamlit** as the SDK.
+3. Upload:
+   - `app.py`
+   - `README.md`
+   - `requirements.txt`
+   - `runtime.txt`
+   - `.gitattributes`
+   - `assets/`
+4. Add `GROQ_API_KEY` in **Settings -> Secrets**.
+5. Optional: add `APP_PASSWORD` in **Settings -> Secrets** to protect the app.
+6. Restart the Space after dependency changes.
+
+For scanned PDF OCR, use the included Dockerfile because OCR needs system packages such as Tesseract.
+
+See [DEPLOYMENT.md](DEPLOYMENT.md) for the full deployment guide.
+
+---
 
-The app is designed to run on Hugging Face Spaces CPU. It uses CPU-compatible embeddings and avoids GPU-only dependencies.
+## 💡 Example Questions
 
-## Usage Guide
+Try these after uploading and processing a document:
 
-1. Upload one or more PDF, TXT, or DOCX files.
-2. Click **Process documents** to extract text, chunk content, generate embeddings, and build a FAISS index.
-3. Choose a summary mode and click **Generate summary**.
-4. Ask document-specific questions in the chat tab.
-5. Open source citations under each answer to inspect retrieved evidence.
-6. Export the summary or chat history as Markdown.
+```text
+Summarize this document in 6 crisp bullet points.
+```
+
+```text
+What are the key risks, warnings, or limitations?
+```
 
-## Example Questions
+```text
+Extract all names, dates, numbers, and important terms.
+```
 
-- "Summarize this document in 5 bullet points."
-- "What are the key risks mentioned?"
-- "Extract all dates, people, and organizations."
-- "What are the main recommendations?"
-- "Explain the document for a non-technical audience."
-- "What evidence supports this answer?"
+```text
+Create an action-item checklist from this document.
+```
 
-## Project Structure
+```text
+Explain this document like I am new to the topic.
+```
 
 ```text
-.
-├── app.py
-├── README.md
-├── requirements.txt
-├── runtime.txt
-├── Dockerfile
-├── .gitattributes
-└── assets/
-    └── .gitkeep
+Create a presentation outline from this document.
 ```
 
-## Privacy and Security
+---
 
-- API keys are read from Hugging Face Space secrets, environment variables, or a password input field.
-- Uploaded documents are processed through temporary files and are not intentionally stored by the app.
-- The FAISS index and chat history live only in the active Streamlit session.
-- Users should avoid uploading highly sensitive documents to public demo deployments.
+## 🔐 Privacy and Security
 
-## Limitations
+- Uploaded files are processed through temporary files.
+- The app does not intentionally store user documents.
+- The FAISS index and chat history live inside the active Streamlit session.
+- API keys should be stored in environment variables or Hugging Face Secrets.
+- Avoid uploading highly confidential documents to public demo environments.
 
-- Quality depends on uploaded document text extraction.
-- Scanned PDFs may require OCR, which is not included in this version.
-- LLM answers are grounded in retrieved chunks, but users should verify important outputs.
-- Free Hugging Face Spaces may have CPU and memory limits.
-- Very large documents may need smaller files or reduced chunk settings.
+---
 
-## Future Improvements
+## ⚠️ Limitations
 
-- OCR for scanned PDFs
-- Multi-document comparison
-- Persistent vector database option
-- User authentication
-- Retrieval quality evaluation metrics
-- CSV, Excel, and HTML support
-- Better citation highlighting inside source documents
+- Scanned PDF OCR requires optional OCR dependencies and works best in Docker mode.
+- Very large documents may be limited by CPU and memory on free hosting.
+- Complex tables may not extract perfectly from PDFs.
+- LLM answers should be reviewed for critical legal, medical, financial, or compliance use cases.
+- Citation quality depends on document extraction and retrieval quality.
+
+---
 
-## Why This Project Matters
+## 🚀 Future Improvements
 
-This project demonstrates practical skills across RAG architecture, document NLP, vector search, LLM integration, Streamlit product UI, Hugging Face deployment, and AI-assisted workflow automation. It is relevant for Data Analyst, Data Scientist, AI Engineer, and RAG Engineer portfolios because it turns unstructured documents into searchable, explainable, and exportable insights.
+- Multi-document comparison mode
+- Persistent user workspaces
+- Better page-level citation highlighting
+- CSV, Excel, PPTX, and web page support
+- Reranking for improved retrieval accuracy
+- Authentication and private document libraries
+- Downloadable summary reports
+- Evaluation dashboard for retrieval quality
+
+---
+
+## 🧑‍💻 Author
+
+<div align="center">
+
+### Built by **Dinesh Barri**
+
+Data Analyst | AI Automation Engineer | Founder @ Plemdo AI
+
+<p>
+  <a href="https://dineshbarri.dev">
+    <img src="https://img.shields.io/badge/Portfolio-dineshbarri.dev-FF5722?style=for-the-badge&logo=vercel&logoColor=white" />
+  </a>
+  <a href="https://github.com/dineshbarri">
+    <img src="https://img.shields.io/badge/GitHub-dineshbarri-181717?style=for-the-badge&logo=github&logoColor=white" />
+  </a>
+  <a href="https://www.linkedin.com/in/dinesh-barri-7654b010b/">
+    <img src="https://img.shields.io/badge/LinkedIn-Dinesh%20Barri-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" />
+  </a>
+  <a href="mailto:dineshbarri1997@gmail.com">
+    <img src="https://img.shields.io/badge/Email-dineshbarri1997%40gmail.com-D14836?style=for-the-badge&logo=gmail&logoColor=white" />
+  </a>
+</p>
+
+</div>
+
+---
 
-## License
+## ⭐ Support
 
-MIT License.
+If you found this project useful, consider giving it a star on GitHub. It helps the project reach more developers, recruiters, and AI builders.

app.py

@@ -3,6 +3,8 @@ import time
 import json
 import hashlib
 import tempfile
+import csv
+import io
 import streamlit as st
 from dotenv import load_dotenv
 from datetime import datetime
@@ -15,6 +17,7 @@ from langchain_community.vectorstores import FAISS
 from langchain_community.document_loaders import PyPDFLoader, TextLoader, Docx2txtLoader
 from langchain_huggingface import HuggingFaceEmbeddings
 from langchain_core.messages import HumanMessage, AIMessage
+from langchain_core.documents import Document
 from langchain.chains import create_history_aware_retriever
 from langchain_core.output_parsers import StrOutputParser
 
@@ -23,7 +26,7 @@ from langchain_core.output_parsers import StrOutputParser
 # ─────────────────────────────────────────────
 load_dotenv()
 st.set_page_config(
-    page_title="DocuChat_AI",
+    page_title="DocuChat_AT",
     page_icon="📄",
     layout="wide",
     initial_sidebar_state="expanded"
@@ -290,6 +293,9 @@ for key, default in {
     "doc_stats": {},
     "doc_intelligence": {},
     "rag_metrics": {},
+    "eval_results": [],
+    "eval_summary": {},
+    "auth_ok": False,
     "last_file_hash": "",
     "full_raw_text": "", # BUG FIX: Stores text so summary can use it without reloading
     "pending_query": "",
@@ -336,7 +342,62 @@ def compute_files_hash(files) -> str:
         h.update(str(f.size).encode())
     return h.hexdigest()
 
-def load_documents(files) -> list:
+def require_authentication():
+    app_password = os.getenv("APP_PASSWORD", "").strip()
+    if not app_password:
+        st.session_state.auth_ok = True
+        return
+    if st.session_state.auth_ok:
+        return
+
+    st.markdown("### 🔐 Private Workspace")
+    st.caption("This deployment is protected. Enter the app password to continue.")
+    password = st.text_input("App Password", type="password", placeholder="Enter workspace password")
+    if st.button("Unlock Workspace", type="primary"):
+        if password == app_password:
+            st.session_state.auth_ok = True
+            st.rerun()
+        else:
+            st.error("Incorrect password.")
+    st.stop()
+
+def ocr_pdf_pages(pdf_path: str, source_name: str, max_pages: int = 8) -> list:
+    """Optional OCR for scanned PDFs. Requires pypdfium2, pytesseract, Pillow, and Tesseract binary."""
+    try:
+        import pypdfium2 as pdfium
+        import pytesseract
+    except Exception as e:
+        raise RuntimeError("OCR packages are not installed. Install pypdfium2, pytesseract, and Pillow.") from e
+
+    docs = []
+    pdf = pdfium.PdfDocument(pdf_path)
+    page_count = min(len(pdf), max_pages)
+    for page_index in range(page_count):
+        page = pdf[page_index]
+        bitmap = page.render(scale=2.0)
+        image = bitmap.to_pil()
+        text = pytesseract.image_to_string(image)
+        if text.strip():
+            docs.append(
+                Document(
+                    page_content=text,
+                    metadata={
+                        "source": source_name,
+                        "page": page_index,
+                        "extraction": "ocr",
+                    },
+                )
+            )
+    return docs
+
+def normalize_source_metadata(docs: list, source_name: str, file_type: str, extraction: str = "text") -> list:
+    for doc in docs:
+        doc.metadata["source"] = source_name
+        doc.metadata["file_type"] = file_type
+        doc.metadata.setdefault("extraction", extraction)
+    return docs
+
+def load_documents(files, use_ocr: bool = False, ocr_page_limit: int = 8) -> list:
     """Safely load documents using tempfile (No local folder clutter)."""
     docs = []
     for file in files:
@@ -354,6 +415,12 @@ def load_documents(files) -> list:
                 loader = TextLoader(temp_path, encoding="utf-8")
             
             loaded = loader.load()
+            loaded = normalize_source_metadata(loaded, file.name, ext, "text")
+            if ext == ".pdf" and use_ocr:
+                extracted_chars = sum(len(doc.page_content.strip()) for doc in loaded)
+                if extracted_chars < 250:
+                    st.write(f"🔍 Running OCR for scanned PDF: {file.name}")
+                    loaded = ocr_pdf_pages(temp_path, file.name, max_pages=ocr_page_limit)
             docs.extend(loaded[:MAX_PAGES]) 
         except Exception as e:
             st.error(f"⚠️ Error loading `{file.name}`: {e}")
@@ -363,7 +430,7 @@ def load_documents(files) -> list:
     return docs
 
 def export_chat() -> str:
-    lines = [f"# DocuChat_AI Export — {datetime.now().strftime('%Y-%m-%d %H:%M')}\n"]
+    lines = [f"# DocuChat_AT Export — {datetime.now().strftime('%Y-%m-%d %H:%M')}\n"]
     for m in st.session_state.messages:
         role = "👤 User" if m["role"] == "user" else "🤖 Assistant"
         lines.append(f"**{role}:** {m['content']}\n")
@@ -483,6 +550,148 @@ def calculate_rag_metrics(retrieved_docs, top_k: int, context_chars: int, answer
         "generated_at": datetime.now().strftime("%H:%M:%S"),
     }
 
+def build_retriever(llm, top_k: int):
+    retriever = st.session_state.vectors.as_retriever(
+        search_type="mmr",
+        search_kwargs={"k": top_k, "fetch_k": top_k * 3},
+    )
+    ctx_prompt = ChatPromptTemplate.from_messages([
+        ("system", "Given the chat history and the latest user question, rephrase it as a standalone search query. Return ONLY the reformulated query."),
+        MessagesPlaceholder("chat_history"),
+        ("human", "{input}"),
+    ])
+    return create_history_aware_retriever(llm, retriever, ctx_prompt)
+
+def format_retrieved_context(retrieved_docs: list) -> tuple[str, int]:
+    context_parts = []
+    total_chars = 0
+    for doc in retrieved_docs:
+        if total_chars + len(doc.page_content) <= MAX_CONTEXT_CHARS:
+            context_parts.append(doc.page_content)
+            total_chars += len(doc.page_content)
+        else:
+            remaining = MAX_CONTEXT_CHARS - total_chars
+            if remaining > 200:
+                context_parts.append(doc.page_content[:remaining])
+                total_chars += remaining
+            break
+    return "\n\n---\n\n".join(context_parts), total_chars
+
+def answer_from_documents(llm, user_query: str, top_k: int, chat_history=None) -> dict:
+    history = chat_history if chat_history is not None else st.session_state.chat_history
+    history_aware_retriever = build_retriever(llm, top_k)
+    retrieved_docs = history_aware_retriever.invoke({
+        "input": user_query,
+        "chat_history": history,
+    })
+    formatted_context, total_chars = format_retrieved_context(retrieved_docs)
+    qa_prompt = ChatPromptTemplate.from_messages([
+        ("system", "You are an expert assistant. Answer using ONLY the provided context. If the answer isn't in the context, say so clearly.\n\nContext:\n{context}"),
+        MessagesPlaceholder("chat_history"),
+        ("human", "{input}"),
+    ])
+    qa_chain = qa_prompt | llm | StrOutputParser()
+    answer = qa_chain.invoke({
+        "input": user_query,
+        "chat_history": history,
+        "context": formatted_context,
+    })
+    return {
+        "answer": answer,
+        "retrieved_docs": retrieved_docs,
+        "context": formatted_context,
+        "context_chars": total_chars,
+        "metrics": calculate_rag_metrics(retrieved_docs, top_k, total_chars, answer),
+    }
+
+def parse_eval_csv(uploaded_file) -> list:
+    raw = uploaded_file.getvalue().decode("utf-8-sig")
+    reader = csv.DictReader(io.StringIO(raw))
+    rows = []
+    for row in reader:
+        question = (row.get("question") or row.get("Question") or "").strip()
+        expected = (row.get("expected_answer") or row.get("Expected Answer") or row.get("answer") or "").strip()
+        expected_source = (row.get("expected_source") or row.get("source") or "").strip()
+        if question and expected:
+            rows.append({
+                "question": question,
+                "expected_answer": expected,
+                "expected_source": expected_source,
+            })
+    return rows
+
+def judge_eval_answer(llm, question: str, expected_answer: str, actual_answer: str, context: str) -> dict:
+    judge_prompt = ChatPromptTemplate.from_template(
+        """
+        You are evaluating a RAG answer. Return ONLY valid JSON.
+
+        Score:
+        - correctness_score: 0-100, how well the actual answer matches the expected answer.
+        - faithfulness_score: 0-100, whether the actual answer is supported by the retrieved context.
+        - notes: one short sentence.
+
+        JSON schema:
+        {{
+          "correctness_score": 0-100,
+          "faithfulness_score": 0-100,
+          "notes": "short note"
+        }}
+
+        Question: {question}
+        Expected answer: {expected_answer}
+        Actual answer: {actual_answer}
+        Retrieved context: {context}
+        """
+    )
+    parsed = safe_json_loads((judge_prompt | llm | StrOutputParser()).invoke({
+        "question": question,
+        "expected_answer": expected_answer,
+        "actual_answer": actual_answer,
+        "context": context[:6000],
+    }))
+    return {
+        "correctness_score": int(parsed.get("correctness_score", 0) or 0),
+        "faithfulness_score": int(parsed.get("faithfulness_score", 0) or 0),
+        "notes": parsed.get("notes", "Evaluation completed."),
+    }
+
+def run_eval_suite(eval_rows: list, llm, top_k: int) -> tuple[list, dict]:
+    results = []
+    for index, row in enumerate(eval_rows, start=1):
+        rag = answer_from_documents(llm, row["question"], top_k, chat_history=[])
+        judge = judge_eval_answer(
+            llm,
+            row["question"],
+            row["expected_answer"],
+            rag["answer"],
+            rag["context"],
+        )
+        results.append({
+            "test_id": index,
+            "question": row["question"],
+            "expected_answer": row["expected_answer"],
+            "actual_answer": rag["answer"],
+            "retrieved_chunks": rag["metrics"]["retrieved_chunks"],
+            "citation_coverage": rag["metrics"]["citation_coverage"],
+            "confidence_score": rag["metrics"]["confidence_score"],
+            "correctness_score": judge["correctness_score"],
+            "faithfulness_score": judge["faithfulness_score"],
+            "notes": judge["notes"],
+        })
+
+    if not results:
+        return [], {}
+
+    summary = {
+        "tests": len(results),
+        "avg_correctness": round(sum(r["correctness_score"] for r in results) / len(results), 1),
+        "avg_faithfulness": round(sum(r["faithfulness_score"] for r in results) / len(results), 1),
+        "avg_confidence": round(sum(r["confidence_score"] for r in results) / len(results), 1),
+        "avg_citation_coverage": round(sum(r["citation_coverage"] for r in results) / len(results), 1),
+        "generated_at": datetime.now().strftime("%Y-%m-%d %H:%M"),
+    }
+    return results, summary
+
 def queue_prompt(prompt: str):
     st.session_state.pending_query = prompt
 
@@ -496,7 +705,7 @@ def render_hero():
             <div class="hero-layout">
                 <div>
                     <div class="hero-kicker">Document intelligence workspace</div>
-                    <h1>DocuChat_AI (Document Intelligence RAG Assistant)</h1>
+                    <h1>DocuChat_AT (Document Intelligence RAG Assistant)</h1>
                     <p>Upload documents, generate summaries, extract insights, and ask grounded questions with source citations.</p>
                 </div>
                 <aside class="signature-card">
@@ -537,9 +746,9 @@ def render_capability_cards():
         """
         <div class="feature-grid">
             <div class="feature-card"><strong>Ask Anything</strong><span>Chat with PDFs, Word files, and text documents using grounded answers.</span></div>
-            <div class="feature-card"><strong>Instant Briefs</strong><span>Generate executive summaries, study notes, and stakeholder-ready updates.</span></div>
-            <div class="feature-card"><strong>Deep Extraction</strong><span>Pull out action items, risks, decisions, dates, names, and definitions.</span></div>
-            <div class="feature-card"><strong>Source Citations</strong><span>Inspect the retrieved document chunks used to answer each question.</span></div>
+            <div class="feature-card"><strong>AI Intelligence</strong><span>Classify documents, extract entities, detect risks, and identify actions.</span></div>
+            <div class="feature-card"><strong>Eval Dashboard</strong><span>Run labeled test questions and score correctness, faithfulness, and citations.</span></div>
+            <div class="feature-card"><strong>OCR Ready</strong><span>Optional scanned PDF OCR with graceful fallback for Streamlit deployments.</span></div>
         </div>
         """,
         unsafe_allow_html=True,
@@ -627,6 +836,60 @@ def render_intelligence_panel():
                 q4.metric("Context Used", f"{metrics.get('context_utilization', 0)}%")
                 st.caption(f"Last evaluated at {metrics.get('generated_at', 'N/A')}. These are lightweight heuristic metrics for visibility, not formal benchmark scores.")
 
+def render_evaluation_panel():
+    if not st.session_state.vectors:
+        st.info("Process documents before running an evaluation suite.")
+        return
+
+    st.markdown("##### Upload labeled test questions")
+    st.caption("CSV columns required: question, expected_answer. Optional: expected_source.")
+    eval_file = st.file_uploader("Evaluation CSV", type=["csv"], key="eval_csv")
+
+    c1, c2 = st.columns([1, 1])
+    with c1:
+        run_eval = st.button("🧪 Run Evaluation", type="primary", use_container_width=True)
+    with c2:
+        clear_eval = st.button("Clear Evaluation", use_container_width=True)
+
+    if clear_eval:
+        st.session_state.eval_results = []
+        st.session_state.eval_summary = {}
+        st.rerun()
+
+    if run_eval:
+        if not eval_file:
+            st.warning("Upload a labeled CSV first.")
+        else:
+            rows = parse_eval_csv(eval_file)
+            if not rows:
+                st.error("No valid rows found. Use columns: question, expected_answer.")
+            else:
+                with st.spinner(f"Running {len(rows)} RAG evaluation tests..."):
+                    st.session_state.eval_results, st.session_state.eval_summary = run_eval_suite(rows, llm, top_k)
+                st.success("Evaluation complete.")
+
+    summary = st.session_state.get("eval_summary", {})
+    results = st.session_state.get("eval_results", [])
+    if summary:
+        m1, m2, m3, m4 = st.columns(4)
+        m1.metric("Tests", summary.get("tests", 0))
+        m2.metric("Correctness", f"{summary.get('avg_correctness', 0)}%")
+        m3.metric("Faithfulness", f"{summary.get('avg_faithfulness', 0)}%")
+        m4.metric("Citation Coverage", f"{summary.get('avg_citation_coverage', 0)}%")
+        st.caption(f"Generated at {summary.get('generated_at')}. Scores are LLM-judged and should be reviewed for critical use cases.")
+
+    if results:
+        st.markdown("##### Test Results")
+        st.dataframe(results, use_container_width=True, hide_index=True)
+        export = json.dumps({"summary": summary, "results": results}, indent=2)
+        st.download_button(
+            "⬇️ Download Evaluation JSON",
+            data=export,
+            file_name=f"docuchat_eval_{datetime.now().strftime('%Y%m%d_%H%M')}.json",
+            mime="application/json",
+            use_container_width=True,
+        )
+
 def render_workspace():
     render_hero()
     render_status_panel()
@@ -635,12 +898,13 @@ def render_workspace():
     st.markdown('<div class="section-title">Document command center</div>', unsafe_allow_html=True)
     st.markdown('<p class="section-copy">Choose a workflow or start with a suggested prompt. Each button sends a ready-made instruction to the assistant.</p>', unsafe_allow_html=True)
 
-    chat_tab, summary_tab, extract_tab, analyze_tab, intel_tab, deliver_tab = st.tabs([
+    chat_tab, summary_tab, extract_tab, analyze_tab, intel_tab, eval_tab, deliver_tab = st.tabs([
         "Chat",
         "Summaries",
         "Extract",
         "Analyze",
         "Intelligence",
+        "Evaluation",
         "Deliverables",
     ])
 
@@ -681,6 +945,10 @@ def render_workspace():
         st.markdown("#### AI document intelligence")
         render_intelligence_panel()
 
+    with eval_tab:
+        st.markdown("#### RAG evaluation dashboard")
+        render_evaluation_panel()
+
     with deliver_tab:
         st.markdown("#### Ready-to-use outputs")
         c1, c2, c3 = st.columns(3)
@@ -694,8 +962,14 @@ def render_workspace():
 # ─────────────────────────────────────────────
 # SIDEBAR UI
 # ─────────────────────────────────────────────
+require_authentication()
+
 with st.sidebar:
-    st.title("📄 DocuChat_AI")
+    st.title("📄 DocuChat_AT")
+    if os.getenv("APP_PASSWORD", "").strip():
+        st.success("🔐 Private mode enabled")
+    else:
+        st.caption("Public demo mode")
     
     if st.session_state.vectors:
         st.success("✅ Vector DB Ready", icon="🟢")
@@ -715,6 +989,8 @@ with st.sidebar:
     with st.expander("⚙️ Advanced Settings"):
         temperature = st.slider("Temperature", 0.0, 1.0, 0.3, 0.05)
         top_k = st.slider("Retrieved Chunks (Top-K)", 2, 10, 4)
+        use_ocr = st.checkbox("Enable OCR fallback for scanned PDFs", value=False)
+        ocr_page_limit = st.slider("OCR Page Limit", 1, 25, 8)
 
     st.divider()
 
@@ -736,7 +1012,7 @@ with st.sidebar:
         elif not uploaded_files:
             st.warning("⚠️ Upload files first.")
         else:
-            file_hash = compute_files_hash(uploaded_files)
+            file_hash = f"{compute_files_hash(uploaded_files)}-ocr-{use_ocr}-{ocr_page_limit}"
             force_reprocess = (file_hash != st.session_state.last_file_hash)
 
             if not force_reprocess and st.session_state.vectors:
@@ -747,7 +1023,7 @@ with st.sidebar:
                     t0 = time.time()
                     
                     st.write("📥 Loading files into memory...")
-                    raw_docs = load_documents(uploaded_files)
+                    raw_docs = load_documents(uploaded_files, use_ocr=use_ocr, ocr_page_limit=ocr_page_limit)
                     
                     if not raw_docs:
                         status.update(label="No content found!", state="error")
@@ -799,7 +1075,7 @@ with st.sidebar:
                     
                     # BUG FIX: Use the saved text instead of raw_docs
                     if not st.session_state.full_raw_text:
-                        temp_docs = load_documents(uploaded_files)
+                        temp_docs = load_documents(uploaded_files, use_ocr=use_ocr, ocr_page_limit=ocr_page_limit)
                         st.session_state.full_raw_text = " ".join([d.page_content for d in temp_docs])
                         
                     full_text = st.session_state.full_raw_text[:6000] 

assets/.gitkeep

@@ -1 +0,0 @@
-

eval_sample.csv

@@ -0,0 +1,4 @@
+question,expected_answer,expected_source
+What is the main purpose of this document?,Replace this with the expected answer from your uploaded document.,Document page or section
+What are the most important risks mentioned?,Replace this with the expected risk statement.,Document page or section
+Who are the key people or organizations mentioned?,Replace this with the expected names or organizations.,Document page or section

requirements.txt

@@ -6,8 +6,11 @@ langchain-community==0.2.16
 langchain-groq==0.1.10
 langchain-huggingface==0.0.3
 langchain-text-splitters==0.2.4
-faiss-cpu==1.13.2
-sentence-transformers==3.1.1
+faiss-cpu
+tiktoken==0.7.0
 pypdf==4.3.1
 docx2txt==0.8
-tiktoken==0.7.0
+sentence-transformers==3.1.1
+pypdfium2==4.30.0
+pytesseract==0.3.13
+Pillow==10.4.0