DEV Community

thedarkking01
thedarkking01

Posted on

FolderZen-an-AI-Powered-File-Organizer

#devchallenge #hf26challenge

Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady Submission 🦥

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

What I Built

FolderZen is a local AI-powered file organizer that turns a folder full of cryptically named documents — doc_12.pdf, final_v3.docx, scan_04.pdf — into a clean, categorized structure with meaningful names, without ever sending your files to the cloud.

You point it at a messy folder. It reads the content of your PDFs, Word documents, and text files, asks a local AI model what each one actually is, and suggests a descriptive filename, a category, and a destination folder. You review every suggestion in an editable table, preview the exact paths before anything moves, then approve and apply.

Who gets to be lazier: anyone whose Downloads folder looks like a crime scene. Students with assignment_FINAL_v3_REAL.docx. Freelancers with invoice_copy2.pdf. Anyone who has spent 10 minutes hunting for a file they definitely saved somewhere.

Step What happens
1. Scan Detects all files, reads metadata
2. Extract Reads text from PDF, DOCX, TXT (up to 1500 chars)
3. AI suggest Sends text to local gemma3:1b via Ollama
4. Review Editable table — approve, reject, or edit each suggestion
5. Preview Shows exact destination paths before touching anything
6. Apply Moves approved files; never overwrites; blocks path traversal
7. Report Success / failure summary

Demo

📹 Add your screen recording or GIF here — record with OBS, ShareX, or Windows Game Bar (Win+G) pointing at the Streamlit app on localhost:8501.

Sample results from the included sample_files/ folder:

Messy filename AI suggestion Category Reason
doc_12.pdf PythonInterviewNotes.pdf Tech Contains Python interview prep notes covering data structures and algorithms
scan_04.pdf Electricity_Bill_October.pdf Finance Appears to be a utility bill with account number and amount due
final_v3.docx FolderZen_Project_Proposal.docx Work Contains a project proposal with objectives and timeline
resume_draft.docx Jane_Doe_Resume.docx Personal Resume document listing skills and work experience

Code

GitHub logo thedarkking01 / FolderZen-an-AI-Powered-File-Organizer

FolderZen 🗂️

Local AI-powered file organizer. No cloud. No API keys. Your files stay on your machine.

FolderZen scans a messy folder, reads document content, and uses a local AI model (via Ollama) to suggest meaningful filenames, categories, and destinations — then lets you review and approve every change before anything moves.

Quick start

# 1. Clone
git clone https://github.com/YOUR_USERNAME/FolderZen.git
cd FolderZen

# 2. Create virtual environment
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate  # macOS / Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Pull the AI model (one-time)
ollama pull gemma3:1b

# 5. Run
streamlit run app.py
Enter fullscreen mode Exit fullscreen mode

Generate sample files (optional)

python create_samples.py
Enter fullscreen mode Exit fullscreen mode

Then point the app at the sample_files/ folder.

Run tests

pytest tests/ -v
Enter fullscreen mode Exit fullscreen mode

How it works

