pyimgtag 0.8.1

Tag macOS Photos library images using local Gemma model for searchable tags

pyimgtag

Tag images using a local Gemma model for searchable tags, with optional Apple Photos integration on macOS.

Overview

pyimgtag uses a vision model to analyse images and generate 1-5 descriptive tags per photo. By default it calls a locally-running Gemma model via Ollama, so image analysis and tagging stay on-device. You can also point pyimgtag at a remote Ollama server or one of three hosted vision APIs — Anthropic Claude, OpenAI, or Google Gemini — by passing --backend. When a cloud backend is selected, the JPEG bytes leave the machine; otherwise they don't.

If EXIF GPS is present, only the latitude/longitude is sent to OpenStreetMap Nominatim for reverse geocoding to a city/place; results are cached locally so repeat lookups stay offline.

Works on macOS, Linux, and Windows. Apple Photos integration (write-back) is macOS-only.

Key features:

• One model call per image, compact prompt, low token usage
• Pluggable vision backends: local Ollama (default), remote Ollama via --ollama-url, Anthropic Claude, OpenAI, or Google Gemini via --backend
• Rich AI metadata: scene category, emotional tone, cleanup classification, text detection, event hints
• EXIF GPS as source of truth for location (never guessed from image content)
• Open reverse geocoding via Nominatim (sends GPS coords to OpenStreetMap; cached locally)
• Supports exported folders and Apple Photos library originals (macOS only)
• Apple Photos write-back: push AI tags and descriptions back as keywords/captions (macOS only)
• Subcommands: run, judge, status, reprocess, cleanup, preflight, query, tags
• Photo quality scoring with professional 13-criterion rubric (new: judge subcommand)
• Dry-run mode, date/limit filters, JSON/CSV export
• SQLite progress DB with schema versioning for incremental re-runs

Requirements

• Python 3.11+
• Ollama installed and running
• Gemma 4 model pulled: ollama pull gemma4:e4b

macOS-specific:

• Apple Silicon or Intel Mac
• Optional: exiftool for reliable HEIC EXIF (falls back to Pillow)
• Optional: pillow-heif for HEIC image loading

All platforms:

• Works on macOS, Linux, and Windows
• EXIF writing via exiftool (if installed) works across platforms
• Apple Photos write-back requires macOS

Quick Start

pip install -e ".[dev]"

# Pull the model
ollama pull gemma4:e4b

# Dry-run on an exported folder, first 20 images
pyimgtag run --input-dir ~/Pictures/exported --limit 20 --dry-run

# Single date
pyimgtag run --input-dir ~/Pictures/exported --date 2026-04-01 --dry-run

# Date range with JSON output
pyimgtag run --input-dir ~/Pictures/exported \
  --date-from 2026-03-01 --date-to 2026-03-31 \
  --output-json results.json

# Photos library
pyimgtag run --photos-library ~/Pictures/Photos\ Library.photoslibrary \
  --limit 50 --dry-run

# Check processing progress
pyimgtag status

# Re-tag all photos (e.g. after prompt improvements)
pyimgtag reprocess

# List photos flagged for deletion
pyimgtag cleanup

# Score photos by quality (judge)
pyimgtag judge --input-dir ~/Pictures/exported --limit 20 --verbose

# Filter to only strong photos, save ranking to JSON
pyimgtag judge --input-dir ~/Pictures/exported \
  --min-score 7 --output-json ranking.json

Installation

# From source
git clone https://github.com/kurok/pyimgtag.git
cd pyimgtag
pip install -e ".[dev]"

# Optional HEIC support
pip install pillow-heif

# Optional exiftool (better EXIF for HEIC)
brew install exiftool

Platform Support

Feature	macOS	Linux	Windows
Image tagging via Ollama	✅	✅	✅
EXIF reading (GPS, dates)	✅	✅	✅
Reverse geocoding (Nominatim)	✅	✅	✅
EXIF writing via exiftool	✅	✅	✅
HEIC conversion (sips / pillow-heif)	✅ sips + pillow-heif	✅ pillow-heif	✅ pillow-heif
RAW image support (rawpy)	✅	✅	✅
Apple Photos library scanning	✅	❌	❌
Apple Photos write-back	✅	❌	❌
Face management (Apple Photos)	✅	❌	❌

Note: Most features work cross-platform. Apple Photos integration and face management are macOS-only — they require AppleScript via osascript.

macOS Setup

# Prerequisites
brew install ollama exiftool
ollama pull gemma4:e4b

