PhotoTools3
PhotoTools3 uses an OpenAI-compatible vision API to generate photo captions and keywords, then writes the results to photo metadata. It can also assess photo quality.
Setup
Install the Python dependencies with uv and make sure ExifTool is installed and
available on PATH (it is a system dependency, not a Python package):
uv sync
Create a .env file in the project root with the LLM connection details and the
prefix used to identify metadata written by PhotoTools3:
llm_api_base_url=http://localhost:1234/v1
llm_api_key=your-api-key
llm_default_temperature=0.2
metadata_prefix=photools3:
LOG_LEVEL=DEBUG
LLM_FLUSH_EVERY_PHOTOS=50
LLM_MAX_RETRIES=5
Keyword suggestions are restricted to the vocabulary in config/keywords.txt.
LOG_LEVEL=DEBUG enables detailed per-request and per-photo timings. The flush
interval uses LM Studio's native model-management API to unload and reload the
model after every 50 attempted batch photos. This requires LM Studio's native
/api/v1 model-management API. Set LLM_FLUSH_EVERY_PHOTOS=0 to disable it;
use 0 for non-LM-Studio OpenAI-compatible providers.
LLM_MAX_RETRIES controls how many corrective retry requests are allowed after
the initial LLM response; 5 means up to 6 requests for a photo.
Generate metadata
The metadata-magic command accepts one or more image paths and/or directories.
The default mode is both, which generates and writes a caption and keywords:
uv run photools3 metadata-magic photo.dng
Choose a mode with --mode:
# Generate only keywords
uv run photools3 metadata-magic photo.dng --mode keywords
# Generate only a caption
uv run photools3 metadata-magic photo.dng --mode captions
# Explicitly request both (the default)
uv run photools3 metadata-magic photo.dng --mode both
Pass multiple files to process them sequentially as a batch:
uv run photools3 metadata-magic photo1.dng photo2.jpg --mode both
Directories are scanned at the top level by default. Add --recursive to
include supported images in subdirectories. You can combine directories and
individual file paths:
uv run photools3 metadata-magic ./photos --recursive --mode keywords
uv run photools3 metadata-magic ./photos photo-to-include.dng --mode captions
The command reports each processed file and exits with a non-zero status if any file fails. In a batch, it continues processing the remaining files after an individual failure. Generated metadata is written using ExifTool and XMP sidecars.
Assess photo quality
The quality command reports an assessment without changing photo metadata:
uv run photools3 quality photo.dng
Help
Show the available commands and options with:
uv run photools3 --help
uv run photools3 metadata-magic --help
uv run photools3 quality --help