⚠️ Community Integration Fork | All credit goes to clusterzx for the original Paperless-AI project.
Paperless-AI is an AI-powered extension for Paperless-ngx created by clusterzx that brings automatic document classification, smart tagging, and semantic search using OpenAI-compatible APIs and Ollama.
This is a community-maintained integration fork that:
- 🧪 Tests and merges pending upstream pull requests
- 📦 Provides optimized Docker images (Lite & Full variants)
- 🔒 Applies security updates and dependency maintenance
- 🐛 Integrates community bug fixes
- 📝 Offers additional documentation
Important: This fork exists purely for experimentation and integration testing. All development credit belongs to the original author. Think of this as a "tinkering workshop" where community fixes are tested before potentially flowing back upstream.
Want the official version? → clusterzx/paperless-ai
Performance Enhancements:
- ⚡ PERF-001: History table with SQL pagination (~25-50x faster with 1000+ documents)
- 🎯 Tag caching with 5-minute TTL (95% reduction in API calls)
- 🔄 Force reload button to bypass cache when needed
Bug Fixes:
- ✅ PR-772: Fixed infinite retry loop with exponential backoff
- ✅ PR-747: History validation tool with real-time progress indicators
- ✅ SSE buffering fix for instant progress feedback
- ✅ Security: Authentication added to all history endpoints
Docker Optimizations:
- 📦 DOCKER-001: Optimized images (Lite ~400MB, Full ~1.2GB)
- 🏗️ Separate build/push workflow for reliability
- 🔧 Multi-stage builds with clean dependency installation
Documentation:
- 📚 Comprehensive COPILOT.md for developers and AI assistants
- 📋 Detailed fix documentation in
Included_Fixes/ - 🔗 Swagger API documentation improvements
UI/UX:
- 🌓 Enhanced dark mode support
- 📱 Responsive mobile menu
- ⏱️ Real-time progress bars with step counts
- 🎨 Improved loading indicators
All fixes are documented in Included_Fixes/ with detailed implementation notes:
| Category | Fix ID | Description | Status |
|---|---|---|---|
| Upstream PRs | PR-772 | Fix infinite retry loop | ✅ Merged |
| PR-747 | History validation tool | ✅ Merged | |
| Performance | PERF-001 | SQL pagination & tag caching | ✅ Applied |
| Security | SEC-001 | SSRF & code injection fixes | ✅ Applied |
| Docker | DOCKER-001 | Optimized Docker images | ✅ Applied |
| Dependencies | DEP-001 | Remove unused sqlite3 | ✅ Applied |
| CI/CD | CI-001 | Automatic version tagging | ✅ Applied |
Full details: Included_Fixes/README.md
It enables fully automated document workflows, contextual chat, and powerful customization — all via an intuitive web interface.
💡 Just ask:
“When did I sign my rental agreement?”
“What was the amount of the last electricity bill?”
“Which documents mention my health insurance?”
Powered by Retrieval-Augmented Generation (RAG), you can now search semantically across your full archive and get precise, natural language answers.
- Detects new documents in Paperless-ngx automatically
- Analyzes content using OpenAI API, Ollama, and other compatible backends
- Assigns title, tags, document type, and correspondent
- Built-in support for:
- Ollama (Mistral, Llama, Phi-3, Gemma-2)
- OpenAI
- DeepSeek.ai
- OpenRouter.ai
- Perplexity.ai
- Together.ai
- LiteLLM
- VLLM
- Fastchat
- Gemini (Google)
- ...and more!
- Natural language document search and Q&A
- Understands full document context (not just keywords)
- Semantic memory powered by your own data
- Fast, intelligent, privacy-friendly document queries
- Web interface for manual AI tagging
- Useful when reviewing sensitive documents
- Accessible via
/manual
- Define rules to limit which documents are processed
- Disable prompts and apply tags automatically
- Set custom output tags for tracked classification
⚠️ First-time install: Restart the container after completing setup (API keys, preferences) to build RAG index.
🔁 Not required for updates.
Images are available on both GitHub Container Registry (GHCR) and Docker Hub:
# Lite version (~500-700 MB) - AI tagging only
docker pull ghcr.io/admonstrator/paperless-ai-patched:latest
# Full version (~1.5-2 GB) - AI tagging + RAG search
docker pull ghcr.io/admonstrator/paperless-ai-patched:latest-fullBenefits of GHCR:
- ✅ No rate limits
- ✅ Unlimited bandwidth
- ✅ Free for public repositories
- ✅ Integrated with GitHub Actions
# Lite version
docker pull admonstrator/paperless-ai-patched:latest
# Full version
docker pull admonstrator/paperless-ai-patched:latest-full- Multi-stage optimized builds for smaller image sizes
- Health monitoring and auto-restart
- Persistent volumes and graceful shutdown
- Works out of the box with minimal setup
- Multi-arch support (amd64, arm64)
# Install dependencies
npm install
# Start development/test mode
npm run test- ✅ Multi-AI model support
- ✅ Multilingual document analysis
- ✅ Tag rules and filters
- ✅ Integrated document chat with RAG
- ✅ Responsive web interface
Note: This is an unofficial community fork. For core features and major changes, please contribute to the upstream project.
For this fork specifically:
- 🐛 Bug reports for integration issues
- 📦 Docker-related improvements
- 📝 Documentation enhancements
- 🧪 Testing feedback
Open an issue or PR if you have improvements to share!
- Upstream Issues: clusterzx/paperless-ai/issues
- Upstream Discord: Join Community
- Fork Issues: Admonstrator/paperless-ai-patched/issues
This project is licensed under the MIT License. See LICENSE for details.
Original work Copyright © clusterzx
Fork maintained by Admonstrator
