Calibre Bookwarden

The Content-Grounded Metadata, Cover Forensics & Curation Guardian for Calibre Libraries.
"The book file is the ground truth. LLMs and OCR are witnesses."

🎯 What is Calibre Bookwarden?

[!NOTE] Evolution to Calibre Bookwarden: Formerly titled Calibre AI Auditor, the project evolved and was rebranded to Calibre Bookwarden to honor its true calling: acting as an incorruptible custodian and guardian of your digital book vault. We eliminated the corporate "AI auditor" jargon because our foundation is deterministic mathematics, container forensics, and zero-risk invariant checking—never stochastic hallucinations.

Music collections have Beets, document archives have Paperless-ngx, and home cinema has Sonarr/Radarr. Yet digital book collectors have spent over 15 years trapped in desktop PyQt interfaces or wrestling with fragile SQLite lockups, corrupted thumbnails, missing series volumes, and AI plugins that hallucinate synopses.

Calibre Bookwarden is a headless, high-performance forensic curation engine built for modern homelabs, power readers, and digital archivists. It verifies metadata and covers directly against the authentic container contents (EPUB OCF container, PDF XMP dictionary, CBZ/CBR comics) with zero-risk read-only audits, deterministic bibliographic authority rules, Shannon entropy vision scoring, and surgical atomic rollbacks.

                  ┌──────────────────────────────────────────────┐
                  │            THE BOOK CONTAINER                │
                  │   EPUB (OCF/OPF) • PDF (XMP) • CBZ (Archive) │
                  │            [ GROUND TRUTH ]                  │
                  └──────────────────────┬───────────────────────┘
                                         │
                   Deterministic Forensic Inspection (No AI)
                                         │
                                         ▼
┌───────────────────────┐      ┌──────────────────┐      ┌─────────────────────────┐
│     Gemini 3.8        │      │    Calibre DB    │      │    Local Tesseract      │
│   Multimodal API      ├─────►│   metadata.db    │◄─────┤      OCR Engine         │
│   [ WITNESS ONLY ]    │      │  [ FAIL-CLOSED ] │      │    [ WITNESS ONLY ]     │
└───────────────────────┘      └──────────────────┘      └─────────────────────────┘

✨ Key Capabilities

🔍 360° Forensic Audit Engine

• Instant Integrity Check: Directly audits SQLite schema, table invariants, and foreign key junction tables (books_authors_link, books_tags_link, data).
• Physical vs. Database Parity: Detects missing format files on disk (FILE_MISSING_ON_DISK), empty format records, and orphaned book directories.
• Junk Title & Extension Strip: Identifies and flags scraper residue like [welib.org], (z-library), _print, and filename leaks (.pdf, .epub) in titles.

🖼️ Cover Quality Scoring (CQS 0–100) & Defect Detection

• Mathematical Quality Evaluation: Scores covers using pixel density, 1:1.5 golden aspect ratio adherence, Laplacian sharpness, and color contrast.
• Spurious Cover Detector: Flags solid monochrome stubs, blank scanner pages, internal body text pages, and Calibre default brown generated templates.
• Image Safety & Decompression Guard: Limits image parsing to 60 MP to neutralize decompression bomb exploits (Image.DecompressionBombError).

🃏 "Cover Deck" Swipeable Review UI

• Tinder-Style Cover Triage: Modern, ultra-lightweight HTMX + Tailwind CSS interface.
• Keyboard-Driven Workflow: Review low-quality (Tier C/D) or spurious covers with left/right arrow keys, compare against high-res candidates from OpenLibrary and Hardcover, and approve upgrades with a single keystroke.

📚 Series Gap Hunter & Multi-Format Consolidator

• Series Gap Hunter: Scans collections and multi-volume sagas to detect missing intermediate and leading books (e.g. owning Volumes 1, 2, and 4; flagging missing Volume 3). Includes runaway span guards (MAX_GAP_SPAN = 200).
• FRBR Multi-Format Consolidator: Detects books duplicated across separate records (e.g. Book ID 100 has EPUB, Book ID 101 has PDF of the same work) and identifies shared ISBN collisions with modulo-10/11 check-digit verification.

⚡ Extreme Performance & O(1) Streaming

• Zero N+1 Query Antipattern: Custom atomic SQL queries with GROUP_CONCAT and compound JOINs.
• Blazing Fast SMB Scans: Audits 3,180 books over local network shares in 45 seconds with <30 MB RAM consumption.
• Keyset Pagination: Streams 100,000+ books with constant memory footprint.

🏛️ Bibliographic Authority Rules & Sort Synchronization

• Standardized Author Sorting: Enforces canonical "Last, First" conventions for complex names, nobility, popes, patristic saints, and classical authors (e.g. Jerome K. Jerome, Toni Morrison).
• Periodicals & Feeds: Automatically classifies news feeds (Financial Times, The Economist Espresso, Nature) into Periodical and News categories.

🏗️ Architecture

