Building SortSense: A Local AI File Organizer Built in a Single Hack Day

Building SortSense: A Local AI File Organizer Built in a Single Hack Day

hacktoberfest #opensource #gemma #ai

Hacktoberfest: Contribution Chronicles

We, Team Brute Force, built SortSense during the Hacktoberfest Hack Day Coimbatore x (INIT Club & IDEA Club). We wanted to tackle a problem almost everyone with a laptop faces: the Downloads folder slowly turns into a mess of files with meaningless names, making it difficult to find what you actually need.

Files received through WhatsApp, browsers, and other platforms often arrive as:

IMG-20261008-WA0004.pdf
DOC-WA0012.pdf
a8f31c92.pdf

Traditional file organizers usually rely on rigid extension-based rules like .pdf → Documents or .jpg → Pictures. But a PDF could be an electricity bill, university notes, an assignment, or something completely different.

Cloud AI can understand documents semantically, but uploading sensitive files such as bills, identity documents, or personal records to external servers isn't always acceptable.

So we built SortSense — a privacy-first file organizer that understands files locally.

How it works

Our stack is Python 3.13, CustomTkinter, Pydantic, watchdog, pypdf, Ollama, and Gemma 4.

Detection: SortSense monitors download directories using watchdog and detects new files as they arrive. It can detect Chrome, Firefox, and OS-default download paths on Windows and Linux.
Extraction: For supported documents, the ingestion pipeline extracts the content using pypdf or plain-text extraction.
Understanding: The extracted content is sent to a locally running Gemma 4 model through Ollama. Gemma determines what the document actually means instead of relying only on its file extension.
Validation: Gemma returns structured JSON containing information such as the category, suggested filename, document type, summary, confidence, and suggested action. A deterministic Pydantic-based validation layer checks the response before any filesystem operation happens.
Organization: SortSense safely renames and moves the file into the appropriate category. It also searches for existing matching folders instead of unnecessarily creating duplicates.
Review: If Gemma's confidence is below our configurable threshold, the file is sent to a Review Queue instead of being silently misplaced.
Dashboard: The CustomTkinter desktop application shows live counters, Activity Log entries, Review Queue items, and settings.

The important part: the files never leave the user's machine.

The Gemma 4 Partner Challenge

We built SortSense around local Gemma 4 inference using gemma4:e4b through Ollama.

Gemma receives the extracted document content and returns a structured analysis containing the document category, filename suggestion, document type, summary, confidence, and suggested action.

For example:

Electricity bill PDF
↓
Gemma 4
↓
Utilities/Electricity_Bill_September_2026.pdf

Or:

Signals & Systems notes
↓
Gemma 4
↓
Study_Notes/Signals_Systems_Semester_Notes.pdf

A key architectural decision was to keep Gemma responsible for understanding and recommendation, while deterministic Python code remains responsible for validation and filesystem operations.

This gives us the flexibility of AI without giving an LLM unrestricted control over the user's files.

What makes SortSense different

The main difference is simple:

Traditional organizers ask what a file is. SortSense tries to understand what the file means.

Our key differentiators are:

Local edge inference: Gemma 4 runs directly on the user's machine.
Privacy-first: No document bytes are uploaded to a cloud AI service.
Semantic organization: Files are classified based on their content rather than just their extension.
Confidence guardrails: Low-confidence results go to a human review queue.
Structured output: Gemma is prompted for strict JSON and the result is validated before filesystem operations.
Smart folder reuse: Existing matching folders are reused to avoid unnecessary fragmentation.
Intelligent renaming: Meaningless filenames can be converted into useful descriptive filenames.
Multi-browser monitoring: Chrome, Firefox, and OS-default download paths can be monitored.
Stuff that broke (and what we learned)

Building the complete system during a single hack day forced us to make a lot of architectural decisions quickly.

AI vs filesystem control: We decided early that the model should never directly manipulate files. Gemma recommends; deterministic Python validates and executes.
Model confidence: AI classification isn't always certain, so we introduced a configurable 0.85 confidence threshold. Anything below it goes to the Review Queue.
Unsafe model output: We added validation for path traversal, invalid extensions, null bytes, empty responses, and other unsafe values before allowing a file operation.
File collisions: We made the routing system collision-safe. Existing files are never overwritten; suffixes such as _1, _2, etc. are added automatically.
Background processing: The filesystem watcher and file-processing pipeline run in background threads, while GUI updates are safely marshalled back to the Tkinter main thread.
Keeping the architecture small: Instead of adding FastAPI, a separate database, or unnecessary cloud services, we kept the system as a lightweight local Python application with Ollama and CustomTkinter.
What we built during the hackathon

Starting from zero, we completed:

-Full watchdog filesystem watcher
-Multi-browser download path detection
-PDF and plain-text ingestion
-Local Gemma 4 integration through Ollama
-Structured JSON prompting
-Deterministic validation layer
-Atomic file routing
-Smart existing-folder search
-Automatic file renaming
-CustomTkinter desktop dashboard
-Live counters
-Activity Log
-Review Queue
-Settings page
-Automated Windows and Linux setup scripts
-89-test pytest suite

Team Brute Force:

Dev Madhav — File watcher daemon, browser path detection, OS directory routing, atomic file move/rename engine

Aadi UR — Document extraction pipeline, metadata sanitisation, GUI pipeline integration and live counter wiring

Jeevan T — Local Gemma 4 integration via Ollama, structured JSON prompt engineering and confidence validation

Rohith Singothu — CustomTkinter desktop dashboard, setup scripts, documentation and MLH submission

Links
GitHub Repo: https://github.com/Minnolter12/bruteforceManager
Demo Video: https://drive.google.com/drive/folders/1ml5yyOWsXLudp3xN56YhwqRokNHoMXOi?usp=drive_link

Live Application: SortSense is a local desktop application and runs directly on the user's machine.

Huge thanks to the team for surviving the sprint!

Dev Madhav
Aadi UR
Jeevan T
Rohith Singothu

(Built for Hacktoberfest Hack Day Coimbatore x (INIT Club & IDEA Club) 2026)