SnapSort

AI-powered file sorting for local folders using Ollama.

SnapSort reads each file name plus a short text preview, asks a local Ollama model to choose a category, and then moves or copies the file into the matching folder. Files that cannot be classified safely are sent to SKIP.

What changed

• Fixed the file-sorting flow so each file is classified independently.
• Added --thought to print the model's thought/decision text when the model exposes it.
• Added persistent log files so users can inspect failures and model decisions after a run.
• Improved error handling for unreadable files, invalid model responses, and destination name collisions.

Requirements

• Python 3.10+
• Ollama installed and running locally
• A downloaded Ollama model, for example:

ollama pull llama3.2

Install

pip install -r requirements.txt

Usage

python snapsort.py <target_folder> <ollama_model> --categories <category1> <category2> [options]

Example:

python snapsort.py "C:\Downloads" "llama3.2" --categories PDFs Docs Images

Copy instead of move:

python snapsort.py "C:\Downloads" "llama3.2" --categories PDFs Docs Images --copy

Show model thought output:

python snapsort.py "C:\Downloads" "llama3.2" --categories Work Personal Archive --thought

Write logs to a custom location:

python snapsort.py "C:\Downloads" "llama3.2" --categories Work Personal --log-file "C:\temp\snapsort.log"

Options

• --categories: Required list of allowed output folders.
• --output: Optional base output folder. Defaults to the target folder.
• --copy: Copy files instead of moving them.
• --thought: Print the model's thought/decision text when available.
• --log-file: Write logs to a specific file. By default SnapSort writes logs to <target>\logs\.

Logs

Every run writes a timestamped log file unless --log-file is provided.

Default location:

<target folder>\logs\snapsort-YYYYMMDD-HHMMSS.log

The log contains:

• startup configuration
• classification attempts
• model responses
• move/copy results
• full error traces when something fails

How it works

1. SnapSort scans the top-level files in the target folder.
2. It sends the file name and up to 400 characters of text preview to Ollama.
3. The model must answer with exactly one allowed category or SKIP.
4. SnapSort moves or copies the file into the chosen folder.
5. Errors are logged and problematic files fall back to SKIP when possible.

Notes

• Binary or unreadable files are classified by filename plus a fallback preview message.
• If a destination file already exists, SnapSort creates a unique name instead of overwriting it.
• Thought output depends on the model or Ollama response format. If unavailable, SnapSort prints a fallback message.

Build

The included build.bat builds a standalone executable with Nuitka:

build.bat

License

MIT