flowchart TD
    subgraph ClientLayer["🖥️ Client & Access Layer"]
        WebUI["WebUI / Cover Deck (HTMX + Tailwind)"]
        CLI["CLI (uvx / typer)"]
        MCP["MCP Server (Model Context Protocol)"]
    end

    subgraph SecurityBoundary["🛡️ Safe Isolation Boundary (Certificate A)"]
        Edge["Caddy Edge (TLS + Tailscale / Loopback Auth)"]
        App["App Service (UID 10001 / Non-Root / Read-Only RootFS)"]
        Queue["PostgreSQL Queue & Lease Store"]
        Verifier["Verifier Worker (Offline Read-Only Mount)"]
    end

    subgraph StorageLayer["💾 Storage & Calibre State"]
        CalibreDB[("Calibre metadata.db (SQLite WAL)")]
        DiskStorage["Ebook Filesystem (EPUB, PDF, CBZ)"]
        CalibreWeb["Calibre-Web Automated (Hot Reload / SIGHUP)"]
    end

    subgraph Witnesses["👁️ Multimodal & External Witnesses"]
        Gemini["Gemini 3.8 Flash API"]
        OCR["Local Tesseract OCR"]
        Hardcover["Hardcover GraphQL / OpenLibrary"]
    end

    WebUI --> Edge
    Edge --> App
    CLI --> App
    App --> Queue
    Queue --> Verifier
    Verifier --> CalibreDB
    Verifier --> DiskStorage
    Verifier --> Witnesses
    Verifier -.->|"Zero Downtime Reload"| CalibreWeb

🚀 Quickstart

Option A: Run via uvx (No Installation Required)

If you have uv installed, run a comprehensive 360° read-only audit in one command:

# Run a 360° forensic audit without modifying any files (using new bookwarden CLI)
uvx --from git+https://github.com/felixapel/calibre-bookwarden.git bookwarden audit-360 --library "/path/to/Calibre Library"

# Synchronize author sort keys to canonical bibliographic standards
uvx --from git+https://github.com/felixapel/calibre-bookwarden.git bookwarden sync-library --library "/path/to/Calibre Library"

# (Note: `bookaudit` remains fully supported as a transparent backwards-compatible alias)

Option B: Docker Compose (Sidecar Pattern for Homelabs)

Run Calibre Bookwarden as a companion sidecar alongside your existing linuxserver/calibre and calibre-web-automated containers:

services:
  calibre-bookwarden:
    image: ghcr.io/felixapel/calibre-bookwarden:latest
    container_name: calibre-bookwarden
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - /mnt/user/MEDIA/Books/Calibre Library:/calibre:ro
      - /mnt/user/appdata/calibre-bookwarden:/config
    environment:
      - BOOKWARDEN_READ_ONLY=true
      - BOOKWARDEN_LIBRARY_PATH=/calibre
      - CALIBRE_WEB_CONTAINER=calibre-web-automated
      - GEMINI_API_KEY=${GEMINI_API_KEY}

Option C: unRAID Community Applications

Install directly from the unRAID web UI using the pre-configured template:

• Template URL: https://raw.githubusercontent.com/felixapel/calibre-bookwarden/main/deploy/unraid/calibre-bookwarden.xml
• Volume Mount: Set /calibre to your Calibre library share (e.g. /mnt/user/MEDIA/Books/Calibre Library).

📊 Live Library Performance

Benchmarked against a production library of 3,180 books over SMB network storage:

🛡️ Safety Invariants (Certificate A)

Calibre Bookwarden operates under strict cryptographic and database constraints:

1. Offline & Read-Only Guarantees: Core auditing strictly mounts /calibre as :ro.
2. Atomic Snapshots: Any write or remediation requires an instant VACUUM INTO backup (metadata.db.bak_<timestamp>) verified on disk before any table modification.
3. Non-Root Execution: Container images run as unprivileged user 10001:10001 with read-only rootfs and CapDrop: ALL.
4. Trigger Preservation: Database triggers (title_sort, author_sort) are registered in Python so SQLite triggers execute cleanly without throwing constraint errors.
5. Human-in-the-Loop Triage: High-impact actions (cover replacement, format merges) support staged dry-runs with preview manifests and reversible rollback journals.

💖 Supporting & Sponsoring

Calibre Bookwarden is an independent open-source project dedicated to digital preservation, content-grounded media verification, and homelab sovereignty.

If this project saved your library from corruption, upgraded your covers, or saved you hours of manual editing, please consider supporting continued development:

Where does funding go?

• 🖥️ Homelab Test Hardware: Maintaining real unRAID, TrueNAS, and multi-GPU testing rigs for local OCR and vision models.
• 🔬 Ebook Forensics Research: Adding deep container parsers for obscure formats (MOBI PalmDOC, DjVu, CBZ comic metadata).
• ☕ Open Source Sustainability: Keeping the project 100% telemetry-free, ad-free, and GPLv3 licensed.

📖 Documentation Index

• 📘 Architecture Specification
• 🔒 Safety Model & Threat Boundaries
• 🌐 API Reference
• 🏠 Homelab Integration Guide
• 🚀 Production Operations Runbook
• 📑 Database Schema & Migration Docs
• 🧪 Testing & Verification Guide
• 📜 ADR-005: Certificate A Production Boundary

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for branch naming, coding standards, and testing requirements before opening a PR.

# Run local quality gates
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest -m "not benchmark and not ocr_live and not network"

📄 License

Licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
Copyright © 2026 Felix Apel and contributors.