admonstrator/paperless-ai-next repository overview

⁠Paperless-AI next

🧠 What makes it "Next"⁠ | 💖 Fuel the Evolution⁠ | 🚀 Quick Start⁠ | 💬 Frequently Asked Questions⁠

⁠📊 At a Glance: Next vs. Original

⁠🚀 The Evolution: What makes it "Next"?

This isn't just a collection of patches; it's a total overhaul of how your documents interact with AI. I took the original logic and ran it through a "Does this actually make my life easier?" filter.

⁠🧠 High-IQ Classification

Connect to OpenAI, Ollama, or any OpenAI-compatible API. We've moved beyond simple keyword matching. The AI now understands intent and context, meaning it knows the difference between an "Electricity Bill" and a "Manual for a Toaster" without you writing a single regex.

⁠👓 Flexible OCR Vision (Mistral + Local)

Waging war against blurry scans, shaky smartphone photos, and handwritten scribbles that standard OCR usually chokes on. You can run OCR with:

• Mistral OCR (provider: mistral)
• local OpenAI-compatible vision APIs (provider: ollama + /v1 endpoint, e.g. LM Studio-compatible)
• native Ollama chat vision APIs (provider: ollama + /api/chat endpoint)

The OCR setup now also validates real image reading instead of only checking endpoint reachability.

⁠⚡️ Performance without the "Spinner-Induced Rage"

I hated the lag in the original UI. I've implemented server-side pagination and aggressive tag caching. Whether you're managing 100 documents or 10,000, the dashboard stays snappy and your browser stays alive.

⁠🛡️ Hardened for Production

I use this for my own life and my own documents. That means security isn't an afterthought - it's a requirement. Expect regular dependency updates, a reduced container attack surface, and error handling that fails gracefully instead of taking your whole stack down with it.

⁠🧩 The "Best of" Community DNA

There were dozens of brilliant ideas and PRs left gathering dust in the original repository. I've personally hand-picked, tested, and integrated the best community suggestions, making this the most feature-complete version of the tool available.

⁠🤖 Vibe-Coded, Human-Vetted

Built with heavy AI assistance but steered by human common sense. It's vibe-coded in the sense that I prioritize how the tool actually feels to use over rigid corporate specs. Yet it's engineered to be more stable than your enterprise-driven Microsoft Access '97 nightmare business software.

⁠💖 Fuel the Evolution

Maintaining this solo, chasing bugs, and keeping up with the rapid pace of AI is a massive labor of love. If this tool saves your sanity (and your weekends), consider fueling the next update. Whether it's a cold energy drink or just a "thanks"; your support keeps the code flowing.

⁠⚠️ A Note on Stability & Migration

Data is sacred. Back it up.

Because Paperless-AI next introduces significant architectural improvements and new database logic, it's a "one-way street" evolution. Since I am cleaning up and optimizing the core logic plus adding new features, there is no guarantee of stability right now.

⁠🚀 Quick Start

⁠Docker Compose (Recommended)

Please check the docker variables here⁠ for all configuration options.

services:
  paperless-ai-next:
    image: admonstrator/paperless-ai-next:latest
    container_name: paperless-ai-next
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - data:/app/data

volumes:
  data:

Then open http://localhost:3000⁠ to complete setup.

⁠OCR Provider Notes

• OCR API key env: OCR_API_KEY (backward-compatible fallback: MISTRAL_API_KEY)
• Local OCR supports model discovery from both /api/tags (Ollama-style) and /v1/models (OpenAI-compatible)
• OCR test sends a real PNG image and expects the exact token: OCR-TEST-182730173401
• For OpenAI-compatible endpoints that reject data URLs, OCR validation automatically retries with raw base64 payload

⁠Container Images

Docker Hub: admonstrator/paperless-ai-next⁠

Versioned release tags use the format vYYYY.MM.## (example: v2026.03.01).

⁠💬 Frequently Asked Questions

⁠"Is this project stable if it's vibe-coded?"

Short answer: I use it every day for my actual documents. If it breaks, my own life becomes a chaotic mess of untagged invoices—so I have a very strong biological incentive to keep it stable.

Long answer: It's not vibe-coded in the sense of being random; I test every feature and try to automate as much of the testing as possible. And NO! it's not just one pile of AI-generated code inside a main.js file. Since I work as an IT architect, I understand the importance of maintainable code.

⁠"So you don't read the code? Should I be worried?"

I can read and understand code logic, but I don't write JavaScript from scratch myself. I treat AI like a talented, slightly erratic junior dev. I guide the architecture, I read and audit the logic of every line it generates, and I test the hell out of it. I am the filter. No "AI-slop" gets merged without passing my "Does this actually solve the problem?" test. Or at least, it doesn't stay merged if I encounter issues in production. You can learn more about the author's background and the AI-assisted development workflow on the About the Project & Author⁠ page.

⁠"Why was RAG (semantic search/chat) support removed?"

We decided to focus the project entirely on its core mission: highly reliable automated document tagging, correspondent detection, and custom field/metadata extraction. Running a secondary Python RAG container with a vector database (ChromaDB) added massive image sizes, high RAM requirements, and severe architectural overhead. For a detailed breakdown of this decision, check out the RAG Deprecation page⁠.

⁠"What if I'm a 'real' developer and I find a bug?"

Please, for the love of all that is holy, open a PR. I welcome everyone; from fellow vibe-coders to the wizards who actually understand memory management. If you see something that makes your inner Senior Architect cry, fix it and send it over. I'm happy to learn, as long as we keep the "it just works" spirit alive.

⁠"Why should I use this instead of the original project?"

If the original works for you, stay there! But if you're tired of loading spinners, want better AI and OCR, then Paperless-AI next is for you. It's a more polished, more powerful, and more user-friendly evolution of the original vision.

⁠"Does this support [Specific Niche AI Provider]?"

If it's OpenAI-compatible, it probably works. If not, open an issue! Since I have an AuDHD brain, I'm prone to hyper-focusing on cool new features — so if your suggestion catches my interest, it might be implemented before my second energy drink.