airename 0.1.0__tar.gz

airename-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# OS-specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Environments and Virtual Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Testing and Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+test/
+
+# Editor / IDE configuration
+.vscode/
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.swp
+
+# Packaging
+dist/
+build/
+*.egg-info/
+

airename-0.1.0/AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md
+
+## Repo Shape
+- `src/airename/__init__.py` contains all runtime logic and `main()` is the only entrypoint.
+- `./airename` is a thin shim that does `from airename import main; main()`.
+- `pyproject.toml` at root defines the package build (hatchling), metadata, and the `airename` console_scripts entry point.
+- `test_airename.py` is the only automated test file; there is no lint/typecheck config, and no CI/workflow config in the repo.
+
+## Verified Commands
+- Show CLI/help: `python3 -m airename --help`
+- Run all tests: `python3 -m unittest test_airename.py`
+- Run one test: `python3 -m unittest test_airename.TestAirename.test_watch_mode`
+- Editable install: `pip install -e .` (run from repo root)
+
+## Python / Test Gotchas
+- The repo works on Python 3.6+ for the current test suite and subprocess helpers because it uses `stdout/stderr=subprocess.PIPE` plus `universal_newlines=True` instead of the Python 3.7+ `capture_output=` and `text=` shortcuts.
+- Tests execute `python -m airename` as a subprocess via `sys.executable` and set `HOME` to a temp directory. If you change config loading or CLI argument parsing, verify through the subprocess-based tests, not just by importing functions.
+- The package must be installed (`pip install -e .`) before tests can run, or you must activate the venv it was installed into.
+- Current tests use fake `.pdf` and `.png` files written as plain text. They cover extension-driven routing and fallback behavior, not real PDF/image parsing.
+
+## Behavior That Is Easy To Miss
+- Config is loaded only from `~/.config/airename/airename.json` via `load_config()`. The loader strips `//`, `/* ... */`, and `#` comments before `json.loads`.
+- Config aliases are real behavior: `interval` or `intervall`, `watch_dir` or `watch_dirs`, `gemini_api_key` or `api_keys.gemini`, `openai_api_key` or `api_keys.openai`.
+- Backend selection is not only `--backend`: in `main()`, models containing `gemini` force the Gemini backend, and models containing `gpt-` or `openai` force the OpenAI-compatible backend.
+- Watch mode only runs when `--watch` is set and no positional files are given. It recursively skips hidden directories and dotfiles, and only processes files after the size is unchanged for 2 poll cycles.
+- Batch size is hard-coded to 30 files per API call in `main()`.
+- `rename_batch()` preserves the original extension, keeps renamed files in the source directory, replaces `:` with `-`, and skips collisions unless `--force` is set.
+
+## External Dependency Notes
+- Runtime is mostly stdlib. `pypdf` and `Pillow` are required dependencies (installed automatically). PDF text extraction prefers `pypdf`, then falls back to `pdftotext`; image datetime extraction prefers Pillow, then `exiftool`, then file mtime.
+- Ollama is the only backend with a preflight connectivity check (`/api/tags`) before processing.

airename-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+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
+```

airename-0.1.0/README.md

@@ -0,0 +1,155 @@
+# 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
+```

airename-0.1.0/airename

@@ -0,0 +1,3 @@
+#!/usr/bin/env python3
+from airename import main
+main()

airename-0.1.0/opencode.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": true
+}

airename-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "airename"
+version = "0.1.0"
+description = "AI-powered cross-platform batch file renaming"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Jürgen Albert", email = "jota@gmx.de"}
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+]
+
+dependencies = [
+    "pypdf",
+    "Pillow",
+]
+
+[project.urls]
+Homepage = "https://github.com/j0ta29/airename"
+Repository = "https://github.com/j0ta29/airename"
+"Bug Tracker" = "https://github.com/j0ta29/airename/issues"
+
+[project.scripts]
+airename = "airename:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/airename"]

airename-0.1.0/pyrightconfig.json

@@ -0,0 +1,10 @@
+{
+  "include": [
+    "airename",
+    "test_airename.py"
+  ],
+  "exclude": [
+    ".venv"
+  ],
+  "typeCheckingMode": "basic"
+}