# 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):

```bash
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:

```dotenv
llm_api_base_url=https://your-openai-compatible-api/v1
llm_api_key=your-api-key
llm_default_temperature=0.2
metadata_prefix=photools3:
```

Keyword suggestions are restricted to the vocabulary in `config/keywords.txt`.

## 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:

```bash
uv run photools3 metadata-magic photo.dng
```

Choose a mode with `--mode`:

```bash
# 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:

```bash
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:

```bash
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:

```bash
uv run photools3 quality photo.dng
```

## Help

Show the available commands and options with:

```bash
uv run photools3 --help
uv run photools3 metadata-magic --help
uv run photools3 quality --help
```