Alpha Release Notice: This project was developed using AI-assisted "vibe coding" methodology with Claude (Opus 4.5) by Anthropic. While functional and tested, users should evaluate suitability for their use case. Use at your own risk.

DeDox = de (undo, remove) + dox (documents) — detoxify your paperwork by transforming chaotic piles of documents into organized, searchable, AI-enhanced archives.

A self-hosted, privacy-first document ingestion service that captures, processes, extracts metadata, and archives documents to Paperless-ngx.

Scan documents with your phone using live edge detection, then watch DeDox automatically extract metadata via local LLM.

Documents are enriched with AI-extracted metadata in Paperless-ngx, then synced to Open WebUI for RAG-powered chat.

Your documents never leave your network. DeDox is designed from the ground up to operate entirely within your local network:

• No cloud dependencies: All processing happens on your hardware
• No external API calls: LLM inference runs locally via Ollama or llama.cpp
• No telemetry or tracking: Your data stays yours
• Air-gapped compatible: Works without any internet connection
• Mobile app: Connects only via local network (LAN/WiFi) — no internet traffic, no external servers

This makes DeDox ideal for sensitive documents like financial records, medical documents, legal paperwork, and personal correspondence.

DeDox integrates with external services via their APIs, making each component completely independent and optional:

• Use existing instances: Already running Paperless-ngx or Open WebUI on your home network? Point DeDox at them — no need to run duplicates
• Mix and match: Don't need AI chat? Disable Open WebUI sync entirely in config/settings.yaml
• Upgrade independently: Each service can be updated, scaled, or replaced without affecting others
• Resource flexibility: Running on limited hardware? Skip Open WebUI and still get full document processing

# config/settings.yaml - Disable Open WebUI if not needed
openwebui:
  enabled: false  # Simply disable if you don't need RAG chat

• 📷 Phone Camera Capture: Live edge detection, perspective correction, multi-page scanning — all via local WiFi, no internet
• 🔍 OCR Processing: Tesseract-based text extraction (German/English) running locally
• 🤖 AI Metadata Extraction: Local LLM-powered extraction of dates, amounts, types, urgency via Ollama or llama.cpp
• 🔐 Privacy First: Zero cloud dependencies, zero external API calls, runs entirely on your local network
• 📦 Paperless-ngx Integration: Seamless archival with full metadata mapping (works with existing instances)
• 💬 Open WebUI RAG (optional): Chat with your documents using semantic search and AI-powered Q&A
• ⚙️ Extensible Pipeline: Configurable processing stages and metadata fields
• 🔌 API-First Design: All integrations via standard APIs — plug into your existing infrastructure

All components communicate via standard REST APIs over your local network — no internet required.

┌─────────────────────────────────────────────────────────────────────┐
│                    Local Network (No Internet)                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐                                                   │
│  │  Mobile App  │ ◀──── WiFi/LAN only, no internet traffic          │
│  └──────┬───────┘                                                   │
│         │                                                            │
│         ▼                                                            │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐  │
│  │   DeDox Web UI  │───▶│  DeDox API      │───▶│ Paperless-ngx   │  │
│  │   (Frontend)    │    │  (Python)       │    │ (existing or new)│  │
│  └─────────────────┘    └────────┬────────┘    └────────┬────────┘  │
│                                  │                       │           │
│                    ┌─────────────┼───────────────────────┤           │
│                    │             │                       │           │
│              ┌──────────┐  ┌─────▼──────┐        ┌──────▼──────┐    │
│              │ Tesseract│  │  Ollama /  │        │  Open WebUI │    │
│              │   OCR    │  │ llama.cpp  │◀───────│  (optional) │    │
│              └──────────┘  └────────────┘        └─────────────┘    │
│                                                                      │
│  API-Based Integration:                                              │
│  • Each component is independent and communicates via REST APIs     │
│  • Use existing Paperless-ngx/Open WebUI instances on your network  │
│  • Remove or disable any optional component without breaking others  │
└─────────────────────────────────────────────────────────────────────┘

DeDox supports two LLM backends:

Configure via environment variable:

# Ollama (default)
DEDOX_LLM_PROVIDER=ollama
DEDOX_OLLAMA_URL=http://ollama:11434

# llama.cpp / OpenAI-compatible
DEDOX_LLM_PROVIDER=openai-compat
DEDOX_OLLAMA_URL=http://your-server:8080
DEDOX_LLM_API_KEY=optional-api-key

llama.cpp users: Start your server with --ctx-size 32768 (or at least 8192) to handle document extraction prompts. The default of 4096 is too small.

