Back to packageRELEASE DETAILS

0.1.0

PyPI

agentic-file-organizer

LLM-powered file organizer that safely moves files into categories

Published15 Mar 2026

Direct dependencies9

Transitive dependenciesNot calculated

README

Version 0.1.0 documentation

Agentic File Organizer

A Python-based file organizer that asks for a folder path at startup, uses an LLM to decide a category and descriptive name for each file, and only moves files (never deletes).

It now supports richer file inspection tools:

Text/code preview for common source and text formats
PDF extraction
DOCX/XLSX/PPTX extraction
OCR for images (via docTR)
VLM image understanding via Ollama (for image-only files)

Setup

From source

Create and activate a virtual environment.
Install dependencies:
- pip install -e .
Install and run Ollama locally.
Run organize-files init --pull-models
OCR uses docTR; model weights are downloaded on first OCR run.
Copy .env.example to .env only if you want to override defaults while developing from source.

End-user install flow

Install Python
Install pipx
Install Ollama from https://ollama.com/download
Install the app:
- pipx install agentic-file-organizer
Complete guided setup:
- organize-files init --pull-models

Useful .env options:

OLLAMA_MODEL (text LLM)
OLLAMA_VLM_MODEL (image model)
ENABLE_OCR=true|false
ENABLE_VLM=true|false
MAX_PREVIEW_CHARS=1200

Run

python -m agentic_file_organizer.main
or organize-files

CLI commands

Guided setup:
- organize-files init
Guided setup + pull models:
- organize-files init --pull-models
Interactive mode:
- organize-files
Non-interactive organize:
- organize-files organize /path/to/folder --preferences "group by project" --yes
Preview only (no changes):
- organize-files organize /path/to/folder --dry-run
Skip verification pass:
- organize-files organize /path/to/folder --no-verify --yes
Environment/model health check:
- organize-files doctor
Pull missing required models:
- organize-files setup-models

Recommended release model

Publish the package to PyPI
Have users install with pipx
Keep Ollama and local models separate from the Python package
Use organize-files init and organize-files doctor for setup validation

Safety

Operates only on files directly inside the folder you manually enter.
Moves files into category folders under that same root folder.
Never deletes files.
Prevents moving outside the chosen root.

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 9

Native requirements

9 direct targetsNot calculated transitive count

Package / target	Requirement	Relationship
ollama Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`ollama>=0.4.7`	runtime
python-dotenv Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`python-dotenv>=1.0.1`	runtime
chromadb Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`chromadb>=0.5.0`	runtime
Pillow Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`Pillow>=10.4.0`	runtime
python-doctr Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`python-doctr>=0.10.0`	runtime
pypdf Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pypdf>=5.1.0`	runtime
python-docx Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`python-docx>=1.1.2`	runtime
openpyxl Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`openpyxl>=3.1.5`	runtime
python-pptx Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`python-pptx>=1.0.2`	runtime