# Install
pip install "pyimgtag[all]"   # includes pillow-heif, photoscript, rawpy, face-recognition, fastapi, uvicorn
# or from source
git clone https://github.com/kurok/pyimgtag.git
cd pyimgtag
pip install -e ".[all,dev]"

Features available: everything including Apple Photos integration, HEIC, face management, and photo review workflows.

Typical macOS workflow:

# Tag your Photos library directly
pyimgtag run --photos-library ~/Pictures/Photos\ Library.photoslibrary --write-back --limit 50

# Score photo quality
pyimgtag judge --photos-library ~/Pictures/Photos\ Library.photoslibrary --min-score 8

# Import named faces from Apple Photos
pyimgtag faces import-photos  # reads system default Photos library

Note: Apple Photos library access requires Full Disk Access permission for your terminal app — grant it in System Settings > Privacy & Security > Full Disk Access.

Linux Setup

# Ubuntu/Debian
sudo apt-get install exiftool python3.11 python3-pip
# or install exiftool from https://exiftool.org

# Fedora/RHEL
sudo dnf install perl-Image-ExifTool python3.11

# Arch
sudo pacman -S perl-image-exiftool python

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull gemma4:e4b

# Install pyimgtag
pip install "pyimgtag[heic]"   # includes pillow-heif for HEIC
# or from source
git clone https://github.com/kurok/pyimgtag.git
cd pyimgtag
pip install -e ".[heic,dev]"

Features available: image tagging, EXIF reading/writing, geocoding, judge, dedup, JSON/CSV export. No Apple Photos integration.

Typical Linux workflow:

# Tag an exported photo directory
pyimgtag run --input-dir ~/Pictures/exported --output-json results.json

# With EXIF write-back (requires exiftool)
pyimgtag run --input-dir ~/Pictures/exported --write-exif

# Score photo quality
pyimgtag judge --input-dir ~/Pictures/exported --min-score 7 --output-json ranking.json

Note: --write-back (Apple Photos) is silently skipped on Linux with a warning. Use --write-exif instead.

Windows Setup

# Install Python 3.11+ from https://python.org
# Install Ollama from https://ollama.com

# Install exiftool — download from https://exiftool.org/
# Or via Chocolatey:
choco install exiftool

# Or via winget:
winget install OliverBetz.ExifTool

ollama pull gemma4:e4b

# Install pyimgtag
pip install "pyimgtag[heic]"
# or from source
git clone https://github.com/kurok/pyimgtag.git
cd pyimgtag
pip install -e ".[heic,dev]"

Features available: same as Linux — tagging, EXIF, geocoding, judge, dedup, export. No Apple Photos integration.

Typical Windows workflow (PowerShell):

# Tag photos in a folder
pyimgtag run --input-dir C:\Users\Me\Pictures\exported --output-json results.json

# Score photo quality
pyimgtag judge --input-dir C:\Users\Me\Pictures\exported --min-score 7

# Check what was processed
pyimgtag status

Note: On Windows, use \ path separators or quote paths with spaces: "C:\My Photos".

Platform Troubleshooting

macOS:

• "Operation not permitted" on Photos library → grant Full Disk Access to Terminal in System Settings > Privacy & Security > Full Disk Access
• exiftool not found → brew install exiftool
• HEIC files not loading → pip install pillow-heif
• Ollama not running → brew services start ollama or run ollama serve

Linux:

• exiftool not found → install via package manager (see setup above)
• HEIC files not loading → pip install pillow-heif
• Ollama not running → ollama serve in a separate terminal
• Permission denied on image folder → check directory permissions with ls -la

Windows:

• exiftool not found → add exiftool directory to PATH, or install via Chocolatey/winget
• Python not found → ensure Python 3.11+ is installed and added to PATH during install
• HEIC files not loading → pip install pillow-heif
• Ollama not running → start Ollama from system tray or run ollama serve
• Long paths issue → enable long path support: Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

Usage

Subcommands

pyimgtag uses subcommands. Run pyimgtag --help for the full list.

pyimgtag run — tag images

# Exported image folder
pyimgtag run --input-dir /path/to/photos

# Apple Photos library
pyimgtag run --photos-library ~/Pictures/Photos\ Library.photoslibrary

# With filters
pyimgtag run --input-dir /path/to/photos \
  --limit 100 --date-from 2026-03-01 --date-to 2026-03-31

# Write tags back to Apple Photos as keywords
pyimgtag run --photos-library ~/Pictures/Photos\ Library.photoslibrary \
  --write-back --limit 10

# Deduplicate by perceptual hash
pyimgtag run --input-dir /path/to/photos --dedup

# Export to JSON
pyimgtag run --input-dir /path/to/photos --output-json results.json

Choosing a vision backend

