Metadata-Version: 2.5
Name: ollama-rename-files
Version: 0.3.5
Summary: Rename messy files by their content with a local Ollama model: CLI and desktop GUI, no API keys, originals backed up.
Project-URL: Homepage, https://github.com/octrow/ollama-rename-files
Project-URL: Issues, https://github.com/octrow/ollama-rename-files/issues
Project-URL: Changelog, https://github.com/octrow/ollama-rename-files/blob/main/CHANGELOG.md
Author: Daniil Petrov
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,file-renamer,gui,local-llm,ollama,pywebview,rename-files
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: End Users/Desktop
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: flask>=3.0
Requires-Dist: httpx>=0.27
Requires-Dist: ollama>=0.5.0
Requires-Dist: pypdf>=6
Requires-Dist: pywebview>=5.0
Description-Content-Type: text/markdown

# Ollama File Renamer

<p align="center">
  <a href="https://github.com/octrow/ollama-rename-files/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/octrow/ollama-rename-files/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/octrow/ollama-rename-files/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/octrow/ollama-rename-files"></a>
  <a href="https://pypi.org/project/ollama-rename-files/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ollama-rename-files"></a>
  <a href="https://pypi.org/project/ollama-rename-files/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/ollama-rename-files"></a>
  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/octrow/ollama-rename-files"></a>
</p>

<p align="center"><img src="assets/readme/hero.svg" alt="Ollama File Renamer: new2.txt becomes docs-update-backend-migration-plan.txt" width="100%"></p>

<p align="center"><b>English</b> | <a href="README.ru.md">Русский</a></p>

Rename messy files by their content with a local Ollama model. `new2.txt` becomes
`docs-update-backend-migration-plan.txt`, `new6.txt` becomes `sql-create-index-orders-slow-reports.txt`. It runs as a desktop window
or a command-line tool, needs no API keys, and copies every original to a backup folder before touching it.

It's for anyone with a folder of notes, snippets and drafts named `Untitled`, `new`, `copy (3)`: developers,
writers, people who dump quick notes into one inbox folder.

<p align="center"><img src="assets/readme/gui-renamed.png" alt="Desktop window after a run: seven new*.txt files renamed by qwen2.5-coder:1.5b, originals in a backup folder" width="720"></p>

## Features

- Runs on your machine: file contents go only to your own Ollama.
- Originals are copied to `backup_<timestamp>/` inside the folder first, and a rename never overwrites an existing file (it adds `-1`, `-2`, ...).
- In the desktop window you pick a folder, see exactly which files will change, then watch each row get its new name.
- It groups the folder into patterns (`new*.txt`, `Untitled*.md`); you choose one or type a prefix and extension.
- Works with any model you have installed in Ollama. Reasoning models work too: their `<think>` output is stripped.
- The CLI can rename several files at once (`-p 4`).
- Reads text files and the text layer of PDFs (`--ext .pdf`). Scanned PDFs without text and other
  binary files are skipped with a reason, and so are empty files.

## Install

