photools3/AGENTS.md

Agent Instructions: PhotoTools3

Environment Setup

Requires a .env file with the following variables:

• llm_api_key: API key for the LLM provider.
• llm_api_base_url: Base URL for the LLM API.
• llm_default_temperature: Float value for temperature.

System Dependencies

• exiftool binary: required by pyexiftool at runtime, not installable via pip/uv.
  • Arch: perl-image-exiftool
  • Debian/Ubuntu: libimage-exiftool-perl

Development Toolchain

• Dependency Management: Use uv.
• Python Version: Requires Python >=3.14.
• Testing: Run pytest to execute the test suite in test/.
• Linting & Formatting: Use ruff and black.

CLI Usage

The primary entry point is the photools3 command:

• photools3 keywords <image_path>: Extracts keywords and captions from a single image.

Architecture & Logic

• src/photools3/photo.py: Core image processing logic, including resizing, RGB conversion, and generating base64 JPEG encodings specifically for LLM vision compatibility.
• src/photools3/llm_session.py: Manages the workflow of sending processed images to the LLM and parsing results.
• Configuration: The list of keywords to extract is maintained in config/keywords.txt.