API Overview

AI Image Renamer CLI can be used as a Python library in your own projects. This section documents the public API for developers who want to integrate image renaming functionality into their applications.

Module Structure

The package is organized into three main modules:

ai_image_renamer/
├── __init__.py     # Public API exports
├── cli.py          # Command-line interface
├── renamer.py      # Core ImageRenamer class
└── utils.py        # Utility functions

Quick Reference

Main Classes

Class	Module	Description
ImageRenamer	renamer	Orchestrates the renaming pipeline

Utility Functions

Function	Module	Description
verify_image_file()	utils	Validate image files
encode_image()	utils	Base64 encode images
sanitize_image_path()	utils	Generate clean filenames
get_words()	utils	Get AI description

Entry Points

Function	Module	Description
main()	cli	CLI entry point

Import Patterns

Import Everything

from ai_image_renamer import ImageRenamer, verify_image_file, get_words

Import Specific Modules

from ai_image_renamer.renamer import ImageRenamer
from ai_image_renamer.utils import verify_image_file, sanitize_image_path
from ai_image_renamer.cli import main

Import Package

import ai_image_renamer

# Access components
renamer = ai_image_renamer.ImageRenamer(args)
is_valid = ai_image_renamer.verify_image_file("photo.jpg")

Basic Usage

Using ImageRenamer Class

import argparse
from ai_image_renamer import ImageRenamer

# Create arguments namespace
args = argparse.Namespace(
    image_paths=["photo1.jpg", "photo2.png"],
    words=5
)

# Process images (renaming happens in constructor)
renamer = ImageRenamer(args)

Using Utility Functions

from ai_image_renamer import (
    verify_image_file,
    encode_image,
    get_words,
    sanitize_image_path
)

# Validate an image
if verify_image_file("photo.jpg"):
    # Get AI description
    description = get_words("photo.jpg", words=6)
    
    # Generate new filename
    new_path = sanitize_image_path("photo.jpg", description)
    print(f"Would rename to: {new_path}")

Design Principles

Separation of Concerns

The API follows the single responsibility principle:

• cli.py: Argument parsing and user interaction
• renamer.py: Pipeline orchestration
• utils.py: Atomic operations (validation, encoding, API calls)

Fail-Safe Defaults

Functions are designed to fail gracefully:

# Returns False instead of raising for invalid files
is_valid = verify_image_file("nonexistent.jpg")  # False

# Returns empty string for failed API calls
description = get_words("photo.jpg", 6)  # "" on failure

# Skips files with short sanitized names
# (handled internally by ImageRenamer)

No External State

Utility functions are pure functions — they don't modify global state or have side effects (except get_words() which makes API calls).

Dependencies

When using the library, these dependencies are automatically installed:

Package	Version	Purpose
groq	~=0.31.0	Groq API client
filetype	~=1.2.0	Magic byte detection
python-dotenv	~=1.1.1	Environment loading

Error Handling

Exception Hierarchy

Exception
├── RuntimeError      # API key not set
├── FileNotFoundError # Image file not found
├── PermissionError   # File access denied
└── OSError          # Filesystem errors

Handling Errors

from ai_image_renamer import ImageRenamer, get_words
import argparse

try:
    args = argparse.Namespace(image_paths=["photo.jpg"], words=6)
    renamer = ImageRenamer(args)
except RuntimeError as e:
    print(f"Configuration error: {e}")
except FileNotFoundError as e:
    print(f"File not found: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Thread Safety

The library is not thread-safe. Key reasons:

• os.rename() is not atomic on all platforms
• Groq API client may share connection pools
• No locking mechanism for file operations

For concurrent processing, use multiprocessing:

from multiprocessing import Pool
from ai_image_renamer import verify_image_file, get_words, sanitize_image_path
import os

def process_image(path):
    if not verify_image_file(path):
        return None
    
    description = get_words(path, 6)
    if not description:
        return None
    
    new_path = sanitize_image_path(path, description)
    os.rename(path, new_path)
    return new_path

# Process in parallel (be mindful of API rate limits!)
with Pool(4) as pool:
    results = pool.map(process_image, image_paths)

Versioning

The package follows Semantic Versioning:

from ai_image_renamer import __version__

print(__version__)  # "1.1.0"

What's Next

• ImageRenamer Class — Deep dive into the main class
• Utility Functions — Individual function documentation
• Examples — Code samples and patterns