• Docker & Docker Compose
• 8GB+ RAM recommended (for local LLM)

1. Clone the repository:

   git clone <repository-url>
   cd dedox

2. Copy and configure environment:

   cp .env.example .env
   # Edit .env with your settings

3. Start all services:

   docker-compose up -d

4. Access the services:

   • DeDox API: http://localhost:8000
   • Paperless-ngx: http://localhost:8080
   • Open WebUI: http://localhost:3000

That's it! DeDox automatically handles:

• Paperless-ngx API token generation
• Open WebUI API key generation
• Knowledge base creation
• Workflow setup

Configuration files are located in config/:

• settings.yaml - Main application settings
• metadata_fields.yaml - Configurable metadata extraction fields
• document_types.yaml - Document type definitions
• urgency_rules.yaml - Urgency calculation rules

Once running, access the API documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

1. Ingest → Store original, return job ID
2. Image Processing → Edge detection, alignment, enhancement
3. OCR → Text extraction with Tesseract
4. Upload to Paperless → Archive processed document with "Processing..." tag
5. Metadata Extraction → LLM-based field extraction
6. Finalize → Update Paperless metadata, remove processing tag

1. Document Updated → Paperless webhook fires
2. Download → Fetch document and metadata from Paperless
3. Upload → Send to Open WebUI for processing
4. Process → Open WebUI extracts embeddings
5. Index → Add to knowledge base for RAG chat

DeDox uses two separate webhooks for different purposes:

Purpose: Trigger DeDox pipeline for OCR and LLM-based metadata extraction

Setup in Paperless:

1. Go to Workflows in Paperless admin
2. Create new workflow:
   • Trigger: Document Updated
   • Filter: Tags contain dedox:reprocess
   • Action: Webhook
   • URL: http://dedox:8000/api/webhooks/paperless/document-updated
   • Method: POST

Purpose: Sync ALL document updates to Open WebUI for semantic search

Setup in Paperless:

1. Go to Workflows in Paperless admin
2. Create new workflow:
   • Trigger: Document Updated
   • Filter: (None - trigger on ALL updates)
   • Action: Webhook
   • URL: http://dedox:8000/api/webhooks/paperless/document-sync
   • Method: POST

Note: These workflows are independent. Reprocessing a document will trigger both: first the DeDox processing pipeline, then when metadata is updated back to Paperless, the sync webhook fires and updates Open WebUI.

Open WebUI settings can be configured in config/settings.yaml:

openwebui:
  enabled: true                        # Enable/disable sync
  base_url: "http://open-webui:8080"   # Internal API URL
  frontend_port: 3000                  # External access port
  api_key: "${DEDOX_OPENWEBUI_API_KEY:}"
  knowledge_base_id: "dedox-documents"
  auto_create_knowledge_base: true
  timeout_seconds: 60
  wait_for_processing: true
  max_processing_wait: 300

To disable Open WebUI sync temporarily, set enabled: false in the config.

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run development server
uvicorn dedox.api.app:app --reload --port 8000

docker-compose up -d

Already have Paperless-ngx or Open WebUI running on your network? Connect DeDox to your existing infrastructure:

# Configure existing service URLs in .env
DEDOX_PAPERLESS_URL=http://your-paperless-server:8000
DEDOX_PAPERLESS_TOKEN=your-existing-token
DEDOX_OPENWEBUI_URL=http://your-openwebui-server:3000  # optional

# Run minimal DeDox (without bundled Paperless/Open WebUI)
docker-compose -f docker-compose.minimal.yml up -d

If you don't need RAG chat capabilities, simply disable Open WebUI in your config:

# config/settings.yaml
openwebui:
  enabled: false

For Proxmox users with an existing llama.cpp server and Open WebUI instance:

# On Proxmox host: create a Debian 12 LXC with Docker
bash deploy/proxmox/create-lxc.sh

# Inside the LXC: interactive setup wizard
pct enter <VMID>
bash /opt/dedox/deploy/proxmox/setup.sh

The setup wizard will:

• Auto-detect your llama.cpp server and available models
• Configure Paperless-ngx with admin credentials
• Connect to your existing Open WebUI instance
• Generate security secrets
• Optionally start all services

See deploy/proxmox/README.md for full documentation.

# Run all tests
pytest

# Run with coverage
pytest --cov=dedox --cov-report=html

# Run specific test file
pytest tests/test_pipeline.py -v

• POST /api/auth/login - Login and get JWT token
• POST /api/auth/register - Register new user
• GET /api/auth/me - Get current user info
• POST /api/auth/api-keys - Create API key