Lazy File Butler：用本地 AI 整理一直擱置的檔案

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

What I Built

My folders collect files with names like scan0042.pdf, untitled.txt, and notes FINAL 2.pdf. Organising them means opening each file, figuring out what it contains, choosing a name, and moving it somewhere sensible.

I built Lazy File Butler to handle the preparation.

It reads files locally and uses an open-weight model to suggest descriptive filenames and categories. I can review the suggestions, edit anything that looks wrong, and approve only the files I want to organize.

The workflow is:

Choose a folder → analyze → review and edit → organize → undo if needed.

It supports text PDFs, scanned PDFs, screenshots, Word documents, and common text formats. Installers, archives, and media can be sorted by file type while keeping their original names.

Nothing moves during analysis.

Demo

Watch the Lazy File Butler demo

The app runs locally, so the video demonstrates the workflow without requiring access to my laptop.

Code

View the source code on GitHub

The project includes setup instructions, tests, and an MIT license for the application source.

How I Built It

The AI naming engine uses Llama 3.2 1B through Ollama, running on my laptop. The model receives extracted document text and proposes a filename, category, and explanation.

The rest of the stack includes:

• Python and FastAPI for the local application server.
• PyMuPDF for PDF text extraction and page rendering.
• Local OCR through macOS text recognition where available, with Tesseract as a fallback.
• SQLite for saved previews, cached results, and move history.
• HTML, CSS, and JavaScript for the interface.

One early problem was that scanned PDFs produced no readable text. I added OCR and checks for later pages, so an empty opening page no longer immediately ends the analysis.

The small model also made category mistakes. I added validation, retries for invalid or generic names, and consistency checks for obvious document-type conflicts. Corrected and OCR-based suggestions are marked for closer review.

The model proposes changes; Python handles file operations. Before moving anything, the application checks file hashes, destination conflicts, and path boundaries. Undo restores original names and locations, but stops if a file has changed or its original location is occupied.

There are 22 automated regression checks covering readers, validation, caching, file moves, and undo safeguards.

Why Does Open Innovation Matter?

A file organizer may need to read personal notes, bills, screenshots, and documents. Running an open-weight model locally means those contents do not need to be sent to a hosted inference provider.

After installing the dependencies and model weights, the local workflow can run without an internet connection. There is no required per-call inference API fee, although hardware and electricity still have costs.

I can inspect the prompts, change the categories, and choose another compatible installed model. I also kept the existing small model rather than making a larger download a requirement.

For this project, local inference was a better fit than a hosted API because it lets the automation work directly with private files while keeping processing on the user's computer.

The Lazy Payoff

Butler reduces the repetitive work of opening documents and deciding how to name and group them. I review one editable preview instead.

For testing, I created a fictional student-project folder containing lecture notes, an invoice, a scanned exam paper, screenshots, code, an archive, and an audio file. This exercises both AI naming and ordinary file-type sorting.

It is still a small-model tool: handwriting recognition and suggestions can be imperfect. That is why checking the extracted text, editing suggestions, and undoing changes are part of the main workflow.

My interpretation of “Slow and Steady” is simple: let the computer do the tedious reading and proposing, while I keep the final say.