You need [Ollama](https://ollama.com/download) running with one model pulled:

```bash
ollama pull qwen2.5-coder:7b
```

Then install the app with one command. It installs [uv](https://docs.astral.sh/uv/), Python and `ollama-rename`
into your user folder, no admin rights needed.

### macOS / Linux

```bash
curl -LsSf https://raw.githubusercontent.com/octrow/ollama-rename-files/main/install.sh | sh
```

### Windows (PowerShell)

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/octrow/ollama-rename-files/main/install.ps1 | iex"
```

Prefer to read it first? Download [`install.sh`](install.sh) or [`install.ps1`](install.ps1), look through it, then run it.
Run it again to update; `sh install.sh --uninstall` (or `$env:INSTALL_UNINSTALL = "1"` on Windows) removes the app.

### From PyPI

Already have Python 3.10+? Install it from [PyPI](https://pypi.org/project/ollama-rename-files/):

```bash
uv tool install ollama-rename-files   # or: pipx install ollama-rename-files
```

Update with `uv tool upgrade ollama-rename-files` (`pipx upgrade ollama-rename-files`).

### Standalone build

No Python needed: download the archive for your system from the
[latest release](https://github.com/octrow/ollama-rename-files/releases/latest) (Linux x86_64 and arm64, macOS on
Apple silicon, Windows), unpack it and run `ollama-rename gui` from the unpacked folder. The builds aren't signed,
so macOS asks you to allow the app in System Settings → Privacy & Security on the first run.

### From source

```bash
git clone https://github.com/octrow/ollama-rename-files.git
cd ollama-rename-files
uv sync
uv run ollama-rename gui
```

## Usage

### Desktop window

```bash
ollama-rename gui
```

Browse to a folder, pick a discovered pattern or type a prefix and extension, and the window lists exactly which
files will change. Choose an installed model and click **Rename N files**: each row fills in with its new name as the
model answers, and **Stop** halts the run after the current file.

The window shows a local page served at `http://127.0.0.1:5000` (change with `--port` or `FILE_RENAMER_PORT`). If that
port is taken by another app, the next free one is used. If File Renamer itself is already running there, you get its
link and a `Restart it? [y/N]` prompt (No by default, and always No without a terminal). `ollama-rename gui --browser`
serves the page without opening a window.

On Linux the window needs Qt or GTK bindings for Python. Without them `ollama-rename gui` opens the same page in
your default browser. For a native window in a source checkout: `uv pip install "pywebview[qt]"`, or install the
system GTK bindings (`python3-gi`). Windows and macOS work out of the box.

### Command line

```bash
# Interactive: asks for the folder, the file pattern, the model and the context length.
# Options you pass on the command line are not asked again.
ollama-rename

# A folder, a model and 500 characters of each file; asks only for the file pattern
ollama-rename -d ~/notes/inbox -m qwen2.5-coder:7b -c 500

# No prompts: every new*.txt file in the folder
ollama-rename -a -d ~/notes/inbox --prefix new --ext .txt

# Four files at a time; asks for everything but the folder
ollama-rename -d ~/notes/inbox -p 4
```

| Option        | Short | Description                                                                     |
|---------------|-------|---------------------------------------------------------------------------------|
| `--auto`      | `-a`  | Run without interactive prompts. Requires `-d`.                                 |
| `--directory` | `-d`  | Folder with the files to rename.                                                |
| `--model`     | `-m`  | Ollama model to use (default `qwen2.5-coder:7b`).                               |
| `--context`   | `-c`  | How many characters of each file to send to the model (default 2048).           |
| `--prefix`    |       | File name prefix to match (default `new`): `new` takes `new1.txt` and `new.txt`, not `newsletter.txt`. Used with `--ext` as the pattern. |
| `--ext`       |       | File extension to match, with the dot (default `.txt`).                         |
| `--parallel`  | `-p`  | Files renamed at the same time. 0 (default) means one by one.                   |

Ollama on another machine or port? Set `OLLAMA_HOST`, e.g. `OLLAMA_HOST=http://192.168.1.20:11434 ollama-rename`.

## How it works

1. Finds the files in the folder that match the pattern: the prefix as a whole word (`new` takes `new1.txt`, not
   `newsletter.txt`) and the extension. A prefix typed in the desktop window matches any name that starts with it.
2. Creates `backup_<timestamp>/` in that folder and copies each file there before renaming it.
3. Sends the first `--context` characters of the file (for a PDF, of its extracted text) to your local Ollama model.
4. Picks the name out of the reply (skipping chatter like "Here is a name:") and cleans it: lowercase, safe
   characters, at most 128 characters. Names in any script work: `заметка-про-бэкап.txt`.
5. Renames the file, keeping its original extension and never overwriting an existing file.
6. Logs every action and prints which files failed and why.

Names follow the pattern `<type>-<action>-<component>-<short-description>`, for example:

- `task-fix-backend-resolve-database-connection-issue.txt`
- `doc-update-project-architecture-notes.md`

The prompt is tuned for software-project notes: type is task, issue, doc, snippet, review or idea. It lives in
`PROMPT_TEMPLATE` in [`rename_files.py`](src/ollama_rename_files/rename_files.py) if you want other names.

## How it differs from ai-renamer

[ai-renamer](https://github.com/ozgrozer/ai-renamer) is a popular Node.js CLI that does the same job and more: it
also renames images and videos, and it talks to Ollama, LM Studio and OpenAI. Pick it if you rename photos or want a
cloud model.

Ollama File Renamer is narrower: text files, PDFs and local Ollama only. What it adds is a desktop window with a preview of
the exact files that will change, a backup copy of every original, renames that never overwrite, and pattern
discovery so you rename `new*.txt` without touching the rest of the folder.

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
```

See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go through [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE)
