Update README.md

README.md

@@ -10,121 +10,130 @@ app_file: app.py
 pinned: false
 ---
 
-# ⚖️ Automated Legal Document Digitization System
+# ⚖️ Automated Legal Document Digitization System (ALDDS)
 
-Upload a photo of a legal document (bailable warrant, summon, etc.) and get back structured JSON data — automatically.
+![Python](https://img.shields.io/badge/Python-3.13-blue.svg)
+![Gradio](https://img.shields.io/badge/Gradio-6.14.0-orange.svg)
+![MongoDB](https://img.shields.io/badge/MongoDB-Atlas-green.svg)
+![Hugging Face](https://img.shields.io/badge/Deploy-Hugging%20Face-yellow.svg)
 
-## Pipeline
+Upload a photo of a legal document (bailable warrant, summon, etc.) and seamlessly convert it into structured JSON data. ALDDS handles the OCR, AI parsing, secure storage, and live dispatcher notifications in a single streamlined pipeline.
 
-```
-Image Upload → Cloudinary Hosting → Tesseract OCR → NVIDIA Qwen 2.5 LLM → Structured JSON
-```
-
----
-
-## Prerequisites
-
-### 1. Install Tesseract OCR (System Binary)
+## 🚀 Pipeline & Architecture
 
-Python's `pytesseract` is only a wrapper — you need the **Tesseract engine** installed on your OS.
-
-#### Windows
-1. Download the installer from: https://github.com/UB-Mannheim/tesseract/wiki
-2. Run the installer (default path: `C:\Program Files\Tesseract-OCR\`)
-3. **Add to PATH** or uncomment the line in `app.py`:
-   ```python
-   pytesseract.pytesseract.tesseract_cmd = r"C:\Program Files\Tesseract-OCR\tesseract.exe"
-   ```
-
-#### Linux (Debian / Ubuntu)
-```bash
-sudo apt-get update
-sudo apt-get install tesseract-ocr
+```text
+Image Upload → Cloudinary Hosting → Tesseract OCR → NVIDIA LLMs → MongoDB → Telegram IO Alert
 ```
 
-#### macOS
-```bash
-brew install tesseract
-```
-
-### 2. Verify Tesseract
-```bash
-tesseract --version
-```
+1. **OCR Extraction**: Uses Tesseract to extract raw text from image uploads.
+2. **AI Parsing**: Leverages advanced NVIDIA models (`qwen/qwen3-coder-480b-a35b-instruct`, Llama 3) to parse the unstructured OCR text into a strict 10-field JSON schema.
+3. **Secure Storage**: Automatically commits the digital record to a MongoDB database.
+4. **Live Dashboard**: A real-time, searchable Police Dashboard built directly into the UI.
+5. **Instant Notifications**: Dispatchers can ping Investigating Officers (IOs) via Telegram with the parsed data using a secure Frontend JavaScript bypass.
 
 ---
 
-## Setup
+## 📋 Features
 
-### 1. Clone & Install Dependencies
+- **Multi-Model Fallback**: The app cycles through a priority list of NVIDIA LLMs ensuring maximum uptime and reliability during the parsing phase.
+- **👮 Live Police Dashboard**: A dedicated tab for station dispatchers to monitor incoming warrants. Includes a real-time MongoDB search filter (by Case No, IO Name, Station, etc.).
+- **📨 Frontend JS Telegram Alerts**: Send an automated markdown summary and document link to an IO via Telegram. The request executes directly in the browser using JavaScript to bypass restrictive institutional or cloud IP firewalls (like Hugging Face).
 
-```bash
-cd police
-pip install -r requirements.txt
-```
+---
 
-### 2. Create a `.env` File
+## 🔑 Environment Setup
 
-Create a `.env` file in the project root with your credentials:
+To run ALDDS locally or in the cloud, you need the following API keys configured in a `.env` file (or as Secrets on Hugging Face).
 
 ```env
-# Cloudinary
+# Cloudinary (Image Hosting)
 CLOUDINARY_CLOUD_NAME=your_cloud_name
 CLOUDINARY_API_KEY=your_api_key
 CLOUDINARY_API_SECRET=your_api_secret
 
-# NVIDIA API
+# NVIDIA API (LLM Parsing)
 NVIDIA_API_KEY=your_nvidia_api_key
+
+# MongoDB (Database)
+MONGODB_URI=mongodb+srv://username:password@cluster0.../?retryWrites=true&w=majority
+
+# Telegram (IO Notifications)
+TELEGRAM_BOT_TOKEN=your_bot_token_here
 ```
 
 | Variable | Where to get it |
 |---|---|
 | `CLOUDINARY_*` | [Cloudinary Console](https://console.cloudinary.com/) → Dashboard |
 | `NVIDIA_API_KEY` | [NVIDIA Build](https://build.nvidia.com/) → API Catalog → Get API Key |
+| `MONGODB_URI` | [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) → Database → Connect |
+| `TELEGRAM_BOT_TOKEN` | [Telegram](https://core.telegram.org/bots) → @BotFather |
 
-### 3. Run the App
+---
+
+## 💻 Local Installation Guide
 
+### 1. Install Tesseract OCR (System Binary)
+Python's `pytesseract` requires the underlying Tesseract engine to be installed on your OS.
+
+**Windows**
+1. Download installer from: https://github.com/UB-Mannheim/tesseract/wiki
+2. Run installer (default path: `C:\Program Files\Tesseract-OCR\`)
+3. The app is hardcoded to look for this path on Windows.
+
+**Linux (Debian/Ubuntu)**
+```bash
+sudo apt-get update
+sudo apt-get install tesseract-ocr
+```
+
+**macOS**
 ```bash
+brew install tesseract
+```
+
+### 2. Run the App
+```bash
+# Clone repository
+git clone https://huggingface.co/spaces/LovnishVerma/ALDDS
+cd ALDDS
+
+# Install Dependencies
+pip install -r requirements.txt
+
+# Run the Server
 python app.py
 ```
+The interface will launch at **http://127.0.0.1:7860**.
+
+---
+
+## ☁️ Hugging Face Spaces Deployment
 
-The Gradio interface will launch at **http://127.0.0.1:7860**.
+If you are deploying ALDDS to Hugging Face Spaces, follow these critical steps:
+
+1. **Set Up Secrets**: Go to your Space **Settings** -> **Variables and secrets**. Add all variables from your `.env` file as **Secrets**.
+2. **System Dependencies**: Hugging Face runs Debian Linux. The repository includes a `packages.txt` file telling Hugging Face to install `tesseract-ocr` and `libtesseract-dev` during the Docker build.
+3. **CRLF Warning**: Ensure that `packages.txt` is saved with Unix (`LF`) line endings. If it has Windows (`CRLF`) line endings, the Hugging Face Docker build will fail with a `Package not found` error.
+4. **Restart**: Always click **Restart Space** after adding or modifying Secrets so the new environment variables are loaded into the container.
 
 ---
 
-## Output Fields
+## 📊 Extracted JSON Schema
 
-The LLM extracts these fields into a JSON object:
+The LLM is strictly prompted to extract the following fields. If a field cannot be found, it defaults to `null`.
 
-| Key | Description |
+| JSON Key | Description |
 |---|---|
-| `Case_FIR_Number` | FIR or case reference number |
-| `Act_and_Sections` | Applicable legal acts and sections |
+| `Case_FIR_Number` | FIR or court case reference number |
+| `Act_and_Sections` | Applicable IPC/CRPC legal acts and sections |
 | `Type_of_Document` | Warrant, summon, notice, etc. |
 | `Target_Police_Station` | Police station the document is addressed to |
 | `IO_Name_and_Belt_No` | Investigating Officer's name and belt number |
 | `IO_Mobile_Number` | IO's contact number |
-| `Person_Name_To_Serve` | Name of the person to be served |
-| `Person_Address` | Address of the person |
+| `Person_Name_To_Serve` | Name of the person to be served/arrested |
+| `Person_Address` | Address of the target person |
 | `Court_Name` | Issuing court name |
-| `Hearing_Date` | Scheduled hearing / appearance date |
+| `Hearing_Date` | Scheduled hearing or appearance date (DD-MM-YYYY) |
 
 ---
-
-## Project Structure
-
-```
-police/
-├── app.py              # Main application (single file)
-├── requirements.txt    # Python dependencies
-├── .env                # API keys (DO NOT commit)
-└── README.md           # This file
-```
-
----
-
-## Notes
-
-- OCR accuracy depends on image quality. Clear, well-lit photos produce the best results.
-- The LLM sets fields to `null` when they can't be extracted from the OCR text.
-- All uploaded images are stored in the `warrants/` folder on your Cloudinary account.
+*Built to streamline station workflows, eliminate manual data entry, and instantly notify field officers.*