Metadata-Version: 2.4
Name: agentic-file-organizer
Version: 0.1.0
Summary: LLM-powered file organizer that safely moves files into categories
License: MIT
Project-URL: Homepage, https://github.com/yourusername/agentic-file-organizer
Project-URL: Bug Tracker, https://github.com/yourusername/agentic-file-organizer/issues
Keywords: file-organizer,llm,ollama,ai,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ollama>=0.4.7
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: chromadb>=0.5.0
Requires-Dist: Pillow>=10.4.0
Requires-Dist: python-doctr>=0.10.0
Requires-Dist: pypdf>=5.1.0
Requires-Dist: python-docx>=1.1.2
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: python-pptx>=1.0.2
Dynamic: license-file

# 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

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

### End-user install flow

1. Install Python
2. Install `pipx`
3. Install Ollama from https://ollama.com/download
4. Install the app:
   - `pipx install agentic-file-organizer`
5. 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.
