metadata

license: mit
title: PDF Insight PRO
sdk: docker
emoji: 💻
colorFrom: blue
colorTo: green
short_description: Agentic RAG APP

PDF Insight Pro

An advanced PDF document analysis tool that combines RAG (Retrieval Augmented Generation) with agentic search capabilities to provide intelligent answers to queries about PDF documents.

Overview
Features
RAG SYSTEM PERFORMANCE
Architecture
Technical Stack
Installation
Usage
API Endpoints
Deployment
Android App
License

Overview

PDF Insight Pro is a sophisticated document analysis tool that allows users to upload PDF documents and ask questions about their content. The system uses state-of-the-art RAG techniques, combining document chunking, embedding generation, similarity search, and LLM processing to provide accurate and contextually relevant answers.

The application employs an agentic approach that can augment the document's information with web search capabilities when needed, ensuring comprehensive and up-to-date responses.

Features

PDF Document Processing: Upload and process PDF documents with automated text extraction and chunking
Agentic RAG System: Combines document retrieval with powerful LLM reasoning
Web Search Integration: Verifies document information with Tavily search API integration
Session Management: Persistent session handling for chat history and document context
Multiple LLM Support: Choose from different language models (Llama 4 Scout, Llama 3.1, Llama 3.3)
FastAPI Backend: High-performance API with async support
Responsive UI: User-friendly interface adaptable to different screen sizes
Docker Containerization: Easy deployment with containerized application
Hugging Face Integration: Automatic deployment to Hugging Face Spaces
Android Application: Native mobile client

RAG System Metrics

Key Metrics Overview:

Metric	Value
Semantic Similarity (Mean)	`0.852`
ROUGE-L F1 Score (Mean)	`0.395`
Semantic Similarity (Max)	`1.000`
ROUGE-L F1 Score (Max)	`1.000`
Semantic Similarity (Min)	`0.592`
ROUGE-L F1 Score (Min)	`0.099`
Standard Deviation (Similarity)	`0.089`
Standard Deviation (ROUGE-L F1)	`0.217`

Quantile Distribution:

Percentile	Semantic Similarity	ROUGE-L F1 Score
25%	`0.7946`	`0.2516`
50%	`0.8732`	`0.3256`
75%	`0.9181`	`0.4951`

Evaluation Status:

Status	Count	Percentage
PASS	`64`	`85.3%`
FAIL	`11`	`14.7%`

Architecture

The application follows a modular architecture with these main components:

System Architecture Diagram

---
config:
  theme: forest
  look: neo
  layout: dagre
