airename

airename is a cross-platform, AI-powered command-line interface (CLI) tool written in Python that automatically renames files or directories using a local Ollama LLM or Google Gemini API based on their actual text, image, or PDF content and metadata.

Every filename is automatically structured with an extracted ISO date/datetime prefix.

---

Features

• Multi-Backend AI Support:
  • Ollama: Local, private, and free (using offline models like llama3 or gemma4).
  • Google Gemini: Remote, high-speed, and extremely smart (using models like gemini-1.5-flash or gemini-1.5-pro).
  • OpenAI-Compatible: Remote or local high-speed processing (using standard OpenAI models like gpt-4o-mini or third-party compatible endpoints such as Groq, DeepSeek, LM Studio, etc.).
• Configuration File Support (~/.config/airename/airename.json):
  • Centralize your preferences. Configure default watch directories, standard models, chosen backend, custom intervals, API keys, and local URLs.
• Content-Aware Renaming:
  • Text Files: Reads the first 4000 characters to extract a fitting, descriptive name and scan for document dates (like invoices, contracts, or letter headers).
  • PDF Files: Uses pypdf to read the first 4000 characters of text from the PDF, treating it as text content for smart renaming.
  • Image Files: Uses original names but prefixes them with their photo-taken date. The date is extracted from EXIF metadata (via Pillow); if the image has no EXIF data, airename tries to parse the date from the filename itself (e.g. messenger exports like IMG-20260602-WA0048.jpg), falling back to a YYYY-MM-DD date-only prefix when no time is available. When the date comes from the filename, it is also written back into the image's EXIF metadata (requires exiftool). Any leftover date/time info is removed from the descriptive part of the name (e.g. IMG-20260602-WA0048 → IMG-WA0048).
• Recursive Watch Mode (-w / --watch):
  • Continuously and recursively monitors one or more target directories (and their subtrees) for files lacking the ISO date/datetime prefix.
  • Write-Stability Safety: Automatically tracks file size and only renames a file once it remains stable (unchanged) for at least 2 consecutive poll cycles. This prevents renaming active downloads or files currently being written.
• High Performance: Automatically batches files (up to 30 files per API call) to optimize LLM throughput.
• Cross-Platform: Run it seamlessly on macOS, Linux, and Windows.
• Safety Features:
  • Dry-Run mode (-d / --dry-run): Safely inspect proposed changes without renaming any files.
  • Interactive mode (-i / --interactive): Confirm each individual file rename with a quick terminal prompt.
  • Collision Prevention: Warns and skips renaming if the target file name already exists on disk.

---

Installation

pip install airename

For development:

git clone https://github.com/j0ta29/airename.git
cd airename
pip install -e .

Prerequisites

To use airename, you need:

1. Python 3.x: Ensure Python is installed.
2. Pillow (Recommended, for Image EXIF):

   pip install Pillow
   

3. pypdf (Recommended, for PDF content-awareness):

   pip install pypdf
   

Backend Prerequisites:

• For Ollama (Local):
  • Download and install from ollama.com. Ensure the service is running (ollama serve).
• For Google Gemini (Remote):
  • Obtain a Gemini API Key from Google AI Studio.
  • Export it as GEMINI_API_KEY, or configure it inside your ~/.config/airename/airename.json file.
• For OpenAI-Compatible Backends (Remote or Local):
  • Obtain your API key from OpenAI (or your provider of choice).
  • Export it as OPENAI_API_KEY, or configure it inside your ~/.config/airename/airename.json file.

---

Configuration File

airename automatically loads default options from a JSON configuration file located at ~/.config/airename/airename.json.

Here is a complete schema example of ~/.config/airename/airename.json:

{
  "backend": "gemini",
  "model": "gemini-1.5-flash",
  "interval": 5,
  "ollama_url": "http://localhost:11434",
  "openai_url": "https://api.openai.com/v1",
  "watch_dirs": ["/Users/username/Downloads", "/Users/username/Documents"],
  "api_keys": {
    "gemini": "AIzaSyYourKeyHere...",
    "openai": "sk-proj-YourKeyHere..."
  }
}

Config File Fields

• backend: "ollama", "gemini", or "openai" (default: ollama).
• model: Default LLM model identifier (e.g. llama3, gemma4, gemini-1.5-flash, gpt-4o-mini).
• interval / intervall: Interval in seconds between directory scans in watch mode (default: 5).
• ollama_url: Host address of your local Ollama server (default: http://localhost:11434).
• openai_url: API base URL for OpenAI-compatible providers (default: https://api.openai.com/v1).
• watch_dir / watch_dirs: Default directory path(s) to recursively monitor if launched without files. watch_dir accepts a single string; watch_dirs accepts a list of strings.
• gemini_api_key or api_keys.gemini: Google Gemini API credentials.
• openai_api_key or api_keys.openai: OpenAI-compatible API credentials.
• batch_size: Number of files sent per API call (default: 3).

Note: Any options passed as CLI flags (such as -m or --interval) will automatically override entries inside the config file.

Usage

airename [OPTIONS] [FILES...]

Options

Option	Long Option	Description
-b <backend>	--backend <backend>	Specify AI backend: ollama, gemini, openai, or apple (default: ollama)
-m <name>	--model <name>	Specify the model to use (defaults: llama3 for Ollama, gemini-1.5-flash for Gemini, gpt-4o-mini for OpenAI)
-w <dir>	--watch <dir>	Continuously and recursively watch directories for unprocessed files (can be specified multiple times)
--interval <sec>		The interval in seconds between directory watch scans (default: 5)
--timeout <sec>		Timeout in seconds for API calls (default: 120)
--batch-size <n>		Files per API call; 0 uses backend default (3)
-o <dir>	--output <dir>	Output directory for renamed files (creates it if needed)
-k	--keep	Keep original files (copy instead of move)
-d	--dry-run	Show proposed changes without actually renaming files
-i	--interactive	Ask for confirmation before renaming each file
-f	--force	Overwrite existing files without warning; in watch mode, also process files that already have an ISO date prefix
-v	--verbose	Print detailed debug / API payloads
	--url <url>	Override the default Ollama API URL (default: http://localhost:11434)
	--openai-url <url>	Override the default OpenAI API base URL (default: https://api.openai.com/v1)
	--completion [{bash,zsh,auto}]	Output a shell completion script for bash or zsh
-h	--help	Show the help message and exit

---

Examples

1. Simple Run using Config Defaults

If you have configured watch_dir, backend, and gemini API keys inside your ~/.config/airename/airename.json file, you can start recursively watching your folder simply by running:

airename

2. Using Google Gemini Backend with CLI overrides

airename -b gemini -d test/*

3. Continuous Recursive Watch Mode (Local Ollama)

airename --watch ~/Downloads --interval 3 -m gemma4

4. Shell Completion

Add to ~/.zshrc or ~/.bashrc:

source <(airename --completion)

---

Testing

To run tests:

python3 test_airename.py