pynamer/README.md

PyNamer

PyNamer is a command-line tool that uses AI vision models to generate descriptive filenames for images. It analyzes the content of images and renames them with meaningful, descriptive filenames in snake_case format.

Features

• Uses LiteLLM to integrate with various vision-capable LLMs (default: GPT-4 Vision)
• Configurable via YAML config file
• Supports multiple image formats (jpg, jpeg, png, gif, webp)
• Automatically resizes large images before processing (configurable max dimension)
• Dry-run mode to preview changes without renaming files
• Handles filename collisions automatically
• Robust config file discovery (user config, package config, or explicit path)

Installation

Option 1: Install from PyPI (recommended)

pip install pynamer

Option 2: Install from source

1. Clone this repository
2. Install the package in development mode:

pip install -e .

Set up your API key

You need to set up your API key for the vision model:

• Set the appropriate environment variable (e.g., OPENAI_API_KEY), or
• Create a custom config file with your API key

Configuration

PyNamer uses the following configuration file locations (in order of precedence):

1. Custom config file specified with -c or --config option
2. User config file at ~/.config/pynamer.yaml (created automatically on first run)
3. Default config file included with the package

You can customize the following settings:

• LLM provider and model
• API key and endpoint
• Supported image formats
• Image resizing parameters (max dimension, output format)
• Prompt templates for filename generation

Example configuration file:

# LLM API Configuration
llm:
  provider: "openai"
  model: "gpt-4-vision-preview"
  api_key: "your-api-key-here"
  max_tokens: 100
  temperature: 0.7

# Image Processing
image:
  supported_formats:
    - ".jpg"
    - ".jpeg"
    - ".png"
    - ".gif"
    - ".webp"
  resize_max_dimension: 1024  # Max width/height before resizing
  resize_format: "JPEG"      # Output format for resized images

# Prompt Configuration
prompt:
  system_message: "You are a helpful assistant that generates concise, descriptive filenames..."
  user_message: "Generate a descriptive filename for this image..."

Usage

After installation, you can use PyNamer directly from the command line:

Basic usage:

pynamer path/to/image.jpg

Process multiple images:

pynamer image1.jpg image2.png image3.jpg

Use a different config file:

pynamer -c custom_config.yaml image.jpg

Preview changes without renaming (dry run):

pynamer -d image.jpg

Enable verbose logging:

pynamer -v image.jpg

Example

Input: IMG_20230615_123456.jpg (a photo of a cat sleeping on a window sill)

Output: orange_cat_sleeping_on_sunny_windowsill.jpg

Development

Building the package

pip install build
python -m build

Installing in development mode

pip install -e .

Requirements

• Python 3.7+
• LiteLLM
• PyYAML
• Access to a vision-capable LLM API (OpenAI, Anthropic, etc.)