Hacktoberfest-week3-challenge

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

Everyone's ~/Downloads and ~/Desktop folders eventually become a digital landfill: cryptic filenames like IMG_9482.png, Invoice_39810_final(1).pdf, duplicate .exe installers, memes, and tax records scattered across hundreds of unsorted icons. Manually opening each file, figuring out what it is, renaming it, and moving it into nested folders is an exhausting, soul-crushing chore—so most of us just leave it and live with the digital guilt.
SlothSort is an autonomous, privacy-first local background agent that handles this entire chore while you sleep.
Instead of relying on naive file-extension sorting (which dumps your restaurant bill and a funny meme into the same folder just because both are .png), SlothSort understands file semantics:

• Inspects Visuals: Passes screenshots, photos, and scanned receipts to a local open-weight vision model to see what's actually depicted.
• Understands Documents: Extracts text snippets from PDFs and documents to differentiate between a quarterly financial statement and a university reading.
• Smart Semantic Renaming: Generates concise, descriptive snake_case filenames (e.g., starbucks_coffee_receipt_oct2026.png instead of Screenshot 2026-10-18 at 14.22.01.png).
• Automated Filing: Moves files cleanly into organized directories (Receipts_and_Invoices, Financial_and_Tax, Work_Documents, Software_Installers, etc.).
• Zero-Guilt Safety Net: Maintains an append-only transaction log (undo_log.json). If you ever disagree with a sort, running slothsort --undo instantly returns every single file back to its exact original location.

Demo

Check out the full video walkthrough and live demonstration of SlothSort sorting messy downloads in real time:

Code

How I Built It

SlothSort was architected around local-first, open-source AI inference:

Local Inference Engine: Ollama running locally on the user's workstation.
Vision Model (llama3.2-vision): An open-weight multimodal model used to inspect raw image bytes (screenshots, photos, receipts, memes) to identify document structure, text headers, and visual context.
Language Model (llama3.2:3b): A lightweight, low-footprint open-weight model for rapid classification and snake_case slug generation from text excerpts and PDF first-page extracts.
Deterministic Rules Layer: Fast bypasses for archives (.zip, .tar.gz) and binary installers (.exe, .dmg, .pkg) so zero model tokens are wasted on obvious files.
Agent Orchestration & CLI: Built in Python using:
pypdf for fast zero-overhead PDF text parsing.
Pillow for image validation.
rich for an aesthetically pleasing sloth terminal UI.
schedule for autonomous, unbothered 2:00 AM daily daemon runs.
pyyaml for customizable watch folders and user categories.

Why Does Open Innovation Matter?

Using open-source AI wasn't just an implementation detail for SlothSort—it is the only reason this project can safely exist:

Non-Negotiable Personal Privacy: A user's Downloads folder is their most sensitive directory. It holds bank statements, tax forms, paystubs, passport scans, and proprietary work documents. Sending every single file to a proprietary closed cloud API (where data might be retained, logged, or scrutinized) is a dealbreaker. With open-weight models running on Ollama, zero bytes ever leave your hardware.
Zero Incurred API Costs ($0.00): Active users accumulate hundreds of files every month. Classifying hundreds of high-res images and documents with commercial cloud vision APIs would easily cost $10–$30/month. Local open weights turn routine personal maintenance into a free utility forever.
Works Anywhere, Completely Offline: Whether on an airplane, train, or spotty cafe Wi-Fi, SlothSort operates without an internet connection, API keys, or rate limits.
Resilience & User Sovereignty: Proprietary APIs change pricing, deprecate models, or throttle requests without notice. Open innovation means you own your compute stack and can freely swap between llama3.2, gemma2, or qwen whenever you choose.

The Lazy Payoff

The Before vs. After:
Before SlothSort: 180+ loose files cluttering the ~/Downloads and ~/Desktop directory. Finding a specific payment receipt meant opening 15 cryptic Screenshot_2026-09-XX files one by one. Total wasted time: ~35–45 minutes of manual dragging, dropping, and renaming every couple of weeks.
With SlothSort: Processed the entire backlog in under 2 minutes of local compute without a single mouse click.
The Ultimate Payoff: 100% hands-off automation. You can continue being as lazy and messy as you want with your downloads—SlothSort wakes up at 2:00 AM, does the chores, and lets you wake up to zero clutter every morning.