feat: hybrid VLM parser with Qwen3-VL-8B via vLLM (v2.0.0)

CLAUDE.md

@@ -4,48 +4,43 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Docling Parser - A Hugging Face Spaces API service that deploys IBM's Docling library for PDF/document parsing. Transforms complex documents (PDFs, images) into LLM-ready markdown/JSON formats. API endpoints are protected by Bearer token authentication.
+Docling Parser (v2.0.0) - A Hugging Face Spaces API service using a hybrid two-pass VLM architecture for PDF/document parsing. Pass 1 runs Docling's standard pipeline (DocLayNet layout + TableFormer ACCURATE + RapidOCR baseline). Pass 2 sends full page images to Qwen3-VL-8B via vLLM for enhanced text recognition. The merge step preserves TableFormer tables while replacing RapidOCR text with VLM output. Includes OpenCV preprocessing (denoise, CLAHE contrast enhancement). API endpoints are protected by Bearer token authentication.
 
 ## Architecture
 
 ```
 hf_docling_parser/
-├── app.py              # FastAPI application with parsing endpoints
-├── Dockerfile          # HF Spaces Docker configuration (GPU-enabled)
-├── requirements.txt    # Python dependencies
-├── README.md           # HF Spaces metadata and API documentation
+├── app.py              # FastAPI + hybrid two-pass parsing (v2.0.0)
+├── start.sh            # Startup script (vLLM + FastAPI dual-process)
+├── Dockerfile          # vLLM base image, Qwen3-VL pre-downloaded
+├── requirements.txt    # Python deps (docling, opencv, pdf2image, etc.)
+├── README.md           # HF Spaces metadata
 ├── CLAUDE.md           # Claude Code development guide
 └── .gitignore          # Git ignore patterns
 ```
 
+**Dual-process Docker architecture:** `start.sh` launches vLLM on port 8000 (GPU model serving) and FastAPI on port 7860 (API). Base image: `vllm/vllm-openai:v0.14.1`.
+
 ## Common Commands
 
 ```bash
-# Local development
-pip install -r requirements.txt
-uvicorn app:app --host 0.0.0.0 --port 7860 --reload
+# Build and test Docker locally (requires A100 GPU)
+docker build --shm-size 32g -t hf-docling .
+docker run --gpus all --shm-size 32g -p 7860:7860 -e API_TOKEN=test hf-docling
 
 # Test the API locally
 curl -X POST "http://localhost:7860/parse" \
   -H "Authorization: Bearer YOUR_API_TOKEN" \
   -F "file=@document.pdf" \
   -F "output_format=markdown"
-
-# Build and test Docker locally
-docker build -t hf-docling .
-docker run --gpus all -p 7860:7860 -e API_TOKEN=test hf-docling
 ```
 
-## Deploying to Hugging Face Spaces
+> **Note:** Local dev without Docker is not practical — the hybrid pipeline requires vLLM + Qwen3-VL-8B running on an A100 GPU.
 
-### First-time Setup
+## Deploying to Hugging Face Spaces
 
-```bash
-hf auth login
-hf repo create docling-parser --repo-type space --space_sdk docker
-git init
-git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/docling-parser
-```
+- **Space URL:** https://huggingface.co/spaces/outcomelabs/docling-parser
+- **API URL:** https://outcomelabs-docling-parser.hf.space
 
 ### Push New Code
 
@@ -57,7 +52,7 @@ git push hf main
 
 ### Settings (configure in HF web UI)
 
-- **Hardware:** Nvidia A10G Large (24GB) or A100 (for larger docs)
+- **Hardware:** Nvidia A100 Large 80GB ($2.50/hr) — vLLM requires GPU
 - **Sleep time:** 1 hour (auto-shutdown after 60 min idle)
 - **Secrets:** `API_TOKEN` (required for API authentication)
 
@@ -78,37 +73,29 @@ git push hf main
 - **uvicorn**: ASGI server
 - **httpx**: HTTP client for URL parsing
 - **pydantic**: Request/response validation
-- **torch**: PyTorch for GPU acceleration
-
-## Environment Variables
+- **opencv-python-headless**: Image preprocessing (denoise, CLAHE)
+- **pdf2image**: PDF page to image conversion for VLM
+- **numpy**: Array operations for image processing
+- **huggingface-hub**: Model/space utilities
 
-| Variable           | Description                                       | Default    |
-| ------------------ | ------------------------------------------------- | ---------- |
-| `API_TOKEN`        | **Required.** Secret token for API authentication | -          |
-| `DO_OCR`           | Enable OCR by default                             | `true`     |
-| `TABLE_MODE`       | Table detection mode (accurate, fast)             | `accurate` |
-| `IMAGES_SCALE`     | Image resolution scale for extraction             | `3.0`      |
-| `DEFAULT_LANG`     | Default OCR language code                         | `en`       |
-| `MAX_FILE_SIZE_MB` | Maximum upload file size in MB                    | `1024`     |
+> **Note:** vLLM and PyTorch are provided by the base Docker image (`vllm/vllm-openai:v0.14.1`), not in `requirements.txt`.
 
-## Docling Pipeline Options
-
-The converter supports these key options:
+## Environment Variables
 
-- `do_ocr`: Enable/disable OCR for scanned documents
-- `do_table_structure`: Enable table structure detection
-- `table_structure_options.mode`: TableFormerMode.ACCURATE or FAST
-- `generate_picture_images`: Extract images from documents
-- `images_scale`: Resolution multiplier for extracted images
-- `accelerator_options.device`: cuda, mps, or cpu
+| Variable                     | Description                                       | Default                     |
+| ---------------------------- | ------------------------------------------------- | --------------------------- |
+| `API_TOKEN`                  | **Required.** Secret token for API authentication | -                           |
+| `MAX_FILE_SIZE_MB`           | Maximum upload file size in MB                    | `1024`                      |
+| `IMAGES_SCALE`               | Image resolution scale for page rendering         | `2.0`                       |
+| `VLM_MODEL`                  | VLM model for text recognition pass               | `Qwen/Qwen3-VL-8B-Instruct` |
+| `VLM_HOST`                   | vLLM server host                                  | `127.0.0.1`                 |
+| `VLM_PORT`                   | vLLM server port                                  | `8000`                      |
+| `VLM_GPU_MEMORY_UTILIZATION` | Fraction of GPU memory for vLLM                   | `0.70`                      |
+| `VLM_MAX_MODEL_LEN`          | Max sequence length for vLLM                      | `8192`                      |
 
 ## Testing
 
-### Start the server
-
-```bash
-API_TOKEN=test uvicorn app:app --host 0.0.0.0 --port 7860 --reload
-```
+> **Note:** Testing requires an A100 GPU with vLLM running. Use the Docker container for testing.
 
 ### Test with curl
 
@@ -163,12 +150,16 @@ The API provides comprehensive logging:
 
 ## Comparison with MinerU
 
-| Feature          | Docling                | MinerU              |
-| ---------------- | ---------------------- | ------------------- |
-| Maintainer       | IBM Research           | OpenDataLab         |
-| Table Detection  | TableFormer (built-in) | Multiple backends   |
-| OCR              | Built-in               | Built-in            |
-| VLM Support      | Optional               | Hybrid backend      |
-| License          | MIT                    | AGPL-3.0            |
-| GPU Memory       | ~8-12GB                | ~6-10GB (pipeline)  |
-| Primary Use Case | Enterprise documents   | General PDF parsing |
+| Feature          | Docling (Hybrid VLM)             | MinerU              |
+| ---------------- | -------------------------------- | ------------------- |
+| Maintainer       | IBM Research + Qwen3-VL          | OpenDataLab         |
+| Table Detection  | TableFormer (built-in)           | Multiple backends   |
+| OCR              | Qwen3-VL-8B via vLLM             | Built-in            |
+| VLM Support      | Hybrid (Standard + VLM two-pass) | Hybrid backend      |
+| License          | MIT                              | AGPL-3.0            |
+| GPU Memory       | ~24GB (vLLM + Docling)           | ~6-10GB (pipeline)  |
+| Primary Use Case | Enterprise documents             | General PDF parsing |
+
+## Workflow Orchestration, Task Management & Core Principles
+
+> **See root `CLAUDE.md`** for full Workflow Orchestration (plan mode, subagents, self-improvement, verification, elegance, bug fixing), Task Management, and Core Principles. Files: `<workspace-root>/tasks/todo.md`, `<workspace-root>/tasks/lessons.md`.

Dockerfile