By default pyimgtag calls a local Ollama server. Use --backend to pick a different provider; the same prompt and result schema apply across backends.

# Default: local Ollama
pyimgtag run --input-dir /path/to/photos

# Remote Ollama server (e.g. on another machine in your LAN)
pyimgtag run --input-dir /path/to/photos --ollama-url http://gpu-host:11434

# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-... pyimgtag run --input-dir /path/to/photos \
  --backend anthropic

# OpenAI (override the default model if needed)
OPENAI_API_KEY=sk-... pyimgtag run --input-dir /path/to/photos \
  --backend openai --model gpt-4o

# Google Gemini
GOOGLE_API_KEY=... pyimgtag run --input-dir /path/to/photos \
  --backend gemini

Per-backend defaults:

Backend	Default model	Auth env var
ollama	gemma4:e4b	none (uses --ollama-url)
anthropic	claude-sonnet-4-6	ANTHROPIC_API_KEY
openai	gpt-4o-mini	OPENAI_API_KEY
gemini	gemini-1.5-flash	GOOGLE_API_KEY (or GEMINI_API_KEY)

Cloud backends send the JPEG bytes for each image to the provider. Use --api-base to override the base URL (for self-hosted gateways or proxies) and --api-key if you want to pass the secret on the command line instead of via an environment variable. The --backend flag works identically for pyimgtag judge.

Run flags:

Flag	Description
--input-dir PATH	Exported image folder
--photos-library PATH	Apple Photos library package (macOS only)
--limit N	Max images to process
--date YYYY-MM-DD	Single date filter
--date-from / --date-to	Date range filter
--extensions jpg,png	File types (default: jpg,jpeg,heic,png)
--skip-no-gps	Skip images without GPS data
--dry-run	Verbose output, no DB writes
--verbose / -v	Detailed per-file output
--output-json FILE	Write results to JSON
--output-csv FILE	Write results to CSV
--jsonl-stdout	JSONL output to stdout
--write-back	Write tags/description back to Apple Photos (macOS only; uses osascript by default — set PYIMGTAG_USE_PHOTOSCRIPT=1 to opt into the faster in-process photoscript path on stable hosts)
--write-exif	Write description and keywords to image EXIF
--dedup	Skip duplicates via perceptual hash
--dedup-threshold N	Hamming distance threshold (default: 5)
--model NAME	Ollama model (default: gemma4:e4b)
--ollama-url URL	Ollama API URL
--max-dim N	Max image dimension (default: 1280)
--timeout N	Model request timeout in seconds
--db PATH	Progress database path
--no-cache	Skip progress DB, reprocess all

pyimgtag status — check progress

# Show processing stats
pyimgtag status

# Output:
# Progress: 142 / 200 (71%)
#   ok:      140
#   error:   2
#   pending: 58

pyimgtag reprocess — reset for re-tagging

# Reset everything (e.g. after prompt improvements)
pyimgtag reprocess

# Reset only failed entries
pyimgtag reprocess --status error

pyimgtag cleanup — find photos to delete

# List photos the AI flagged as "delete"
pyimgtag cleanup

# Also include "review" (uncertain) candidates
pyimgtag cleanup --include-review

# Output:
# Cleanup candidates (delete): 12
#
#   [delete]  /path/to/blurry_photo.jpg  | 2026-03-15  | tags: blurry, dark
#   [delete]  /path/to/screenshot.png    | 2026-04-01  | tags: screenshot, text

pyimgtag query — search tagged images

# Search by tag
pyimgtag query --tag sunset

# Search by location
pyimgtag query --location "San Francisco"

# Output as JSON
pyimgtag query --tag beach --output-json matches.json

pyimgtag tags — manage tags

# List all tags with image counts
pyimgtag tags list

# Rename a tag across all images
pyimgtag tags rename old-name new-name

# Delete a tag from all images
pyimgtag tags delete unwanted-tag --dry-run

# Merge one tag into another
pyimgtag tags merge source-tag target-tag

pyimgtag preflight — check prerequisites

# Verify Ollama, model, and source path
pyimgtag preflight --input-dir ~/Pictures/exported

pyimgtag judge — score photo quality

Score each image against a 13-criterion professional rubric. Outputs a ranked list with weighted scores as integers on a 1–10 scale (no decimal component). Requires Ollama.

# Score all images in a folder
pyimgtag judge --input-dir ~/Pictures/exported

# Only show photos scoring 3.5 or above
pyimgtag judge --input-dir ~/Pictures/exported --min-score 7

# Verbose breakdown (per-criterion scores)
pyimgtag judge --input-dir ~/Pictures/exported --limit 20 --verbose

