GitHub - linuxrebel/DocuBrowser: This does for Documents what repo-browser does for repos. A local AI powered Document search engine
Pangram verdict · v3.3
We believe that this document is mainly AI-generated, with some AI-assisted and human-written content
AI likelihood · overall
AIArticle text · 1,415 words · 6 segments analyzed
DocuBrowse v0.9.0 Packaged for Linux (RPM, DEB, tarball), Windows (zip), and macOS (dmg). Interfaces are stable; breaking changes are avoided where possible. DocuBrowse turns a messy pile of documents into something you can actually search. Point it at your files — PDFs, ebooks, Word docs, notes, whatever — and it builds a smart index that understands not just keywords, but meaning. Ask for "that contract about the lease renewal" and find it even if those exact words never appear. Click any result for an instant AI summary before you even open the file. PII aware and works with multiple document directories. DocuBrowse runs entirely on your own machine using local AI models — no internet connection required, no accounts, no API keys, and no per-query costs eating into a token budget. Your data. Your AI. Under the hood: SQLite FTS5 keyword search plus AI-powered semantic similarity and synopsis generation (Ollama + nomic-embed-text + dolphin3). Supports multiple document and source code types. Navigation Features Screenshots Quick Start CLI Reference Configuration Architecture API Endpoints Search Algorithm Security File Structure Troubleshooting Known Limitations Recent Changes Roadmap AI-Assisted Dev License Features ↑ Top 🔍 Dual Search Modes Keyword Search — fast full-text search via SQLite FTS5 (title, author, subject, tags, snippet) Semantic Search — AI-powered similarity via Ollama embeddings (nomic-embed-text:latest) Hybrid Mode (default) — 70% semantic + 30% keyword, merged and re-ranked 📖 AI Synopsis Click any document title for a Kindle-style book-jacket synopsis, generated on demand via Ollama (dolphin3:latest) and cached in the database after first generation. Semantic search embeddings are produced by a second local model (nomic-embed-text:latest) 📚 Document Indexing Formats: PDF, DOCX, PPTX, XLSX, EPUB, MOBI, AZW3, AZW, HTML, TXT, Markdown PDF intelligence: pdfplumber (preferred) with pypdf fallback for bloated-object files; layout=False retry for complex layouts; scanned
(image-only) PDFs detected and routed to ocr_list_pdfs.txt Word documents: python-docx extracts paragraphs, tables, and core properties (title, author, subject) Presentations: python-pptx extracts slide text, notes, and core properties Spreadsheets: openpyxl extracts cell values and sheet names E-books: ebooklib for EPUB; mobi package + Calibre fallback for MOBI/AZW3; DRM-encrypted AZW files indexed with metadata only (title/author visible, body not searchable) Metadata: title, author, subject extracted from document metadata fields; auto-generated tags from directory structure and content keywords PII protection: post-ingest scanner detects SSN, credit card, bank routing/account number, DOB, MRN, driver license, passport patterns; removes matching documents and permanently blacklists them 🎨 User Interface Dark/Light theme toggle Paginated results (50 docs/page) with Back/Next controls Alphabetic index bar (A–Z, 0–9) for quick navigation, with state preserved across page loads; Home button to reset Tag cloud for filtering by topic Relevance score badges (0–100%) on every result Open button on each result card — launches the file in your default app via xdg-open Click document title for an AI synopsis; 📋 copies path to clipboard; 🗑 deletes file from disk and index (with confirmation) Moved/deleted documents: clicking a doc whose file no longer exists shows a dismissable modal (and removes it from the index on dismiss) if its filesystem is mounted, or a toast (no index change) if the filesystem can't be verified (e.g. unmounted drive) ⚙ Settings (/settings) General panel: document directory (with live directory
browser), any number of additional scan directories (added/removed under the same panel — automatically included in scan/rescan, no extra command needed), working directory, and port Ignored Directories panel: browse to add a directory to ignore_dirs.txt, with a confirmation prompt before purging already-indexed documents under it, and a confirmation before removing an entry ⚡ Performance Search latency: <150ms typical Parallel PDF extraction with ProcessPoolExecutor (physical-core-aware worker count) Memory-safe: kernel-enforced RLIMIT_AS (6 GB/worker) + pause/resume on free-RAM threshold Screenshots ↑ Top Click any thumbnail to view full size. Dark Mode Light Mode Settings AI Synopsis Settings is a standalone page at /settings (opened in a new tab via the gear icon). The General panel covers the document directory (with live directory browser, plus any number of additional scan directories), working directory, and port; the Ignored Directories panel manages scan exclusions, each with a directory browser, add/clear controls, and confirmation before removal. Quick Start ↑ Top Prerequisites Python 3.9+ pdfplumber, pypdf — PDF extraction python-docx — Word documents python-pptx — PowerPoint presentations openpyxl — Excel spreadsheets ebooklib, beautifulsoup4, mobi — E-books psutil — cross-platform process and hardware detection Calibre — E-book metadata and conversion (required for MOBI/AZW3/AZW indexing): sudo dnf install calibre or sudo apt install calibre Ollama — installed automatically by docubrowser start if missing Modern browser (Chrome, Firefox, Safari, Edge) See INSTALL.md for a full step-by-step guide. Install (recommended) DocuBrowse ships as RPM, DEB, tarball, Windows zip, and macOS dmg packages. Download the appropriate package from the Releases page. #
Fedora / RHEL sudo dnf install ./docubrowser-foss-0.9.0-7.noarch.rpm # Debian / Ubuntu / Mint sudo apt install ./docubrowser-foss_0.9.0-7_all.deb # Any Linux (tarball) tar xzf docubrowser-foss-0.9.0-7.tar.gz cd docubrowser-foss-0.9.0-7 sudo ./install.sh Windows: Extract the zip, then double-click Install.bat. Requires Python 3.9+ and Ollama to be pre-installed. Installs to %USERPROFILE%\DocuBrowse with a Start Menu shortcut — no admin required. You may need to log out and back in for the shortcut to appear. macOS: Open the dmg, then double-click Install.command (right-click → Open the first time — the scripts are unsigned). Requires Python 3.9+. Installs to ~/Applications/DocuBrowse/ with a Python virtualenv, CLI wrappers at /usr/local/bin/docubrowser and /usr/local/bin/docuback (sudo prompted; falls back to ~/bin/ if declined), and a DocuBrowse.app launcher that starts the server and opens the web UI in Terminal. All Linux methods install to /opt/docubrowser/ with a Python virtualenv, CLI wrappers at /usr/bin/docubrowser and /usr/bin/docuback, a desktop menu entry under Office, and all Python dependencies from requirements.txt. Once installed, the CLI is the docubrowser command — drop the ./ and .py from every example below. For example, docubrowser start and docubrowser rescan. The ./docubrowser.py <cmd> form shown throughout the rest of this README is the dev / cloned-repo path (running directly out of a checkout). To uninstall: sudo dnf remove docubrowser-foss (RPM), sudo apt remove docubrowser-foss (DEB), sudo ./uninstall.sh (tarball), double-click Uninstall.bat (Windows), or double-click Uninstall.command (macOS — on the dmg or in ~/Applications/DocuBrowse/).
First Run (dev / cloned repo) cd /path/to/DocuBrowse # Scan and index your documents ./docubrowser.py rescan # Start the server ./docubrowser.py start # Open the UI ./docubrowser.py open On an installed system, use the docubrowser command instead, e.g. docubrowser rescan / docubrowser start / docubrowser open. docubrowser.py start automatically verifies Ollama is installed, running, and has both required models — nomic-embed-text:latest (embeddings) and dolphin3:latest (synopsis generation) — installing/starting/pulling as needed. CLI Reference ↑ Top Usage: docubrowser.py <command> [options] Commands Command Description start Start the search server (runs Ollama check first) stop Stop the server restart Stop then start status Show server status, document count, embedding count, tag count scan [TYPE ...] Scan and index documents (no embedding) rescan [TYPE ...] Scan + generate embeddings scan-file --file PATH Extract and index a single file, then embed it embed Generate/refresh embeddings for un-embedded documents open Open the DocuBrowse UI in your default browser purge Scan index for PII and remove matching documents ignore add|remove|list DIR Manage directories excluded from scanning (auto-purges on add) report Walk doc directory and show file-type breakdown (no DB changes) scan-missing [--db PATH] [--dry-run] Opt-in cleanup: classify every indexed path as present/missing/unmounted, delete missing rows (cascades), leave unmounted rows alone stopall Stop all running scans, embeds, and the server duplist List duplicate
documents (exact SHA256 + optional near-duplicate) dupclean Interactive TUI to review and remove duplicate documents Global Options --db PATH SQLite database path (overrides config) --port PORT Server port (overrides config) --config FILE Config file path Command Examples # Server management ./docubrowser.py start ./docubrowser.py start --port 9000 ./docubrowser.py status ./docubrowser.py stop ./docubrowser.py stopall # Scanning ./docubrowser.py scan # scan all supported types ./docubrowser.py scan pdf # PDFs only ./docubrowser.py scan pdf txt # PDFs and plain text ./docubrowser.py scan --limit 100 # first 100 unindexed files only ./docubrowser.py rescan # scan + embed all types ./docubrowser.py rescan pdf --workers 4 # PDFs only, 4 workers ./docubrowser.py rescan --no-embed # scan without embedding step ./docubrowser.py rescan --doc-dir /data/docs # Single-file indexing (useful for retrying blacklisted files) ./docubrowser.py scan-file --file /path/to/document.pdf ./docubrowser.py scan-file --file /path/with spaces/doc.pdf # no quoting needed ./docubrowser.py scan-file --file /path/to/doc.pdf --no-embed # Reporting and maintenance ./docubrowser.py report # file-type breakdown, no DB changes ./docubrowser.py embed # embed any un-embedded docs ./docubrowser.py purge --dry-run # preview PII matches (safe) ./docubrowser.py purge # remove PII documents (prompts) # Excluding directories from scanning ./docubrowser.py ignore add /mnt/data/Documents/myWorkDocs # exclude + purge indexed docs under