---
flowchart TD
 subgraph subGraph0["Presentation Layer"]
    direction TB
        Browser["Web Browser UI"]
        Android["Android WebView Client"]
  end
 subgraph subGraph1["API Layer"]
    direction TB
        APIGateway["FastAPI Entrypoints"]
        ChatRoutes["chat_routes.py"]
        SessionRoutes["session_routes.py"]
        UploadRoutes["upload_routes.py"]
        UtilityRoutes["utility_routes.py"]
        AppMain["app.py"]
  end
 subgraph subGraph2["Config & Models"]
    direction TB
        ConfigLoader["config.py"]
        DataModels["models.py"]
  end
 subgraph subGraph3["Service Layer"]
    direction TB
        RAGService["rag_service.py"]
        LLMService["llm_service.py"]
        SessionService["session_service.py"]
  end
 subgraph subGraph4["Utility Layer"]
    direction TB
        TextProc["text_processing.py"]
        FaissUtil["faiss_utils.py"]
        SessionUtil["session_utils.py"]
  end
 subgraph Storage["Storage"]
    direction TB
        UploadStore["/uploads (PDFs & sessions)"]
        FAISSIndex["FAISS Index (ephemeral/disk)"]
  end
 subgraph subGraph6["Docker Container"]
    direction TB
        subGraph1
        subGraph2
        subGraph3
        subGraph4
        Storage
  end
 subgraph subGraph7["External & DevOps"]
    direction TB
        GroqAPI["Groq LLM API"]
        TavilyAPI["Tavily Web Search API"]
        CI["GitHub Actions CI/CD"]
        HFS["HuggingFace Spaces"]
        DockerfileNode["Dockerfile"]
  end
 subgraph subGraph8["Static Assets"]
    direction TB
        StaticApp["Static Web App"]
  end
    Browser -- HTTP JSON --> StaticApp
    StaticApp -- HTTP JSON --> AppMain
    Android -- HTTP JSON --> AppMain
    AppMain -- routes --> ChatRoutes & SessionRoutes & UploadRoutes & UtilityRoutes
    ChatRoutes -- calls --> RAGService
    SessionRoutes -- calls --> SessionService
    UploadRoutes -- calls --> TextProc
    UtilityRoutes -- calls --> SessionUtil
    RAGService -- uses --> LLMService & FaissUtil
    RAGService -- calls --> GroqAPI & TavilyAPI
    LLMService -- uses --> ConfigLoader
    SessionService -- uses --> SessionUtil
    TextProc -- writes/reads --> UploadStore
    SessionUtil -- writes/reads --> UploadStore
    FaissUtil -- reads/writes --> FAISSIndex
    CI -- build & deploy --> DockerfileNode
    DockerfileNode -- deploy --> HFS
     Browser:::frontend
     Android:::frontend
     APIGateway:::api
     ChatRoutes:::api
     SessionRoutes:::api
     UploadRoutes:::api
     UtilityRoutes:::api
     AppMain:::api
     ConfigLoader:::service
     DataModels:::service
     RAGService:::service
     LLMService:::service
     SessionService:::service
     TextProc:::util
     FaissUtil:::util
     SessionUtil:::util
     UploadStore:::util
     FAISSIndex:::util
     GroqAPI:::external
     TavilyAPI:::external
     CI:::devops
     HFS:::devops
     DockerfileNode:::devops
     StaticApp:::frontend
    classDef frontend fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef api fill:#DFFFD6,stroke:#333,stroke-width:1px
    classDef service fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef util fill:#E3E4FA,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef devops fill:#CCFFFF,stroke:#333,stroke-width:1px
    click Android "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/Android%20App/app/src/main/res/layout/activity_splash.xml"
    click ChatRoutes "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/api/chat_routes.py"
    click SessionRoutes "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/api/session_routes.py"
    click UploadRoutes "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/api/upload_routes.py"
    click UtilityRoutes "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/api/utility_routes.py"
    click AppMain "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/app.py"
    click ConfigLoader "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/configs/config.py"
    click DataModels "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/models/models.py"
    click RAGService "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/services/rag_service.py"
    click LLMService "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/services/llm_service.py"
    click SessionService "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/services/session_service.py"
    click TextProc "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/utils/text_processing.py"
    click FaissUtil "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/utils/faiss_utils.py"
    click SessionUtil "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/utils/session_utils.py"
    click CI "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/.github/workflows/sync_to_hf.yml"
    click DockerfileNode "https://github.com/jatin-mehra119/pdf-insight-beta/tree/main/Dockerfile"
    click StaticApp "https://github.com/jatin-mehra119/pdf-insight-beta/blob/main/static/js/app.js"

Backend Components

PDF Processing Module (preprocessing.py):
- Document loading and text extraction using PyMuPDF
- Intelligent chunking with metadata preservation
- Embedding generation with sentence transformers
- FAISS vector index for similarity search
RAG Engine:
- Context retrieval based on semantic similarity
- LLM integration using Groq API
- Agentic processing with tool-calling capabilities
- Web search augmentation with Tavily API
API Layer (app.py):
- FastAPI framework for REST endpoints
- Session management and persistence
- File upload and processing
- Chat interface and history management

Workflow

Document Processing:
- User uploads a PDF document
- System extracts text using PyMuPDF
- Text is chunked into semantically meaningful segments
- Embeddings are generated for each chunk
- A FAISS index is built for efficient similarity search
Query Processing:
- User submits a question about the document
- System retrieves relevant chunks using semantic similarity
- Relevant chunks are combined into a context window
- Context and query are sent to the LLM for processing
- Optional: Web search integration for fact verification
Response Generation:
- LLM generates a response based on the provided context
- If web search is enabled, additional information may be incorporated
- Response is returned to the user
- Chat history is updated and persisted

Project Structure

The project is organized into a modular architecture with clear separation of concerns:

