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

What I Built
Let's be completely honest: nobody enjoys organizing their Downloads or Inbox folder.

Every developer, student, and creator ends up with a chaotic dumping ground of files named receipt_oct.txt, script_dump (2).py, db_notes_final_v2.md, or invoice_9482.pdf. We tell ourselves we’ll organize them over the weekend, but we never do.

To honor the "Slow and Steady" Hacktoberfest challenge, I built SlothSort — an autonomous, 100% offline file-organization agent that does the thinking and filing for you, so you never have to lift a finger again.

Drop any messy file into the inbox/ directory (or let the background watcher monitor your downloads), and SlothSort:

Peeks inside the file: Extracts snippets from text files, scripts, or PDFs.
Consults a local open-weight AI (llama3.2:3b): Understands the context and determines the ideal category (Invoices_and_Finance, Academics_and_Notes, Code_and_Dev, Identity_and_Docs, Media_and_Design, Misc).
Smartly renames the file: Turns cryptic names like db_assignment_notes.md into descriptive, searchable snake_case names like cs_401_advanced_database_systems_assignment_3_notes.md.
Files it away safely: Handles duplicate name collisions automatically.

Demo
Here is SlothSort in action running a live batch sort on unorganized files:
[🦥 SlothSort] Found 3 cluttered file(s) in 'inbox/'. Initiating batch sort...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[🦥 SlothSort] Examining: db_assignment_notes.md
↳ Extraction: via text reader (.md) (833 chars)
↳ Classifying: with llama3.2:3b (100% offline)...
↳ Category: Academics_and_Notes
↳ Clean Name: cs_401_advanced_database_systems_assignment_3_notes.md
↳ Reason: File content snippet is related to academic notes and assignment analysis.
↳ Engine: Local Ollama (llama3.2:3b)
↳ Filed to: organized\Academics_and_Notes\cs_401_advanced_database_systems_assignment_3_notes.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[🦥 SlothSort] Examining: receipt_oct.txt
↳ Extraction: via text reader (.txt) (610 chars)
↳ Classifying: with llama3.2:3b (100% offline)...
↳ Category: Invoices_and_Finance
↳ Clean Name: receipt_oct.txt
↳ Reason: File contains an invoice receipt.
↳ Engine: Local Ollama (llama3.2:3b)
↳ Filed to: organized\Invoices_and_Finance\receipt_oct_1.txt

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[🦥 SlothSort] Examining: script_dump.py
↳ Extraction: via text reader (.py) (667 chars)
↳ Classifying: with llama3.2:3b (100% offline)...
↳ Category: Code_and_Dev
↳ Clean Name: bubble_sort_algorithm_demo.py
↳ Reason: File contains code snippet for a sorting algorithm.
↳ Engine: Local Ollama (llama3.2:3b)
↳ Filed to: organized\Code_and_Dev\bubble_sort_algorithm_demo.py

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[🦥 SlothSort] Batch sorting complete! Successfully organized 3 file(s).
Check your sorted files in: organized/

SlothSort also features a Live Watcher Daemon (python sloth_sort.py --watch) powered by watchdog that continuously runs in the background, filing files the second they land in your inbox.

Code
The complete source code, tests, and documentation are open-sourced on GitHub:

  .---.   _       ___ _      _   _   ___             _   
 /  _  \ | |     / __| |___ | |_| |_/ __| ___ _ _ _| |_ 
|  / \  || |__   \__ \ / _ \|  _| ' \__ \/ _ \ '_|  _|
|  \_/  || '_ \  |___/_\___/ \__|_||_|___/\___/_|  \__|
 \___/\_/|_.__/  🦥 Zero effort file organization 🦥

How I Built It
The agent was built from the ground up to be lightweight, self-contained, and completely free from external API dependencies:

Local Inference Engine: Powered by Ollama running Meta's llama3.2:3b model. On an everyday developer laptop GPU (an RTX 3050 6GB), it offloads 100% of layers to VRAM, evaluating prompts at >2,200 tokens/sec and generating responses at ~54 tokens/sec.
Structured JSON Outputs: Configured Ollama with format='json' and an explicit system prompt demanding strict JSON containing category, clean_name, and a single-sentence reason.
Intelligent File Extractors:
pypdf: Extracts the first page of PDF receipts, academic papers, and forms (up to 800 characters) for fast zero-latency reading.
Universal Text Reader: Handles .txt, .md, .py, .sql, .json, .csv, .sh, .yml, etc.
Binary Fallback: Reliably falls back to file extensions and metadata for image and media assets.
Fail-Safe Heuristic Engine: If Ollama is offline or warming up, SlothSort gracefully falls back to a deterministic regex/keyword rule engine so no file is ever stranded or misplaced.
watchdog: Powers the --watch daemon mode for real-time filesystem event monitoring.
colorama: Provides retro terminal aesthetics with sloth wisdom quotes.
Why Does Open Innovation Matter?
This project highlights exactly why open-weight models and local AI are indispensable:

Total Privacy for Sensitive Personal Documents:
Would you send your bank statements, medical bills, college grade sheets, or tax forms to a third-party closed cloud API every time you organize your desktop? Absolutely not. With open models via Ollama, your data never leaves your laptop.
₹0 / $0 Cost Forever:
Closed APIs charge per token. A file organizer that runs in the background all day watching your downloads folder would burn API tokens on every download. Open-weight models like llama3.2:3b deliver high-speed intelligence with zero monthly subscription costs and zero API bills.
No Internet Required:
Whether you're on a flight, on a train, or off the grid, SlothSort runs completely offline.
The Lazy Payoff
Manually reviewing files, opening PDFs to see what they are, inventing clear filenames, and moving them into folders usually takes 15–30 minutes every week.

With SlothSort:

You spend 0 minutes.
You just save files anywhere into inbox/ (or hook it up to your Downloads directory).

The sloth agent slowly, steadily, and autonomously keeps your workspace pristine while you take a well-deserved nap. 🦥

Prize Categories
Main Track: Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady
Built with ❤️, Python, Ollama, and maximum sloth energy.