Metadata-Version: 2.4
Name: airename
Version: 0.1.0
Summary: AI-powered cross-platform batch file renaming
Project-URL: Homepage, https://github.com/j0ta29/airename
Project-URL: Repository, https://github.com/j0ta29/airename
Project-URL: Bug Tracker, https://github.com/j0ta29/airename/issues
Author-email: Jürgen Albert <jota@gmx.de>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: pillow
Requires-Dist: pypdf
Description-Content-Type: text/markdown

# 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 authentic photo-taken date extracted from EXIF metadata (via `Pillow`).
- **Recursive Watch Mode (`-w` / `--watch`)**:
  - Continuously and recursively monitors a target directory tree 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

```bash
pip install airename
```

For development:
```bash
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):
   ```bash
   pip install Pillow
   ```
3. **pypdf** (Recommended, for PDF content-awareness):
   ```bash
   pip install pypdf
   ```

### Backend Prerequisites:

- **For Ollama (Local)**:
  - Download and install from [ollama.com](https://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`:

```json
{
  "backend": "gemini",
  "model": "gemini-1.5-flash",
  "interval": 5,
  "ollama_url": "http://localhost:11434",
  "openai_url": "https://api.openai.com/v1",
  "watch_dir": "/Users/username/Downloads",
  "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 to recursively monitor if launched without a path argument.
- `gemini_api_key` or `api_keys.gemini`: Google Gemini API credentials.
- `openai_api_key` or `api_keys.openai`: OpenAI-compatible API credentials.

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

```bash
airename [OPTIONS] [FILES...]
```

### Options

| Option | Long Option | Description |
| :--- | :--- | :--- |
| `-b <backend>`| `--backend <backend>` | Specify AI backend: `ollama`, `gemini`, or `openai` (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 a directory for unprocessed files |
| `--interval <sec>` | | The interval in seconds between directory watch scans (default: `5`) |
| `-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 |
| `-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`) |
| `-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:
```bash
airename
```

### 2. Using Google Gemini Backend with CLI overrides
```bash
airename -b gemini -d test/*
```

### 3. Continuous Recursive Watch Mode (Local Ollama)
```bash
airename --watch ~/Downloads --interval 3 -m gemma4
```

---

## Testing

To run tests:
```bash
python3 test_airename.py
```
