LazySort AI: Drop the mess and let local Gemma sort it out

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

What I Built

I built LazySort AI, a local-first file organizer for the folder everyone keeps promising to clean “later.”

Give it a cluttered folder and LazySort will:

1. scan the files without following unsafe symlinks,
2. extract a limited amount of useful text,
3. ask a locally running Gemma model what each file represents,
4. propose a category, subcategory, and descriptive filename,
5. explain each suggestion and assign a confidence level,
6. wait for the user to approve or edit the plan, and
7. safely organize only the approved files.

It is deliberately not another extension-based sorter. A traditional rule can see that two files are PDFs; it cannot tell that one is an invoice and the other is a project report. LazySort uses the meaning of the document to decide where it belongs.

The people who get to be lazier are anyone with an overgrown Downloads folder: developers, students, freelancers, and people who would rather do almost anything than open and rename forty mystery documents.

The safety rule is simple:

Gemma suggests → LazySort validates → the user approves → LazySort moves

The model never receives direct filesystem access. LazySort never deletes files, never overwrites an existing file, and records completed operations so the last organization run can be undone.

Demo

The repository includes a fictional sample folder at demo/upload-this-folder, so the workflow can be demonstrated without exposing personal documents.

The demo covers selecting a folder, checking that Gemma is ready, reviewing its explanations and confidence, editing and approving suggestions, organizing the files, confirming that zero files were deleted, and undoing the run.

Code

AryanSharma9917 / lazysort-ai

LazySort AI

Drop the mess. Let AI sort it out.

LazySort is a local-first file organizer that uses Gemma 3 through Ollama to understand messy files, propose meaningful folders and names, and let you approve every change. It is a submission project for the Hacktoberfest 2026 Week 3: Slow and Steady challenge.

Instead of opening, identifying, renaming, and sorting files one by one, select a folder and review the organization plan Gemma prepares. LazySort never deletes files.

Why open-source AI?

File names and document contents can be personal. When OLLAMA_BASE_URL points to localhost, inference happens on your machine: there is no mandatory proprietary AI API, no analytics, and no permanent storage of extracted content. You can also swap the configured Ollama model. If you configure a remote Ollama endpoint, extracted information is sent to that server—local inference is not an absolute privacy guarantee.

Features

• Semantic classification and descriptive renaming…

View on GitHub

Repository: github.com/AryanSharma9917/lazysort-ai

The project is open source under the MIT License. The README includes installation instructions, architecture notes, a safe demo guide, API documentation, security limitations, and testing instructions.

How I Built It

LazySort is a Python application with a focused web dashboard rather than a chatbot interface.

The main components are:

• FastAPI for the local application and validated API endpoints
• Gemma 3 4B as the open-weight reasoning model
• Ollama for local model serving
• Pydantic for strict structured-output validation
• PyPDF and python-docx for bounded document extraction
• HTML, CSS, and vanilla JavaScript for the review dashboard

Understanding files with Gemma

For each file, LazySort sends Gemma the filename, MIME type, size, and a bounded content excerpt. Gemma returns JSON containing:

{
  "category": "Finance",
  "subcategory": "Expenses",
  "suggested_filename": "october-expenses.csv",
  "reason": "The file contains dated vendor and expense amounts.",
  "confidence": "high"
}

Pydantic validates every response. If Gemma returns malformed output, LazySort retries once. If the second answer is still invalid, the file is marked as low-confidence and sent to manual review instead of being silently acted upon.

Treating documents and model output as untrusted

File content can contain prompt injection, so the classification prompt explicitly labels filenames and extracted text as untrusted data—not instructions. It tells Gemma to ignore commands inside documents and never suggest deletion, shell commands, absolute paths, or unsupported details.

Prompt instructions are only one layer. Deterministic application code enforces the real security boundary:

• category, subcategory, and filename are sanitized separately;
• traversal sequences, path separators, control characters, and reserved names are rejected;
• the original extension must be preserved;
• every source and destination must remain under the selected root;
• symlinks and protected operating-system directories are rejected;
• file extraction has configurable byte and character limits; and
• conflicts receive deterministic numeric suffixes instead of overwriting data.

Preview, approval, and undo

The default behavior is a dry run. The dashboard shows the current file, proposed destination, suggested name, explanation, and confidence before anything changes. The user can edit suggestions and approve files individually or together.

Execution is a separate API request. Every successful move is written to a transaction log containing filesystem metadata only—never document contents. If one operation fails, LazySort reports the partial result accurately. Undo walks the completed transaction in reverse and refuses to overwrite a file that has appeared at the original location.

The automated suite currently contains 25 passing tests covering scanning, extraction limits, ignored directories, path sanitization, traversal rejection, symlinks, structured-output parsing, malformed responses, retries, conflict naming, moves, partial failures, undo, API validation, and safe folder uploads. Ollama is mocked in automated tests, so CI does not need to download a multi-gigabyte model.

Why Does Open Innovation Matter?

The files we postpone organizing are often the files we least want to send to an unknown server: invoices, resumes, meeting notes, expense records, and personal documents.

With the default localhost Ollama configuration, Gemma processes extracted content on the user's own machine. LazySort requires no proprietary model account, has no mandatory per-request fee, performs no analytics, and does not permanently store extracted document text. The model is controlled by an environment variable, so users can inspect the stack and experiment with another compatible local model instead of waiting for a vendor to expose an option.

Open innovation also shaped the safety design. Because the entire classification and execution boundary is visible in the repository, users can inspect exactly what reaches the model, which paths are rejected, and why the model cannot directly manipulate files. That is especially important for a tool whose purpose is handling private local data.

There are honest limitations. Local inference speed depends on the user's hardware. Scanned PDFs need OCR, which is not included yet. Images and unsupported formats currently rely on filename and metadata rather than full multimodal analysis. Model suggestions can still be wrong, which is why human approval is a required part of the architecture.

If a user changes OLLAMA_BASE_URL to a remote server, extracted information is sent to that server. “Local-first” describes the default configuration; it is not a promise of absolute privacy under every configuration.

The Lazy Payoff

The included demonstration organizes four fictional files into useful destinations such as:

Finance/Expenses/october_expenses.csv
Meeting Notes/Project Management/project_willow_meeting_notes.txt
Project Management/Briefs/project-brief-willow.md
documents/personal_profile/morgan_example_profile.txt

Without LazySort, each file requires the same repetitive loop: open it, work out what it is, choose a folder, invent a useful name, create the folder, and move the file. LazySort turns that into one review screen.

For the demonstrated four-file run:

• files classified and organized: 4
• manual open/read/rename/move loops replaced: 4
• files deleted: 0
• organization runs that can be undone: 1

The payoff grows with the mess, while the important decision remains with the user: approve the plan, then get back to doing something better.

Prize Categories

• Best Use of Gemma — Gemma 3 4B is the semantic engine at the center of every organization proposal and runs locally through Ollama.