Step What happens
1. Scan Detects all files, reads metadata
2. Extract Reads text from PDF, DOCX, TXT (up
…
View on GitHub

Project structure:

FolderZen/
├── app.py               # Streamlit UI — all 4 steps
├── file_scanner.py      # Folder scanning and metadata
├── document_reader.py   # PDF, DOCX, TXT text extraction
├── ai_organizer.py      # Ollama prompt + JSON response parser
├── file_operations.py   # Safe move/rename with collision detection
├── create_samples.py    # Generates demo files
├── requirements.txt
└── tests/
    ├── test_scanner.py          # 6 tests
    └── test_file_operations.py  # 9 tests — 15 passing total
Enter fullscreen mode Exit fullscreen mode

Quick start:

git clone https://github.com/thedarkking01/FolderZen-an-AI-Powered-File-Organizer
cd FolderZen

python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

pip install -r requirements.txt
ollama pull gemma3:1b
streamlit run app.py
Enter fullscreen mode Exit fullscreen mode

Run tests:

pytest tests/ -v
Enter fullscreen mode Exit fullscreen mode

How I Built It

Open-source AI used: Gemma 3 1B by Google, running locally via Ollama.

The core AI loop lives in ai_organizer.py. For each readable file, FolderZen:

  1. Extracts up to 1500 characters of text using PyMuPDF (PDF) or python-docx (DOCX)
  2. Sends a structured prompt to gemma3:1b via the Ollama Python client
  3. Parses the model's JSON response — category, suggested filename, destination folder, and a one-sentence reason
  4. Falls back gracefully if the model returns malformed output

The prompt is deliberately minimal to keep the 1B model fast and on-task:

You are a file organizer. Given a document snippet, return ONLY a JSON object with:
- "category": one of [Work, Finance, Personal, Education, Legal, Medical, Tech, Other]
- "suggested_name": descriptive filename without extension
- "destination": short folder path
- "reason": one sentence explaining why
Enter fullscreen mode Exit fullscreen mode

Temperature is set to 0.2 so suggestions are consistent rather than creative. The 1B model processes each file in roughly 3–8 seconds on an RTX 2050 with 4 GB VRAM — no internet required.

The file operations layer (file_operations.py) is intentionally separate from the AI layer and handles three safety concerns independently:

  • Collision detection — _unique_path() appends _1, _2 … rather than overwriting
  • Path traversal prevention — _no_traversal() resolves both paths and checks relative_to() before any move executes
  • Character sanitisation — strips < > : " / \ | ? * from filenames and folder names

The UI is Streamlit with st.data_editor for the review table, so users can edit the AI's suggestions inline before approving them. Nothing moves until the user explicitly clicks Apply approved changes.

Full stack:

Component Choice
UI Streamlit
AI runtime Ollama (local)
AI model Gemma 3 1B (open-weight)
PDF reading PyMuPDF
DOCX reading python-docx
File ops pathlib + shutil
Tests pytest — 15 tests, all passing

Why Does Open Innovation Matter?

A closed-API version of this tool would have a fundamental problem: to organize your files, it would need to read your files. That means your electricity bills, your resume, your medical documents, your contracts — all uploaded to a third-party server to be processed.

With an open-weight model running locally via Ollama, none of that happens. The text extracted from your documents goes to a process running on your own GPU and never leaves your machine. There is no API key to leak, no usage bill, no terms of service that change what happens to your data next quarter.

Open innovation also made the 1B model size possible. Gemma 3 1B is small enough to run on a laptop GPU with 4 GB VRAM and still produce useful, structured output. That's only possible because Google released the weights openly — a closed-API equivalent would require a network round-trip and a paid account just to categorize a text file.

For a tool that touches personal documents, local-first isn't a nice-to-have. It's the only honest architecture.

My Agent Session

Save and embed your DevRelay session here using the agent_session tag, or remove this section.

The Lazy Payoff

I tested FolderZen on the included sample_files/ folder with 12 mixed files — PDFs, DOCXs, TXTs, an empty file, and a file with no extension.

Manual organization (rename + sort into folders by hand): ~8 minutes

FolderZen (scan → suggestions → review → apply): ~2.5 minutes

  • Scan: instant
  • AI suggestions for 12 files: ~60 seconds on RTX 2050
  • Review and approve: ~45 seconds
  • Apply + report: instant

The AI got 10 out of 12 filenames right without any editing. The two it got wrong were files with very short content (under 50 chars) — it suggested generic names instead of something specific. That's expected for a 1B model with minimal context, and the editable review table exists exactly for those cases.

The real payoff isn't the 5-minute saving on 12 files. It's that the review step forces you to look at every file before it moves — the human stays in the loop, and the AI handles the tedious part of reading and naming.

Prize Categories

  • 🏆 Best Use of Open-Source AI
  • 🛠️ Most Useful Developer Tool

Top comments (0)