Feat: Add PDF Decryption Support for Password-Protected Files

Summary

This PR adds support for processing password-protected PDF files in the document processing pipeline. Users can now decrypt and process encrypted PDFs by setting a password in the environment configuration.

Motivation

Previously, the system would fail to process encrypted PDF files without any clear indication of what went wrong. This enhancement allows users to work with password-protected documents, which is common in enterprise and academic environments where sensitive documents are often encrypted.

Changes Made

1. Configuration Management (lightrag/api/config.py)

• Addedpdf_decrypt_password parameter toglobal_args
• Reads fromPDF_DECRYPT_PASSWORD environment variable
• Defaults toNone if not set

2. Document Processing (lightrag/api/routers/document_routes.py)

• Modifiedpipeline_enqueue_file function to detect encrypted PDFs
• Implemented decryption logic using PyPDF2'sdecrypt() method
• Added comprehensive error handling for three scenarios:
  • No password provided: Clear error message directing users to setPDF_DECRYPT_PASSWORD
  • Incorrect password: Friendly error indicating the password is wrong
  • Decryption failure: Detailed error with exception information

3. Documentation (env.example)

• AddedPDF_DECRYPT_PASSWORD configuration example
• Included clear comments explaining the feature

Usage

Configuration

Add to your.env file:

# PDF decryption password for protected PDF filesPDF_DECRYPT_PASSWORD=your_password_here

Behavior

• Unencrypted PDFs: Process normally (no change in behavior)
• Encrypted PDFs with password set: Automatically decrypt and process
• Encrypted PDFs without password: Fail gracefully with helpful error message
• Encrypted PDFs with wrong password: Fail with clear indication of incorrect password

Error Messages

All error messages are user-friendly and appear in English:

• "PDF is encrypted but no password provided - Please set PDF_DECRYPT_PASSWORD environment variable"
• "Failed to decrypt PDF - incorrect password - The provided PDF_DECRYPT_PASSWORD is incorrect for this file"
• "PDF decryption failed - Error during PDF decryption: [details]"

Technical Notes

• Only affects PyPDF2 processing engine (DEFAULT mode)
• DOCLING mode is unchanged
• Password is accessed viaglobal_args.pdf_decrypt_password for consistency with other configuration
• Backward compatible - no breaking changes for existing deployments

Testing Recommendations

1. Test with unencrypted PDF - should work as before
2. Test with encrypted PDF without password set - should show friendly error
3. Test with encrypted PDF and correct password - should decrypt and process successfully
4. Test with encrypted PDF and incorrect password - should show password error

Checklist

• Code follows project style guidelines
• Comments are in English
• Environment variable documented inenv.example
• Error handling is comprehensive and user-friendly
• Backward compatible with existing functionality
• Configuration managed throughglobal_args pattern