📚 pyPDFLibrarianSort

Modern web-based PDF management platform - AI-powered organization with 98% cost savings + digital signatures with zero AI credits.

Complete PDF management: AI organization + digital signatures, all in one modern web interface

🎯 Key Features

• 🤖 Three AI Providers - Choose Gemini, Anthropic (Claude), or DeepSeek
• 💰 98% Cost Savings - Batch processing: $0.10 for 200 PDFs vs $10 individual
• 🌐 Modern Web Interface - Drag & drop, real-time preview, visual approval
• ✍️ PDF Signature Tool - Add signatures to PDFs with NO AI credits (web + CLI)
• 👀 Watch Mode - Auto-organize PDFs as they arrive (24/7 background mode)
• 🔍 Smart Renaming - Detects gibberish filenames, reads content, suggests better names
• 🌲 Deep Hierarchy - Preserves multi-level folder structures (3+ levels)
• 📊 Content Analysis - Reads PDF content for accurate categorization
• 🎒 Cross-Platform - Works on Windows, macOS, Linux
• 🔒 Privacy-First - Only filenames/metadata sent to API, never PDF content

💰 Cost Comparison

PDFs	Single Mode	Batch Mode	Savings
50	$2.50	$0.05	98% ✅
200	$10.00	$0.10	99% ✅
500	$25.00	$0.15	99% ✅

Why such huge savings? Batch mode processes ALL PDFs in a single API call instead of one call per PDF!

📖 Documentation

Getting Started

• Quick Start Guide - Get running in 5 minutes
• Project Brief - 30-second overview
• Get Started - Detailed setup guide

User Guides

• Web Interface Guide - Using the web UI
• PDF Signature Guide - Sign PDFs with no AI credits
• Watch Mode - Auto-organization setup
• Smart Renaming - How gibberish detection works
• Features Summary - Complete feature list

Reference

• Error Handling - Troubleshooting guide
• Portable Usage - Cross-platform usage
• Hierarchical Categories - Category system explained

For Developers

• CLAUDE.md - AI assistant guidance
• Skills Directory - Reusable development skills

📋 Table of Contents

• Installation
• Quick Start
• Usage Modes
• Cost Comparison
• Contributing
• License

🔧 Installation

git clone https://github.com/peterbamuhigire/pyPDFLibrarianSort.git
cd pyPDFLibrarianSort
pip install -r requirements.txt

Get an API key:

• Gemini: https://aistudio.google.com/app/apikey
• Anthropic: https://console.anthropic.com/
• DeepSeek: https://platform.deepseek.com/

See docs/guides/GET_STARTED.md for detailed setup instructions.

🚀 Quick Start

Web Interface (Recommended - All Features):

python web_interface.py
# Opens http://localhost:5000 automatically
# Access: PDF Organization + PDF Signatures

PDF Organization:

• Batch Mode: python organize_batch.py (cost-effective)
• Watch Mode: python watch_setup.py (auto-organize 24/7)

PDF Signatures (No AI Credits):

python sign_setup.py  # Interactive wizard
# OR
python sign_batch.py --signature sig.png --input document.pdf

See docs/guides/QUICK_START.md for detailed usage.

📖 Features & Usage Modes

PDF Organization (AI-Powered)

Mode	Best For	Cost (200 PDFs)	Command
Web Interface	Interactive use, visual review	$0.10	python web_interface.py
Watch Mode	Auto-organize 24/7	$0.10-0.20	python watch_setup.py
Batch Mode	One-time organization	$0.10	python organize_batch.py
Single Mode	Maximum accuracy	$10.00	python organize_simple.py

PDF Signatures (No AI Credits)

Mode	Best For	Cost	Command
Web Interface	Interactive signing with preview	$0	python web_interface.py
Interactive CLI	Step-by-step configuration	$0	python sign_setup.py
Direct CLI	Scripting & automation	$0	python sign_batch.py

Signature Features: 4 corner positions • Page selection (all/first/last/odd/even/ranges) • Size control (10-100%) • Opacity (10-100%) • Rotation (0-360°) • Batch processing

See docs/features/FEATURES_SUMMARY.md for detailed comparisons.

See comprehensive documentation in docs/ directory for detailed guides on configuration, troubleshooting, and advanced usage.

🤝 Contributing

We welcome contributions! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📝 License

MIT License - see LICENSE for details.

Free to use, modify, and distribute!

🙏 Credits

• AI Organization: Powered by Google Gemini, Anthropic Claude, and DeepSeek
• PDF Processing: ReportLab, PyPDF, Pillow
• Built with ❤️ for PDF management needs
• Thanks to all contributors!

🔗 Links

• Documentation
• Issue Tracker
• Discussions
• Gemini API

---

⭐ Star this repo if it helped you organize your PDF library!

💡 Have questions? Open a Discussion

🐛 Found a bug? Report an Issue