Sorted

Sorted is an offline, non-intrusive metadata-only utility that monitors specified directories and semantically organizes files into your predefined destination folders based on natural language similarity.

Usage Setup

To deploy Sorted locally:

1. Clone the repository to your local machine.
2. Setup a virtual environment to isolate dependencies:

   python3 -m venv .venv
   source .venv/bin/activate

3. Install dependencies using the provided requirements.txt:

   pip install -r requirements.txt

4. Launch the application by executing python src/main.py.

The system will present the desktop interface for initial configuration. For a headless or terminal-exclusive experience, launch with the --cli argument.

---

System Architecture

1. Event-Driven Monitoring

The application uses the watchdog library to intercept real-time file system events. Newly created or modified files in designated watch paths are placed into a processing queue, executing asynchronously via a standard single-threaded sequential laborer (ThreadPoolExecutor limited to max_workers=1).

2. Inference Pipeline

When a file is processed, its text content is extracted—using embedded local OCR for images and scanned PDFs—and passed through a local transformer (all-MiniLM-L6-v2). The model produces a vector embedding representing the semantic content of the document.

3. Vector Routing and Classification

The embedding is queried against a local FAISS (Facebook AI Similarity Search) index containing embeddings of known target contexts.

• Confidence Threshold: A rank-weighted approach evaluates the FAISS results. If the similarity score falls below the required threshold, the file remains safely untouched in its original location and enters the Wait Queue.
• Folder Organization Utility: The system provides a recursive folder organizer to index and route pre-existing file archives in bulk with zero risk of data loss.
• Review and Training Loop: Unsure files wait in the Wait Queue. You can manually assign them a destination inside the UI, which organically updates the FAISS index to refine future AI classifications.

4. Same-Origin HTTP Hosting

To eliminate CORS issues across local file systems, Sorted serves both its API and its front-end UI from the exact same local webserver (http://127.0.0.1:8099/) using FastAPI's static directory mounting, ensuring robust, error-free browser integration.

---

Research and Evaluation

System benchmarks and evaluations on precision and latency against datasets are recorded in EVALUATIONS.md.