PDF-Insight-Beta/
├── app.py                      # Main FastAPI application entry point
├── gen_dataset.py             # Dataset generation and RAG evaluation scripts
├── test_RAG.ipynb            # Jupyter notebook for RAG system testing and metrics
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Container configuration for deployment
├── LICENSE                    # MIT license file
├── README.md                 # Project documentation
├── README_hf.md              # Hugging Face Spaces specific documentation
├──
├── api/                       # API route handlers (modular FastAPI routes)
│   ├── __init__.py           # Exports all route handlers
│   ├── chat_routes.py        # Chat and conversation management endpoints
│   ├── session_routes.py     # Session lifecycle management
│   ├── upload_routes.py      # PDF upload and processing endpoints
│   └── utility_routes.py     # Utility endpoints (models, health checks)
├──
├── configs/                   # Configuration management
│   └── config.py             # Centralized configuration and environment variables
├──
├── models/                    # Pydantic data models
│   └── models.py             # Request/response models for API validation
├──
├── services/                  # Core business logic services
│   ├── __init__.py           # Service module initialization
│   ├── llm_service.py        # Language model integration and management
│   ├── rag_service.py        # RAG implementation with agentic capabilities
│   └── session_service.py    # Session persistence and management
├──
├── utils/                     # Utility functions and helpers
│   ├── __init__.py           # Utility module initialization
│   ├── faiss_utils.py        # FAISS vector database operations
│   ├── session_utils.py      # Session data serialization/deserialization
│   └── text_processing.py    # PDF text extraction and chunking utilities
├──
├── static/                    # Frontend web application
│   ├── index.html            # Main web interface
│   ├── css/
│   │   └── styles.css        # Application styling and responsive design
│   └── js/
│       └── app.js            # Frontend JavaScript for user interactions
├──
├── development_scripts/       # Legacy and development utilities
│   ├── app.py               # Original monolithic application (deprecated)
│   └── preprocessing.py      # Original preprocessing functions (deprecated)
├──
├── uploads/                   # Temporary storage for uploaded files and sessions
│   ├── *.pdf                # Uploaded PDF documents
│   └── *_session.pkl        # Serialized session data
├──
└── Android App/              # Native Android application
    ├── app/                  # Android app source code
    │   ├── src/main/java/com/jatinmehra/  # Java source files
    │   ├── src/main/res/     # Android resources (layouts, drawables, etc.)
    │   └── AndroidManifest.xml  # Android app configuration
    ├── gradle/               # Gradle build system files
    └── build.gradle          # Project build configuration

Key Components Description

Core Application Files

app.py: Main FastAPI application that orchestrates all components and sets up the web server
gen_dataset.py: Comprehensive evaluation script for RAG system performance using the neural-bridge dataset
test_RAG.ipynb: Interactive Jupyter notebook for testing RAG capabilities and analyzing metrics

API Layer (`api/`)

chat_routes.py: Handles chat interactions, query processing, and conversation flow
session_routes.py: Manages session lifecycle, history retrieval, and cleanup operations
upload_routes.py: Processes PDF uploads, text extraction, and document indexing
utility_routes.py: Provides system utilities like model listing and health checks

Configuration (`configs/`)

config.py: Centralizes all application settings, API keys, model configurations, and environment variables

Data Models (`models/`)

models.py: Defines Pydantic models for request/response validation and API documentation

Business Logic (`services/`)

llm_service.py: Manages language model interactions, prompt engineering, and response generation
rag_service.py: Implements the core RAG pipeline with agentic search capabilities and tool integration
session_service.py: Handles session persistence, chat history, and user context management

Utilities (`utils/`)

faiss_utils.py: Provides FAISS vector database operations for similarity search and indexing
session_utils.py: Handles session serialization, deserialization, and data persistence
text_processing.py: PDF text extraction, intelligent chunking, and preprocessing utilities

Frontend (`static/`)

index.html: Responsive web interface with modern UI design
styles.css: CSS styling with mobile-first responsive design principles
app.js: JavaScript for dynamic interactions, file uploads, and chat functionality

Mobile Application (`Android App/`)

Native Android client: WebView-based mobile application that interfaces with the web app
Java source code: Activity management, splash screen, and WebView configuration
Android resources: UI layouts, icons, and mobile-specific configurations

Technical Stack

Backend

Python 3.12: Core programming language
FastAPI: API framework with async support
PyMuPDF: PDF processing library
LangChain: Framework for LLM application development
FAISS: Vector similarity search library from Facebook AI
Sentence Transformers: Text embedding generation
Groq API: LLM inference service
Tavily API: Web search integration
Uvicorn: ASGI server

Frontend

HTML/CSS/JavaScript: Core web technologies
Font Awesome: Icon library
Highlight.js: Code syntax highlighting
Marked.js: Markdown rendering
Responsive Design: Mobile-friendly interface

