Findrix

Local AI-powered semantic search for your images and documents. Describe what you're looking for in natural language and find it instantly across your files.

Uses SigLIP 2 for image search and Nomic Embed Text v2 for document search — runs entirely on your machine.

Features

• Image search — Find screenshots, photos, and graphics by describing what's in them
• Document search — Search through code, PDFs, DOCX, markdown, HTML, config files, and more
• Three interfaces — Web UI, desktop GUI (Tkinter), and CLI
• GPU accelerated — fp16 inference, torch.compile, batch prefetching pipeline
• Incremental indexing — Only embeds new files, with periodic checkpoints
• Smart chunking — Splits documents at natural boundaries (paragraphs, sentences) with overlap
• Cross-platform — Works on Windows, macOS, and Linux
• Fully local — No data leaves your machine

Quick Start

1. Install

pip install -e .

Or install dependencies directly:

pip install torch transformers sentence-transformers numpy Pillow fastapi uvicorn PyPDF2 python-docx

Requires Python 3.10+ and a CUDA-capable GPU (CPU fallback available but slower).

2. Configure search directories

# Add directories to search
findrix config --add-dir "/path/to/your/screenshots"
findrix config --add-dir "/path/to/downloads"

# View current config
findrix config --show

Default directories: ~/Desktop and ~/Downloads. Configuration is stored in ~/.findrix/config.json.

3. Build the index

# Index images
findrix image index

# Index documents
findrix text index

4. Search

Web UI (recommended):

findrix server
# Opens http://localhost:8420 in your browser

Desktop GUI:

findrix gui

CLI:

findrix image search "error message in terminal"
findrix text search "database connection pooling"

Architecture

findrix/
├── __init__.py          # Package metadata
├── __main__.py          # Unified CLI dispatcher
├── config.py            # Centralized configuration
├── image_search.py      # Image indexing & search (SigLIP 2)
├── text_search.py       # Document indexing & search (Nomic Embed v2)
├── gui.py               # Desktop GUI (Tkinter)
├── server.py            # Web server (FastAPI)
└── web/
    └── index.html       # Web frontend

Data Directory

All index files and configuration are stored in ~/.findrix/:

~/.findrix/
├── config.json           # Search directories, server settings
├── image_index.npz       # Image embeddings
├── text_index.npz        # Text embeddings
└── search_settings.json  # GUI preferences

Models

Component	Model	Embedding Dim	Purpose
Image search	google/siglip2-so400m-patch14-384	1152	Vision-language embeddings
Document search	nomic-ai/nomic-embed-text-v2-moe	768	Text embeddings (MoE)

Models are downloaded automatically from Hugging Face on first run.

How it works

1. Indexing — Walks your configured directories, embeds each image/document chunk, and saves the embeddings to .npz files
2. Searching — Embeds your text query, computes cosine similarity against all stored embeddings, and returns the top matches
3. Incremental updates — Re-running index only processes new files; use reindex to force a full rebuild

CLI Reference

# Image search
findrix image index                          # Build/update index
findrix image index --dir /path/to/pics      # Index specific directory
findrix image reindex                        # Force full re-index
findrix image search "query"                 # Search (top 10)
findrix image search "query" --top 20        # Search (top 20)
findrix image search "query" --open          # Search & open top result
findrix image config                         # Show configuration

# Document search
findrix text index                           # Build/update index
findrix text reindex                         # Force full re-index
findrix text search "query"                  # Search (top 10)
findrix text search "query" --top 20         # Search (top 20)
findrix text search "query" --open           # Search & open top result
findrix text config                          # Show configuration

# Server
findrix server                               # Start web UI (default port 8420)
findrix server --port 9000                   # Custom port

# GUI
findrix gui                                  # Launch desktop GUI

# Configuration
findrix config --show                        # Show current config
findrix config --add-dir /path/to/dir        # Add search directory
findrix config --remove-dir /path            # Remove search directory

You can also run via python -m findrix instead of findrix.

Web API

When running findrix server, the following endpoints are available:

Endpoint	Method	Description
/	GET	Web frontend
/api/status	GET	Index stats and readiness
/api/search/images?q=...	GET	Search images (params: threshold, sort, page, per_page)
/api/search/docs?q=...	GET	Search documents (params: threshold, sort, page, per_page)
/api/thumb/{id}?size=200	GET	Get image thumbnail
/api/open	POST	Open file in default app
/api/reveal	POST	Reveal file in explorer

Configuration

Config file (~/.findrix/config.json)

{
  "search_dirs": ["/path/to/your/pictures", "/path/to/downloads"],
  "exclude_dirs": ["node_modules", ".git", "__pycache__", "..."],
  "server_port": 8420,
  "server_host": "0.0.0.0"
}

Filtering

Both indexers support filtering via constants in their source files:

• EXCLUDE_DIRS — Directory names to skip (e.g., node_modules, .git)
• MIN_FILE_SIZE / MAX_FILE_SIZE — File size bounds
• IMAGE_EXTENSIONS / TEXT_EXTENSIONS — Supported file types

Supported document types

Code, text/markdown, JSON/YAML/TOML/XML/CSV configs, HTML/CSS, PDFs, and DOCX files. See TEXT_EXTENSIONS in text_search.py for the full list.

Performance

Approximate benchmarks (NVIDIA GPU with 16 GB VRAM):

• Image indexing: ~60-400 img/s (fp16, batch size 128)
• Image search: <50ms per query
• Document indexing: ~50-1000 chunks/s
• Document search: <20ms per query

License

MIT