image-namer 1.0.1

Rename image files based on their visual contents using AI vision models.

Image Namer

Rename image files based on their visual contents using AI vision models.

Transform generic filenames like IMG_2347.jpg into descriptive names like golden-retriever-puppy--running-in-park.jpg using AI vision analysis.

Features

• 🤖 AI-powered naming using Ollama (local) or OpenAI (cloud)
• 🏠 Local-first with Ollama for privacy
• ⚡ Intelligent caching to avoid redundant API calls
• 🔄 Idempotent - won't rename already-suitable files
• 📁 Batch processing with recursive folder support
• 📝 Markdown reference updates for Obsidian and standard markdown
• 🔍 Dry-run mode to preview changes safely
• 🎯 Smart collision handling

Quick Start

Installation (Recommended: pipx)

Install Image Namer using pipx for a clean, isolated installation:

# Install pipx (if needed)
brew install pipx  # macOS
# or: python3 -m pip install --user pipx

# Install image-namer
pipx install git+https://github.com/svetzal/image-namer.git

# Verify installation
image-namer --help

Why pipx? It installs Python CLI tools in isolated environments, preventing dependency conflicts with other projects.

Setup AI Provider

Image Namer requires an AI vision model. Choose one:

Option 1: Ollama (Recommended - Free & Local)

# Install from https://ollama.com
ollama pull gemma3:27b

Option 2: OpenAI (Cloud - Requires API Key)

export OPENAI_API_KEY='sk-proj-...'

Basic Usage

# Preview rename (dry-run)
image-namer file photo.jpg

# Apply rename
image-namer file photo.jpg --apply

# Process entire folder
image-namer folder ~/Pictures/screenshots --apply

# Update markdown references
image-namer folder ~/Documents/notes/images --apply --update-refs

Documentation

📚 Full Documentation (comprehensive guides and reference)

Quick links:

• Installation Guide - Detailed setup instructions
• Getting Started - Your first rename
• How-To Guides - Step-by-step workflows
• CLI Reference - Complete command docs

Development

Setup

# Clone repository
git clone https://github.com/svetzal/image-namer.git
cd image-namer

# Install with development dependencies (using uv)
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

Testing

pytest                    # Run all tests with coverage
pytest -v --no-cov       # Verbose without coverage
flake8 src               # Lint code

Documentation

# Install docs dependencies (included in [dev])
pip install -e ".[dev]"

# Serve docs locally
mkdocs serve

# Build docs locally
mkdocs build

Note: Documentation is automatically deployed to GitHub Pages when a new release is published. See docs/GITHUB_PAGES_SETUP.md for details.

Requirements

• Python 3.13 or later
• AI provider: Ollama (local) or OpenAI (cloud)

License

MIT License - see LICENSE

Project Status

🎉 Version 1.0.0 - Production Ready

Complete Features

✅ Core Functionality

• Single file and batch folder renaming with AI vision analysis
• Smart pre-flight assessment to skip already-suitable files
• Intelligent caching system (dramatically reduces LLM calls)
• Idempotent operations (won't rename if name already matches content)

✅ Markdown Integration

• Automatic reference updates in standard Markdown and Obsidian
• Preserves alt text and aliases
• URL-encoded path handling

✅ AI Providers

• Ollama (local, privacy-focused, default)
• OpenAI (cloud-based)
• Easy provider switching via CLI or environment variables

✅ Developer-Friendly

• 94 comprehensive tests with 88% coverage
• Type-safe with Pydantic models
• Well-documented code and APIs
• Flake8 compliant

What's Not Included (By Design)

• GUI interface (CLI-first approach)
• Video or PDF processing (images only)
• Multi-language filename support (English slugs)

See CHANGELOG.md for detailed release notes.