@@ -1,9 +1,9 @@
-# Hugging Face Spaces Dockerfile for Docling Document Parser API
-# Optimized for GPU-accelerated document parsing
-# Build: v1.0.0 - Using IBM's Docling library
+# Hugging Face Spaces Dockerfile for Docling VLM Document Parser API
+# GPU-accelerated document parsing with Docling + Qwen3-VL-8B via vLLM
+# Build: v2.0.0 - Docling with VLM backend for superior accuracy
 
-# Use PyTorch base image with CUDA support
-FROM pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime
+# Use vLLM base image with CUDA, PyTorch, and vLLM pre-installed
+FROM vllm/vllm-openai:v0.14.1
 
 USER root
 
@@ -23,8 +23,6 @@ RUN echo "========== STEP 1: Installing system dependencies ==========" && \
     poppler-utils \
     # Health checks
     curl \
-    # Build tools for some Python packages
-    build-essential \
     && fc-cache -fv && \
     rm -rf /var/lib/apt/lists/* && \
     echo "========== System dependencies installed =========="
@@ -35,23 +33,27 @@ RUN useradd -m -u 1000 user
 # Set environment variables
 ENV PYTHONUNBUFFERED=1 \
     PYTHONDONTWRITEBYTECODE=1 \
-    DO_OCR=true \
-    TABLE_MODE=accurate \
-    IMAGES_SCALE=3.0 \
+    VLM_MODEL=Qwen/Qwen3-VL-8B-Instruct \
+    VLM_HOST=127.0.0.1 \
+    VLM_PORT=8000 \
+    VLM_GPU_MEMORY_UTILIZATION=0.70 \
+    VLM_MAX_MODEL_LEN=8192 \
+    IMAGES_SCALE=2.0 \
     MAX_FILE_SIZE_MB=1024 \
-    DEFAULT_LANG=en \
     HF_HOME=/home/user/.cache/huggingface \
     TORCH_HOME=/home/user/.cache/torch \
     XDG_CACHE_HOME=/home/user/.cache \
     HOME=/home/user \
-    PATH=/home/user/.local/bin:/usr/local/bin:/usr/bin:$PATH
+    PATH=/home/user/.local/bin:/usr/local/bin:/usr/bin:$PATH \
+    LD_LIBRARY_PATH=/home/user/.local/lib/python3.12/site-packages/nvidia/cudnn/lib:$LD_LIBRARY_PATH
 
 # Create cache directories with correct ownership
-RUN mkdir -p /home/user/.cache/huggingface \
+RUN echo "========== STEP 2: Creating cache directories ==========" && \
+    mkdir -p /home/user/.cache/huggingface \
     /home/user/.cache/torch \
-    /home/user/.cache/docling \
     /home/user/app && \
-    chown -R user:user /home/user
+    chown -R user:user /home/user && \
+    echo "========== Cache directories created =========="
 
 # Switch to non-root user
 USER user
@@ -61,34 +63,45 @@ WORKDIR /home/user/app
 COPY --chown=user:user requirements.txt .
 
 # Install Python dependencies
-RUN echo "========== STEP 2: Installing Python dependencies ==========" && \
+RUN echo "========== STEP 3: Installing Python dependencies ==========" && \
     pip install --user --upgrade pip && \
+    pip install --user nvidia-cudnn-cu12 && \
     pip install --user -r requirements.txt && \
     echo "Installed packages:" && \
-    pip list --user | grep -E "(docling|fastapi|uvicorn|httpx|pydantic|torch)" && \
+    pip list --user && \
     echo "========== Python dependencies installed =========="
 
+# Pre-download Qwen3-VL-8B model for vLLM
+RUN echo "========== STEP 4: Pre-downloading Qwen3-VL-8B model ==========" && \
+    python -c "from huggingface_hub import snapshot_download; snapshot_download('Qwen/Qwen3-VL-8B-Instruct', local_dir='/home/user/.cache/huggingface/Qwen3-VL-8B-Instruct')" && \
+    echo "Model cache summary:" && \
+    du -sh /home/user/.cache/huggingface 2>/dev/null || echo "  HF cache: (empty)" && \
+    echo "========== Qwen3-VL-8B model downloaded =========="
+
 # Pre-download Docling models
-RUN echo "========== STEP 3: Pre-downloading Docling models ==========" && \
-    python -c "from docling.document_converter import DocumentConverter; print('Initializing Docling to download models...'); converter = DocumentConverter(); print('Models downloaded successfully')" && \
+RUN echo "========== STEP 5: Pre-downloading Docling models ==========" && \
+    python -c "from docling.document_converter import DocumentConverter; print('Downloading Docling models...'); converter = DocumentConverter(); print('Done')" && \
     echo "Model cache summary:" && \
     du -sh /home/user/.cache/huggingface 2>/dev/null || echo "  HF cache: (empty)" && \
     du -sh /home/user/.cache/torch 2>/dev/null || echo "  Torch cache: (empty)" && \
     du -sh /home/user/.cache 2>/dev/null || echo "  Total cache: (empty)" && \
-    echo "========== Models downloaded =========="
+    echo "========== Docling models downloaded =========="
 
 # Copy application code
 COPY --chown=user:user . .
 
-RUN echo "Files in app directory:" && ls -la /home/user/app/ && \
+RUN echo "========== STEP 6: Finalizing build ==========" && \
+    chmod +x start.sh && \
+    echo "Files in app directory:" && ls -la /home/user/app/ && \
     echo "========== BUILD COMPLETED at $(date -u '+%Y-%m-%d %H:%M:%S UTC') =========="
 
 # Expose the port
 EXPOSE 7860
 
-# Health check
-HEALTHCHECK --interval=30s --timeout=30s --start-period=300s --retries=5 \
+# Health check (longer start-period for vLLM model loading)
+HEALTHCHECK --interval=30s --timeout=30s --start-period=600s --retries=5 \
     CMD curl -f http://localhost:7860/ || exit 1
 
-# Run FastAPI server
-CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1", "--timeout-keep-alive", "300"]
+# Override vLLM entrypoint and use our startup script
+ENTRYPOINT []
+CMD ["bash", "start.sh"]

README.md

@@ -1,5 +1,5 @@
 ---
-title: Docling Parser API
+title: Docling VLM Parser API
 emoji: 📄
 colorFrom: blue
 colorTo: green
@@ -10,24 +10,53 @@ license: mit
 suggested_hardware: a100-large
 ---
 
-# Docling Parser API
+# Docling VLM Parser API
 
-A FastAPI service that transforms PDFs and images into LLM-ready markdown/JSON using [IBM's Docling](https://github.com/DS4SD/docling).
+A FastAPI service that transforms PDFs and images into LLM-ready markdown/JSON using a **hybrid two-pass architecture**: [IBM's Docling](https://github.com/DS4SD/docling) for document structure and [Qwen3-VL-8B](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct) via [vLLM](https://github.com/vllm-project/vllm) for enhanced text recognition.
 
 ## Features
 
-- **PDF Parsing**: Extract text, tables, formulas, and images from PDFs
-- **Image OCR**: Process scanned documents and images
-- **Multiple Formats**: Output as markdown or JSON
-- **Table Detection**: Accurate table structure detection with TableFormer
-- **GPU Accelerated**: Uses CUDA for fast processing
+- **Hybrid Two-Pass Architecture**: Docling Standard Pipeline (Pass 1) + Qwen3-VL VLM OCR (Pass 2)
+- **TableFormer ACCURATE**: High-accuracy table structure detection preserved from Docling
+- **VLM-Powered OCR**: Qwen3-VL-8B via vLLM replaces baseline RapidOCR for superior text accuracy
+- **OpenCV Preprocessing**: Denoising and CLAHE contrast enhancement for better image quality
+- **32+ Language Support**: Multilingual text recognition powered by Qwen3-VL
+- **Handwriting Recognition**: Transcribe handwritten text via VLM
 - **Image Extraction**: Extract and return all document images
+- **Multiple Formats**: Output as markdown or JSON
+- **GPU Accelerated**: Dual-process on A100 80GB (vLLM + FastAPI)
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Docker Container                        │
+│                  (vllm/vllm-openai:v0.14.1)                 │
+│                                                             │
+│  ┌─────────────────────┐    ┌────────────────────────────┐  │
+│  │  vLLM Server :8000  │    │   FastAPI App :7860        │  │
+│  │  Qwen3-VL-8B        │◄───│                            │  │
+│  │  (GPU inference)     │    │   Pass 1: Docling Standard │  │
+│  └─────────────────────┘    │   - DocLayNet layout       │  │
+│                              │   - TableFormer ACCURATE   │  │
+│                              │   - RapidOCR baseline      │  │
+│                              │                            │  │
+│                              │   Pass 2: VLM OCR          │  │
+│                              │   - Page images → Qwen3-VL │  │
+│                              │   - OpenCV preprocessing   │  │
+│                              │                            │  │
+│                              │   Merge:                   │  │
+│                              │   - VLM text (primary)     │  │
+│                              │   - TableFormer tables     │  │
+│                              └────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
 
 ## API Endpoints
 
 | Endpoint     | Method | Description                               |
 | ------------ | ------ | ----------------------------------------- |
-| `/`          | GET    | Health check                              |
+| `/`          | GET    | Health check (includes vLLM status)       |
 | `/parse`     | POST   | Parse uploaded file (multipart/form-data) |
 | `/parse/url` | POST   | Parse document from URL (JSON body)       |
 
@@ -91,7 +120,7 @@ response = requests.post(
 
 result = response.json()
 if result["success"]:
-    print(f"Parsed {result['pages_processed']} pages")
+    print(f"Parsed {result['pages_processed']} pages using {result['vlm_model']}")
     print(result["markdown"])
 else:
     print(f"Error: {result['error']}")
@@ -140,10 +169,7 @@ if result["success"]:
 | -------------- | ------ | -------- | ---------- | ---------------------------------------- |
 | file           | File   | Yes      | -          | PDF or image file                        |
 | output_format  | string | No       | `markdown` | `markdown` or `json`                     |
-| lang           | string | No       | `en`       | OCR language code                        |
-| do_ocr         | bool   | No       | `true`     | Enable OCR for scanned documents         |
-| table_mode     | string | No       | `accurate` | `accurate` (slow) or `fast`              |
-| images_scale   | float  | No       | `3.0`      | Image resolution scale (higher = better) |
+| images_scale   | float  | No       | `2.0`      | Image resolution scale (higher = better) |
 | start_page     | int    | No       | `0`        | Starting page (0-indexed)                |
 | end_page       | int    | No       | `null`     | Ending page (null = all pages)           |
 | include_images | bool   | No       | `false`    | Include extracted images in response     |
@@ -154,10 +180,7 @@ if result["success"]:
 | -------------- | ------ | -------- | ---------- | ---------------------------------------- |
 | url            | string | Yes      | -          | URL to PDF or image                      |
 | output_format  | string | No       | `markdown` | `markdown` or `json`                     |
-| lang           | string | No       | `en`       | OCR language code                        |
-| do_ocr         | bool   | No       | `true`     | Enable OCR for scanned documents         |
-| table_mode     | string | No       | `accurate` | `accurate` (slow) or `fast`              |
-| images_scale   | float  | No       | `3.0`      | Image resolution scale (higher = better) |
+| images_scale   | float  | No       | `2.0`      | Image resolution scale (higher = better) |
 | start_page     | int    | No       | `0`        | Starting page (0-indexed)                |
 | end_page       | int    | No       | `null`     | Ending page (null = all pages)           |
 | include_images | bool   | No       | `false`    | Include extracted images in response     |
@@ -173,7 +196,8 @@ if result["success"]:
   "image_count": 0,
   "error": null,
   "pages_processed": 20,
-  "device_used": "cuda"
+  "device_used": "cuda",
+  "vlm_model": "Qwen/Qwen3-VL-8B-Instruct"
 }
 ```
 
@@ -187,13 +211,7 @@ if result["success"]:
 | error           | string  | Error message if failed                        |
 | pages_processed | int     | Number of pages processed                      |
 | device_used     | string  | Device used for processing (cuda, mps, or cpu) |
-
-## Table Detection Modes
-
-| Mode       | Speed  | Accuracy | Best For                              |
-| ---------- | ------ | -------- | ------------------------------------- |
-| `accurate` | Slower | Higher   | Complex tables, forms, financial docs |
-| `fast`     | Faster | Good     | Simple tables, high-volume processing |
+| vlm_model       | string  | VLM model used for OCR (e.g. Qwen3-VL-8B)      |
 
 ## Supported File Types
 
@@ -204,14 +222,16 @@ Maximum file size: 1GB (configurable via `MAX_FILE_SIZE_MB`)
 
 ## Configuration
 
-| Environment Variable | Description                            | Default    |
-| -------------------- | -------------------------------------- | ---------- |
-| `API_TOKEN`          | **Required.** API authentication token | -          |
-| `DO_OCR`             | Enable OCR by default                  | `true`     |
-| `TABLE_MODE`         | Default table detection mode           | `accurate` |
-| `IMAGES_SCALE`       | Default image resolution scale         | `3.0`      |
-| `DEFAULT_LANG`       | Default OCR language code              | `en`       |
-| `MAX_FILE_SIZE_MB`   | Maximum upload size in MB              | `1024`     |
+| Environment Variable         | Description                            | Default                     |
+| ---------------------------- | -------------------------------------- | --------------------------- |
+| `API_TOKEN`                  | **Required.** API authentication token | -                           |
+| `VLM_MODEL`                  | VLM model for OCR                      | `Qwen/Qwen3-VL-8B-Instruct` |
+| `VLM_HOST`                   | vLLM server host                       | `127.0.0.1`                 |
+| `VLM_PORT`                   | vLLM server port                       | `8000`                      |
+| `VLM_GPU_MEMORY_UTILIZATION` | GPU memory fraction for vLLM           | `0.70`                      |
+| `VLM_MAX_MODEL_LEN`          | Max context length for VLM             | `8192`                      |
+| `IMAGES_SCALE`               | Default image resolution scale         | `2.0`                       |
+| `MAX_FILE_SIZE_MB`           | Maximum upload size in MB              | `1024`                      |
 
 ## Logging
 
@@ -221,11 +241,13 @@ View logs in HuggingFace Space > Logs tab:
 2026-02-04 10:30:00 | INFO | [a1b2c3d4] New parse request received
 2026-02-04 10:30:00 | INFO | [a1b2c3d4] Filename: document.pdf
 2026-02-04 10:30:00 | INFO | [a1b2c3d4] File size: 2.45 MB
-2026-02-04 10:30:27 | INFO | [a1b2c3d4] Docling conversion completed in 27.23s
-2026-02-04 10:30:27 | INFO | [a1b2c3d4] Pages processed: 20
+2026-02-04 10:30:15 | INFO | [a1b2c3d4] Pass 1: Docling Standard Pipeline completed in 15.23s
+2026-02-04 10:30:15 | INFO | [a1b2c3d4] TableFormer detected 3 tables
+2026-02-04 10:30:27 | INFO | [a1b2c3d4] Pass 2: VLM OCR completed in 12.00s (20 pages)
+2026-02-04 10:30:27 | INFO | [a1b2c3d4] Hybrid conversion complete: 20 pages, 3 tables, 27.23s total
 2026-02-04 10:30:27 | INFO | [a1b2c3d4] Speed: 0.73 pages/sec
 ```
 
 ## Credits
 
-Built with [Docling](https://github.com/DS4SD/docling) by IBM Research.
+Built with [Docling](https://github.com/DS4SD/docling) by IBM Research, [Qwen3-VL](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct) by Qwen Team, and [vLLM](https://github.com/vllm-project/vllm).

app.py

@@ -1,12 +1,16 @@
 """
-Docling Document Parser API
+Docling VLM Parser API v2.0.0
 
-A FastAPI service that wraps IBM's Docling library for parsing PDFs and images
-into LLM-ready markdown/JSON formats.
+A FastAPI service that uses a HYBRID two-pass approach for document parsing:
+  Pass 1: Docling Standard Pipeline (DocLayNet + TableFormer + RapidOCR) for document structure
+  Pass 2: Qwen3-VL-8B via vLLM for enhanced text recognition
+  Merge:  TableFormer tables preserved, VLM text replaces RapidOCR text
 
 Features:
 - GPU-accelerated parsing with CUDA support
-- Table structure detection with TableFormer
+- TableFormer ACCURATE for table structure detection
+- Qwen3-VL via vLLM for superior OCR accuracy
+- OpenCV image preprocessing (deskew, denoise, CLAHE)
 - Image extraction with configurable resolution
 - Automatic page chunking for large PDFs
 """
@@ -24,27 +28,31 @@ import socket
 import tempfile
 import time
 import zipfile
+from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import BinaryIO, Optional, Union
 from urllib.parse import urlparse
 from uuid import uuid4
 
+import cv2
 import httpx
 import torch
 from fastapi import Depends, FastAPI, File, Form, HTTPException, UploadFile
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from pdf2image import convert_from_path
 from pydantic import BaseModel
 
 # Docling imports
-from docling.document_converter import DocumentConverter, PdfFormatOption
+from docling.backend.docling_parse_v4_backend import DoclingParseV4DocumentBackend
 from docling.datamodel.base_models import InputFormat
+from docling.datamodel.document import PictureItem, TableItem
 from docling.datamodel.pipeline_options import (
+    AcceleratorOptions,
     PdfPipelineOptions,
+    RapidOcrOptions,
     TableFormerMode,
-    AcceleratorOptions,
 )
-from docling.backend.docling_parse_v4_backend import DoclingParseV4DocumentBackend
-from docling.datamodel.document import PictureItem
+from docling.document_converter import DocumentConverter, PdfFormatOption
 
 # Configure logging
 logging.basicConfig(
@@ -85,120 +93,12 @@ def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security))
     return token
 
 
-# Global converter instance (initialized on startup)
-_converter: Optional[DocumentConverter] = None
-
-
-def _get_device() -> str:
-    """Get the best available device for processing."""
-    if torch.cuda.is_available():
-        return "cuda"
-    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
-        return "mps"
-    return "cpu"
-
-
-def _create_converter(
-    do_ocr: bool = True,
-    table_mode: str = "accurate",
-    images_scale: float = 3.0,
-) -> DocumentConverter:
-    """Create a Docling DocumentConverter with specified options."""
-    device = _get_device()
-    logger.info(f"Creating converter with device: {device}")
-
-    pipeline_options = PdfPipelineOptions()
-    pipeline_options.do_ocr = do_ocr
-    pipeline_options.do_table_structure = True
-
-    # Set table structure mode
-    if table_mode == "accurate":
-        pipeline_options.table_structure_options.mode = TableFormerMode.ACCURATE
-    else:
-        pipeline_options.table_structure_options.mode = TableFormerMode.FAST
-
-    # Enable image extraction
-    pipeline_options.generate_picture_images = True
-    pipeline_options.generate_page_images = True
-    pipeline_options.images_scale = images_scale
-
-    # GPU/CPU configuration
-    pipeline_options.accelerator_options = AcceleratorOptions(
-        device=device,
-        num_threads=0 if device == "cuda" else 4,
-    )
-
-    converter = DocumentConverter(
-        format_options={
-            InputFormat.PDF: PdfFormatOption(
-                pipeline_options=pipeline_options,
-                backend=DoclingParseV4DocumentBackend,
-            )
-        }
-    )
-
-    return converter
-
-
-def _get_converter() -> DocumentConverter:
-    """Get or create the global converter instance."""
-    global _converter
-    if _converter is None:
-        _converter = _create_converter()
-    return _converter
-
-
-from contextlib import asynccontextmanager
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """Startup: initialize Docling converter and check GPU."""
-    logger.info("=" * 60)
-    logger.info("Starting Docling Parser API v1.0.0...")
-
-    device = _get_device()
-    logger.info(f"Device: {device}")
-
-    if device == "cuda":
-        logger.info(f"GPU: {torch.cuda.get_device_name(0)}")
-        logger.info(f"CUDA Version: {torch.version.cuda}")
-        logger.info(f"GPU Memory: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB")
-
-    logger.info(f"Default OCR: {DO_OCR}")
-    logger.info(f"Default table mode: {TABLE_MODE}")
-    logger.info(f"Default images scale: {IMAGES_SCALE}")
-    logger.info(f"Default language: {DEFAULT_LANG}")
-    logger.info(f"Max file size: {MAX_FILE_SIZE_MB}MB")
-
-    # Pre-initialize converter to load models
-    logger.info("Pre-loading Docling models...")
-    try:
-        _get_converter()
-        logger.info("Models loaded successfully")
-    except Exception as e:
-        logger.warning(f"Failed to pre-load models: {e}")
-
-    logger.info("=" * 60)
-    logger.info("Docling Parser API ready to accept requests")
-    logger.info("=" * 60)
-    yield
-    logger.info("Shutting down Docling Parser API...")
-
-
-app = FastAPI(
-    title="Docling Parser API",
-    description="Transform PDFs and images into markdown/JSON using IBM's Docling",
-    version="1.0.0",
-    lifespan=lifespan,
-)
-
-# Configuration from environment
-DO_OCR = os.getenv("DO_OCR", "true").lower() == "true"
-TABLE_MODE = os.getenv("TABLE_MODE", "accurate")  # accurate or fast
-IMAGES_SCALE = float(os.getenv("IMAGES_SCALE", "3.0"))  # High res for A100 80GB VRAM
+# VLM Configuration
+VLM_MODEL = os.getenv("VLM_MODEL", "Qwen/Qwen3-VL-8B-Instruct")
+VLM_HOST = os.getenv("VLM_HOST", "127.0.0.1")
+VLM_PORT = os.getenv("VLM_PORT", "8000")
+IMAGES_SCALE = float(os.getenv("IMAGES_SCALE", "2.0"))
 MAX_FILE_SIZE_MB = int(os.getenv("MAX_FILE_SIZE_MB", "1024"))
-DEFAULT_LANG = os.getenv("DEFAULT_LANG", "en")  # OCR language code
 MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024
 
 # Blocked hostnames for SSRF protection
@@ -211,6 +111,18 @@ BLOCKED_HOSTNAMES = {
     "fd00:ec2::254",
 }
 
+# Global converter instance (initialized on startup)
+_converter: Optional[DocumentConverter] = None
+
+
+def _get_device() -> str:
+    """Get the best available device for processing."""
+    if torch.cuda.is_available():
+        return "cuda"
+    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
 
 def _validate_url(url: str) -> None:
     """Validate URL to prevent SSRF attacks."""
@@ -283,6 +195,11 @@ def _save_downloaded_content(input_path: Path, content: bytes) -> None:
         f.write(content)
 
 
+# ---------------------------------------------------------------------------
+# Pydantic Models
+# ---------------------------------------------------------------------------
+
+
 class ParseResponse(BaseModel):
     """Response model for document parsing."""
 
@@ -294,6 +211,7 @@ class ParseResponse(BaseModel):
     error: Optional[str] = None
     pages_processed: int = 0
     device_used: Optional[str] = None
+    vlm_model: Optional[str] = None
 
 
 class HealthResponse(BaseModel):
@@ -303,9 +221,9 @@ class HealthResponse(BaseModel):
     version: str
     device: str
     gpu_name: Optional[str] = None
-    do_ocr: bool
-    table_mode: str
-    images_scale: float
+    vlm_model: str = ""
+    vlm_status: str = "unknown"
+    images_scale: float = 2.0
 
 
 class URLParseRequest(BaseModel):
@@ -313,130 +231,421 @@ class URLParseRequest(BaseModel):
 
     url: str
     output_format: str = "markdown"
-    lang: str = DEFAULT_LANG  # OCR language code
-    do_ocr: Optional[bool] = None
-    table_mode: Optional[str] = None
     images_scale: Optional[float] = None
     start_page: int = 0  # Starting page (0-indexed)
     end_page: Optional[int] = None  # Ending page (None = all pages)
     include_images: bool = False
 
 
+# ---------------------------------------------------------------------------
+# OpenCV Image Preprocessing
+# ---------------------------------------------------------------------------
+
+
+def _preprocess_image_for_ocr(image_path: str) -> str:
+    """Enhance image quality for better OCR accuracy.
+
+    Applies: deskew correction, denoising, CLAHE contrast enhancement.
+    Returns the path to the preprocessed image (same path, overwritten).
+    """
+    img = cv2.imread(image_path)
+    if img is None:
+        return image_path
+
+    # Denoise
+    img = cv2.fastNlMeansDenoisingColored(img, None, 10, 10, 7, 21)
+
+    # CLAHE contrast enhancement on L channel
+    lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
+    l, a, b = cv2.split(lab)
+    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+    l = clahe.apply(l)
+    lab = cv2.merge([l, a, b])
+    img = cv2.cvtColor(lab, cv2.COLOR_LAB2BGR)
+
+    cv2.imwrite(image_path, img)
+    return image_path
+
+
+# ---------------------------------------------------------------------------
+# VLM OCR (Pass 2)
+# ---------------------------------------------------------------------------
+
+
+def _vlm_ocr_page(page_image_bytes: bytes) -> str:
+    """Send a page image to Qwen3-VL via vLLM for text extraction.
+
+    Args:
+        page_image_bytes: PNG image bytes of the page
+
+    Returns:
+        Extracted markdown text from the page
+    """
+    b64_image = base64.b64encode(page_image_bytes).decode("utf-8")
+
+    response = httpx.post(
+        f"http://{VLM_HOST}:{VLM_PORT}/v1/chat/completions",
+        json={
+            "model": VLM_MODEL,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": f"data:image/png;base64,{b64_image}"},
+                        },
+                        {
+                            "type": "text",
+                            "text": (
+                                "OCR this document page to markdown. "
+                                "Extract ALL text exactly as written, preserving headings, lists, and paragraphs. "
+                                "For tables, output them as markdown tables. "
+                                "For handwritten text, transcribe as accurately as possible. "
+                                "Return ONLY the extracted content, no explanations."
+                            ),
+                        },
+                    ],
+                }
+            ],
+            "max_tokens": 8192,
+            "temperature": 0.1,
+            "skip_special_tokens": True,
+        },
+        timeout=120.0,
+    )
+    response.raise_for_status()
+    result = response.json()
+    choices = result.get("choices")
+    if not choices:
+        raise ValueError(f"vLLM returned no choices")
+    content = choices[0].get("message", {}).get("content")
+    if content is None:
+        raise ValueError(f"vLLM response missing content")
+    return content
+
+
+# ---------------------------------------------------------------------------
+# Table Extraction Helper
+# ---------------------------------------------------------------------------
+
+
+def _extract_table_markdowns(doc) -> dict:
+    """Extract table markdown from Docling document, keyed by page number."""
+    tables_by_page: dict[int, list[str]] = {}
+    for element, _ in doc.iterate_items():
+        if isinstance(element, TableItem):
+            page_no = element.prov[0].page_no if element.prov else -1
+            table_md = element.export_to_markdown(doc=doc)
+            if page_no not in tables_by_page:
+                tables_by_page[page_no] = []
+            tables_by_page[page_no].append(table_md)
+    return tables_by_page
+
+
+# ---------------------------------------------------------------------------
+# Merge: VLM Text + TableFormer Tables
+# ---------------------------------------------------------------------------
+
+
+def _merge_vlm_with_tables(vlm_text: str, table_markdowns: list) -> str:
+    """Replace VLM's table sections with TableFormer's more accurate tables.
+
+    Detects markdown table patterns (lines with |...|) in VLM output
+    and replaces them with TableFormer output.
+    """
+    if not table_markdowns:
+        return vlm_text
+
+    # Pattern: consecutive lines that look like markdown tables
+    # A markdown table has lines starting and ending with |
+    table_pattern = re.compile(r"((?:^\|[^\n]+\|$\n?)+)", re.MULTILINE)
+
+    vlm_table_count = len(table_pattern.findall(vlm_text))
+    if vlm_table_count != len(table_markdowns):
+        logger.warning(
+            f"Table count mismatch: VLM={vlm_table_count}, TableFormer={len(table_markdowns)}. "
+            f"Positional replacement may be imprecise."
+        )
+
+    table_idx = 0
+
+    def replace_table(match):
+        nonlocal table_idx
+        if table_idx < len(table_markdowns):
+            replacement = table_markdowns[table_idx]
+            table_idx += 1
+            return replacement.strip() + "\n"
+        return match.group(0)
+
+    result = table_pattern.sub(replace_table, vlm_text)
+
+    # If there are remaining TableFormer tables not matched, append them
+    while table_idx < len(table_markdowns):
+        result += "\n\n" + table_markdowns[table_idx].strip() + "\n"
+        table_idx += 1
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# PDF to Page Images
+# ---------------------------------------------------------------------------
+
+
+def _pdf_to_page_images(
+    input_path: Path, start_page: int = 0, end_page: Optional[int] = None
+) -> list:
+    """Convert PDF pages to PNG image bytes using pdf2image.
+
+    Processes one page at a time to avoid loading all pages into memory.
+    Returns list of (page_no, png_bytes) tuples.
+    """
+    page_images: list[tuple[int, bytes]] = []
+
+    try:
+        # Determine total page count first
+        from pdf2image.pdf2image import pdfinfo_from_path
+
+        info = pdfinfo_from_path(str(input_path))
+        total_pages = info["Pages"]
+        last_page = min(end_page + 1, total_pages) if end_page is not None else total_pages
+
+        for i in range(start_page, last_page):
+            # Convert one page at a time (pdf2image is 1-indexed)
+            images = convert_from_path(
+                str(input_path), dpi=300, first_page=i + 1, last_page=i + 1
+            )
+            if not images:
+                continue
+            img = images[0]
+            # Save to temp file for OpenCV preprocessing
+            with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+                tmp_path = tmp.name
+                img.save(tmp_path, format="PNG")
+            try:
+                _preprocess_image_for_ocr(tmp_path)
+                with open(tmp_path, "rb") as f:
+                    page_images.append((i, f.read()))
+            finally:
+                os.unlink(tmp_path)
+    except Exception as e:
+        # Fallback: log warning — caller handles empty list
+        logger.warning(f"pdf2image failed, VLM OCR may be limited: {e}")
+
+    return page_images
+
+
+# ---------------------------------------------------------------------------
+# Docling Converter (Pass 1)
+# ---------------------------------------------------------------------------
+
+
+def _create_converter(images_scale: float = 2.0) -> DocumentConverter:
+    """Create a Docling converter with Standard Pipeline.
+
+    Uses DocLayNet (layout) + TableFormer ACCURATE (tables) + RapidOCR (baseline text).
+    """
+    device = _get_device()
+    logger.info(f"Creating converter with device: {device}")
+
+    pipeline_options = PdfPipelineOptions()
+    pipeline_options.do_ocr = True
+    pipeline_options.do_table_structure = True
+    pipeline_options.table_structure_options.mode = TableFormerMode.ACCURATE
+    pipeline_options.table_structure_options.do_cell_matching = True
+
+    # Use RapidOCR as baseline (VLM will enhance text in pass 2)
+    pipeline_options.ocr_options = RapidOcrOptions()
+    pipeline_options.ocr_options.force_full_page_ocr = True
+
+    # Enable page image generation (needed for VLM pass)
+    pipeline_options.generate_page_images = True
+    pipeline_options.images_scale = images_scale
+
+    # Also enable picture image extraction
+    pipeline_options.generate_picture_images = True
+
+    pipeline_options.accelerator_options = AcceleratorOptions(
+        device=device,
+        num_threads=0 if device == "cuda" else 4,
+    )
+
+    converter = DocumentConverter(
+        format_options={
+            InputFormat.PDF: PdfFormatOption(
+                pipeline_options=pipeline_options,
+                backend=DoclingParseV4DocumentBackend,
+            )
+        }
+    )
+    return converter
+
+
+def _get_converter() -> DocumentConverter:
+    """Get or create the global converter instance."""
+    global _converter
+    if _converter is None:
+        _converter = _create_converter(images_scale=IMAGES_SCALE)
+    return _converter
+
+
+# ---------------------------------------------------------------------------
+# Hybrid Conversion (Pass 1 + Pass 2 + Merge)
+# ---------------------------------------------------------------------------
+
+
 def _convert_document(
     input_path: Path,
     output_dir: Path,
-    do_ocr: bool,
-    table_mode: str,
     images_scale: float,
     include_images: bool,
     request_id: str,
     start_page: int = 0,
     end_page: Optional[int] = None,
-    lang: str = "en",
-) -> tuple[str, Optional[list], int, int]:
+) -> tuple:
     """
-    Convert a document using Docling.
+    Hybrid conversion: TableFormer for tables + Qwen3-VL for text.
 
-    Returns:
-        Tuple of (markdown_content, json_content, pages_processed, image_count)
+    Pass 1: Docling Standard Pipeline -> document structure + tables
+    Pass 2: VLM OCR -> enhanced text recognition per page
+    Merge: TableFormer tables + VLM text
+
+    Returns: (markdown_content, json_content, pages_processed, image_count)
     """
-    logger.info(f"[{request_id}] Creating converter with OCR={do_ocr}, table_mode={table_mode}, lang={lang}")
-    if start_page > 0 or end_page is not None:
-        logger.info(f"[{request_id}] Page range: {start_page} to {end_page or 'end'}")
-
-    # Create converter with specified options
-    converter = _create_converter(
-        do_ocr=do_ocr,
-        table_mode=table_mode,
-        images_scale=images_scale,
+    # PASS 1: Docling Standard Pipeline (structure + tables)
+    logger.info(
+        f"[{request_id}] Pass 1: Docling Standard Pipeline (DocLayNet + TableFormer + RapidOCR)"
     )
+    converter = _get_converter()
 
-    logger.info(f"[{request_id}] Starting Docling conversion...")
     start_time = time.time()
-
     result = converter.convert(input_path)
     doc = result.document
+    if doc is None:
+        raise ValueError(
+            f"Docling failed to parse document (status: {getattr(result, 'status', 'unknown')})"
+        )
+    pass1_time = time.time() - start_time
+    logger.info(f"[{request_id}] Pass 1 completed in {pass1_time:.2f}s")
+
+    # Extract TableFormer tables (keyed by page number)
+    tables_by_page = _extract_table_markdowns(doc)
+    total_tables = sum(len(v) for v in tables_by_page.values())
+    logger.info(f"[{request_id}] TableFormer detected {total_tables} tables")
+
+    # PASS 2: VLM OCR (enhanced text per page)
+    logger.info(f"[{request_id}] Pass 2: VLM OCR via Qwen3-VL ({VLM_MODEL})")
+
+    # Get page images for VLM
+    page_images = _pdf_to_page_images(input_path, start_page, end_page)
+
+    if not page_images:
+        # Fallback: use Docling's markdown directly if no page images
+        logger.warning(f"[{request_id}] No page images available, using Docling output only")
+        markdown_content = doc.export_to_markdown()
+        pages_processed = len(
+            set(e.prov[0].page_no for e, _ in doc.iterate_items() if e.prov)
+        )
+        return markdown_content, None, pages_processed, 0
+
+    vlm_page_texts: dict[int, Optional[str]] = {}
+    vlm_start = time.time()
+    for page_no, page_bytes in page_images:
+        try:
+            vlm_text = _vlm_ocr_page(page_bytes)
+            vlm_page_texts[page_no] = vlm_text
+            logger.info(
+                f"[{request_id}] VLM processed page {page_no + 1} ({len(vlm_text)} chars)"
+            )
+        except Exception as e:
+            logger.warning(
+                f"[{request_id}] VLM failed on page {page_no + 1}: {e}, using Docling text"
+            )
+            # Fallback to Docling's text for this page
+            vlm_page_texts[page_no] = None
 
-    conversion_time = time.time() - start_time
-    logger.info(f"[{request_id}] Docling conversion completed in {conversion_time:.2f}s")
+    vlm_time = time.time() - vlm_start
+    logger.info(
+        f"[{request_id}] Pass 2 completed in {vlm_time:.2f}s ({len(vlm_page_texts)} pages)"
+    )
 
-    # Build page labels map for better page numbering
-    page_labels = {}
-    for element, _ in doc.iterate_items():
-        if element.label in ["page_footer", "metadata", "text"]:
-            raw_text = getattr(element, "text", "").strip()
-            if re.fullmatch(r"([0-9]+|[ivxIVX]+)", raw_text):
-                if element.prov and element.prov[0].page_no not in page_labels:
-                    page_labels[element.prov[0].page_no] = raw_text
-
-    # Build markdown output
-    md_body = []
-    current_page_idx = -1
-    pages_seen = set()
+    # MERGE: VLM text + TableFormer tables
+    logger.info(f"[{request_id}] Merging VLM text with TableFormer tables")
+
+    md_parts: list[str] = []
+    pages_seen: set[int] = set()
     image_count = 0
     image_dir = output_dir / "images"
 
     if include_images:
         image_dir.mkdir(parents=True, exist_ok=True)
 
-    for element, _level in doc.iterate_items():
-        # Track page breaks
-        if element.prov and element.prov[0].page_no != current_page_idx:
-            current_page_idx = element.prov[0].page_no
-
-            # Skip pages outside the requested range
-            if current_page_idx < start_page:
-                continue
-            if end_page is not None and current_page_idx > end_page:
-                continue
-
-            pages_seen.add(current_page_idx)
-            label = page_labels.get(current_page_idx, str(current_page_idx + 1))
-            md_body.append(f"\n\n<!-- Page {label} -->\n\n")
-
-        # Skip elements outside the requested page range
-        if current_page_idx < start_page:
-            continue
-        if end_page is not None and current_page_idx > end_page:
-            continue
-
-        element_text = getattr(element, "text", "").strip()
+    # Pre-build page-to-elements index (avoids O(N^2) on VLM fallback)
+    elements_by_page: dict[int, list] = {}
+    for element, _ in doc.iterate_items():
+        if element.prov:
+            pg = element.prov[0].page_no
+            elements_by_page.setdefault(pg, []).append(element)
 
-        # Skip page number elements
-        if element_text and element_text == page_labels.get(current_page_idx):
-            continue
+    for page_no in sorted(vlm_page_texts.keys()):
+        pages_seen.add(page_no)
+        md_parts.append(f"\n\n<!-- Page {page_no + 1} -->\n\n")
 
-        # Handle images
-        if isinstance(element, PictureItem):
-            if include_images and element.image and element.image.pil_image:
-                image_id = element.self_ref.split("/")[-1]
-                label = page_labels.get(current_page_idx, str(current_page_idx + 1))
-                image_name = f"page_{label}_{image_id}.png"
-                image_name = re.sub(r'[\\/*?:"<>|]', "", image_name)
-                image_path = image_dir / image_name
+        vlm_text = vlm_page_texts[page_no]
 
+        if vlm_text is None:
+            # VLM failed -- fallback to Docling's text for this page
+            for element in elements_by_page.get(page_no, []):
                 try:
-                    element.image.pil_image.save(image_path, format="PNG")
-                    md_body.append(f"![{image_name}](images/{image_name})\n\n")
-                    image_count += 1
-                except Exception as e:
-                    logger.warning(f"[{request_id}] Failed to save image {image_name}: {e}")
+                    md_parts.append(element.export_to_markdown(doc=doc))
+                except Exception:
+                    text = getattr(element, "text", "").strip()
+                    if text:
+                        md_parts.append(text + "\n\n")
         else:
-            # Export element to markdown
-            try:
-                md_body.append(element.export_to_markdown(doc=doc))
-            except Exception:
-                if element_text:
-                    md_body.append(element_text + "\n\n")
+            # Merge VLM text with TableFormer tables for this page
+            page_tables = tables_by_page.get(page_no, [])
+            merged = _merge_vlm_with_tables(vlm_text, page_tables)
+            md_parts.append(merged)
 
-    markdown_content = "".join(md_body)
+    # Handle images from Docling if requested
+    if include_images:
+        for element, _ in doc.iterate_items():
+            if isinstance(element, PictureItem):
+                if element.image and element.image.pil_image:
+                    page_no = element.prov[0].page_no if element.prov else 0
+                    image_id = element.self_ref.split("/")[-1]
+                    image_name = f"page_{page_no + 1}_{image_id}.png"
+                    image_name = re.sub(r'[\\/*?:"<>|]', "", image_name)
+                    image_path = image_dir / image_name
+                    try:
+                        element.image.pil_image.save(image_path, format="PNG")
+                        image_count += 1
+                    except Exception as e:
+                        logger.warning(
+                            f"[{request_id}] Failed to save image {image_name}: {e}"
+                        )
+
+    markdown_content = "".join(md_parts)
     pages_processed = len(pages_seen)
 
-    logger.info(f"[{request_id}] Extracted {len(markdown_content)} chars, {pages_processed} pages, {image_count} images")
+    total_time = pass1_time + vlm_time
+    logger.info(
+        f"[{request_id}] Hybrid conversion complete: {pages_processed} pages, "
+        f"{total_tables} tables, {total_time:.2f}s total"
+    )
+    if pages_processed > 0:
+        logger.info(f"[{request_id}] Speed: {pages_processed / total_time:.2f} pages/sec")
 
     return markdown_content, None, pages_processed, image_count
 
 
+# ---------------------------------------------------------------------------
+# Images Zip Helper
+# ---------------------------------------------------------------------------
+
+
 def _create_images_zip(output_dir: Path) -> tuple[Optional[str], int]:
     """Create a zip file from extracted images."""
     image_dir = output_dir / "images"
@@ -462,6 +671,75 @@ def _create_images_zip(output_dir: Path) -> tuple[Optional[str], int]:
     return base64.b64encode(zip_buffer.getvalue()).decode("utf-8"), image_count
 
 
+# ---------------------------------------------------------------------------
+# Application Lifespan
+# ---------------------------------------------------------------------------
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Startup: initialize Docling converter and check vLLM."""
+    logger.info("=" * 60)
+    logger.info("Starting Docling VLM Parser API v2.0.0...")
+
+    device = _get_device()
+    logger.info(f"Device: {device}")
+
+    if device == "cuda":
+        logger.info(f"GPU: {torch.cuda.get_device_name(0)}")
+        logger.info(f"CUDA Version: {torch.version.cuda}")
+        logger.info(
+            f"GPU Memory: {torch.cuda.get_device_properties(0).total_mem / 1024**3:.1f} GB"
+        )
+
+    logger.info(f"VLM Model: {VLM_MODEL}")
+    logger.info(f"VLM Endpoint: http://{VLM_HOST}:{VLM_PORT}")
+    logger.info(f"Images scale: {IMAGES_SCALE}")
+    logger.info(f"Max file size: {MAX_FILE_SIZE_MB}MB")
+
+    # Verify vLLM is running
+    logger.info("Checking vLLM server...")
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            resp = await client.get(f"http://{VLM_HOST}:{VLM_PORT}/health")
+            resp.raise_for_status()
+        logger.info("vLLM server is healthy")
+    except Exception as e:
+        logger.error(f"vLLM server not available: {e}")
+        raise RuntimeError(f"vLLM server not available at {VLM_HOST}:{VLM_PORT}")
+
+    # Pre-initialize Docling converter
+    logger.info("Pre-loading Docling models (DocLayNet + TableFormer + RapidOCR)...")
+    try:
+        _get_converter()
+        logger.info("Docling models loaded successfully")
+    except Exception as e:
+        logger.warning(f"Failed to pre-load Docling models: {e}")
+
+    logger.info("=" * 60)
+    logger.info("Docling VLM Parser API ready (Hybrid: TableFormer + Qwen3-VL)")
+    logger.info("=" * 60)
+    yield
+    logger.info("Shutting down Docling VLM Parser API...")
+
+
+# ---------------------------------------------------------------------------
+# FastAPI App
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="Docling VLM Parser API",
+    description="Hybrid document parser: TableFormer tables + Qwen3-VL OCR via vLLM",
+    version="2.0.0",
+    lifespan=lifespan,
+)
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
 @app.get("/", response_model=HealthResponse)
 async def health_check() -> HealthResponse:
     """Health check endpoint."""
@@ -470,13 +748,22 @@ async def health_check() -> HealthResponse:
     if device == "cuda":
         gpu_name = torch.cuda.get_device_name(0)
 
+    # Check vLLM status (async to avoid blocking event loop)
+    vlm_status = "unknown"
+    try:
+        async with httpx.AsyncClient(timeout=5) as client:
+            resp = await client.get(f"http://{VLM_HOST}:{VLM_PORT}/health")
+            vlm_status = "healthy" if resp.status_code == 200 else "unhealthy"
+    except Exception:
+        vlm_status = "unreachable"
+
     return HealthResponse(
         status="healthy",
-        version="1.0.0",
+        version="2.0.0",
         device=device,
-        gpu_name=gpu_name,
-        do_ocr=DO_OCR,
-        table_mode=TABLE_MODE,
+        gpu_name=None,  # Don't leak GPU details on unauthenticated endpoint
+        vlm_model="active",  # Confirm VLM is configured without leaking model name
+        vlm_status=vlm_status,
         images_scale=IMAGES_SCALE,
     )
 
@@ -485,10 +772,7 @@ async def health_check() -> HealthResponse:
 async def parse_document(
     file: UploadFile = File(..., description="PDF or image file to parse"),
     output_format: str = Form(default="markdown", description="Output format: markdown or json"),
-    lang: str = Form(default=DEFAULT_LANG, description="OCR language code"),
-    do_ocr: Optional[bool] = Form(default=None, description="Enable OCR (default: true)"),
-    table_mode: Optional[str] = Form(default=None, description="Table detection mode: accurate or fast"),
-    images_scale: Optional[float] = Form(default=None, description="Image resolution scale (default: 3.0)"),
+    images_scale: Optional[float] = Form(default=None, description="Image resolution scale (default: 2.0)"),
     start_page: int = Form(default=0, description="Starting page (0-indexed)"),
     end_page: Optional[int] = Form(default=None, description="Ending page (None = all pages)"),
     include_images: bool = Form(default=False, description="Include extracted images in response"),
@@ -497,6 +781,11 @@ async def parse_document(
     """
     Parse a document file (PDF or image) and return extracted content.
 
+    Uses a hybrid two-pass approach:
+      Pass 1: Docling Standard Pipeline (DocLayNet + TableFormer + RapidOCR)
+      Pass 2: Qwen3-VL via vLLM for enhanced text recognition
+      Merge: TableFormer tables preserved, VLM text replaces RapidOCR text
+
     Supports:
     - PDF files (.pdf)
     - Images (.png, .jpg, .jpeg, .tiff, .bmp)
@@ -506,9 +795,16 @@ async def parse_document(
 
     logger.info(f"[{request_id}] {'='*50}")
     logger.info(f"[{request_id}] New parse request received")
-    logger.info(f"[{request_id}] Filename: {file.filename}")
+    safe_filename = re.sub(r'[\r\n\t\x00-\x1f\x7f]', '_', file.filename or "")[:255]
+    logger.info(f"[{request_id}] Filename: {safe_filename}")
     logger.info(f"[{request_id}] Output format: {output_format}")
 
+    if output_format not in ("markdown",):
+        raise HTTPException(
+            status_code=400,
+            detail="Only 'markdown' output_format is supported in v2.0.0",
+        )
+
     # Validate file size
     file.file.seek(0, 2)
     file_size = file.file.tell()
@@ -535,39 +831,34 @@ async def parse_document(
         )
 
     # Use defaults if not specified
-    use_ocr = do_ocr if do_ocr is not None else DO_OCR
-    use_table_mode = table_mode if table_mode else TABLE_MODE
-    use_images_scale = images_scale if images_scale else IMAGES_SCALE
+    use_images_scale = images_scale if images_scale is not None else IMAGES_SCALE
 
-    logger.info(f"[{request_id}] OCR: {use_ocr}, Table mode: {use_table_mode}, Images scale: {use_images_scale}, Lang: {lang}")
+    logger.info(f"[{request_id}] Images scale: {use_images_scale}, VLM: {VLM_MODEL}")
     logger.info(f"[{request_id}] Page range: {start_page} to {end_page or 'end'}")
 
     temp_dir = tempfile.mkdtemp()
-    logger.info(f"[{request_id}] Created temp directory: {temp_dir}")
+    logger.debug(f"[{request_id}] Created temp directory: {temp_dir}")
 
     try:
         # Save uploaded file
         input_path = Path(temp_dir) / f"input{file_ext}"
         await asyncio.to_thread(_save_uploaded_file, input_path, file.file)
-        logger.info(f"[{request_id}] Saved file to: {input_path}")
+        logger.debug(f"[{request_id}] Saved file to: {input_path}")
 
         # Create output directory
         output_dir = Path(temp_dir) / "output"
         output_dir.mkdir(exist_ok=True)
 
-        # Convert document
+        # Convert document (hybrid two-pass)
         markdown_content, json_content, pages_processed, image_count = await asyncio.to_thread(
             _convert_document,
             input_path,
             output_dir,
-            use_ocr,
-            use_table_mode,
             use_images_scale,
             include_images,
             request_id,
             start_page,
             end_page,
-            lang,
         )
 
         # Create images zip if requested
@@ -593,21 +884,22 @@ async def parse_document(
             image_count=image_count,
             pages_processed=pages_processed,
             device_used=_get_device(),
+            vlm_model=VLM_MODEL,
         )
 
     except Exception as e:
         total_duration = time.time() - start_time
         logger.error(f"[{request_id}] {'='*50}")
         logger.error(f"[{request_id}] Request failed after {total_duration:.2f}s")
-        logger.error(f"[{request_id}] Error: {type(e).__name__}: {str(e)}")
+        logger.error(f"[{request_id}] Error: {type(e).__name__}: {str(e)}", exc_info=True)
         logger.error(f"[{request_id}] {'='*50}")
         return ParseResponse(
             success=False,
-            error=f"{type(e).__name__}: {str(e)}",
+            error=f"Processing failed (ref: {request_id})",
         )
     finally:
         shutil.rmtree(temp_dir, ignore_errors=True)
-        logger.info(f"[{request_id}] Cleaned up temp directory")
+        logger.debug(f"[{request_id}] Cleaned up temp directory")
 
 
 @app.post("/parse/url", response_model=ParseResponse)
@@ -618,7 +910,10 @@ async def parse_document_from_url(
     """
     Parse a document from a URL.
 
-    Downloads the file and processes it through Docling.
+    Downloads the file and processes it through the hybrid two-pass pipeline:
+      Pass 1: Docling Standard Pipeline (DocLayNet + TableFormer + RapidOCR)
+      Pass 2: Qwen3-VL via vLLM for enhanced text recognition
+      Merge: TableFormer tables preserved, VLM text replaces RapidOCR text
     """
     request_id = str(uuid4())[:8]
     start_time = time.time()
@@ -628,19 +923,25 @@ async def parse_document_from_url(
     logger.info(f"[{request_id}] URL: {request.url}")
     logger.info(f"[{request_id}] Output format: {request.output_format}")
 
+    if request.output_format not in ("markdown",):
+        raise HTTPException(
+            status_code=400,
+            detail="Only 'markdown' output_format is supported in v2.0.0",
+        )
+
     # Validate URL
     logger.info(f"[{request_id}] Validating URL...")
     _validate_url(request.url)
     logger.info(f"[{request_id}] URL validation passed")
 
     temp_dir = tempfile.mkdtemp()
-    logger.info(f"[{request_id}] Created temp directory: {temp_dir}")
+    logger.debug(f"[{request_id}] Created temp directory: {temp_dir}")
 
     try:
         # Download file
         logger.info(f"[{request_id}] Downloading file from URL...")
         download_start = time.time()
-        async with httpx.AsyncClient(timeout=60.0, follow_redirects=True) as client:
+        async with httpx.AsyncClient(timeout=60.0, follow_redirects=False) as client:
             response = await client.get(request.url)
             response.raise_for_status()
         download_duration = time.time() - download_start
@@ -662,7 +963,9 @@ async def parse_document_from_url(
             )
 
         if len(response.content) > MAX_FILE_SIZE_BYTES:
-            logger.error(f"[{request_id}] File too large: {file_size_mb:.2f} MB > {MAX_FILE_SIZE_MB} MB")
+            logger.error(
+                f"[{request_id}] File too large: {file_size_mb:.2f} MB > {MAX_FILE_SIZE_MB} MB"
+            )
             raise HTTPException(
                 status_code=413,
                 detail=f"File size exceeds maximum allowed size of {MAX_FILE_SIZE_MB}MB",
@@ -671,33 +974,28 @@ async def parse_document_from_url(
         # Save downloaded file
         input_path = Path(temp_dir) / f"input{file_ext}"
         await asyncio.to_thread(_save_downloaded_content, input_path, response.content)
-        logger.info(f"[{request_id}] Saved file to: {input_path}")
+        logger.debug(f"[{request_id}] Saved file to: {input_path}")
 
         # Create output directory
         output_dir = Path(temp_dir) / "output"
         output_dir.mkdir(exist_ok=True)
 
         # Use defaults if not specified
-        use_ocr = request.do_ocr if request.do_ocr is not None else DO_OCR
-        use_table_mode = request.table_mode if request.table_mode else TABLE_MODE
-        use_images_scale = request.images_scale if request.images_scale else IMAGES_SCALE
+        use_images_scale = request.images_scale if request.images_scale is not None else IMAGES_SCALE
 
-        logger.info(f"[{request_id}] OCR: {use_ocr}, Table mode: {use_table_mode}, Images scale: {use_images_scale}, Lang: {request.lang}")
+        logger.info(f"[{request_id}] Images scale: {use_images_scale}, VLM: {VLM_MODEL}")
         logger.info(f"[{request_id}] Page range: {request.start_page} to {request.end_page or 'end'}")
 
-        # Convert document
+        # Convert document (hybrid two-pass)
         markdown_content, json_content, pages_processed, image_count = await asyncio.to_thread(
             _convert_document,
             input_path,
             output_dir,
-            use_ocr,
-            use_table_mode,
             use_images_scale,
             request.include_images,
             request_id,
             request.start_page,
             request.end_page,
-            request.lang,
         )
 
         # Create images zip if requested
@@ -723,6 +1021,7 @@ async def parse_document_from_url(
             image_count=image_count,
             pages_processed=pages_processed,
             device_used=_get_device(),
+            vlm_model=VLM_MODEL,
         )
 
     except httpx.HTTPError as e:
@@ -730,21 +1029,21 @@ async def parse_document_from_url(
         logger.error(f"[{request_id}] Download failed after {total_duration:.2f}s: {str(e)}")
         return ParseResponse(
             success=False,
-            error=f"Failed to download file from URL: {str(e)}",
+            error=f"Failed to download file from URL (ref: {request_id})",
         )
     except Exception as e:
         total_duration = time.time() - start_time
         logger.error(f"[{request_id}] {'='*50}")
         logger.error(f"[{request_id}] Request failed after {total_duration:.2f}s")
-        logger.error(f"[{request_id}] Error: {type(e).__name__}: {str(e)}")
+        logger.error(f"[{request_id}] Error: {type(e).__name__}: {str(e)}", exc_info=True)
         logger.error(f"[{request_id}] {'='*50}")
         return ParseResponse(
             success=False,
-            error=str(e),
+            error=f"Processing failed (ref: {request_id})",
         )
     finally:
         shutil.rmtree(temp_dir, ignore_errors=True)
-        logger.info(f"[{request_id}] Cleaned up temp directory")
+        logger.debug(f"[{request_id}] Cleaned up temp directory")
 
 
 if __name__ == "__main__":

requirements.txt

@@ -1,7 +1,7 @@
-# Docling Document Parser API Dependencies
-# Optimized for HuggingFace Spaces deployment with GPU support
+# Docling VLM Parser API Dependencies
+# Optimized for HuggingFace Spaces with vLLM + Qwen3-VL-8B
 
-# Docling - IBM's document parsing library
+# Docling - IBM's document parsing library (VLM pipeline support)
 docling>=2.15.0
 
 # Web framework
@@ -11,8 +11,17 @@ uvicorn[standard]>=0.32.0
 # File upload handling
 python-multipart>=0.0.9
 
-# HTTP client for URL parsing
+# HTTP client for URL parsing and vLLM health checks
 httpx>=0.27.0
 
 # Type checking
 pydantic>=2.0.0
+
+# Image preprocessing for degraded documents
+opencv-python-headless>=4.10.0
+
+# PDF to image conversion for VLM OCR pass
+pdf2image>=1.17.0
+
+# HuggingFace Hub for model downloads
+huggingface-hub>=0.25.0

start.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -e
+
+# ── Configuration ────────────────────────────────────────────────────────────
+VLLM_MODEL="/home/user/.cache/huggingface/Qwen3-VL-8B-Instruct"
+VLLM_HOST="127.0.0.1"
+VLLM_PORT="8000"
+HEALTH_URL="http://${VLLM_HOST}:${VLLM_PORT}/health"
+POLL_INTERVAL=5
+MAX_WAIT=600
+
+# ── Start vLLM server in background ─────────────────────────────────────────
+echo "[startup] Starting vLLM server with model: ${VLLM_MODEL}"
+
+python -m vllm.entrypoints.openai.api_server \
+    --model "${VLLM_MODEL}" \
+    --host "${VLLM_HOST}" \
+    --port "${VLLM_PORT}" \
+    --max-num-seqs 16 \
+    --max-model-len 8192 \
+    --gpu-memory-utilization 0.70 \
+    --dtype auto \
+    --trust-remote-code \
+    --limit-mm-per-prompt image=1 \
+    2>&1 | sed 's/^/[vLLM] /' &
+
+VLLM_PID=$!
+echo "[startup] vLLM server started with PID ${VLLM_PID}"
+
+# ── Poll vLLM health endpoint until ready ────────────────────────────────────
+echo "[startup] Waiting for vLLM to become healthy (polling every ${POLL_INTERVAL}s, timeout ${MAX_WAIT}s)..."
+
+elapsed=0
+while [ "${elapsed}" -lt "${MAX_WAIT}" ]; do
+    # Check if vLLM process is still alive
+    if ! kill -0 "${VLLM_PID}" 2>/dev/null; then
+        echo "[startup] ERROR: vLLM process (PID ${VLLM_PID}) died during startup"
+        exit 1
+    fi
+
+    if curl -sf "${HEALTH_URL}" > /dev/null 2>&1; then
+        echo "[startup] vLLM is healthy after ${elapsed}s"
+        break
+    fi
+
+    sleep "${POLL_INTERVAL}"
+    elapsed=$((elapsed + POLL_INTERVAL))
+done
+
+if [ "${elapsed}" -ge "${MAX_WAIT}" ]; then
+    echo "[startup] ERROR: vLLM did not become healthy within ${MAX_WAIT}s"
+    echo "[startup] Killing vLLM process (PID ${VLLM_PID})"
+    kill "${VLLM_PID}" 2>/dev/null || true
+    exit 1
+fi
+
+# ── Start FastAPI with vLLM cleanup on exit ──────────────────────────────────
+_cleanup() {
+    echo "[startup] Shutting down vLLM (PID ${VLLM_PID})"
+    kill "${VLLM_PID}" 2>/dev/null
+    wait "${VLLM_PID}" 2>/dev/null
+}
+trap _cleanup EXIT TERM INT
+
+echo "[startup] Starting FastAPI server on 0.0.0.0:7860"
+
+python -m uvicorn app:app \
+    --host 0.0.0.0 \
+    --port 7860 \
+    --workers 1 \
+    --timeout-keep-alive 300