Note: The frontend was developed with assistance from Claude 3.7 AI.

DevOps

Docker: Containerization
GitHub Actions: CI/CD pipeline
Hugging Face Spaces: Deployment platform

Installation

Prerequisites

Python 3.12+
API keys for Groq and Tavily

Local Setup

Clone the repository:

git clone https://github.com/Jatin-Mehra119/PDF-Insight-Beta.git
cd PDF-Insight-Beta

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Create a .env file with your API keys:

GROQ_API_KEY=your_groq_api_key
TAVILY_API_KEY=your_tavily_api_key

Run the application:

uvicorn app:app --host 0.0.0.0 --port 8000 --reload

Docker Deployment

Build the Docker image:

docker build -t pdf-insight-pro .

Run the container:

docker run -p 7860:7860 \
  --mount type=secret,id=GROQ_API_KEY,dst=/run/secrets/GROQ_API_KEY \
  --mount type=secret,id=TAVILY_API_KEY,dst=/run/secrets/TAVILY_API_KEY \
  pdf-insight-pro

Usage

Open the application in your browser at http://localhost:8000
Upload a PDF document using the interface
Wait for processing to complete
Ask questions about the document in the chat interface
Toggle the "Use web search" option for enhanced responses

API Endpoints

GET /: Redirect to static HTML interface
POST /upload-pdf: Upload and process a PDF document
- Returns a session ID for subsequent queries
POST /chat: Send a query about the uploaded document
- Requires session ID from previous upload
- Optional parameter to enable web search
POST /chat-history: Retrieve chat history for a session
POST /clear-history: Clear chat history for a session
POST /remove-pdf: Remove PDF and session data
GET /models: List available language models

Deployment

Hugging Face Spaces

This project is configured for automatic deployment to Hugging Face Spaces using GitHub Actions. The workflow in .github/workflows/sync_to_hf.yml handles the deployment process.

To deploy to your own space:

Fork this repository
Create a Hugging Face Space
Add your Hugging Face token as a GitHub secret named HF_TOKEN
Update the username and space name in the workflow file
Push to the main branch to trigger deployment

Android App

The repository includes an Android application that serves as a mobile interface to the web application. Rather than implementing a native client with direct API integration, the Android app utilizes a WebView component to load the deployed web interface from Hugging Face Spaces. This approach ensures consistency between the web and mobile experiences while reducing maintenance overhead.

Android App Features

WebView integration to the deployed web application
Splash screen with app branding
Responsive design that adapts to the mobile interface
Native Android navigation and user experience
Direct access to the full functionality of the web application

Implementation Details

The Android app is implemented using Java and consists of:

SplashActivity: Displays the app logo and transitions to the main activity
MainActivity: Contains a WebView component that loads the deployed web application
WebView configuration: Enables JavaScript, DOM storage, and handles file uploads

License

MIT

Spaces:

jatinmehra
/

PDF-Insight-PRO

Running

PDF Insight Pro

Table of Contents

Overview

Features

RAG System Metrics

Architecture

System Architecture Diagram

Backend Components

Workflow

Project Structure

Key Components Description

Core Application Files

API Layer (`api/`)

Configuration (`configs/`)

Data Models (`models/`)

Business Logic (`services/`)

Utilities (`utils/`)

Frontend (`static/`)

Mobile Application (`Android App/`)

Technical Stack

Backend

Frontend

DevOps

Installation

Prerequisites

Local Setup

Docker Deployment

Usage

API Endpoints

Deployment

Hugging Face Spaces

Android App

Android App Features

Implementation Details

License

PDF Insight Pro

Table of Contents

Overview

Features

RAG System Metrics

Architecture

System Architecture Diagram

Backend Components

Workflow

Project Structure

Key Components Description

Core Application Files

API Layer (api/)

Configuration (configs/)

Data Models (models/)

Business Logic (services/)

Utilities (utils/)

Frontend (static/)

Mobile Application (Android App/)

Technical Stack

Backend

Frontend

DevOps

Installation

Prerequisites

Local Setup

Docker Deployment

Usage

API Endpoints

Deployment

Hugging Face Spaces

Android App

Android App Features

Implementation Details

License

API Layer (`api/`)

Configuration (`configs/`)

Data Models (`models/`)

Business Logic (`services/`)

Utilities (`utils/`)

Frontend (`static/`)

Mobile Application (`Android App/`)