photo-tagger 0.1.0__tar.gz

photo_tagger-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: photo-tagger
+Version: 0.1.0
+Summary: CLI tool to describe photos and add keywords using AI
+Keywords: photo,tagging,cli,ai,exif,metadata,image recognition
+Author: Julio Batista Silva
+Author-email: Julio Batista Silva <python@juliobs.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Dist: cyclopts>=4.5.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: rawpy>=0.26.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-ai>=1.59.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pyexiftool>=0.5.6
+Requires-Dist: pillow>=12.1.1
+Requires-Python: >=3.14, <4
+Project-URL: Homepage, https://juliobs.com/projects/photo-tagger/
+Project-URL: Documentation, https://github.com/jbsilva/photo-tagger
+Project-URL: Repository, https://github.com/jbsilva/photo-tagger
+Project-URL: Issues, https://github.com/jbsilva/photo-tagger/issues
+Description-Content-Type: text/markdown
+
+# Photo Tagger
+
+Photo Tagger is a command-line helper that asks a vision-language model to analyze your photos and
+writes Lightroom-compatible metadata.
+
+By default it keeps your originals untouched by creating XMP sidecars, but you can embed the updates
+directly into each photo with `--embed-in-photo`.
+
+## Highlights
+
+- Works with RAW and standard image formats (CR3, CR2, NEF, JPG, PNG, and more)
+- Generates a title, a concise description, and hierarchical keywords
+- Merges with existing metadata unless you opt-in to overwrite
+- Supports Ollama and LM Studio compatible OpenAI APIs
+- Converts images to compact JPEG bytes to minimize token usage
+- Generates detailed log files for easy debugging and auditing
+- Highly configurable via CLI flags and environment variables
+
+## Requirements
+
+- Python 3.14+
+- [ExifTool](https://exiftool.org/) available on `PATH`
+- A running Ollama or LM Studio server exposing a vision-language model (for example Qwen-VL)
+- `libraw` support for `rawpy` (install via Homebrew on macOS: `brew install libraw`)
+
+## Installation
+
+For end-users, the recommended installation method is via
+[uv](https://docs.astral.sh/uv/guides/tools/):
+
+```bash
+uv tool install photo-tagger
+```
+
+For development (tests, linting):
+
+```bash
+uv sync --group dev --group test
+```
+
+## Configuration
+
+Environment variables provide defaults so you can keep the CLI concise:
+
+- `OLLAMA_BASE_URL` – override the Ollama HTTP endpoint (default `http://localhost:11434/v1`)
+- `OLLAMA_API_KEY` – optional API key passed to Ollama requests
+- `LM_STUDIO_BASE_URL` – override the LM Studio endpoint (default `http://localhost:1234/v1`)
+- `LM_STUDIO_API_KEY` / `OPENAI_API_KEY` – API key for LM Studio’s OpenAI-compatible server
+- `MODEL_NAME` – default model name (default `qwen3-vl:32b`)
+- `JPEG_DIMENSIONS`, `JPEG_QUALITY`, `TEMPERATURE`, `MAX_TOKENS`, `RETRIES` – fine-tune runtime
+
+Any CLI flag takes precedence over the environment.
+
+## Usage
+
+The CLI is exposed as `photo-tagger` once installed, or you can invoke it directly:
+
+```bash
+photo-tagger -i ./photos --ext cr3,jpg -r
+```
+
+Key options:
+
+- `-i/--input PATH` – repeatable; mix files and directories
+- `--ext` – comma-separated extension list used when scanning directories (default `cr3,jpg`)
+- `-r/--recursive` – recurse into subdirectories while scanning inputs
+- `-m/--model` – model identifier understood by your provider
+- `--provider` – `ollama` or `lmstudio` (defaults to `lmstudio`)
+- `--url` / `--api-key` – override provider endpoint and credentials
+- `--overwrite-keywords` – replace instead of merge existing keyword metadata
+- `--no-write-title` / `--no-write-description` – skip writing those fields
+- `--no-backup-xmp` – avoid creating `*_original` snapshot before writing
+- `--embed-in-photo` – write metadata directly into the image instead of creating an XMP sidecar
+- `--jpeg-dimensions`, `--jpeg-quality`, `--temperature`, `--max-tokens`, `--retries` – control
+  inference behavior
+
+A successful run creates or updates an `.xmp` sidecar for every processed image (unless you embed
+the metadata). Existing metadata is merged so Lightroom keeps hierarchical keywords such as
+`Animal|Bird|Osprey` intact.
+
+### Examples
+
+Process a folder of RAW and JPEG files recursively:
+
+```bash
+photo-tagger -i ~/Pictures/Portfolio --ext cr3,jpg -r
+```
+
+Tag a few explicit files and overwrite existing keywords:
+
+```bash
+photo-tagger \
+  -i IMG_0001.CR3 \
+  -i IMG_0002.CR3 \
+  --overwrite-keywords
+```
+
+Embed metadata directly into a set of JPEGs:
+
+```bash
+photo-tagger -i ./exports --ext jpg --embed-in-photo
+```
+
+Send requests to a remote Ollama host with a custom model:
+
+```bash
+photo-tagger -i ./shoot --provider ollama --model llava:34b --url http://ollama-box:11434/v1
+```
+
+## Logging
+
+Logs are written to stderr and to a timestamped file (for example `20260101...-photo_tagger.log`).
+Adjust levels with `--console-log-level` and `--file-log-level`, or disable either by setting the
+value to `OFF`.
+
+## Testing
+
+Run the unit tests with:
+
+```bash
+pytest
+```
+
+If you plan to contribute, also run `ruff check` for linting before opening a PR.

photo_tagger-0.1.0/README.md

@@ -0,0 +1,124 @@
+# Photo Tagger
+
+Photo Tagger is a command-line helper that asks a vision-language model to analyze your photos and
+writes Lightroom-compatible metadata.
+
+By default it keeps your originals untouched by creating XMP sidecars, but you can embed the updates
+directly into each photo with `--embed-in-photo`.
+
+## Highlights
+
+- Works with RAW and standard image formats (CR3, CR2, NEF, JPG, PNG, and more)
+- Generates a title, a concise description, and hierarchical keywords
+- Merges with existing metadata unless you opt-in to overwrite
+- Supports Ollama and LM Studio compatible OpenAI APIs
+- Converts images to compact JPEG bytes to minimize token usage
+- Generates detailed log files for easy debugging and auditing
+- Highly configurable via CLI flags and environment variables
+
+## Requirements
+
+- Python 3.14+
+- [ExifTool](https://exiftool.org/) available on `PATH`
+- A running Ollama or LM Studio server exposing a vision-language model (for example Qwen-VL)
+- `libraw` support for `rawpy` (install via Homebrew on macOS: `brew install libraw`)
+
+## Installation
+
+For end-users, the recommended installation method is via
+[uv](https://docs.astral.sh/uv/guides/tools/):
+
+```bash
+uv tool install photo-tagger
+```
+
+For development (tests, linting):
+
+```bash
+uv sync --group dev --group test
+```
+
+## Configuration
+
+Environment variables provide defaults so you can keep the CLI concise:
+
+- `OLLAMA_BASE_URL` – override the Ollama HTTP endpoint (default `http://localhost:11434/v1`)
+- `OLLAMA_API_KEY` – optional API key passed to Ollama requests
+- `LM_STUDIO_BASE_URL` – override the LM Studio endpoint (default `http://localhost:1234/v1`)
+- `LM_STUDIO_API_KEY` / `OPENAI_API_KEY` – API key for LM Studio’s OpenAI-compatible server
+- `MODEL_NAME` – default model name (default `qwen3-vl:32b`)
+- `JPEG_DIMENSIONS`, `JPEG_QUALITY`, `TEMPERATURE`, `MAX_TOKENS`, `RETRIES` – fine-tune runtime
+
+Any CLI flag takes precedence over the environment.
+
+## Usage
+
+The CLI is exposed as `photo-tagger` once installed, or you can invoke it directly:
+
+```bash
+photo-tagger -i ./photos --ext cr3,jpg -r
+```
+
+Key options:
+
+- `-i/--input PATH` – repeatable; mix files and directories
+- `--ext` – comma-separated extension list used when scanning directories (default `cr3,jpg`)
+- `-r/--recursive` – recurse into subdirectories while scanning inputs
+- `-m/--model` – model identifier understood by your provider
+- `--provider` – `ollama` or `lmstudio` (defaults to `lmstudio`)
+- `--url` / `--api-key` – override provider endpoint and credentials
+- `--overwrite-keywords` – replace instead of merge existing keyword metadata
+- `--no-write-title` / `--no-write-description` – skip writing those fields
+- `--no-backup-xmp` – avoid creating `*_original` snapshot before writing
+- `--embed-in-photo` – write metadata directly into the image instead of creating an XMP sidecar
+- `--jpeg-dimensions`, `--jpeg-quality`, `--temperature`, `--max-tokens`, `--retries` – control
+  inference behavior
+
+A successful run creates or updates an `.xmp` sidecar for every processed image (unless you embed
+the metadata). Existing metadata is merged so Lightroom keeps hierarchical keywords such as
+`Animal|Bird|Osprey` intact.
+
+### Examples
+
+Process a folder of RAW and JPEG files recursively:
+
+```bash
+photo-tagger -i ~/Pictures/Portfolio --ext cr3,jpg -r
+```
+
+Tag a few explicit files and overwrite existing keywords:
+
+```bash
+photo-tagger \
+  -i IMG_0001.CR3 \
+  -i IMG_0002.CR3 \
+  --overwrite-keywords
+```
+
+Embed metadata directly into a set of JPEGs:
+
+```bash
+photo-tagger -i ./exports --ext jpg --embed-in-photo
+```
+
+Send requests to a remote Ollama host with a custom model:
+
+```bash
+photo-tagger -i ./shoot --provider ollama --model llava:34b --url http://ollama-box:11434/v1
+```
+
+## Logging
+
+Logs are written to stderr and to a timestamped file (for example `20260101...-photo_tagger.log`).
+Adjust levels with `--console-log-level` and `--file-log-level`, or disable either by setting the
+value to `OFF`.
+
+## Testing
+
+Run the unit tests with:
+
+```bash
+pytest
+```
+
+If you plan to contribute, also run `ruff check` for linting before opening a PR.

photo_tagger-0.1.0/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "photo-tagger"
+version = "0.1.0"
+description = "CLI tool to describe photos and add keywords using AI"
+readme = "README.md"
+requires-python = ">=3.14,<4"
+authors = [{ name = "Julio Batista Silva", email = "python@juliobs.com" }]
+license = "MIT"
+keywords = [
+    "photo",
+    "tagging",
+    "cli",
+    "ai",
+    "exif",
+    "metadata",
+    "image recognition",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "cyclopts>=4.5.2",
+    "httpx>=0.28.1",
+    "rawpy>=0.26.1",
+    "pydantic>=2.12.5",
+    "pydantic-ai>=1.59.0",
+    "loguru>=0.7.3",
+    "pyexiftool>=0.5.6",
+    "pillow>=12.1.1",
+]
+
+[dependency-groups]
+dev = [
+    "bandit>=1.9.3",
+    "litellm>=1.81.12",
+    "ruff>=0.15.1",
+    "zuban>=0.5.1",
+]
+test = [
+    "inline-snapshot>=0.31.1",
+    "pytest-cov>=7.0.0",
+    "pytest-random-order>=1.2.0",
+    "pytest-xdist[psutil]>=3.8.0",
+    "pytest>=9.0.2",
+]
+
+[project.urls]
+Homepage = "https://juliobs.com/projects/photo-tagger/"
+Documentation = "https://github.com/jbsilva/photo-tagger"
+Repository = "https://github.com/jbsilva/photo-tagger"
+Issues = "https://github.com/jbsilva/photo-tagger/issues"
+
+[project.scripts]
+photo-tagger = "photo_tagger.main:app"
+
+[build-system]
+requires = ["uv_build >= 0.10.3"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+indent-width = 4
+target-version = "py314"
+fix = true
+unsafe-fixes = false
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D203", # one-blank-line-before-class
+    "D212", # multi-line-summary-first-line
+]
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/{test_*.py,conftest.py}" = [
+    "S101",   # Allow assert in tests
+    "S105",   # Allow hardcoded password in strings in tests
+    "S106",   # Allow hardcoded password in function calls in tests
+    "ARG001", # Allow unused arguments in tests (for pytest fixtures)
+]
+"**/__init__.py" = [
+    "D104", # Allow empty __init__.py files
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+force-wrap-aliases = true
+lines-after-imports = 2
+
+[tool.zuban]
+strict = true
+disallow_untyped_defs = true
+warn_unreachable = true
+python_executable = ".venv/bin/python"
+
+[tool.bandit]
+exclude_dirs = [".git", ".venv", "__pycache__", "tests"]
+
+[tool.bandit.assert_used]
+skips = ['tests/test_*.py']
+
+[tool.pytest.ini_options]
+addopts = [
+    "-ra",
+    "--durations=10",
+    "--import-mode=importlib",
+    "--random-order",
+    "--numprocesses=logical",
+    "--dist=load",
+    "--tb=short",
+    "--verbose",
+    "--cov=src/photo_tagger",
+    "--cov-report=term-missing",
+    "-m",
+    "not integration",
+]
+markers = [
+    "integration: marks tests as integration tests (deselect with '-m \"not integration\"')",
+]