# Sort by filename instead of score
pyimgtag judge --input-dir ~/Pictures/exported --sort-by name

# Score Photos library
pyimgtag judge --photos-library ~/Pictures/Photos\ Library.photoslibrary \
  --limit 50 --min-score 8

# Save full ranking to JSON
pyimgtag judge --input-dir ~/Pictures/exported \
  --output-json ranking.json

Sample output (brief mode):

[1/5] golden_hour.jpg → 9/10 outstanding | + impact, composition_center | - edit_integrity, noise_cleanliness
  Golden light over the cityscape; strong composition but slight haloing on edges.
[2/5] portrait.jpg → 7/10 solid | + focus_sharpness, lighting | - creativity_style, color_mood
  Well-lit portrait; technically solid but conventional treatment.

Sample output (--verbose):

[1/5] golden_hour.jpg
  Score:   9/10  (core: 9, visible: 8)
  Best:    impact=10, composition_center=10, lighting=8
  Weakest: edit_integrity=6, noise_cleanliness=6, subject_separation=6
  Verdict: Golden light over the cityscape; strong composition but slight haloing on edges.

Judge flags:

Flag	Default	Description
--input-dir PATH	—	Exported image folder
--photos-library PATH	—	Apple Photos library (macOS only)
--limit N	unlimited	Max images to score
--extensions EXT,...	jpg,jpeg,heic,png,tiff,webp	File types
--min-score SCORE	—	Only show images scoring ≥ SCORE
--sort-by score|name	score	Final sort order
--output-json FILE	—	Write ranked results to JSON
--verbose	false	Per-criterion breakdown
--no-recursive	false	Do not scan subdirectories
--model NAME	gemma4:e4b	Ollama model
--ollama-url URL	http://localhost:11434	Ollama API URL
--max-dim N	1280	Max image dimension before resize
--timeout N	120	Request timeout (seconds)

Sample verbose output

[1/50] sunset_beach.jpg
  Path:     /Users/me/Pictures/exported/sunset_beach.jpg
  Date:     2026-04-01 14:30:00
  Tags:     sunset, beach, ocean, waves, sand
  Summary:  golden hour sunset over the Pacific
  Scene:    outdoor_leisure
  Tone:     positive
  Cleanup:  keep
  Event:    outing
  Signif.:  high
  GPS:      37.7749, -122.4194
  Location: San Francisco, California, United States
  Status:   ok

--- Summary ---
  Scanned:          200
  Processed:        50
  Skipped (date):   0
  Skipped (no GPS): 0
  Skipped (no file):0
  Model failures:   2
  Geocode failures: 0

Output schema

Each result (JSON/CSV) includes:

Field	Description
file_path	Full path to image
file_name	Filename
source_type	directory or photos_library
image_date	EXIF or file date
tags	1-5 vision model tags
scene_summary	Short scene description
scene_category	indoor_home, indoor_work, outdoor_leisure, outdoor_travel, transport, other
emotional_tone	positive, neutral, negative, mixed
cleanup_class	keep, review, delete
has_text	Whether image contains readable text
text_summary	Extracted text summary (if has_text)
event_hint	outing, gathering, work, travel, daily, other
significance	high, medium, low
gps_lat / gps_lon	EXIF GPS coordinates
nearest_place	Village/town/suburb
nearest_city	City
nearest_region	State/region
nearest_country	Country
processing_status	ok or error
error_message	Error details if any
phash	Perceptual hash (when --dedup used)

Judge output schema

Results from pyimgtag judge --output-json use a different structure:

Field	Description
file_path	Full path to image
file_name	Filename
weighted_score	Overall weighted score (integer 1–10)
core_score	Artistic criteria average (integer 1–10)
visible_score	Technical criteria average (integer 1–10)
verdict	One-sentence summary of key strength and weakness
scores.impact	Emotional pull and memorability (integer 1–10)
scores.story_subject	Clear subject and meaning (integer 1–10)
scores.composition_center	Visual flow, balance, center of interest (integer 1–10)
scores.lighting	Quality, control, mood support (integer 1–10)
scores.creativity_style	Originality of treatment (integer 1–10)
scores.color_mood	Color balance and mood fit (integer 1–10)
scores.presentation_crop	Crop, framing, aspect ratio (integer 1–10)
scores.technical_excellence	Exposure, retouching, overall finish (integer 1–10)
scores.focus_sharpness	Critical detail is sharp (integer 1–10)
scores.exposure_tonal	Highlights and shadows under control (integer 1–10)
scores.noise_cleanliness	Clean detail, no distracting grain (integer 1–10)
scores.subject_separation	Subject stands out from background (integer 1–10)
scores.edit_integrity	No halos, overprocessing, or clone artefacts (integer 1–10)

