Summary

FrankSherlock is a local-only, AI-powered application for intelligent cataloging and searching of media files across large directories, such as those found on Network Attached Storage (NAS) devices. It offers privacy-preserving organization by classifying images, extracting text from documents and media, and enabling robust search capabilities without any data leaving the user's machine. This makes it ideal for users who manage extensive personal media libraries and require advanced search and organization tools.

How It Works

The system operates by performing a read-only scan of specified directories, processing image, PDF, and video files. Core to its functionality is the use of Ollama's qwen2.5vl:7b vision LLM for classifying media content, identifying objects, and detecting specific types like anime or documents. Text extraction is handled by Surya OCR, with a vision LLM fallback, and further processed for key information. All indexed data, including generated thumbnails and extracted text, is stored in a local SQLite database with FTS5 for efficient full-text search. Its incremental scanning approach ensures rapid updates and efficient handling of large directories, while features like exact and perceptual duplicate detection, along with local face recognition via ONNX models (SCRFD, ArcFace), provide advanced media management capabilities.

Quick Start & Requirements

Installation is straightforward via pre-built binaries (AppImage for Linux, DMG for macOS, MSI for Windows) available on the project's Releases page. A key prerequisite is having Ollama installed and running (ollama serve). An NVIDIA GPU is recommended for optimal performance on Linux and Windows, while Apple Silicon is natively supported on macOS. Users building from source will need Node.js 20+ and Rust 1.77+. Note that the Windows MSI installer may trigger a SmartScreen warning due to being unsigned.

Highlighted Details

• Incremental Scanning: Optimized for directories with over 100,000 files, utilizing filesystem metadata for discovery and resuming scans from checkpoints, making rescans of unchanged directories exceptionally fast.
• Duplicate Detection: Identifies both exact duplicates (via SHA-256 fingerprints) and near-duplicates (using dHash perceptual hashing combined with LLM description similarity), with a 3-tier confidence coloring system for safe deletion.
• Face Recognition: Employs local ONNX models (SCRFD for detection, ArcFace for recognition) to cluster faces, allowing users to name, merge, and search for individuals within their photo library.
• Advanced Search: Supports full-text search across filenames, paths, descriptions, OCR text, and recognized character/series names, including natural language query parsing.

Maintenance & Community

The project utilizes GitHub Actions for CI/CD, running tests and building release binaries on tagged releases. No specific community channels (e.g., Discord, Slack) or detailed contributor information were found in the provided README.

Licensing & Compatibility

FrankSherlock is licensed under the GNU General Public License v3.0 (GPL-3.0). This is a strong copyleft license, meaning derivative works must also be licensed under GPL-3.0, which may impose restrictions on integration into closed-source commercial products.

Limitations & Caveats

The Windows MSI installer may present a "Windows protected your PC" warning due to a lack of code-signing. While an NVIDIA GPU is recommended for performance, it is not strictly required for basic functionality. The benchmark test files are not included in the repository due to copyright and privacy concerns.