🗂️ FileSense – Smart File Organizer

Quick Overview

Tired of your Downloads folder looking like a digital junkyard? FileSense uses advanced AI to understand what each file is about and organizes it automatically.

🧠 Semantic Understanding

Reads file content and understands meaning using SentenceTransformers embeddings.

⚡ Lightning Fast

FAISS indexing provides fast similarity searches locally on your machine.

👁️ OCR Enabled

Automatically extracts text from scanned PDFs and image-only documents.

🕵️ Fully Offline

Works entirely offline—nothing leaves your device, complete privacy.

🔄 Real-time Watch

Detects and organizes new files automatically as they appear.

🖥️ Easy GUI

Desktop launcher with start/stop controls, logs, and system tray support.

📽️ Demo Video 📖 Deep Wiki

How It Works

FileSense follows a four-step pipeline: extract text, generate embeddings, find best match, move file.

1️⃣ Create FAISS Index

Build a semantic search index from your folder descriptions:

python scripts/create_index.py

2️⃣ Process Files in Bulk

Scan and classify all files with optional multithreading:

python scripts/script.py --dir ./files --threads 8

3️⃣ Watch Folder Real-time

Automatically organize new files as they arrive:

python scripts/watcher_script.py --dir ./files

4️⃣ Launch with GUI

Simple desktop interface with logs and tray control:

python scripts/launcher.py

Project Structure

FileSense/
├── scripts/
│   ├── create_index.py      # Build FAISS index from folder labels
│   ├── process_file.py      # Extract, classify, and move files
│   ├── script.py            # Bulk organizer with threading
│   ├── watcher_script.py    # Real-time folder monitoring
│   ├── launcher.py          # GUI desktop app
│   └── multhread.py         # Multithreading handler
├── folder_labels.json       # Folder names and descriptions
├── folder_embeddings.faiss  # (auto-generated) FAISS vector index
└── files/                   # Drop unorganized files here

Core Features

Feature	Description
🧠 Semantic Sorting	Understands file content using transformer embeddings, not just names.
⚡ FAISS Indexing	Builds a fast semantic search index for folder labels.
👁️ OCR Fallback	Extracts text from scanned/image PDFs using pdfplumber + pytesseract.
🧩 Keyword Boosting	Gives weight bonuses for subject-specific terms.
🧵 Multithreading	Handles multiple files simultaneously for faster processing.
🕵️ Real-time Watcher	Detects and organizes files automatically as they appear.
🖥️ GUI Launcher	Desktop interface with controls, logs, and system tray icon.
🔐 Offline Privacy	Works entirely offline—nothing leaves your device.

Installation & Setup

Requirements

Python 3.8+ with the following libraries:

pip install sentence-transformers faiss-cpu numpy pdfplumber pytesseract pillow python-docx watchdog pystray

On Linux, also install tesseract:

sudo apt install tesseract-ocr

Quick Start

Clone the repo: git clone https://github.com/ahhyoushh/filesense.git && cd filesense
Edit folder_labels.json with your desired folder names and descriptions
Create the index: python scripts/create_index.py
Drop files in /files and run the organizer
Choose your method: bulk process, real-time watch, or GUI launcher

💡 Pro Tip: Use the GUI launcher for the easiest experience. It handles everything with a simple interface.

Configuration Options

Setting	File	Description
`--dir / -d`	script.py / watcher_script.py	Directory to scan or watch
`--threads / -t`	script.py	Maximum concurrent threads (default: 4)
`THRESHOLD`	process_file.py	Minimum similarity score to accept match (default: 0.45)
`MODEL_NAME`	create_index.py	SentenceTransformer model (default: all-mpnet-base-v2)

What I Learned

🧠 Embeddings & NLP

Web browsers download process, handling .tmp files, etc.
SentenceTransformer embeddings enable semantic matching beyond keywords
Embeddings capture meaning and context in high-dimensional space
Keyword boosting improves accuracy for domain-specific classification

⚡ Vector Search at Scale

FAISS provides fast nearest-neighbor searches locally
Building indexes scales better than brute-force similarity
Indexing trades memory for speed—perfect for real-time processing

🎯 OCR & Document Processing

Combining pdfplumber + pytesseract handles varied PDF formats
Fallback strategies are critical for messy real-world data
OCR preprocessing (contrast, rotation) significantly improves accuracy

⚙️ Concurrent Processing

Multithreading improves throughput for I/O-bound file operations
Thread pools prevent resource exhaustion and improve stability
Race conditions require careful synchronization in file operations

🔐 Privacy-First Design

Offline-first architecture eliminates data transmission risks
Users value speed and control over cloud convenience
Local processing builds trust with your users

🎨 UX & Product Design

Downloading from web consists of many steps rather than file magically appearing
Non-technical users need simple GUI controls
Fallback mechanisms (keywords, filename matching) improve reliability
Real-time feedback and logs reduce user uncertainty

Future Enhancements

🤖 fine tune models to generate folder descriptions for folder names
🚀 Incremental FAISS updates (no full rebuilds needed)
📸 Better image-only classification using vision models
↩️ Undo/recovery feature to relocate moved files
🏷️ Auto-renaming using extracted metadata
📊 Web dashboard for previews and remote control
💾 Embedding caching for faster reprocessing

Ready to Get Started?

Bring order to your digital chaos with FileSense.

View on GitHub