Architecture

src/pyimgtag/
  main.py              CLI entry point and subcommand dispatch (thin)
  models.py            Data classes (ExifData, TagResult, GeoResult, ImageResult)
  scanner.py           Directory and Photos library scanning
  exif_reader.py       EXIF GPS + date extraction (exiftool + Pillow)
  ollama_client.py     Ollama vision API client (rich structured response)
  geocoder.py          Nominatim reverse geocoder with disk cache
  filters.py           Date/GPS filter logic
  output_writer.py     JSON/CSV/JSONL output
  progress_db.py       SQLite progress DB with versioned migrations
  applescript_writer.py  Apple Photos keyword/description write-back
  dedup.py             Perceptual hash duplicate detection
  heic_converter.py    HEIC to JPEG conversion (macOS sips)
  cache.py             Simple JSON disk cache
  judge_scorer.py        Weighted rubric score computation (13-criterion)
  commands/
    run.py             `pyimgtag run` handler
    judge.py           `pyimgtag judge` handler
    db.py              `pyimgtag status/reprocess/cleanup` handlers
    query.py           `pyimgtag query` handler
    tags.py            `pyimgtag tags` handler
    faces.py           `pyimgtag faces` handler
    preflight_cmd.py   `pyimgtag preflight` handler
    review_cmd.py      `pyimgtag review` handler

Development

pip install -e ".[dev,lint,security]"

pytest tests/ -v
ruff format src/ tests/ && ruff check src/ tests/ --fix
python -m mypy src/pyimgtag/ --ignore-missing-imports --disable-error-code import-untyped
python -m bandit -r src/pyimgtag/ -c pyproject.toml
pre-commit install && pre-commit run --all-files

Resume and Enrichment

Rerunning pyimgtag run on an already-processed library normally skips unchanged files. With --resume-from-db, those files are re-hydrated from the database instead of being silently skipped, so their results still appear in output files and the --write-back path runs again.

Only local enrichment is repeated (EXIF, reverse geocoding). The AI model is not called again.

# Normal run — first pass, all files sent to Ollama
pyimgtag run --photos-library ~/Pictures/Photos\ Library.photoslibrary \
             --db ~/my-progress.db --write-back

# Resume after interruption — unchanged files load from DB, only new files hit Ollama
pyimgtag run --photos-library ~/Pictures/Photos\ Library.photoslibrary \
             --db ~/my-progress.db --write-back --resume-from-db

# Threaded resume — cached-item enrichment runs in a background thread
# while the main thread continues sending new files to Ollama
pyimgtag run --photos-library ~/Pictures/Photos\ Library.photoslibrary \
             --db ~/my-progress.db --write-back --resume-from-db --resume-threaded

A file is eligible for DB resume if:

• Its size and modification time have not changed since the last run.
• The cached entry has at least one tag.

Use pyimgtag reprocess --db ~/my-progress.db to force a full re-run for all files, or pyimgtag reprocess --db ~/my-progress.db --status error to retry only failed files.

Local webapp

pyimgtag run, pyimgtag judge, and pyimgtag faces scan auto-start a local webapp at http://127.0.0.1:8770 by default. The same app also hosts:

• /review — browse DB entries, edit tags, change cleanup class.
• /faces — manage person clusters, rename, merge, delete.

The standalone commands continue to work and serve the same unified app:

• pyimgtag review on http://127.0.0.1:8765 (review at /review).
• pyimgtag faces ui on http://127.0.0.1:8766 (faces at /faces).

Flags (apply to run, judge, faces scan):

• --no-web — terminal-only mode, no server started.
• --web — force-enable (overrides PYIMGTAG_NO_WEB=1).
• --web-host HOST — bind host (default 127.0.0.1).
• --web-port PORT — bind port (default 8770).
• --no-browser — do not auto-open the browser.

Environment variable:

• PYIMGTAG_NO_WEB=1 — disable the dashboard by default (same as --no-web).

Pause semantics are cooperative: the gate is checked before each file so in-flight Ollama / face-detection requests are never interrupted mid-call.

Migration note: the pyimgtag review and pyimgtag faces ui commands now serve the unified app, so the URL paths have shifted. Bookmarks that used http://localhost:8765/api/stats should be updated to http://localhost:8765/review/api/stats.

Contributing

See CONTRIBUTING.md.

Security

Found a vulnerability? Please follow the disclosure flow in SECURITY.md -- do not file a public issue.

License

MIT -- see LICENSE.