E2e workflow (#21)

Reviewed-on: #21
Co-authored-by: Mathias Scheider <mathias2784@web.de>

.env.template

@@ -1,3 +1,10 @@
 LLM_API_BASE_URL = "http://localhost:1234/v1"
 LLM_API_KEY = "not-relevant"
 LLM_DEFAULT_TEMPERATURE = 1.0
+
+METADATA_PREFIX = "photools|"
+LOG_LEVEL=INFO
+LLM_REQUEST_TIMEOUT_SECONDS=10
+LLM_MAX_COMPLETION_TOKENS=1024
+LLM_MAX_RETRIES=5
+LLM_MAX_KEYWORDS=15

.gitea/workflows/ci.yml

@@ -18,9 +18,20 @@ jobs:
         run: uv sync --frozen
       - name: copy env
         run: cp .env.template .env
+      - name: Install exiftool (system dependency)
+        run: |
+          if command -v exiftool >/dev/null 2>&1; then
+            echo "exiftool already installed"
+          elif command -v sudo >/dev/null 2>&1; then
+            sudo apt-get update && sudo apt-get install -y --no-install-recommends libimage-exiftool-perl
+          else
+            apt-get update && apt-get install -y --no-install-recommends libimage-exiftool-perl
+          fi
       - name: Run pytest
         run: uv run pytest .
-      - name: Check formatting (black)
-        run: uv run black --check . --extend-exclude .venv
       - name: Lint (ruff)
         run: uv run ruff check .
+      - name: Typing (mypy)
+        run: uv run mypy .
+      - name: Check formatting (black)
+        run: uv run black --check . --extend-exclude .venv

AGENTS.md

@@ -1,22 +1,42 @@
 # 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`.
+
+## Code style
+
+- Avoid overly verbose docstrings or comments. Be precise!
+
+## Comunication
+
+- When done with code modifications, give a one-liner for the currently unstaged changes that can be used as a commit message.

README.md

@@ -0,0 +1,101 @@
+# 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=http://localhost:1234/v1
+llm_api_key=your-api-key
+llm_default_temperature=0.2
+metadata_prefix=photools3:
+LOG_LEVEL=DEBUG
+LLM_REQUEST_TIMEOUT_SECONDS=10
+LLM_MAX_COMPLETION_TOKENS=1024
+LLM_MAX_RETRIES=5
+LLM_MAX_KEYWORDS=15
+```
+
+Keyword suggestions are restricted to the vocabulary in `config/keywords.txt`.
+`LOG_LEVEL=DEBUG` enables detailed per-request and per-photo timings.
+`LLM_MAX_RETRIES` controls retries for malformed or structurally invalid
+responses; `5` means up to 6 requests for a photo. A valid response with
+unsupported keywords gets at most one targeted correction retry, then remaining
+invalid keywords are discarded.
+Each request is limited by `LLM_REQUEST_TIMEOUT_SECONDS`; a timeout reloads the
+LM Studio model before retrying. `LLM_MAX_COMPLETION_TOKENS` caps the generated
+response length. When all retries are exhausted, the model is reloaded before
+the failed photo is reported. `LLM_MAX_KEYWORDS` sets the maximum number of
+distinct keywords requested and stored per photo; excess keywords are discarded.
+
+## 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
+```

pyproject.toml

@@ -9,14 +9,16 @@ authors = [
 requires-python = ">=3.14"
 dependencies = [
     "black>=26.5.1",
+    "mypy>=2.4.0",
     "openai>=3.22.0",
     "pillow>=12.3.0",
     "pydantic>=2.13.5",
     "pydantic-settings>=2.15.0",
+    "pyexiftool>=0.5.6",
     "pytest>=9.1.1",
     "ruff>=0.16.9",
     "typer>=0.12.0",
-    "utils>=0.1.2",
+    "utils>=0.1.3",
 ]
 
 [project.scripts]
@@ -29,6 +31,13 @@ build-backend = "uv_build"
 [tool.uv.sources]
 utils = { index = "gitea" }
 
+[tool.black]
+target-version = [ "py314" ]
+
+[[tool.mypy.overrides]]
+module = ["exiftool", "exiftool.*", "utils", "utils.*"]
+ignore_missing_imports = true
+
 [[tool.uv.index]]
 name = "gitea"
 url = "https://gitea.schneiderserver.site/api/packages/mathias2784/pypi/simple"

src/photools3/cli.py

@@ -3,16 +3,30 @@ from pathlib import Path
 from typing import Annotated
 
 import typer
+from PIL import Image
 from utils.logging_config import LoggingSettings
 
-from photools3.llm_session import (
+from photools3.llm_session import LlmSessionQuality
-    LlmSessionCaptionsAndKeywords,
-    LlmSessionQuality,
-)
 from photools3.photo import Photo
+from photools3.processing import (
+    ProcessingMode,
+    process_batch,
+    process_photo,
+)
+from photools3.settings import settings
 
 app = typer.Typer(help="PhotoTools3: A CLI for image processing.")
-LoggingSettings()
+LoggingSettings(LOG_LEVEL=settings.log_level)
+for name in (
+    "uvicorn",
+    "uvicorn.error",
+    "uvicorn.access",
+    "PIL",
+    "openai",
+    "httpx2",
+    "httpcore2",
+):
+    logging.getLogger(name).setLevel(logging.WARNING)
 logger = logging.getLogger(__name__)
 
 
@@ -21,9 +35,7 @@ def main(
     ctx: typer.Context,
     version: bool | None = typer.Option(None, "--version", is_eager=True),
 ):
-    """
+    """Main entry point for PhotoTools3 CLI."""
-    Main entry point for PhotoTools3 CLI.
-    """
     if version:
         typer.echo("photools3 version 0.1.0")
         raise typer.Exit()
@@ -33,36 +45,118 @@ def main(
         raise typer.Exit()
 
 
-@app.command("keywords")
+@app.command("metadata-magic")
-def keywords(
+def metadata_magic(
-    file_path: Annotated[Path, typer.Argument(..., help="Path to the image file")],
+    paths: Annotated[
+        list[Path], typer.Argument(..., help="Photo file(s) and/or directory paths")
+    ],
+    mode: Annotated[
+        ProcessingMode,
+        typer.Option(
+            "--mode",
+            case_sensitive=False,
+            help="Metadata to generate and write",
+        ),
+    ] = ProcessingMode.BOTH,
+    recursive: Annotated[
+        bool,
+        typer.Option(
+            "--recursive/--no-recursive",
+            help="Recursively discover photos inside input directories",
+        ),
+    ] = False,
 ):
-    session = LlmSessionCaptionsAndKeywords()
+    """Generate and write keywords, captions, or both for photos."""
-    _run_llm_task(file_path, session)
+    _run_processing(paths, mode, recursive)
 
 
 @app.command("quality")
 def quality(
     file_path: Annotated[Path, typer.Argument(..., help="Path to the image file")],
 ):
-    session = LlmSessionQuality()
+    """Assess a photo's quality without changing its metadata."""
-    _run_llm_task(file_path, session)
-
-
-def _run_llm_task(
-    file_path: Path, session: LlmSessionCaptionsAndKeywords | LlmSessionQuality
-):
     try:
-        logger.info(f"Processing: {file_path}")
+        with LlmSessionQuality() as session, Photo(file_path) as photo:
-        photo = Photo(file_path)
+            result = session.call([photo])
-        result = session.call([photo])
+        logger.info("Quality assessment for %s: %s", file_path, result)
-        logger.info(result)
     except FileNotFoundError:
-        logger.error(f"Error: File '{file_path}' does not exist.")
+        logger.error("Photo not found: %s", file_path)
+        raise typer.Exit(code=1) from None
+    except Exception as exc:
+        logger.error("Error assessing photo %s: %s", file_path, exc)
+        raise typer.Exit(code=1) from exc
+
+
+def _run_processing(inputs: list[Path], mode: ProcessingMode, recursive: bool) -> None:
+    photo_paths = _expand_photo_paths(inputs, recursive)
+    if not photo_paths:
+        logger.error("No supported photo files found in the given input paths.")
         raise typer.Exit(code=1)
-    except Exception as e:  # noqa: BLE001
+
+    logger.info("Processing %d photo(s) in %s mode", len(photo_paths), mode.value)
+    if len(photo_paths) == 1:
+        path = photo_paths[0]
+        try:
+            process_photo(path, mode)
+        except FileNotFoundError:
+            logger.error("Photo not found: %s", path)
+            raise typer.Exit(code=1) from None
+        except Exception as exc:
+            logger.error("Failed to process %s: %s", path, exc)
+            raise typer.Exit(code=1) from exc
+        logger.info("Processed: %s", path)
+        return
+
+    try:
+        outcomes = process_batch(photo_paths, mode)
+    except Exception as exc:
+        logger.error("Batch processing failed: %s", exc)
+        raise typer.Exit(code=1) from exc
+
+    failures = 0
+    for outcome in outcomes:
+        if outcome.succeeded:
+            logger.info("Processed: %s", outcome.path)
+        else:
+            failures += 1
+            logger.error("Failed to process %s: %s", outcome.path, outcome.error)
+
+    logger.info(
+        "Batch complete: %d succeeded, %d failed", len(outcomes) - failures, failures
+    )
+    if failures:
         raise typer.Exit(code=1)
-        logger.error(f"Error processing image: {e}")
+
+
+def _expand_photo_paths(inputs: list[Path], recursive: bool) -> list[Path]:
+    """Expand directories to supported image files, preserving input order."""
+    supported_extensions = {
+        ".dng",
+        *(extension.lower() for extension in Image.registered_extensions()),
+    }
+    discovered: list[Path] = []
+
+    for path in inputs:
+        if not path.is_dir():
+            discovered.append(path)
+            continue
+
+        try:
+            candidates = path.rglob("*") if recursive else path.iterdir()
+            discovered.extend(
+                sorted(
+                    candidate
+                    for candidate in candidates
+                    if candidate.is_file()
+                    and candidate.suffix.lower() in supported_extensions
+                )
+            )
+        except OSError as exc:
+            logger.error("Could not read directory %s: %s", path, exc)
+            raise typer.Exit(code=1) from exc
+
+    # Avoid processing the same exact path more than once while retaining order.
+    return list(dict.fromkeys(discovered))
 
 
 if __name__ == "__main__":

src/photools3/llm_session.py

@@ -1,38 +1,69 @@
 import json
 import logging
 import re
+import time
 
 import openai
 from openai import OpenAI
-from pydantic import ValidationError
+from pydantic import BaseModel, ValidationError
 
+from photools3.lm_studio import LMStudioModelManager
 from photools3.models import (
     LlmMessageContent,
     LlmMessageRole,
     LlmMessageType,
     LlmRequest,
     LlmRequestMessage,
+    LlmResponseCaption,
     LlmResponseCaptionsAndKeywords,
     LlmResponseGeneral,
+    LlmResponseKeywords,
     LlmResponseQuality,
+    load_valid_keywords,
 )
 from photools3.photo import Photo
-from photools3.settings import Settings
+from photools3.settings import settings
 
 logger = logging.getLogger(__name__)
 
-settings = Settings()  # type: ignore[reportCallIssue]
+
+def _clean_llm_response(txt: str):
+    # remove ```json ... ``` wrap
+    txt = re.sub(r"^```json(.*)```$", r"\1", txt, flags=re.DOTALL).strip()
+    return txt
+
+
+def _correction_prompt(instruction: str) -> LlmRequestMessage:
+    return LlmRequestMessage(
+        role=LlmMessageRole.user,
+        content=instruction,
+    )
+
+
+def _request_with_correction(base_request: LlmRequest, instruction: str) -> LlmRequest:
+    return base_request.model_copy(
+        update={"messages": [*base_request.messages, _correction_prompt(instruction)]}
+    )
+
+
+def _validation_summary(exception: ValidationError) -> str:
+    return "; ".join(
+        f"{'.'.join(map(str, error['loc']))}: {error['msg']}"
+        for error in exception.errors(include_input=False)
+    )
 
 
 class LlmSession:
     base_url: str = str(settings.llm_api_base_url)
     api_key: str = settings.llm_api_key
-    response_model = LlmResponseGeneral
+    response_model: type[BaseModel] = LlmResponseGeneral
+    prompt: str = ""
 
     def __init__(
         self, system_prompt: str, temperature: float = settings.llm_default_temperature
     ):
         self._models: list = []
+        self._model_id: str | None = None
 
         self.system_prompt = system_prompt
         self.temperature = temperature
@@ -40,10 +71,30 @@ class LlmSession:
         self.client = OpenAI(
             base_url=self.base_url,
             api_key=self.api_key,
+            max_retries=0,
         )
+        self._model_manager = LMStudioModelManager(self.base_url, self.api_key)
+
+    def close(self):
+        self.client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
+    def flush_model(self):
+        """Unload and reload this session's model through LM Studio."""
+        if self._model_id is None:
+            self._model_id = self.models[0].id
+        self._model_manager.reload_model(self._model_id)
 
     def client_chat_completion_create(self, request: LlmRequest, choice_no: int = 0):
-        response = self.client.chat.completions.create(**request.model_dump())
+        response = self.client.chat.completions.create(
+            **request.model_dump(),
+            timeout=settings.llm_request_timeout_seconds,
+        )
         return response.choices[choice_no].message.content
 
     def is_api_reachable(self) -> bool:
@@ -61,52 +112,141 @@ class LlmSession:
 
     def call(
         self,
-        prompt: str,
         photos: list[Photo],
         model_id=None,
-        max_retries: int = 2,
+        max_retries: int | None = None,
+        prompt: str | None = None,
     ):
-        if not model_id:
+        retry_limit = settings.llm_max_retries if max_retries is None else max_retries
-            model_id = self.models[0].id
+        if retry_limit < 0:
+            raise ValueError("max_retries must be greater than or equal to zero")
 
-        request = self._build_request(prompt, photos, model_id)
+        if model_id is None:
+            if self._model_id is None:
+                self._model_id = self.models[0].id
+            model_id = self._model_id
+        else:
+            self._model_id = model_id
 
-        last_error = None
+        base_request = self._build_request(prompt or self.prompt, photos, model_id)
-        for attempt in range(max_retries + 1):
+        request = base_request
+        tag_correction_used = False
+        valid_keywords = load_valid_keywords()
+        max_keywords = settings.llm_max_keywords
+
+        for attempt in range(retry_limit + 1):
+            request_started = time.perf_counter()
             try:
                 result_raw = self.client_chat_completion_create(request)
-                # Clean the response (strip markdown code blocks if present)
+            except openai.APITimeoutError as exc:
-                json_str = re.sub(
+                logger.warning(
-                    r"^```json(.*)```$", r"\1", result_raw, flags=re.DOTALL
+                    "LLM request timed out after %.2f seconds; reloading model",
-                ).strip()
+                    time.perf_counter() - request_started,
+                )
+                self.flush_model()
+                if attempt < retry_limit:
+                    continue
+                raise ValueError(
+                    f"LLM request timed out after {retry_limit + 1} attempts"
+                ) from exc
+            except Exception:
+                logger.debug(
+                    "LLM request attempt %d/%d failed after %.2f seconds",
+                    attempt + 1,
+                    retry_limit + 1,
+                    time.perf_counter() - request_started,
+                )
+                raise
 
-                # Parse and validate against the class-level response_model
+            logger.debug(
-                return self.response_model.model_validate_json(json_str)
+                "LLM request attempt %d/%d completed in %.2f seconds",
-
+                attempt + 1,
-            except (json.JSONDecodeError, ValidationError) as e:
+                retry_limit + 1,
-                last_error = e
+                time.perf_counter() - request_started,
-                if attempt < max_retries:
+            )
-                    logger.info("Chatbot response is invalid; promting to correct ...")
+            try:
-                    # Prepare a correction prompt
+                response_data = json.loads(_clean_llm_response(result_raw))
-                    correction_prompt = (
+            except (json.JSONDecodeError, TypeError) as exc:
-                        f"The previous response was invalid due to: {e}. "
+                if attempt < retry_limit:
-                        f"Please provide the corrected JSON based on this content: "
+                    logger.info("Chatbot response was not valid JSON; retrying")
-                        f"{json_str if 'json_str' in locals() else 'the original input'}"
+                    request = _request_with_correction(
-                    )
+                        base_request,
-                    # Append correction prompt as a new user message for the next attempt
+                        "Return one complete JSON object matching the schema. "
-                    request.messages.append(
+                        f"The previous response was invalid: {exc}",
-                        LlmRequestMessage(
-                            role=LlmMessageRole.user,
-                            content=correction_prompt,
-                        )
                     )
                     continue
-                else:
+
-                    raise ValueError(
+                logger.warning(
-                        f"Failed to parse or validate LLM response after {max_retries} retries: {e}"
+                    "LLM retry limit reached; reloading model before failing"
+                )
+                self.flush_model()
+                raise ValueError(
+                    f"Failed to parse LLM response after {retry_limit} retries: {exc}"
+                ) from exc
+
+            if (
+                isinstance(response_data, dict)
+                and "tags" in self.response_model.model_fields
+                and isinstance(response_data.get("tags"), list)
+            ):
+                tags = response_data["tags"]
+                considered_tags = tags[:max_keywords]
+                invalid_tags = [
+                    tag
+                    for tag in considered_tags
+                    if not isinstance(tag, str) or tag not in valid_keywords
+                ]
+
+                if invalid_tags and not tag_correction_used and attempt < retry_limit:
+                    tag_correction_used = True
+                    logger.info(
+                        "LLM returned unsupported keywords; requesting one correction"
                     )
-            except Exception:
+                    request = _request_with_correction(
-                raise
+                        base_request,
+                        f"These keywords are not allowed: {invalid_tags!r}. "
+                        "Replace them with exact allowed keywords when sensible; "
+                        f"otherwise omit them. Return at most {max_keywords} "
+                        "distinct keywords and do not list the vocabulary.",
+                    )
+                    continue
+
+                if len(tags) > max_keywords:
+                    logger.info(
+                        "Discarding keywords beyond configured limit of %d",
+                        max_keywords,
+                    )
+                if invalid_tags:
+                    logger.warning("Discarding unsupported keywords: %s", invalid_tags)
+
+                response_data = dict(response_data)
+                valid_tags = [
+                    tag
+                    for tag in tags
+                    if isinstance(tag, str) and tag in valid_keywords
+                ]
+                response_data["tags"] = list(dict.fromkeys(valid_tags))[:max_keywords]
+
+            try:
+                return self.response_model.model_validate(response_data)
+            except ValidationError as exc:
+                if attempt < retry_limit:
+                    logger.info("LLM response did not match the schema; retrying")
+                    request = _request_with_correction(
+                        base_request,
+                        "Return one complete JSON object matching the schema. "
+                        f"Validation issues: {_validation_summary(exc)}",
+                    )
+                    continue
+
+                logger.warning(
+                    "LLM retry limit reached; reloading model before failing"
+                )
+                self.flush_model()
+                raise ValueError(
+                    f"Failed to validate LLM response after {retry_limit} retries: "
+                    f"{_validation_summary(exc)}"
+                ) from exc
 
     def _build_request(
         self,
@@ -118,6 +258,7 @@ class LlmSession:
         return LlmRequest(
             model=model_id,
             temperature=self.temperature,
+            max_tokens=settings.llm_max_completion_tokens,
             messages=[
                 # System prompt
                 LlmRequestMessage(
@@ -149,28 +290,59 @@ class LlmSession:
 
 class LlmSessionCaptionsAndKeywords(LlmSession):
     response_model = LlmResponseCaptionsAndKeywords
+    prompt = "Give me a caption and keywords for the following photo"
 
     def __init__(self, temperature: float = settings.llm_default_temperature):
         super().__init__(
             system_prompt=(
                 "You are a helpful photographer's assistant that helps to write **captions** and **keywords** to photos:\n"
                 "Answer in German.\n"
+                f"Choose at most {settings.llm_max_keywords} distinct, relevant keywords. "
+                "Do not repeat or enumerate the allowed-keyword list.\n"
                 "Output must be a JSON of the following schema:\n"
                 f"{self.response_model.model_json_schema()}"
             ),
             temperature=temperature,
         )
 
-    def call(self, photos: list[Photo], model_id=None):
+
-        return super().call(
+class LlmSessionCaption(LlmSession):
-            prompt="Give me a caption and keyword for the following photo(s)",
+    response_model = LlmResponseCaption
-            photos=photos,
+    prompt = "Write a caption for the following photo"
-            model_id=model_id,
+
+    def __init__(self, temperature: float = settings.llm_default_temperature):
+        super().__init__(
+            system_prompt=(
+                "You are a helpful photographer's assistant that writes captions "
+                "for photos. Answer in German.\n"
+                "Output must be a JSON of the following schema:\n"
+                f"{self.response_model.model_json_schema()}"
+            ),
+            temperature=temperature,
+        )
+
+
+class LlmSessionKeywords(LlmSession):
+    response_model = LlmResponseKeywords
+    prompt = "Choose appropriate keywords for the following photo"
+
+    def __init__(self, temperature: float = settings.llm_default_temperature):
+        super().__init__(
+            system_prompt=(
+                "You are a helpful photographer's assistant that chooses keywords "
+                "for photos. Answer in German.\n"
+                f"Choose at most {settings.llm_max_keywords} distinct, relevant keywords. "
+                "Do not repeat or enumerate the allowed-keyword list.\n"
+                "Output must be a JSON of the following schema:\n"
+                f"{self.response_model.model_json_schema()}"
+            ),
+            temperature=temperature,
         )
 
 
 class LlmSessionQuality(LlmSession):
     response_model = LlmResponseQuality
+    prompt = "Assess the quality of the following photos to help me decide which ones to sort out"
 
     def __init__(self, temperature: float = settings.llm_default_temperature):
         super().__init__(
@@ -182,10 +354,3 @@ class LlmSessionQuality(LlmSession):
             ),
             temperature=temperature,
         )
-
-    def call(self, photos: list[Photo], model_id=None):
-        return super().call(
-            prompt="Assess the quality of the following photos to help me decide which ones to sort out",
-            photos=photos,
-            model_id=model_id,
-        )

src/photools3/lm_studio.py

@@ -0,0 +1,135 @@
+import json
+import logging
+import time
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit, urlunsplit
+from urllib.request import Request, urlopen
+
+logger = logging.getLogger(__name__)
+
+_LOAD_CONFIG_KEYS = (
+    "context_length",
+    "eval_batch_size",
+    "flash_attention",
+    "num_experts",
+    "offload_kv_cache_to_gpu",
+)
+
+
+class LMStudioError(RuntimeError):
+    """Raised when LM Studio model management fails."""
+
+
+class LMStudioModelManager:
+    """Unload and reload a model through LM Studio's native REST API."""
+
+    def __init__(self, openai_base_url: str, api_key: str, timeout: float = 600):
+        parsed_url = urlsplit(openai_base_url)
+        path = parsed_url.path.rstrip("/")
+        path = path.removesuffix("/v1")
+        root_url = urlunsplit(
+            (parsed_url.scheme, parsed_url.netloc, path, "", "")
+        ).rstrip("/")
+        self.api_base_url = f"{root_url}/api/v1"
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def reload_model(self, model_id: str) -> None:
+        """Unload the matching loaded instance and reload it with its config."""
+        started = time.perf_counter()
+        models_response = self._request("GET", "/models")
+        model, loaded_instance = self._find_model(models_response, model_id)
+        model_key = model["key"]
+
+        if loaded_instance is not None:
+            self._request(
+                "POST",
+                "/models/unload",
+                {"instance_id": loaded_instance["id"]},
+            )
+            load_config = loaded_instance.get("config", {})
+        else:
+            load_config = {}
+
+        load_body = {"model": model_key}
+        load_body.update(
+            {
+                key: load_config[key]
+                for key in _LOAD_CONFIG_KEYS
+                if key in load_config and load_config[key] is not None
+            }
+        )
+        self._request("POST", "/models/load", load_body)
+        logger.info(
+            "Reloaded LM Studio model %s in %.1f seconds",
+            model_key,
+            time.perf_counter() - started,
+        )
+
+    @staticmethod
+    def _find_model(models_response: dict, model_id: str) -> tuple[dict, dict | None]:
+        models = models_response.get("models")
+        if not isinstance(models, list):
+            raise LMStudioError("LM Studio model list response has no models array")
+
+        for model in models:
+            loaded_instances = model.get("loaded_instances", [])
+            for instance in loaded_instances:
+                if instance.get("id") == model_id:
+                    return model, instance
+
+        matching_models = [model for model in models if model.get("key") == model_id]
+        if len(matching_models) != 1:
+            raise LMStudioError(
+                f"Could not uniquely identify LM Studio model {model_id!r}"
+            )
+
+        model = matching_models[0]
+        loaded_instances = model.get("loaded_instances", [])
+        if len(loaded_instances) > 1:
+            raise LMStudioError(
+                f"Multiple loaded instances found for LM Studio model {model_id!r}"
+            )
+        loaded_instance = loaded_instances[0] if loaded_instances else None
+        return model, loaded_instance
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> dict:
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        headers = {"Accept": "application/json"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        request = Request(
+            f"{self.api_base_url}{path}",
+            data=data,
+            headers=headers,
+            method=method,
+        )
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                response_body = response.read()
+        except HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")
+            raise LMStudioError(
+                f"LM Studio {method} {path} returned HTTP {exc.code}: {detail}"
+            ) from exc
+        except (URLError, TimeoutError) as exc:
+            raise LMStudioError(
+                f"Could not reach LM Studio at {self.api_base_url}: {exc}"
+            ) from exc
+
+        if not response_body:
+            return {}
+        try:
+            result = json.loads(response_body)
+        except json.JSONDecodeError as exc:
+            raise LMStudioError(
+                f"LM Studio {method} {path} returned invalid JSON"
+            ) from exc
+        if not isinstance(result, dict):
+            raise LMStudioError(
+                f"LM Studio {method} {path} returned an unexpected response"
+            )
+        return result

src/photools3/metadata_writer.py

@@ -0,0 +1,180 @@
+import logging
+import shutil
+from pathlib import Path
+from typing import Annotated, Any
+
+import exiftool
+from pydantic import StringConstraints
+
+from photools3.settings import settings
+
+log = logging.getLogger(__name__)
+
+_EXIFTOOL_MISSING_MSG = (
+    "exiftool binary not found in PATH. "
+    "Install the system package: 'perl-image-exiftool' (Arch) or 'libimage-exiftool-perl' (Debian/Ubuntu)."
+)
+if shutil.which("exiftool") is None:
+    raise FileNotFoundError(_EXIFTOOL_MISSING_MSG)
+
+XmpKey = Annotated[str, StringConstraints(pattern=r"^\w+\:\w+")]
+
+type Caption = str
+type Keywords = list[str]
+type Color = int
+type XmpMetadata = dict[str, Any]
+
+XMP_KEYS_CAPTION: list[XmpKey] = [
+    "XMP:Description",
+    "EXIF:ImageDescription",
+    "IPTC:Caption-Abstract",
+]
+
+XMP_KEYS_KEYWORDS: list[XmpKey] = [
+    "XMP:HierarchicalSubject",
+    "XMP:Subject",
+    "IPTC:Keywords",
+]
+
+
+def _prefixed(txt: str) -> str:
+    return f"{settings.metadata_prefix}{txt}"
+
+
+def _is_prefixed(txt: str) -> bool:
+    return txt.startswith(settings.metadata_prefix)
+
+
+def _separate_prefixed_caption(txt: str) -> tuple[str, str | None]:
+    separated = [x.strip() for x in txt.split(settings.metadata_prefix)]
+    return (separated[0], separated[1] if len(separated) > 1 else None)
+
+
+class MetadataWriter:
+    """
+    Write metadata (captions and keywords) to image files.
+    For DNG files, creates/updates XMP sidecar files.
+    """
+
+    def __init__(
+        self,
+        path: Path,
+        force_sidecar: bool = False,
+        append: bool = True,
+    ):
+        self.path: Path = path
+        self.force_sidecar: bool = force_sidecar
+        self.append: bool = append
+
+        self._metadata: XmpMetadata | None = None
+
+    @property
+    def sidecar_path(self) -> Path:
+        return Path(str(self.path) + ".xmp")
+
+    @property
+    def metadata(self) -> Any:
+        path = self.sidecar_path if self.sidecar_path.exists() else self.path
+        if not path.exists():
+            log.warning(f"File not found: {path}")
+            return None
+        try:
+            with exiftool.ExifToolHelper() as exif:
+                metadata = exif.get_metadata([path])[0]
+        except Exception as exc:  # noqa: BLE001
+            log.error(f"Could not read metadata from {path}: {exc}")
+            return None
+        return metadata
+
+    def get_caption(self) -> str:
+        result = (self.metadata or {}).get(XMP_KEYS_CAPTION[0], "")
+        assert isinstance(result, str)
+        return result
+
+    def get_keywords(self) -> list[str]:
+        result = (self.metadata or {}).get(XMP_KEYS_KEYWORDS[0], []) or []
+        if isinstance(result, str):
+            result = [result]
+        assert isinstance(result, list)
+        return result
+
+    def set_metadata(self, metadata_tags: dict[str, Any]):
+        try:
+            with exiftool.ExifToolHelper() as exif:
+                if not self.sidecar_path.exists():
+                    exif.execute("-o", str(self.sidecar_path), str(self.path))
+                exif.set_tags(
+                    [str(self.sidecar_path)],
+                    tags=metadata_tags,
+                    params=["-overwrite_original"],
+                )
+        except Exception as exc:
+            log.error(f"Could not write metadata to file {self.sidecar_path}: {exc}")
+            raise RuntimeError(
+                f"Could not write metadata to file {self.sidecar_path}"
+            ) from exc
+
+    def write_caption(
+        self, caption: Caption, include_prefix: bool = True, override: bool = True
+    ):
+        existing_no_prefix, existing_prefix = _separate_prefixed_caption(
+            self.get_caption()
+        )
+        if existing_no_prefix:
+            existing_no_prefix = (
+                f"{existing_no_prefix}."
+                if not existing_no_prefix.endswith(".")
+                else existing_no_prefix
+            )
+            existing_no_prefix = f"{existing_no_prefix} "
+
+        if include_prefix and existing_prefix and not override:
+            return
+        if not include_prefix and existing_no_prefix and not override:
+            return
+        if include_prefix:
+            caption = f"{existing_no_prefix}{_prefixed(caption)}"
+        metadata_tags = {key: caption for key in XMP_KEYS_CAPTION}
+        self.set_metadata(metadata_tags)
+
+    def write_keywords(self, keywords: Keywords, include_prefix: bool = True):
+        if include_prefix:
+            keywords = list(map(_prefixed, keywords))
+        existing = self.get_keywords()
+        keywords = list(set(existing + keywords))
+        metadata_tags = {tag: keywords for tag in XMP_KEYS_KEYWORDS}
+        self.set_metadata(metadata_tags)
+
+    def write_color(self, color: Color):
+        self.set_metadata({"XMP-darktable:Colorlabels": color})
+
+    def write(
+        self,
+        caption: Caption | None = None,
+        keywords: Keywords | None = None,
+        color: Color | None = None,
+    ):
+        metadata_tags: XmpMetadata = {}
+        if caption is not None:
+            existing_no_prefix, _ = _separate_prefixed_caption(self.get_caption())
+            if existing_no_prefix:
+                existing_no_prefix = (
+                    f"{existing_no_prefix}."
+                    if not existing_no_prefix.endswith(".")
+                    else existing_no_prefix
+                )
+                existing_no_prefix = f"{existing_no_prefix} "
+            caption = f"{existing_no_prefix}{_prefixed(caption)}"
+            metadata_tags.update({key: caption for key in XMP_KEYS_CAPTION})
+
+        if keywords is not None:
+            keywords = list(map(_prefixed, keywords))
+            existing = self.get_keywords()
+            keywords = list(set(existing + keywords))
+            metadata_tags.update({tag: keywords for tag in XMP_KEYS_KEYWORDS})
+
+        if color is not None:
+            metadata_tags["XMP-darktable:Colorlabels"] = color
+
+        if metadata_tags:
+            self.set_metadata(metadata_tags)

src/photools3/models.py

@@ -1,3 +1,4 @@
+import json
 from enum import StrEnum
 from functools import lru_cache
 from typing import Annotated, Any, Literal
@@ -10,7 +11,7 @@ from pydantic import (
     model_validator,
 )
 
-from .settings import KEYWORDS_LIST_PATH
+from .settings import KEYWORDS_LIST_PATH, settings
 
 
 @lru_cache
@@ -42,6 +43,7 @@ class LlmRequest(BaseModel):
     model: str = "gpt-4o"
     messages: list[LlmRequestMessage]
     temperature: float | None = None
+    max_tokens: int
 
 
 class LlmMessageRole(StrEnum):
@@ -86,7 +88,7 @@ class LlmResponseGeneral(BaseModel):
     text: str
 
 
-class LlmResponseCaptionsAndKeywords(BaseModel):
+class LlmResponseCaption(BaseModel):
     caption: Annotated[
         str,
         Field(
@@ -96,16 +98,24 @@ class LlmResponseCaptionsAndKeywords(BaseModel):
             )
         ),
     ]
-    tags: list[str] = Field(
+
-        description=(
+
-            "A list of keywords that properly tag the photo. "
+def _keyword_tags_field():
-            "Allowed keywords: "
+    allowed_keywords = json.dumps(
-            + str(load_valid_keywords())
+        sorted(load_valid_keywords()), ensure_ascii=False, separators=(",", ":")
-            .replace("'", '"')
-            .replace("{", "[")
-            .replace("}", "]")
-        )
     )
+    return Field(
+        max_length=settings.llm_max_keywords,
+        description=(
+            f"Choose at most {settings.llm_max_keywords} distinct, relevant keywords. "
+            "Do not enumerate the vocabulary. Allowed keywords: "
+            f"{allowed_keywords}"
+        ),
+    )
+
+
+class _LlmResponseWithTags(BaseModel):
+    tags: list[str] = _keyword_tags_field()
 
     @field_validator("tags")
     @classmethod
@@ -119,6 +129,22 @@ class LlmResponseCaptionsAndKeywords(BaseModel):
         return v
 
 
+class LlmResponseKeywords(_LlmResponseWithTags):
+    pass
+
+
+class LlmResponseCaptionsAndKeywords(_LlmResponseWithTags):
+    caption: Annotated[
+        str,
+        Field(
+            description=(
+                "A brief but precise description of what the picture shows. "
+                "No interpretation; just what is visible"
+            )
+        ),
+    ]
+
+
 class LlmResponseQuality(BaseModel):
     rating: Annotated[
         Literal["ok", "review", "not_ok"],

src/photools3/photo.py

@@ -1,6 +1,7 @@
 import base64
 from io import BytesIO
 from pathlib import Path
+from typing import Self
 
 from PIL import Image
 
@@ -17,6 +18,15 @@ class Photo:
         self.path = path
         self.image = Image.open(path)
 
+    def close(self):
+        self.image.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
     def resize(self, image_max_size=1024) -> Photo:
         """Limiting max dimensions while maintaining aspect ratio"""
         self.image.thumbnail((image_max_size, image_max_size), Image.Resampling.LANCZOS)
@@ -24,7 +34,9 @@ class Photo:
 
     def to_rgb(self):
         if self.image.mode != "RGB":
-            self.image = self.image.convert("RGB")
+            original = self.image
+            self.image = original.convert("RGB")
+            original.close()
         return self
 
     def get_encoded(self):

src/photools3/processing.py

@@ -0,0 +1,138 @@
+import logging
+import time
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from photools3.llm_session import (
+    LlmSession,
+    LlmSessionCaption,
+    LlmSessionCaptionsAndKeywords,
+    LlmSessionKeywords,
+)
+from photools3.metadata_writer import MetadataWriter
+from photools3.models import (
+    LlmResponseCaption,
+    LlmResponseCaptionsAndKeywords,
+    LlmResponseKeywords,
+)
+from photools3.photo import Photo
+
+logger = logging.getLogger(__name__)
+
+type ProcessingResponse = (
+    LlmResponseCaption | LlmResponseKeywords | LlmResponseCaptionsAndKeywords
+)
+
+
+class ProcessingMode(StrEnum):
+    KEYWORDS = "keywords"
+    CAPTIONS = "captions"
+    BOTH = "both"
+
+
+@dataclass(frozen=True)
+class ProcessingOutcome:
+    path: Path
+    result: ProcessingResponse | None = None
+    error: str | None = None
+
+    @property
+    def succeeded(self) -> bool:
+        return self.error is None and self.result is not None
+
+
+def _create_session(mode: ProcessingMode) -> LlmSession:
+    if mode == ProcessingMode.KEYWORDS:
+        return LlmSessionKeywords()
+    if mode == ProcessingMode.CAPTIONS:
+        return LlmSessionCaption()
+    return LlmSessionCaptionsAndKeywords()
+
+
+def process_photo(
+    path: Path | str,
+    mode: ProcessingMode | str = ProcessingMode.BOTH,
+    *,
+    session: LlmSession | None = None,
+) -> ProcessingResponse:
+    """Process one photo and write the requested LLM result to its metadata.
+
+    If a session is supplied, its lifecycle remains the caller's responsibility.
+    """
+    path = Path(path)
+    mode = ProcessingMode(mode)
+    owns_session = session is None
+    active_session = session if session is not None else _create_session(mode)
+
+    logger.info(f"Processing photo: {path!s}")
+
+    try:
+        with Photo(path) as photo:
+            result = active_session.call([photo])
+
+        caption: str | None = None
+        keywords: list[str] | None = None
+        if mode == ProcessingMode.CAPTIONS:
+            if not isinstance(result, LlmResponseCaption):
+                raise TypeError("Caption mode returned an unexpected response type")
+            caption = result.caption
+        elif mode == ProcessingMode.KEYWORDS:
+            if not isinstance(result, LlmResponseKeywords):
+                raise TypeError("Keywords mode returned an unexpected response type")
+            keywords = result.tags
+        else:
+            if not isinstance(result, LlmResponseCaptionsAndKeywords):
+                raise TypeError("Both mode returned an unexpected response type")
+            caption = result.caption
+            keywords = result.tags
+
+        MetadataWriter(path).write(caption=caption, keywords=keywords)
+        return result
+    finally:
+        if owns_session:
+            active_session.close()
+
+
+def process_batch(
+    paths: Iterable[Path | str],
+    mode: ProcessingMode | str = ProcessingMode.BOTH,
+) -> list[ProcessingOutcome]:
+    """Process photos sequentially, reusing one LLM client for the whole batch.
+
+    A failed photo is recorded in its outcome and does not stop later photos.
+    Only one decoded image is held at a time.
+    """
+    mode = ProcessingMode(mode)
+    session = _create_session(mode)
+    outcomes: list[ProcessingOutcome] = []
+
+    try:
+        for item in paths:
+            path = Path(item)
+            photo_started = time.perf_counter()
+            try:
+                result = process_photo(path, mode, session=session)
+            except Exception as exc:
+                logger.exception("Failed to process %s", path)
+                # Keep only a string, not the exception/traceback, which can
+                # retain references to the just-processed image and stack.
+                outcomes.append(
+                    ProcessingOutcome(
+                        path=path,
+                        error=f"{type(exc).__name__}: {exc}",
+                    )
+                )
+            else:
+                outcomes.append(ProcessingOutcome(path=path, result=result))
+            finally:
+                logger.debug(
+                    "Photo processing for %s took %.2f seconds",
+                    path,
+                    time.perf_counter() - photo_started,
+                )
+    finally:
+        session.close()
+
+    return outcomes

src/photools3/settings.py

@@ -1,5 +1,6 @@
 from pathlib import Path
 
+from pydantic import Field
 from pydantic_core import Url
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -13,8 +14,18 @@ KEYWORDS_LIST_PATH = CONFIG_DIR / "keywords.txt"
 
 
 class Settings(BaseSettings):
-    model_config = SettingsConfigDict(env_file=".env")
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
 
     llm_api_base_url: Url
     llm_api_key: str
     llm_default_temperature: float
+    llm_request_timeout_seconds: float = Field(default=10, gt=0)
+    llm_max_completion_tokens: int = Field(default=1024, gt=0)
+    llm_max_retries: int = Field(default=5, ge=0)
+    llm_max_keywords: int = Field(default=15, ge=1)
+    log_level: str = "INFO"
+
+    metadata_prefix: str
+
+
+settings = Settings()  # type: ignore[call-arg]

test/test_cli.py

@@ -1,100 +1,197 @@
-import logging
 from pathlib import Path
+from types import SimpleNamespace
 from unittest.mock import patch
 
-import pytest
 from typer.testing import CliRunner
 
 from photools3.cli import app
+from photools3.processing import ProcessingMode
 
 runner = CliRunner()
 
-CLI_LOGGER = "photools3.cli"
+
+def _success_outcome(path: Path):
+    return SimpleNamespace(path=path, succeeded=True, error=None)
 
 
-@pytest.fixture
+def test_metadata_magic_command_defaults_to_both_for_single_photo(tmp_path):
-def mock_photo_logic(tmp_path):
+    image_path = tmp_path / "photo.jpg"
-    """Fixture to mock the core logic of keywords command."""
+    image_path.write_bytes(b"test image")
+
     with (
-        patch("photools3.cli.LlmSessionCaptionsAndKeywords") as mocked_session,
+        patch("photools3.cli.process_photo") as process_photo,
-        patch("photools3.cli.Photo") as mocked_photo,
+        patch("photools3.cli.process_batch") as process_batch,
     ):
-
+        result = runner.invoke(app, ["metadata-magic", str(image_path)])
-        # Configure session mock
-        session_instance = mocked_session.return_value
-        session_instance.call.return_value = {
-            "caption": "A beautiful test image",
-            "args": ["test", "mock", "image"],  # Wait, the code uses 'tags'
-        }
-        # Let me re-check the code in cli.py
-        # result.get("tags", [])
-        session_instance.call.return_value = {
-            "caption": "A beautiful test image",
-            "tags": ["test", "mock", "image"],
-        }
-
-        # Configure photo mock
-        photo_instance = mocked_photo.return_value
-        photo_instance.path = tmp_path / "test_image.jpg"
-
-        yield {
-            "session": session_instance,
-            "photo_class": mocked_photo,
-            "photo_instance": photo_instance,
-        }
-
-
-@pytest.fixture
-def dummy_file(tmp_path):
-    """Fixture to create a dummy file for CLI testing."""
-    dummy_path = tmp_path / "test_image.jpg"
-    dummy_path.write_text("dummy content")
-    return dummy_path
-
-
-def test_keywords_command_success(mock_photo_logic, dummy_file, caplog):
-    """Test the 'keywords' command with a valid file path."""
-    # Ensure the mock photo instance points to our dummy file
-    mock_photo_logic["photo_class"].return_value.path = dummy_file
-
-    with caplog.at_level(logging.INFO, logger=CLI_LOGGER):
-        result = runner.invoke(app, ["keywords", str(dummy_file)])
 
     assert result.exit_code == 0
-    assert "Processing: " in caplog.text
+    process_photo.assert_called_once_with(image_path, ProcessingMode.BOTH)
-    # The result is logged as a raw dictionary string
+    process_batch.assert_not_called()
-    assert (
+
-        "{'caption': 'A beautiful test image', 'tags': ['test', 'mock', 'image']}"
+
-        in caplog.text
+def test_metadata_magic_command_selects_caption_mode(tmp_path):
+    image_path = tmp_path / "photo.jpg"
+    image_path.write_bytes(b"test image")
+
+    with patch("photools3.cli.process_photo") as process_photo:
+        result = runner.invoke(
+            app, ["metadata-magic", str(image_path), "--mode", "captions"]
+        )
+
+    assert result.exit_code == 0
+    process_photo.assert_called_once_with(image_path, ProcessingMode.CAPTIONS)
+
+
+def test_metadata_magic_command_batches_multiple_files(tmp_path):
+    paths = [tmp_path / "one.jpg", tmp_path / "two.jpg"]
+    for path in paths:
+        path.write_bytes(b"test image")
+
+    with (
+        patch("photools3.cli.process_photo") as process_photo,
+        patch("photools3.cli.process_batch") as process_batch,
+    ):
+        process_batch.return_value = [_success_outcome(path) for path in paths]
+        result = runner.invoke(
+            app,
+            ["metadata-magic", *(str(path) for path in paths), "--mode", "keywords"],
+        )
+
+    assert result.exit_code == 0
+    process_photo.assert_not_called()
+    process_batch.assert_called_once_with(paths, ProcessingMode.KEYWORDS)
+
+
+def test_metadata_magic_command_expands_directories_recursively(tmp_path):
+    root = tmp_path / "photos"
+    nested = root / "nested"
+    nested.mkdir(parents=True)
+    top_level_photo = root / "one.jpg"
+    nested_photo = nested / "two.png"
+    sidecar = root / "one.jpg.xmp"
+    for path in (top_level_photo, nested_photo, sidecar):
+        path.write_bytes(b"placeholder")
+
+    with (
+        patch("photools3.cli.process_photo") as process_photo,
+        patch("photools3.cli.process_batch") as process_batch,
+    ):
+        process_batch.return_value = [
+            _success_outcome(nested_photo),
+            _success_outcome(top_level_photo),
+        ]
+        result = runner.invoke(
+            app, ["metadata-magic", str(root), "--recursive", "--mode", "both"]
+        )
+
+    assert result.exit_code == 0
+    process_photo.assert_not_called()
+    process_batch.assert_called_once_with(
+        [nested_photo, top_level_photo], ProcessingMode.BOTH
     )
 
 
-def test_keywords_command_file_not_found(caplog):
+def test_metadata_magic_command_does_not_recurse_by_default(tmp_path):
-    """Test the 'keywords' command with a non-existent file path."""
+    root = tmp_path / "photos"
-    non_existent_file = Path("non_existent_file.jpg")
+    nested = root / "nested"
+    nested.mkdir(parents=True)
+    top_level_photo = root / "one.jpg"
+    nested_photo = nested / "two.jpg"
+    top_level_photo.write_bytes(b"placeholder")
+    nested_photo.write_bytes(b"placeholder")
 
-    with caplog.at_level(logging.ERROR, logger=CLI_LOGGER):
+    with (
-        result = runner.invoke(app, ["keywords", str(non_existent_file)])
+        patch("photools3.cli.process_photo") as process_photo,
+        patch("photools3.cli.process_batch") as process_batch,
+    ):
+        result = runner.invoke(app, ["metadata-magic", str(root)])
+
+    assert result.exit_code == 0
+    process_photo.assert_called_once_with(top_level_photo, ProcessingMode.BOTH)
+    process_batch.assert_not_called()
+
+
+def test_metadata_magic_command_returns_failure_if_any_batch_item_fails(tmp_path):
+    paths = [tmp_path / "one.jpg", tmp_path / "two.jpg"]
+    for path in paths:
+        path.write_bytes(b"test image")
+
+    with patch("photools3.cli.process_batch") as process_batch:
+        process_batch.return_value = [
+            _success_outcome(paths[0]),
+            SimpleNamespace(
+                path=paths[1], succeeded=False, error="RuntimeError: write failed"
+            ),
+        ]
+        result = runner.invoke(app, ["metadata-magic", *(str(path) for path in paths)])
 
     assert result.exit_code == 1
-    assert f"Error: File '{non_existent_file}' does not exist." in caplog.text
 
 
-def test_keywords_command_error_during_processing(mock_photo_logic, dummy_file):
+def test_metadata_magic_command_returns_failure_for_single_photo_error(tmp_path):
-    """Test the 'keywords' command when an exception occurs during processing."""
+    image_path = tmp_path / "photo.jpg"
-    # Configure the session mock to raise an exception
+    image_path.write_bytes(b"test image")
-    mock_photo_logic["session"].call.side_effect = Exception("LLM error")
 
-    result = runner.invoke(app, ["keywords", str(dummy_file)])
+    with patch("photools3.cli.process_photo", side_effect=RuntimeError("LLM error")):
+        result = runner.invoke(app, ["metadata-magic", str(image_path)])
+
+    assert result.exit_code == 1
+
+
+def test_keywords_alias_is_not_registered():
+    result = runner.invoke(app, ["keywords", "photo.jpg"])
+
+    assert result.exit_code == 2
+    assert "No such command 'keywords'" in result.output
+
+
+def test_old_process_command_name_is_not_registered():
+    result = runner.invoke(app, ["process", "photo.jpg"])
+
+    assert result.exit_code == 2
+    assert "No such command 'process'" in result.output
+
+
+def test_metadata_magic_command_rejects_empty_directory(tmp_path):
+    with (
+        patch("photools3.cli.process_photo") as process_photo,
+        patch("photools3.cli.process_batch") as process_batch,
+    ):
+        result = runner.invoke(app, ["metadata-magic", str(tmp_path)])
+
+    assert result.exit_code == 1
+    process_photo.assert_not_called()
+    process_batch.assert_not_called()
+
+
+def test_quality_command_closes_photo_and_session(tmp_path):
+    image_path = tmp_path / "photo.jpg"
+    image_path.write_bytes(b"test image")
+
+    with (
+        patch("photools3.cli.LlmSessionQuality") as session_class,
+        patch("photools3.cli.Photo") as photo_class,
+    ):
+        result = runner.invoke(app, ["quality", str(image_path)])
+
+    assert result.exit_code == 0
+    session_class.return_value.__enter__.return_value.call.assert_called_once_with(
+        [photo_class.return_value.__enter__.return_value]
+    )
+    session_class.return_value.__exit__.assert_called_once()
+    photo_class.return_value.__exit__.assert_called_once()
+
+
+def test_quality_command_reports_error_and_exits(tmp_path):
+    image_path = tmp_path / "photo.jpg"
+
+    with patch("photools3.cli.Photo", side_effect=FileNotFoundError(image_path)):
+        result = runner.invoke(app, ["quality", str(image_path)])
 
-    # Note: cli.py raises typer.Exit(code=1) before logging the
-    # "Error processing image: ..." message (the logger.error call is dead
-    # code after the raise), so only the exit code can be asserted here.
     assert result.exit_code == 1
 
 
 def test_version_command():
-    """Test the --version option."""
     result = runner.invoke(app, ["--version"])
 
     assert result.exit_code == 0

test/test_llm_session_mocked.py

@@ -1,6 +1,10 @@
 from unittest.mock import MagicMock, patch
 
-from photools3.llm_session import LlmSession
+import openai
+import pytest
+
+from photools3.llm_session import LlmSession, LlmSessionCaptionsAndKeywords
+from photools3.models import LlmResponseCaptionsAndKeywords
 
 
 def test_llm_session_mocked(test_photo):
@@ -84,3 +88,216 @@ def test_llm_session_captions_and_keywords_mocked(test_photo):
 
         # Verify that the mock was called
         assert mock_client.chat.completions.create.called
+
+
+def test_llm_session_retries_from_original_request_without_accumulating_messages():
+    with patch("photools3.llm_session.OpenAI") as mocked_openai:
+        mock_client = MagicMock()
+        mocked_openai.return_value = mock_client
+        mock_model = MagicMock()
+        mock_model.id = "gpt-4o"
+        mock_client.models.list.return_value.data = [mock_model]
+
+        def response(content):
+            message = MagicMock()
+            message.content = content
+            choice = MagicMock()
+            choice.message = message
+            result = MagicMock()
+            result.choices = [choice]
+            return result
+
+        mock_client.chat.completions.create.side_effect = [
+            response('{"wrong": "first"}'),
+            response('{"wrong": "second"}'),
+            response('{"text": "correct"}'),
+        ]
+
+        session = LlmSession(system_prompt="You are a helper.")
+        result = session.call(photos=[], prompt="Return JSON")
+
+    assert result.text == "correct"
+    requests = mock_client.chat.completions.create.call_args_list
+    messages_per_attempt = [call.kwargs["messages"] for call in requests]
+    assert [len(messages) for messages in messages_per_attempt] == [2, 3, 3]
+    final_correction = messages_per_attempt[2][-1]["content"]
+    assert "Field required" in final_correction
+    assert '"wrong"' not in final_correction
+
+
+def test_llm_session_uses_configured_retry_count(monkeypatch):
+    monkeypatch.setattr("photools3.llm_session.settings.llm_max_retries", 1)
+
+    with patch("photools3.llm_session.OpenAI") as mocked_openai:
+        mock_client = MagicMock()
+        mocked_openai.return_value = mock_client
+        mock_model = MagicMock()
+        mock_model.id = "gpt-4o"
+        mock_client.models.list.return_value.data = [mock_model]
+
+        def response(content):
+            message = MagicMock()
+            message.content = content
+            choice = MagicMock()
+            choice.message = message
+            result = MagicMock()
+            result.choices = [choice]
+            return result
+
+        mock_client.chat.completions.create.side_effect = [
+            response('{"wrong": "first"}'),
+            response('{"wrong": "second"}'),
+            response('{"text": "would be a third call"}'),
+        ]
+        session = LlmSession(system_prompt="You are a helper.")
+
+        with (
+            patch.object(session, "flush_model") as flush_model,
+            pytest.raises(ValueError, match="after 1 retries"),
+        ):
+            session.call(photos=[])
+
+    assert mock_client.chat.completions.create.call_count == 2
+    flush_model.assert_called_once()
+
+
+def test_llm_session_reloads_after_timeout_and_retries(monkeypatch):
+    monkeypatch.setattr(
+        "photools3.llm_session.settings.llm_request_timeout_seconds", 10
+    )
+    monkeypatch.setattr("photools3.llm_session.settings.llm_max_completion_tokens", 768)
+    monkeypatch.setattr("photools3.llm_session.settings.llm_max_retries", 1)
+
+    with patch("photools3.llm_session.OpenAI") as mocked_openai:
+        mock_client = MagicMock()
+        mocked_openai.return_value = mock_client
+        mock_model = MagicMock()
+        mock_model.id = "gpt-4o"
+        mock_client.models.list.return_value.data = [mock_model]
+
+        response_message = MagicMock(content='{"text": "recovered"}')
+        response_choice = MagicMock(message=response_message)
+        success_response = MagicMock(choices=[response_choice])
+        mock_client.chat.completions.create.side_effect = [
+            openai.APITimeoutError(request=MagicMock()),
+            success_response,
+        ]
+
+        session = LlmSession(system_prompt="You are a helper.")
+        with patch.object(session, "flush_model") as flush_model:
+            result = session.call(photos=[])
+
+    assert result.text == "recovered"
+    flush_model.assert_called_once()
+    calls = mock_client.chat.completions.create.call_args_list
+    assert len(calls) == 2
+    assert all(call.kwargs["timeout"] == 10 for call in calls)
+    assert all(call.kwargs["max_tokens"] == 768 for call in calls)
+    mocked_openai.assert_called_once_with(
+        base_url=session.base_url,
+        api_key=session.api_key,
+        max_retries=0,
+    )
+
+
+@pytest.mark.parametrize("failure_kind", ["invalid_response", "timeout"])
+def test_llm_session_reloads_when_retry_limit_is_exhausted(monkeypatch, failure_kind):
+    monkeypatch.setattr("photools3.llm_session.settings.llm_max_retries", 0)
+
+    with patch("photools3.llm_session.OpenAI") as mocked_openai:
+        mock_client = MagicMock()
+        mocked_openai.return_value = mock_client
+        mock_model = MagicMock()
+        mock_model.id = "gpt-4o"
+        mock_client.models.list.return_value.data = [mock_model]
+
+        if failure_kind == "timeout":
+            mock_client.chat.completions.create.side_effect = openai.APITimeoutError(
+                request=MagicMock()
+            )
+        else:
+            response_message = MagicMock(content='{"wrong": "shape"}')
+            response_choice = MagicMock(message=response_message)
+            mock_client.chat.completions.create.return_value = MagicMock(
+                choices=[response_choice]
+            )
+
+        session = LlmSession(system_prompt="You are a helper.")
+        with (
+            patch.object(session, "flush_model") as flush_model,
+            pytest.raises(ValueError),
+        ):
+            session.call(photos=[])
+
+    flush_model.assert_called_once()
+    assert mock_client.chat.completions.create.call_count == 1
+
+
+def test_invalid_keywords_get_one_correction_then_invalid_tags_are_dropped(monkeypatch):
+    monkeypatch.setattr("photools3.llm_session.settings.llm_max_keywords", 3)
+    monkeypatch.setattr("photools3.llm_session.settings.llm_max_retries", 5)
+
+    with patch("photools3.llm_session.OpenAI") as mocked_openai:
+        mock_client = MagicMock()
+        mocked_openai.return_value = mock_client
+        mock_model = MagicMock()
+        mock_model.id = "gpt-4o"
+        mock_client.models.list.return_value.data = [mock_model]
+
+        def response(content):
+            message = MagicMock(content=content)
+            choice = MagicMock(message=message)
+            return MagicMock(choices=[choice])
+
+        mock_client.chat.completions.create.side_effect = [
+            response(
+                '{"caption": "A caption", "tags": ["not_allowed", "architektur"]}'
+            ),
+            response(
+                '{"caption": "A caption", '
+                '"tags": ["still_invalid", "architektur", "personen"]}'
+            ),
+        ]
+        session = LlmSessionCaptionsAndKeywords()
+        with patch.object(session, "flush_model") as flush_model:
+            result = session.call(photos=[])
+
+    assert result.tags == ["architektur", "personen"]
+    assert mock_client.chat.completions.create.call_count == 2
+    flush_model.assert_not_called()
+    correction = mock_client.chat.completions.create.call_args_list[1].kwargs[
+        "messages"
+    ][-1]["content"]
+    assert "not_allowed" in correction
+    assert '"caption"' not in correction
+
+
+def test_excess_keywords_are_truncated_to_configured_limit(monkeypatch):
+    monkeypatch.setattr("photools3.llm_session.settings.llm_max_keywords", 2)
+
+    with patch("photools3.llm_session.OpenAI") as mocked_openai:
+        mock_client = MagicMock()
+        mocked_openai.return_value = mock_client
+        mock_model = MagicMock()
+        mock_model.id = "gpt-4o"
+        mock_client.models.list.return_value.data = [mock_model]
+        message = MagicMock(
+            content=(
+                '{"caption": "A caption", '
+                '"tags": ["architektur", "personen", "landschaft"]}'
+            )
+        )
+        mock_client.chat.completions.create.return_value = MagicMock(
+            choices=[MagicMock(message=message)]
+        )
+
+        result = LlmSessionCaptionsAndKeywords().call(photos=[])
+
+    assert result.tags == ["architektur", "personen"]
+    assert mock_client.chat.completions.create.call_count == 1
+
+
+def test_keyword_response_schema_includes_configured_max_items():
+    schema = LlmResponseCaptionsAndKeywords.model_json_schema()
+
+    assert schema["properties"]["tags"]["maxItems"] == 15

test/test_lm_studio.py

@@ -0,0 +1,102 @@
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from photools3.lm_studio import LMStudioError, LMStudioModelManager
+
+
+def _http_response(payload: dict):
+    response = MagicMock()
+    response.__enter__.return_value = response
+    response.read.return_value = json.dumps(payload).encode("utf-8")
+    return response
+
+
+def test_reload_model_unloads_and_reloads_preserving_context_config():
+    model_response = {
+        "models": [
+            {
+                "key": "qwen/qwen3-vl-4b",
+                "loaded_instances": [
+                    {
+                        "id": "qwen/qwen3-vl-4b-instance",
+                        "config": {
+                            "context_length": 16384,
+                            "eval_batch_size": 256,
+                            "flash_attention": True,
+                            "offload_kv_cache_to_gpu": False,
+                            "parallel": 2,
+                        },
+                    }
+                ],
+            }
+        ]
+    }
+    with patch(
+        "photools3.lm_studio.urlopen",
+        side_effect=[
+            _http_response(model_response),
+            _http_response({"instance_id": "qwen/qwen3-vl-4b-instance"}),
+            _http_response({"instance_id": "qwen/qwen3-vl-4b-instance"}),
+        ],
+    ) as mocked_urlopen:
+        manager = LMStudioModelManager(
+            "http://localhost:1234/v1", "test-token", timeout=12
+        )
+        manager.reload_model("qwen/qwen3-vl-4b")
+
+    requests = [call.args[0] for call in mocked_urlopen.call_args_list]
+    assert requests[0].full_url == "http://localhost:1234/api/v1/models"
+    assert requests[0].get_method() == "GET"
+    assert requests[0].get_header("Authorization") == "Bearer test-token"
+
+    assert requests[1].full_url.endswith("/models/unload")
+    assert json.loads(requests[1].data) == {"instance_id": "qwen/qwen3-vl-4b-instance"}
+
+    assert requests[2].full_url.endswith("/models/load")
+    assert json.loads(requests[2].data) == {
+        "model": "qwen/qwen3-vl-4b",
+        "context_length": 16384,
+        "eval_batch_size": 256,
+        "flash_attention": True,
+        "offload_kv_cache_to_gpu": False,
+    }
+
+
+def test_reload_model_loads_by_key_if_no_instance_is_loaded():
+    model_response = {"models": [{"key": "qwen/model", "loaded_instances": []}]}
+    with patch(
+        "photools3.lm_studio.urlopen",
+        side_effect=[
+            _http_response(model_response),
+            _http_response({"status": "loaded"}),
+        ],
+    ) as mocked_urlopen:
+        manager = LMStudioModelManager("http://localhost:1234/v1", "token")
+        manager.reload_model("qwen/model")
+
+    assert mocked_urlopen.call_count == 2
+    load_request = mocked_urlopen.call_args.args[0]
+    assert load_request.full_url.endswith("/models/load")
+    assert json.loads(load_request.data) == {"model": "qwen/model"}
+
+
+def test_reload_model_rejects_ambiguous_model_selection():
+    model_response = {
+        "models": [
+            {
+                "key": "qwen/model",
+                "loaded_instances": [
+                    {"id": "instance-1", "config": {}},
+                    {"id": "instance-2", "config": {}},
+                ],
+            }
+        ]
+    }
+    with patch(
+        "photools3.lm_studio.urlopen", return_value=_http_response(model_response)
+    ):
+        manager = LMStudioModelManager("http://localhost:1234/v1", "token")
+        with pytest.raises(LMStudioError, match="Multiple loaded instances"):
+            manager.reload_model("qwen/model")

test/test_metadata_writer.py

@@ -0,0 +1,243 @@
+import shutil
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from photools3.metadata_writer import (
+    MetadataWriter,
+    _is_prefixed,
+    _prefixed,
+)
+from photools3.settings import settings
+from test.test_photo import PATHS_DNG_EXAMPLES
+
+PREFIX = settings.metadata_prefix
+
+
+@pytest.fixture
+def make_dng_file(tmp_path):
+    def _make(src: Path) -> Path:
+        dst = tmp_path / f"copy_{src.name}"
+        shutil.copy(src, dst)
+        return dst
+
+    return _make
+
+
+@pytest.fixture
+def metadata_writer_on_existing(make_dng_file):
+    metadata_writer = MetadataWriter(make_dng_file(PATHS_DNG_EXAMPLES[0]))
+    metadata_writer.write_caption(
+        "Let's pretend this is the caption of the original image",
+        include_prefix=False,
+    )
+    return metadata_writer
+
+
+@pytest.mark.parametrize("pic", PATHS_DNG_EXAMPLES)
+def test_read_metadata(make_dng_file, pic):
+    """primitive test for `MetadataWriter`"""
+    file_path = make_dng_file(pic)
+    result = MetadataWriter(file_path)
+    assert result
+    assert result.metadata
+    assert isinstance(result.metadata, dict)
+
+
+@pytest.mark.parametrize(
+    "pic, expected_keywords",
+    [
+        (PATHS_DNG_EXAMPLES[0], ["architektur", "zeit|abend"]),
+        (PATHS_DNG_EXAMPLES[1], ["architektur"]),
+        (PATHS_DNG_EXAMPLES[2], ["morgen", "tiere|vögel"]),
+        (
+            PATHS_DNG_EXAMPLES[3],
+            [
+                "abend",
+                "architektur",
+                "bewegungsunschärfe",
+                "lichter",
+                "mainz",
+                "spiegelung",
+                "wasser",
+            ],
+        ),
+        (
+            PATHS_DNG_EXAMPLES[4],
+            ["grau", "landschaft", "landschaft|weinberge", "personen", "tiefe", "weg"],
+        ),
+    ],
+)
+def test_get_keywords(make_dng_file, pic, expected_keywords):
+    path = make_dng_file(pic)
+    result = MetadataWriter(path).get_keywords()
+    assert sorted(result) == sorted(expected_keywords)
+
+
+def test_prefixed():
+    txt = "bla_bla"
+    txt_prefixed = _prefixed(txt)
+    assert txt_prefixed == f"{PREFIX}bla_bla"
+
+
+@pytest.mark.parametrize(
+    "txt, expected_result",
+    [
+        (f"{PREFIX}some text", True),
+        ("prefix is missing here", False),
+        ("some_perfix|but not the right one", False),
+    ],
+)
+def test_is_prefixed(txt, expected_result):
+    assert _is_prefixed(txt) == expected_result
+
+
+@pytest.mark.parametrize("pic", PATHS_DNG_EXAMPLES)
+def test_read_metadata_sidecar_path(make_dng_file, pic):
+    file_path = make_dng_file(pic)
+    metadata_writer = MetadataWriter(file_path)
+    assert isinstance(metadata_writer.sidecar_path, Path)
+    assert str(metadata_writer.sidecar_path).lower().endswith(".dng.xmp")
+
+    # file does not exits yet, only the name
+    assert not metadata_writer.sidecar_path.exists()
+
+
+@pytest.mark.parametrize("pic", PATHS_DNG_EXAMPLES)
+def test_set_caption(make_dng_file, pic):
+    metadata_writer = MetadataWriter(make_dng_file(pic))
+    assert not metadata_writer.sidecar_path.exists()  # sidecar does not exist yet ...
+    metadata_writer.write_caption("This is a test")
+    assert metadata_writer.sidecar_path.exists()  # ... but now!
+    result = metadata_writer.get_caption()
+    assert result
+    assert result == f"{PREFIX}This is a test"
+
+
+def test_set_caption_on_existing(metadata_writer_on_existing):
+    assert (
+        metadata_writer_on_existing.get_caption()
+        == "Let's pretend this is the caption of the original image"
+    )
+
+    metadata_writer_on_existing.write_caption("Another caption")
+    assert (
+        metadata_writer_on_existing.get_caption()
+        == f"Let's pretend this is the caption of the original image. {PREFIX}Another caption"
+    )
+
+    metadata_writer_on_existing.write_caption("Updated caption")
+    assert (
+        metadata_writer_on_existing.get_caption()
+        == f"Let's pretend this is the caption of the original image. {PREFIX}Updated caption"
+    )
+
+    metadata_writer_on_existing.write_caption("Don't do this!", override=False)
+    assert (
+        metadata_writer_on_existing.get_caption()
+        == f"Let's pretend this is the caption of the original image. {PREFIX}Updated caption"
+    )
+
+
+@pytest.mark.parametrize(
+    "pic, expected_keywords",
+    [
+        (
+            PATHS_DNG_EXAMPLES[0],
+            [
+                "architektur",
+                "zeit|abend",
+                f"{PREFIX}hund",
+                f"{PREFIX}katze",
+                f"{PREFIX}maus",
+            ],
+        ),
+        (
+            PATHS_DNG_EXAMPLES[1],
+            ["architektur", f"{PREFIX}hund", f"{PREFIX}katze", f"{PREFIX}maus"],
+        ),
+        (
+            PATHS_DNG_EXAMPLES[2],
+            [
+                "morgen",
+                "tiere|vögel",
+                f"{PREFIX}hund",
+                f"{PREFIX}katze",
+                f"{PREFIX}maus",
+            ],
+        ),
+        (
+            PATHS_DNG_EXAMPLES[3],
+            [
+                "abend",
+                "architektur",
+                "bewegungsunschärfe",
+                "lichter",
+                "mainz",
+                "spiegelung",
+                "wasser",
+                f"{PREFIX}hund",
+                f"{PREFIX}katze",
+                f"{PREFIX}maus",
+            ],
+        ),
+        (
+            PATHS_DNG_EXAMPLES[4],
+            [
+                "grau",
+                "landschaft",
+                "landschaft|weinberge",
+                "personen",
+                "tiefe",
+                "weg",
+                f"{PREFIX}hund",
+                f"{PREFIX}katze",
+                f"{PREFIX}maus",
+            ],
+        ),
+    ],
+)
+def test_set_keywords(make_dng_file, pic, expected_keywords):
+    metadata_writer = MetadataWriter(make_dng_file(pic))
+    metadata_writer.write_keywords(["hund", "katze", "maus"])
+    result = metadata_writer.get_keywords()
+    assert result
+    assert isinstance(result, list)
+    assert f"{PREFIX}hund" in result
+    assert f"{PREFIX}katze" in result
+    assert f"{PREFIX}maus" in result
+
+
+def test_set_keywords_on_existing():
+    # TODO
+    ...
+
+
+def test_write_caption_and_keywords_in_one_metadata_update(tmp_path):
+    writer = MetadataWriter(tmp_path / "photo.jpg")
+    with (
+        patch.object(writer, "get_caption", return_value="Original caption"),
+        patch.object(writer, "get_keywords", return_value=["existing"]),
+        patch.object(writer, "set_metadata") as set_metadata,
+    ):
+        writer.write(caption="Generated caption", keywords=["architektur"])
+
+    set_metadata.assert_called_once()
+    metadata_tags = set_metadata.call_args.args[0]
+    assert metadata_tags["XMP:Description"] == (
+        f"Original caption. {PREFIX}Generated caption"
+    )
+    assert set(metadata_tags["XMP:Subject"]) == {
+        "existing",
+        f"{PREFIX}architektur",
+    }
+
+
+def test_set_metadata_surfaces_write_failures(tmp_path):
+    writer = MetadataWriter(tmp_path / "photo.jpg")
+    with patch("photools3.metadata_writer.exiftool.ExifToolHelper") as exif:
+        exif_instance = exif.return_value.__enter__.return_value
+        exif_instance.execute.side_effect = OSError("ExifTool failed")
+        with pytest.raises(RuntimeError, match="Could not write metadata"):
+            writer.set_metadata({"XMP:Description": "caption"})

test/test_photo.py

@@ -48,6 +48,15 @@ def test_load_photo():
     assert isinstance(photo.image, Image.Image)
 
 
+def test_photo_context_manager_closes_image(tmp_path):
+    path = _make_image_file(tmp_path, "RGB")
+    with Photo(path) as photo:
+        image = photo.image
+        assert image.fp is not None
+
+    assert image.fp is None
+
+
 def test_resize_method_exists():
     """Test that resize method exists and returns a Photo instance"""
     photo = Photo(PATHS_DNG_EXAMPLES[0])

test/test_processing.py

@@ -0,0 +1,129 @@
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from PIL import Image
+
+from photools3.models import (
+    LlmResponseCaption,
+    LlmResponseCaptionsAndKeywords,
+    LlmResponseKeywords,
+)
+from photools3.processing import (
+    ProcessingMode,
+    _create_session,
+    process_batch,
+    process_photo,
+)
+
+
+@pytest.fixture
+def image_path(tmp_path):
+    path = tmp_path / "photo.png"
+    Image.new("RGB", (20, 20)).save(path)
+    return path
+
+
+@pytest.mark.parametrize(
+    ("mode", "response", "expected_metadata"),
+    [
+        (
+            ProcessingMode.KEYWORDS,
+            LlmResponseKeywords(tags=["architektur"]),
+            {"caption": None, "keywords": ["architektur"]},
+        ),
+        (
+            ProcessingMode.CAPTIONS,
+            LlmResponseCaption(caption="Ein Haus"),
+            {"caption": "Ein Haus", "keywords": None},
+        ),
+        (
+            ProcessingMode.BOTH,
+            LlmResponseCaptionsAndKeywords(caption="Ein Haus", tags=["architektur"]),
+            {"caption": "Ein Haus", "keywords": ["architektur"]},
+        ),
+    ],
+)
+def test_process_photo_writes_only_requested_metadata(
+    image_path, mode, response, expected_metadata
+):
+    session = MagicMock()
+    session.call.return_value = response
+
+    with (
+        patch("photools3.processing._create_session", return_value=session),
+        patch("photools3.processing.MetadataWriter") as writer_class,
+    ):
+        result = process_photo(image_path, mode)
+
+    assert result == response
+    session.call.assert_called_once()
+    session.close.assert_called_once()
+    writer_class.assert_called_once_with(image_path)
+    writer_class.return_value.write.assert_called_once_with(**expected_metadata)
+
+
+def test_process_photo_does_not_close_a_caller_owned_session(image_path):
+    session = MagicMock()
+    session.call.return_value = LlmResponseCaption(caption="Ein Haus")
+
+    with patch("photools3.processing.MetadataWriter"):
+        process_photo(image_path, ProcessingMode.CAPTIONS, session=session)
+
+    session.close.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    ("mode", "constructor"),
+    [
+        (ProcessingMode.KEYWORDS, "LlmSessionKeywords"),
+        (ProcessingMode.CAPTIONS, "LlmSessionCaption"),
+        (ProcessingMode.BOTH, "LlmSessionCaptionsAndKeywords"),
+    ],
+)
+def test_create_session_selects_mode_specific_response_model(mode, constructor):
+    with patch(f"photools3.processing.{constructor}") as session_class:
+        assert _create_session(mode) is session_class.return_value
+
+    session_class.assert_called_once_with()
+
+
+def test_process_batch_is_sequential_reuses_session_and_continues_after_error():
+    active_photos = 0
+    max_active_photos = 0
+
+    class TrackingPhoto:
+        def __init__(self, path):
+            self.path = path
+
+        def __enter__(self):
+            nonlocal active_photos, max_active_photos
+            active_photos += 1
+            max_active_photos = max(max_active_photos, active_photos)
+            return self
+
+        def __exit__(self, exc_type, exc_value, traceback):
+            nonlocal active_photos
+            active_photos -= 1
+
+    session = MagicMock()
+    response = LlmResponseCaptionsAndKeywords(caption="Ein Haus", tags=["architektur"])
+    session.call.side_effect = [response, RuntimeError("temporary error"), response]
+    paths = [Path("one.jpg"), Path("two.jpg"), Path("three.jpg")]
+
+    with (
+        patch("photools3.processing._create_session", return_value=session),
+        patch("photools3.processing.Photo", TrackingPhoto),
+        patch("photools3.processing.MetadataWriter") as writer_class,
+    ):
+        outcomes = process_batch(paths, ProcessingMode.BOTH)
+
+    assert [outcome.succeeded for outcome in outcomes] == [True, False, True]
+    assert [outcome.path for outcome in outcomes] == paths
+    assert outcomes[1].error == "RuntimeError: temporary error"
+    assert max_active_photos == 1
+    assert active_photos == 0
+    assert session.call.call_count == 3
+    assert all(len(call.args[0]) == 1 for call in session.call.call_args_list)
+    assert writer_class.return_value.write.call_count == 2
+    session.close.assert_called_once()

test/test_settings.py

@@ -6,11 +6,9 @@ from photools3.settings import (
     PHOTOOLS3_DIR,
     ROOT_DIR,
     SRC_DIR,
-    Settings,
+    settings,
 )
 
-settings = Settings()
-
 
 def test_photools3_dir():
     assert PHOTOOLS3_DIR == Path(__file__).parent.parent.resolve() / "src" / "photools3"

uv.lock

@@ -1,6 +1,10 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.14"
+resolution-markers = [
+    "python_full_version >= '3.15'",
+    "python_full_version < '3.15'",
+]
 
 [[package]]
 name = "annotated-doc"
@@ -33,6 +37,70 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/12/b8/4bd346e22b28902df4d651910f5242c28d84e4a5c2435ca5c3f797ed7e2e/anyio-4.15.1-py3-none-any.whl", hash = "sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101", size = 132079, upload-time = "2026-09-05T10:42:37.923Z" },
 ]
 
+[[package]]
+name = "ast-serialize"
+version = "0.12.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c2/1c/7257e6ec9382843915ce475558ce4492ccb5ed39122c256bb369c27e2ebf/ast_serialize-0.12.1.tar.gz", hash = "sha256:5285a390caf1c44368ae270f037f797b91427d138b7d43cad0f1fda4c83518d9", size = 954408, upload-time = "2026-10-03T12:25:00.221Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4a/f7/e976169da322c009bb083a52d21e88fbfe5f071e1806e8c8361ab4ac477a/ast_serialize-0.12.1-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:e73255c9227fd74eac8a9b55c4049e8ad7b66d1f690bf827c98a86b2e594def7", size = 897232, upload-time = "2026-10-03T12:23:21.945Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/89/5545f6f4d38dd41b4e2a20050967ccd722508bc90fab0dfba463d8c8b994/ast_serialize-0.12.1-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:4655ef993e69e01bb47d2d99647de9bbb74af03938438656832cd010d95de348", size = 1235397, upload-time = "2026-10-03T12:23:23.835Z" },
+    { url = "https://files.pythonhosted.org/packages/22/19/e9b839ef9b57626e15e20dd7cf764a9a6b50f9750f86d0a49bc3a971fb72/ast_serialize-0.12.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:bac5a99a2c91dd823be9b8c44645694fccbb0750773cc5b27889a9f6f22fce89", size = 1216331, upload-time = "2026-10-03T12:23:25.557Z" },
+    { url = "https://files.pythonhosted.org/packages/26/2a/d054d4ff8ba42472a22e3da6eb6dee0e69a32c477b5077eefdbada99f554/ast_serialize-0.12.1-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6485e681625ed7a094221f16a7ff2ef154946112266a05cf83bde50c959ef345", size = 1281194, upload-time = "2026-10-03T12:23:27.349Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/0c/c73eddfa180a7a4c1613c0f3d3ef020b05dca9b922ac08212463c33ad11f/ast_serialize-0.12.1-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:a513bc6f60980d01767f7cbe39b17ce0373e722824a74ce28d6cea49ee3c8460", size = 1287170, upload-time = "2026-10-03T12:23:29.333Z" },
+    { url = "https://files.pythonhosted.org/packages/94/77/39dc75d8b718844859b64a9067c9df0cfce218ca45ea215fb24a1fda3cf7/ast_serialize-0.12.1-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:82866f3523d53ffca8d2a69a750bec52908b69f728012e40959bebce2620453c", size = 1531238, upload-time = "2026-10-03T12:23:30.954Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/c0/6a6a6f94f45a288c4bac2eb8379a3d9654574a0f9249380ce3b07f6d64bb/ast_serialize-0.12.1-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:243054a05a5190f5d087b5c8b16423e7f1cefa4991bac26e9c8ace18074b75b6", size = 1307154, upload-time = "2026-10-03T12:23:32.645Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/3d/80f843892bd0f7c0d95ec5422ba3dc315c1ce011e6f08b06d5f71bd82c25/ast_serialize-0.12.1-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7d9fbe5a3e8acddfc2fddff3dbbc7ea0e9798b3df3428f851b8abc52a3806f31", size = 1301506, upload-time = "2026-10-03T12:23:34.63Z" },
+    { url = "https://files.pythonhosted.org/packages/df/cc/49a5fe852706f545e3e005584c5be89456bc637a8c9179aeaa8b9f26e8e4/ast_serialize-0.12.1-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:d3d516da3463071d27e64caf54d88cba25cf4ad4afcc807e0bcf67743719f03e", size = 1297616, upload-time = "2026-10-03T12:23:36.377Z" },
+    { url = "https://files.pythonhosted.org/packages/49/5c/1208c91d6e00cc43cc276bd6233c40c9b4ec3ef8537c83281dd5372cbdb8/ast_serialize-0.12.1-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:8d6711adf11136c77e3a35517de9488a5081d1012874fae99c2876b64f4daace", size = 1354884, upload-time = "2026-10-03T12:23:38.035Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/80/2b5fc912ff0be64d8d61ff5dc7dc405c6311297a0e2039b848b7d14333f2/ast_serialize-0.12.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:cbe239bee4bd609186daf60b95b7b0f47146c7f7f55f6da83807d747d6fe753f", size = 1457911, upload-time = "2026-10-03T12:23:39.679Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/f8/d720429bf8933efbd0cc2038c0a50b6267a585d503500845c44bc6c8ff66/ast_serialize-0.12.1-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:5bbf582286c9dc6b4c544ef645dc99e4b3aa09db28892bc60344141f6926641f", size = 1563023, upload-time = "2026-10-03T12:23:41.585Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/0a/99e6cc92bdbae5db60f84a14a0fb1ae77b6087e451d77808d87558162c9a/ast_serialize-0.12.1-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:99e33c93efb5254a70c525b46038212371dfe5693d48eb2d0d5f17d936a263d7", size = 1556601, upload-time = "2026-10-03T12:23:43.361Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/05/59de9e16a2e333da534f30776d0f5e426034b64c67c17843425e3cc827d1/ast_serialize-0.12.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:aa6c17a2b7f07e81fa8cfcc4aa7c832b3e57733853aebea113ab502f9b0963db", size = 1665039, upload-time = "2026-10-03T12:23:45.257Z" },
+    { url = "https://files.pythonhosted.org/packages/33/83/35ed67a127167b484b42a071df440f84b14c0d20ea8f69dbed5cc96bfd98/ast_serialize-0.12.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:f896fa38e0af38821e1ab1425c5dee89e359623e165765bdeae7d0eb6909e76d", size = 1472263, upload-time = "2026-10-03T12:23:46.811Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/b0/3ab8613bbb690297f1bb687d780a248c486df0f4131b6a82044fcb49e438/ast_serialize-0.12.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:af699e81fd7ce80b8b03945826d8ea23dd36d072f10d4613402da597ba4ee9c6", size = 1499242, upload-time = "2026-10-03T12:23:48.531Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/a0/a28894d3b06f8775cea8989f371bd9f72ce562c32bc807770e7fb920ce17/ast_serialize-0.12.1-cp314-cp314t-win32.whl", hash = "sha256:10b59afc108eb285146acb23d1b5ec0fc58bb3c09cb2ab8876402df06c373c3b", size = 1119488, upload-time = "2026-10-03T12:23:50.419Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/b2/0c44952f4ba4e14bb7f60a5858e2960dfefb9884e6ff007aaf64337dba5c/ast_serialize-0.12.1-cp314-cp314t-win_amd64.whl", hash = "sha256:72e871f6995a066c1b19104f8a6b5832b1163adb9a8267c2aa4711fbb0f4d1f3", size = 1157434, upload-time = "2026-10-03T12:23:52.383Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/1e/cb594c63f46a01d53629af1c4f9e42cd02afcea1c2fe483e12f22743ebac/ast_serialize-0.12.1-cp314-cp314t-win_arm64.whl", hash = "sha256:3398e458047d21c9bc1b323fe5aab77c608dc9ddb65b2d44deebaff503a1f1eb", size = 1129094, upload-time = "2026-10-03T12:23:54.133Z" },
+    { url = "https://files.pythonhosted.org/packages/16/05/ca16884f9498386f3646bb18be59f0e31d44e992d252d7d6f5e4f8ae1ee2/ast_serialize-0.12.1-cp315-abi3.abi3t-macosx_10_12_x86_64.whl", hash = "sha256:410233de149ab8414cb27c6fc73e9d2baa35d6f971672d540d752060d980ffb4", size = 1235686, upload-time = "2026-10-03T12:23:55.863Z" },
+    { url = "https://files.pythonhosted.org/packages/29/f2/34e87ed30e292cf365523712c4bcfef1967d9c3c2749de21b1f93b1fe0f3/ast_serialize-0.12.1-cp315-abi3.abi3t-macosx_11_0_arm64.whl", hash = "sha256:b9a2310845302f1a6bd45ae8a67d5760211103a8d66410b854bfa440d107e093", size = 1215598, upload-time = "2026-10-03T12:23:57.48Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/dc/c498f41c957b6ff31b97ed8ceccf3a84f85af7debca1125183cab95bb58b/ast_serialize-0.12.1-cp315-abi3.abi3t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6ff65f40f49d5e1a1a043ba366081d59a4e26a9f5c1b07eb1170e172115da7ca", size = 1281911, upload-time = "2026-10-03T12:23:58.954Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/60/70ccefae9d88058c4c234bf0aed93f54aca36eb74087736e76e9515aee96/ast_serialize-0.12.1-cp315-abi3.abi3t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:536d783c4d91331f094e0a892221e619be5ffbe6fb6640885f14d7f226ec90ca", size = 1287296, upload-time = "2026-10-03T12:24:00.429Z" },
+    { url = "https://files.pythonhosted.org/packages/08/e9/4fc697879c7128e29f9dab2ed19a9b586a56b621e5ea4aee2ae28c18e116/ast_serialize-0.12.1-cp315-abi3.abi3t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:c42d2d65f388d1960c5796231eb9bf5a988c46228633eb489605c4549ad16c52", size = 1532339, upload-time = "2026-10-03T12:24:02.053Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/9e/9e2bd489731602a94dbd0c576ebe1cc487a2d0f6127be743f44711166f0d/ast_serialize-0.12.1-cp315-abi3.abi3t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a5628a12acc875fe7a167910f18d101dd101c2a7b1e6c2b6f7289ffaff25805c", size = 1308988, upload-time = "2026-10-03T12:24:03.61Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/69/e9cae837bd766a66db6953ffb5fc7f04b1945e02b0a9e4c6a0b6acb08f17/ast_serialize-0.12.1-cp315-abi3.abi3t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9e855adfa5bb982b2e6fe09056b2d584f6dd4fce085d91a07d1155683751b6b5", size = 1303412, upload-time = "2026-10-03T12:24:05.62Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/1e/5ef8c62d5031d93187ed0d8dade5d942de9920c3fbd678c7652362b9a7a2/ast_serialize-0.12.1-cp315-abi3.abi3t-manylinux_2_31_riscv64.whl", hash = "sha256:fafe1471e8aca6c87b4913b7b54ff97197adf702fbe28692284b929dfa62ff96", size = 1298466, upload-time = "2026-10-03T12:24:07.242Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/f3/25ded60844a1a437edc840e597b6f81daf91dc4a26035416e14298d3a091/ast_serialize-0.12.1-cp315-abi3.abi3t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a5cac246474d2a703147d1605a6ac5ba0fa9e0a443cf1cf42513adf4df02686f", size = 1355617, upload-time = "2026-10-03T12:24:09.125Z" },
+    { url = "https://files.pythonhosted.org/packages/05/68/a0d3cc8d8042208a2cbef7b26483f4941b44dd5dd717bb19f20e4a4c0d66/ast_serialize-0.12.1-cp315-abi3.abi3t-musllinux_1_2_aarch64.whl", hash = "sha256:6e25cd319fb0d7b39fcac666784ec86708ccbc78d07a698b1400cf5ed40c045b", size = 1458949, upload-time = "2026-10-03T12:24:10.772Z" },
+    { url = "https://files.pythonhosted.org/packages/df/a0/5e4d355c48a9f125b8bec7b1b98d4d2dcd8324ff1d4dfcb03678a03c1414/ast_serialize-0.12.1-cp315-abi3.abi3t-musllinux_1_2_armv7l.whl", hash = "sha256:657a7354ea16ed4d29f8127ed477c6fee3915c111d135f020ca835a991438e90", size = 1562328, upload-time = "2026-10-03T12:24:12.404Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/5f/3d40f6a7908200f2f0ed9ce1bad130d00e06d0405baa7918d4a4299b25dd/ast_serialize-0.12.1-cp315-abi3.abi3t-musllinux_1_2_i686.whl", hash = "sha256:9eb9de7e59621acdb3e66984f374272b33d56d15a04763e2fd0604211e1c8303", size = 1557751, upload-time = "2026-10-03T12:24:14.455Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/13/d53e5a7e299d6dbaeab23a424eea2c98c821b46ed7b05abbe14743beeb63/ast_serialize-0.12.1-cp315-abi3.abi3t-musllinux_1_2_ppc64le.whl", hash = "sha256:09cc4d3103c1fc97f6845ba307af1db9cde5226bef47f8843220dde83f2276ba", size = 1666238, upload-time = "2026-10-03T12:24:16.171Z" },
+    { url = "https://files.pythonhosted.org/packages/37/5b/7638ee3ae35a64e4467160a37dc7565cddfe2a87f06cef2fd07c93cfd503/ast_serialize-0.12.1-cp315-abi3.abi3t-musllinux_1_2_riscv64.whl", hash = "sha256:c9e2a592706fd791c2271ce9c8f4e38c98d3ea0b4a86b511e09a4fe3ac44ab37", size = 1472620, upload-time = "2026-10-03T12:24:18.053Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/e7/6e9e621e0e4a3be5a9a5f8b6961982964d2367013dbe64feb5adaa43e56d/ast_serialize-0.12.1-cp315-abi3.abi3t-musllinux_1_2_x86_64.whl", hash = "sha256:f4ac042e95a575432c1730ca4cb9183066a2074886a599f46c1f1b0955fb8198", size = 1500141, upload-time = "2026-10-03T12:24:20.036Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/4f/3217da5b671711c09cc6be580095839cad539983662a6599405bd75c1a19/ast_serialize-0.12.1-cp315-abi3.abi3t-win32.whl", hash = "sha256:b3cd105995942cc6163a229674a86161ba1305f646493efd59bd6723a357ee14", size = 1118382, upload-time = "2026-10-03T12:24:21.599Z" },
+    { url = "https://files.pythonhosted.org/packages/80/1e/6074cf29dca8ceff27d50e845c88e7a2eaaa7f0b6f3972909e878d844737/ast_serialize-0.12.1-cp315-abi3.abi3t-win_amd64.whl", hash = "sha256:a9cd24a26126088693ca054547ea0a391398a29cf1a3a2bec1009b4b6acc8b82", size = 1158034, upload-time = "2026-10-03T12:24:23.316Z" },
+    { url = "https://files.pythonhosted.org/packages/92/a0/81ce428f9f3f1ca45f8b62c9711c30452bf8190476e8685cea0f72d8d008/ast_serialize-0.12.1-cp315-abi3.abi3t-win_arm64.whl", hash = "sha256:9649cd903db0dc047906c6dd740784a2ba665d54f7e43ba31457edbce76c9493", size = 1129437, upload-time = "2026-10-03T12:24:25.044Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/d9/1c08adb90728607d0d07d188df4558ae863d688b4458087efe9fafeca458/ast_serialize-0.12.1-cp315-cp315-pyemscripten_2026_5_wasm32.whl", hash = "sha256:5ef62601db3ce5c23445132262a193075e211fb2fc87b46b7550dd351fac0976", size = 897419, upload-time = "2026-10-03T12:24:26.699Z" },
+    { url = "https://files.pythonhosted.org/packages/80/fb/1eabd2c0673283054468b1c6cb539aeb877636d6c84b280279f2d7a177a9/ast_serialize-0.12.1-cp39-abi3-macosx_10_12_x86_64.whl", hash = "sha256:98d91cd3a6cb76a39512ee090a539d1e3206b732ad8150eb38918cffa1ddf515", size = 1241515, upload-time = "2026-10-03T12:24:28.493Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/d7/c56955934a431a0fa3e4e9aa7af4a53ceab2a61241005427545208945eb4/ast_serialize-0.12.1-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:8a32f184ce3e4b1d0b06d642a1243281cf55b99e0323680b1b8f904029fd7700", size = 1228048, upload-time = "2026-10-03T12:24:30.556Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/4e/2b2ca4602baf92f842316ea617423402089df4fbd2ea42571ba28725ba46/ast_serialize-0.12.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e62126ac2be2d9340ac1b3ee7a0466a883ecbed634cff0929c88ca0b671483b7", size = 1292087, upload-time = "2026-10-03T12:24:32.45Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/49/9ebd05218a87ca31f4f855d5e3df14239bba3c58f2aed9d02c7cba5d94f5/ast_serialize-0.12.1-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0f93a70fa9826c04ea9f2c3a880f87f4cca09a828144ed5084682abd28110980", size = 1295355, upload-time = "2026-10-03T12:24:34.423Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/09/6db7c4327e7a56aba805f7190d377a159fc0bf6bdefb410dc7860624dfa3/ast_serialize-0.12.1-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1858887be56a64a2aea899423dfe43787c34c75c18b0d7497de8e618d54b2790", size = 1541231, upload-time = "2026-10-03T12:24:36.05Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/85/7ab6097e5fe23cd4657b0e5a2fabb4f789f91e441a3ee40b3ca8b79be238/ast_serialize-0.12.1-cp39-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:89a2bc39a820bc7785b60c53a5742b4e8dd4c1a599294e2dd68fae545883d44a", size = 1317324, upload-time = "2026-10-03T12:24:37.737Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/60/58961e7fd129e226ce36788fe328d20034f3105f5d3380df690050517737/ast_serialize-0.12.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:50a9eaedf1db4857dad7cc47dd757ed70bfcc40b89d44d516c4a2f0d5033bd76", size = 1311809, upload-time = "2026-10-03T12:24:39.306Z" },
+    { url = "https://files.pythonhosted.org/packages/15/c7/09d973db87d4575cba470fd80a3fa489322f7d6882546e43a4b21012468e/ast_serialize-0.12.1-cp39-abi3-manylinux_2_31_riscv64.whl", hash = "sha256:c30b609e8fea426b310543126de876592236a25aa8ebd59f1e2b323dd52a4085", size = 1306678, upload-time = "2026-10-03T12:24:40.891Z" },
+    { url = "https://files.pythonhosted.org/packages/84/27/84f69c22bcdaa5256b4fe43ff972fc117668fff8e68495807d5792eadcce/ast_serialize-0.12.1-cp39-abi3-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:7b1ad06513022cfa1337744959255af0ef16119d2beb1e547b67f37ad9433d4a", size = 1362009, upload-time = "2026-10-03T12:24:42.809Z" },
+    { url = "https://files.pythonhosted.org/packages/43/46/76ee342ef22cd6d82ccd6089d5e2f7163246de73d1816ccb4b6ec0550db6/ast_serialize-0.12.1-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:6add54b495e37ae3cf3a1f0d5eaba364814eb72e93026adc41b7791e4b0d45d3", size = 1467959, upload-time = "2026-10-03T12:24:44.496Z" },
+    { url = "https://files.pythonhosted.org/packages/31/4d/18e48154bbf6058eed8d9b54fcebb2e130f8a380db1a2a202b4faac48626/ast_serialize-0.12.1-cp39-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:5fc136cd08001b817ad0b3e7426f50a7d2b8982dc7c6491f0af78af4c3dd8672", size = 1571157, upload-time = "2026-10-03T12:24:46.156Z" },
+    { url = "https://files.pythonhosted.org/packages/34/76/6b16ddf0510e713613a5f5441b13407c1bde6158df04946b9f1fdc65add3/ast_serialize-0.12.1-cp39-abi3-musllinux_1_2_i686.whl", hash = "sha256:45a9e6b700bbd973d49942668a5cdbeffa693f2e250b8a5409abd1fa9d351854", size = 1566873, upload-time = "2026-10-03T12:24:48.542Z" },
+    { url = "https://files.pythonhosted.org/packages/75/33/9f6169ae7f60c2da4baec03450073d3f1edb39e95ab538be0d25a7d2f72e/ast_serialize-0.12.1-cp39-abi3-musllinux_1_2_ppc64le.whl", hash = "sha256:a1d8267f83c613ea0a31f2518df074bd62e98a4b3a4892f6a529d74e08e02dba", size = 1673030, upload-time = "2026-10-03T12:24:50.566Z" },
+    { url = "https://files.pythonhosted.org/packages/11/51/0d78755bd61d6cf8980f0cfdc7fa8ede38df46a5423c9f7a3da0cff587ec/ast_serialize-0.12.1-cp39-abi3-musllinux_1_2_riscv64.whl", hash = "sha256:9a0cbab9796e6ce841197feeba4008faa96b4cc7741129542fd81c882d7a4f01", size = 1480052, upload-time = "2026-10-03T12:24:52.277Z" },
+    { url = "https://files.pythonhosted.org/packages/01/ae/ad4c0e5129991f2761f388420c5ded37cb134ec5882e3e59043d33c1ad87/ast_serialize-0.12.1-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:b4282695f1d51a3c6ef76560351bad5af880eff7d755aefea325bffb9bf68c25", size = 1508940, upload-time = "2026-10-03T12:24:53.846Z" },
+    { url = "https://files.pythonhosted.org/packages/38/6b/3299182794d38815ae6e9c7ede9bb8f2e4aa93c3578bed201c1ea746643a/ast_serialize-0.12.1-cp39-abi3-win32.whl", hash = "sha256:119d1b0cadaba4a6e475f9bbe79eecc79351e373142eabe7c353f0250d70aebb", size = 1125618, upload-time = "2026-10-03T12:24:55.405Z" },
+    { url = "https://files.pythonhosted.org/packages/86/14/5d4fb733c18a1d69e237c067b183842f3a7ea1c999a51ddc87093a281c88/ast_serialize-0.12.1-cp39-abi3-win_amd64.whl", hash = "sha256:3d6ed63d4fc1ec867b8cb522d58c36df0e8f05e487bea0ffd102043a37636d72", size = 1165798, upload-time = "2026-10-03T12:24:57.052Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/f4/b54123680025c0b7253117418f023d1b2487f1102552acbdd9d8ee96b622/ast_serialize-0.12.1-cp39-abi3-win_arm64.whl", hash = "sha256:610a41351de68199de9a1434499083b4256c0df7658ec1cfc0a0a7b20b08d317", size = 1136560, upload-time = "2026-10-03T12:24:58.689Z" },
+]
+
 [[package]]
 name = "black"
 version = "26.5.1"
@@ -462,6 +530,76 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/81/db/e655086b7f3a705df045bf0933bdd9c2f79bb3c97bfef1384598bb79a217/keyring-25.7.0-py3-none-any.whl", hash = "sha256:be4a0b195f149690c166e850609a477c532ddbfbaed96a404d4e43f8d5e2689f", size = 39160, upload-time = "2025-11-16T16:26:08.402Z" },
 ]
 
+[[package]]
+name = "librt"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/f5/9dc696772d241814bacac7880bac32f2930b5a6ebc1f85317b83161a011c/librt-0.16.0.tar.gz", hash = "sha256:ac38d6d8d66bf3d744148dbbc0b8e193e195a51e364ed55e224631f5721891fc", size = 219839, upload-time = "2026-09-29T00:55:32.891Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/93/9e0cf7da129a93c3dc7f45bc3cd4a660f2aaa995aa8a6f95c2583ef41239/librt-0.16.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:931a0bb0fcac88f263e269e46eb30ba8e21402cd3c62ca40cb97034c0693fab1", size = 149844, upload-time = "2026-09-29T00:53:31.391Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/26/8a90d2a8f2b2e471bb486b7aec117b8ae622715ed6c39853aec48ea20073/librt-0.16.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1bc17e54e5305f8d40b7ca203671ff5a9e59c1d0f8ea0f625dcca53a3984de11", size = 154111, upload-time = "2026-09-29T00:53:32.718Z" },
+    { url = "https://files.pythonhosted.org/packages/35/ce/67abb46258da4d3e42ff5b141db6f38c59357bef84c7979f183b22f924f1/librt-0.16.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:877698bf6bca5721d8be345f2fe09778e40ecadea8b58c73075f2b1a53666bf2", size = 494234, upload-time = "2026-09-29T00:53:34.466Z" },
+    { url = "https://files.pythonhosted.org/packages/12/f9/ea7162414a16f8f1bbd3b493ad6d22b926c5471916e078350bdbca8c4e5f/librt-0.16.0-cp314-cp314-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:5981c011b306781ce561e18e14230a14524a3d8109b97553666c942c18f31a96", size = 491173, upload-time = "2026-09-29T00:53:36.124Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/09/9b3e869060dd33f9989b80ba4fea306f6db8cecefcdfe6d7346ef0603f65/librt-0.16.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:afced3dfc17cd805ecf7a3d77996a71cf5f2c75aa66eb0c21a9930f4fc992f86", size = 505547, upload-time = "2026-09-29T00:53:37.686Z" },
+    { url = "https://files.pythonhosted.org/packages/50/07/79007d2165f649ea93e08c0962d1d62c70af9cde77965255095bf9d96f9a/librt-0.16.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ca8052401c55d7511dda6760719fda7618067e83535d7d0010096d216c34b667", size = 523057, upload-time = "2026-09-29T00:53:39.301Z" },
+    { url = "https://files.pythonhosted.org/packages/61/0c/8fbaff66d0ba376d8864653f5acce1569bae27e89648671f26f7eca67ab8/librt-0.16.0-cp314-cp314-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1e511762a074005bb0aa569166779834e75e438370226930d0ce1866d4b6a33b", size = 515158, upload-time = "2026-09-29T00:53:41.012Z" },
+    { url = "https://files.pythonhosted.org/packages/df/2e/23ff0dece76f07a4124413a57682efa0bbeb5765ac0122bc0955513f82ca/librt-0.16.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:f1e8591bd8a5a628cd7f07954c6a1592359a878bf032957a8e9057a41d644311", size = 534183, upload-time = "2026-09-29T00:53:42.451Z" },
+    { url = "https://files.pythonhosted.org/packages/26/c4/e11dea21d9a29486eba78887380374189d472734fa32cc50cb37ca44d3d0/librt-0.16.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:a4aaefb4ba6c07e1aeebb2795c8958148f1d6f9af3b555b53d23d766edb6d67a", size = 540663, upload-time = "2026-09-29T00:53:44.272Z" },
+    { url = "https://files.pythonhosted.org/packages/44/75/e873ae158a8b7f5359be33e7fd6c1fbe02d9a78a3e89a77de6b0e837f476/librt-0.16.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:d92db7a0f6aee44f1baee94750457e8d2d1c6ccea41842de6268d34e8dc7eddd", size = 545908, upload-time = "2026-09-29T00:53:45.812Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/36/8939d3f6a93e11bd9592e6fe28d2b44f1c2dc4bed6e22e72359a91e18ffb/librt-0.16.0-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:378dfaffb38e59c24a87cde5713cd865d51ff7383fa12947f3907f306ea1ca55", size = 523302, upload-time = "2026-09-29T00:53:47.596Z" },
+    { url = "https://files.pythonhosted.org/packages/71/14/35309f44a077f0f42ade0e2e7cd88c0cea760c661af205c01ea90d3c0e1f/librt-0.16.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:3e0c39bdc85370422e8b637be76eb1fd07d30967551b03e62267dd156f553152", size = 565911, upload-time = "2026-09-29T00:53:49.278Z" },
+    { url = "https://files.pythonhosted.org/packages/78/0c/df6255b94967f3159ebc46f08d8e783c12da6ee269ddb74b2efed63c640c/librt-0.16.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:1b384b90ab79a7bc30b566895809a636e0666f21f3cf12b54823d025b7e83839", size = 79119, upload-time = "2026-09-29T00:53:50.938Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/44/d30d5a5461378c9d33f36736c6791c3b4c4ba4b1ffe0da7350aedcb2c9a0/librt-0.16.0-cp314-cp314-win32.whl", hash = "sha256:52327da75a94012e7f932f913d20d3876bed3c102be00e6c3e8600ff7bdd58a7", size = 100140, upload-time = "2026-09-29T00:53:52.205Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/98/769712f356a1e897df3581bb0c3100375d054a000de26099360ea65b5111/librt-0.16.0-cp314-cp314-win_amd64.whl", hash = "sha256:3f0b8114c44b2ac06ff5dacd08e07e8e807ff4f46083f2a1602685122559be41", size = 120464, upload-time = "2026-09-29T00:53:53.495Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/d3/ae2abccc8bdc8b063c1613a77686e17b74e9d3d60cfe6f12c63fa2821b9f/librt-0.16.0-cp314-cp314-win_arm64.whl", hash = "sha256:8caf96a4ef8fb27d0ac0d1ad8337d26a240acd4a02fe4345d0a8f264753e8f99", size = 110889, upload-time = "2026-09-29T00:53:54.817Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/26/0737d4be058dd6376eade7dd8b380d4b869b6394cee929393a5a431c45bb/librt-0.16.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:953107e2f68d0f3512c48f898b0dbf0ce5cc52bba0f318d847c985dc555ee4cc", size = 159838, upload-time = "2026-09-29T00:53:56.22Z" },
+    { url = "https://files.pythonhosted.org/packages/01/96/9bc96531d7c620e9949af904470f02e3fa8f35129ab8e8f281c51eaa3788/librt-0.16.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ad37d5b9abd49c9a655dcda7ea52a8a752884062ef1ee71ae17c2f2a0f81fe6a", size = 162018, upload-time = "2026-09-29T00:53:57.532Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/fa/b0289dcb186eb3f97221ba00da5f4bd3ba7fa5e99752d48aa8d336615334/librt-0.16.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2c4aa329c17bd1aaea4f6e89335d8ccd494b3a5830b6654462273e50e11023f0", size = 703983, upload-time = "2026-09-29T00:53:59.024Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/ab/05ebbbde7530fc5eeb58fbd1581522a9f64f132fa703c4c595eed6e14760/librt-0.16.0-cp314-cp314t-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:0ead24d2562a49473dddd9efef8581f020007eb0054389c3ee3ffad38b1ca4c9", size = 683847, upload-time = "2026-09-29T00:54:00.671Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/75/f52aeecd4dbadbddf80725ba7de126d8bd5d0eb66247eae17a81ed90dd4d/librt-0.16.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:02118f56a9c36ddd07dfd9b919d9ecc117ba20a90987d56aa4c429fa34509188", size = 698045, upload-time = "2026-09-29T00:54:02.247Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/55/fa277a835cd6eb42380591ceb85f48c5b4d2b2d7e2cb9869e1e17d24d237/librt-0.16.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4e29522c62e28595ff7e324c6834ade51127707f0e255b18d1c1cf03d39c1048", size = 724640, upload-time = "2026-09-29T00:54:04.078Z" },
+    { url = "https://files.pythonhosted.org/packages/25/e4/2cf64354f3fde8ebd591b3b48f96510bee24ac5f7d1e567adbbe210abdbd/librt-0.16.0-cp314-cp314t-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3ff4b2367926b69c6215635902cccb04048e73094e9862900d27cb2c6bbff143", size = 731748, upload-time = "2026-09-29T00:54:05.741Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/c9/c180af3e94e01aa529fa93d7733fec2abc47f222345400cf21d5481d5f8a/librt-0.16.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c6f1b27bf1632a7e016af9f145f82be95e1edd7721a646505c21059257cb5a04", size = 754960, upload-time = "2026-09-29T00:54:07.38Z" },
+    { url = "https://files.pythonhosted.org/packages/95/d6/01073aa78c58f356b10d9c57b3fe9abb143df338142bcd316df417b89db0/librt-0.16.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:5696d7f52e7b37217cb3a8f92c744fe835942602fdd4c1a8bc4741d3bfdce15e", size = 747000, upload-time = "2026-09-29T00:54:09.06Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/d8/1de3783908658d697a8cfc00582f61299ffba7796d7260c112e4700b1109/librt-0.16.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:6072e92dd876ff6ceeb6cf371e35e51f479349837391341f479b08df4564242b", size = 749569, upload-time = "2026-09-29T00:54:10.702Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/32/e817f66c96d6caa8bb8435ff93c4c220624d59efc506be59ab98fcd01d0c/librt-0.16.0-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:39ca4f2f2fe05de8e63493da592d84311adabe5bef52b193851981da9816b302", size = 729483, upload-time = "2026-09-29T00:54:12.25Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/c9/23992ccd2b9d22798fdd0f61353183a47414e651da782ad83eb680f50833/librt-0.16.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f9807485a908f00355820f18e91e045ffdcdc5adb68aaec40a1e2b88c5f7bba1", size = 776584, upload-time = "2026-09-29T00:54:13.837Z" },
+    { url = "https://files.pythonhosted.org/packages/67/3b/e8af957f08e6e2e8e566b099e43d2748418aa565df6ee1d9d3331209fdfe/librt-0.16.0-cp314-cp314t-win32.whl", hash = "sha256:94be5cb7bca4df6201f4183e9e4fa2086c655283d20b38cd84500a69057575a7", size = 104402, upload-time = "2026-09-29T00:54:15.568Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/1c/946e6443d7cd32347a086043395e421e52fd603c9163d2ec970ceab8eed6/librt-0.16.0-cp314-cp314t-win_amd64.whl", hash = "sha256:d46ca272b251d033dd4527b0dec5f261a28a52bd5fa0f99c117b0a1f8588cc2d", size = 126227, upload-time = "2026-09-29T00:54:17.165Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/a3/bc4f9959d3c62bcbf9e5fd3470a8bbd8bf33224ed4c25d7fba173201b8ac/librt-0.16.0-cp314-cp314t-win_arm64.whl", hash = "sha256:b9d6d4b14e92d876f8026b54c20c445f36425214c1081dc76f74e40db386b82b", size = 116493, upload-time = "2026-09-29T00:54:18.567Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/4b/10fdb42dfab4c1533e1570e686b18e86ff4328b406361b39fb3016667638/librt-0.16.0-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:6fe436af2eaf630474f491af5d032cbe45f93fcff5c3b9fe4ab194a7255b20ff", size = 149829, upload-time = "2026-09-29T00:54:19.933Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/30/a90ca13f1d3d91af1680000a4038536907018fbd51764767287a05d28b8b/librt-0.16.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:8ff5d26c529336be9bd7ae04483235d77778ee7d6444a95353102b542601ce81", size = 154522, upload-time = "2026-09-29T00:54:21.306Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/dd/bcf364eacfa070bb1fc88d503111ae7177914197ba1fa717c748926e7930/librt-0.16.0-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:909d8e3c1faee44cb762b1c519ff8613dcc5ceae5c99987a00917b5a31fd1d6a", size = 497593, upload-time = "2026-09-29T00:54:22.798Z" },
+    { url = "https://files.pythonhosted.org/packages/18/c1/2c4e81e347bdabfe8346bfc6dc37ae5e154d61c88e30848ec0606025a5e0/librt-0.16.0-cp315-cp315-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:6d4a64283ee61824b5790de882bc68e2d9d7a5143537cb7a966f7354f71646d4", size = 480459, upload-time = "2026-09-29T00:54:24.364Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/d7/fef2a3cb8400701be496f6e459876f650b3451f407e30cb243de571ae615/librt-0.16.0-cp315-cp315-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:5810ba811297fdf37a1531a57667cb8ace0842013ca8606bf9eb7c24cf4be154", size = 507814, upload-time = "2026-09-29T00:54:25.997Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/6f/53762927a32e9dc9eb1d1c1f3528da281290c86d96929a8af652f671266e/librt-0.16.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e56aaf8c167548dc8e5d6f3bd0f48dcdd299a23c73be3f744aab79d99e9c7f5d", size = 525114, upload-time = "2026-09-29T00:54:27.747Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/67/0b9d031f303c4e8c691a9a8ef9d272f13b530c11cc563b819df621b6a348/librt-0.16.0-cp315-cp315-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:8f36c58e33b304b525c6c9c5076399c6ebf1109e17b9051a05a407b091b9215b", size = 520465, upload-time = "2026-09-29T00:54:29.331Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/d5/2056a3a85864e882eb17a203a10ddb26fa748bc9718ec67e79059ab46cae/librt-0.16.0-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:242e00b3d4fa37c3d3c1ca5f5c9adb7d909ddb1eac9c41f2787320d00caa0af2", size = 537257, upload-time = "2026-09-29T00:54:30.915Z" },
+    { url = "https://files.pythonhosted.org/packages/54/57/e0d79790c163cbc0909e209a6f62e30bb713b647f905a176cdc64848fd4d/librt-0.16.0-cp315-cp315-musllinux_1_2_i686.whl", hash = "sha256:0253721561787b8df8443eb347b7a6461015354e5bdd37ee38a41fef220d2bb0", size = 527442, upload-time = "2026-09-29T00:54:32.478Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/50/1c0c95aba7af51f4752ea34fbf2eb79b36e7cae3a72536248e8c735de735/librt-0.16.0-cp315-cp315-musllinux_1_2_ppc64le.whl", hash = "sha256:3e483a8d69ede8067db70c0e83007423b6925de6fd53afed01d66160f2e9398c", size = 548139, upload-time = "2026-09-29T00:54:34.183Z" },
+    { url = "https://files.pythonhosted.org/packages/98/91/a8a43dd5138d4f55f88846b8f0c85454a4fad69952cebfcff9948f831290/librt-0.16.0-cp315-cp315-musllinux_1_2_riscv64.whl", hash = "sha256:69ba927445cfaaffb4081003ef5224c55a5c2ab67ef956f416ef744916e44121", size = 529708, upload-time = "2026-09-29T00:54:35.761Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/41/d5226881ab2b7c20d9d587b37bdd4a0ec8775a96d00ca87ac9f385587db4/librt-0.16.0-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:d6a365f2ab45a984d0e00eee0dd17f599ceab8cadab6ea07b6111c8132fc0e42", size = 567781, upload-time = "2026-09-29T00:54:37.409Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/bf/2345ba57a626e8c78c4ddcc724636a8df5a593fe46c1ee76bbf477e32b0d/librt-0.16.0-cp315-cp315-pyemscripten_2026_5_wasm32.whl", hash = "sha256:f01f3805f2dae4781c0c34b440e31740d082950bdaf89a6f601ad589a28af57a", size = 79177, upload-time = "2026-09-29T00:54:38.792Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/40/99e77936cc9207f629b077bf7cbc5e2f0827cddd7c29792f04ef881bd2c3/librt-0.16.0-cp315-cp315-win32.whl", hash = "sha256:b0e3e721c75d2e79a76d4422c79d7ba705fe1bbafec907037fe7a657a480a0e3", size = 100127, upload-time = "2026-09-29T00:54:40.251Z" },
+    { url = "https://files.pythonhosted.org/packages/56/1e/801fe26bc622061b9dfd010e166d94142cb774b733217e6d98d1c0cf2638/librt-0.16.0-cp315-cp315-win_amd64.whl", hash = "sha256:bc02954b1295de798bbdb0b4e2d8a28c2117de8b5c73dcbeb27dc32572dfb971", size = 120480, upload-time = "2026-09-29T00:54:41.722Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/a9/d533983055bd36e112627384c2c038845d1df882540b8bcefb566475640b/librt-0.16.0-cp315-cp315-win_arm64.whl", hash = "sha256:c5db585d43449a5f54303d4b2774e45e1babd975cfe1630a3d708c0b80c3e560", size = 110915, upload-time = "2026-09-29T00:54:43.052Z" },
+    { url = "https://files.pythonhosted.org/packages/55/fe/d62238fa9c653b0e0613290349467cb65711b5800e8e474f45e942a0ad95/librt-0.16.0-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:f06c689cb14afd9b612727553a5ec5a40febf113ca41c4413a2b0b334285884b", size = 159714, upload-time = "2026-09-29T00:54:44.497Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/ac/f31efe7818700be72ba4f9af8a80fa67c39808c8d26dacc55dc1f6f35172/librt-0.16.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:13b4e8aba90b0b1c82474e9844aa9ffe7ad3faa484350e1da64cb8188d903134", size = 162086, upload-time = "2026-09-29T00:54:45.968Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/16/4d7487bf86a9d7e8e18f37ba5538789233ea693637379b75701bd35ec9de/librt-0.16.0-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5a269c46ae327d8e6f8c1f85f7516cb52c0fa48127565a1105a4f4a05ff2a0b4", size = 712727, upload-time = "2026-09-29T00:54:47.486Z" },
+    { url = "https://files.pythonhosted.org/packages/77/74/50cd550ccc1a517b9ed62347625c01ddf8c4afad66490312677c011458f6/librt-0.16.0-cp315-cp315t-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:a33e0dae1f8592146a4764d54ce842b278732d21a84e17c3bbe6b1bc158a2248", size = 681106, upload-time = "2026-09-29T00:54:49.126Z" },
+    { url = "https://files.pythonhosted.org/packages/df/5d/7293f712975ee6fdd2251411fd9ef1c62bc99c7b83ecbe62dbc999b1fab7/librt-0.16.0-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:47ada6ea32636492c61aa8ad27ae3b9404bfe7a97e3ba946d1984236cc741da0", size = 705921, upload-time = "2026-09-29T00:54:50.905Z" },
+    { url = "https://files.pythonhosted.org/packages/67/f7/8aab946f11d59d1bece9ffc65d994b200c789a8ca5a95c17e17e609f912a/librt-0.16.0-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c43bd6e642d8a248c114327f98dd25ac5a7cb5aa168ef02f0559b91874df16b8", size = 731786, upload-time = "2026-09-29T00:54:52.584Z" },
+    { url = "https://files.pythonhosted.org/packages/43/76/1c42ab31e7cb8384ebf6d3af607213c495222474f4940443ae7639ab7685/librt-0.16.0-cp315-cp315t-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c3d1bb7841a816ace6449bb26d3f9560dbfa20e71c568d23f0f62bf1e68f50b1", size = 744964, upload-time = "2026-09-29T00:54:54.217Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/2e/4b19982d933d2dfced671e840b219e4c1cd3f507df6e6dabb51bbd4e3850/librt-0.16.0-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:3931f7a3db322e7f44e02a280e3949326ce9579ad388ee8d691dc7c76da9fb70", size = 765305, upload-time = "2026-09-29T00:54:55.815Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/1b/e872583de2dcb3ac7746e7a2321aeeb168274f3952a87dc66e05ddb29faf/librt-0.16.0-cp315-cp315t-musllinux_1_2_i686.whl", hash = "sha256:f4462528b6000afe8f16907b5c7c2553abf1df005ba5140e6eb394541c3624c3", size = 744959, upload-time = "2026-09-29T00:54:57.532Z" },
+    { url = "https://files.pythonhosted.org/packages/10/de/a18c6bcfb297af2674233e90b3c3661c3a0af0f1434a0c966d2ef708a835/librt-0.16.0-cp315-cp315t-musllinux_1_2_ppc64le.whl", hash = "sha256:80039ba9b6a7d5f1a0175a4cca6bbefead87bd854c80abad1cb30afe47a830db", size = 758138, upload-time = "2026-09-29T00:54:59.484Z" },
+    { url = "https://files.pythonhosted.org/packages/22/1c/0df1d732539c297bb1a093e1fe3204d2faf76a9022cf4e1d1c2fce059790/librt-0.16.0-cp315-cp315t-musllinux_1_2_riscv64.whl", hash = "sha256:7a1d272724b581bb6bc769dfdafed6da2ecc9886ba2450311de55a4ac2e1e9cd", size = 744268, upload-time = "2026-09-29T00:55:01.179Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/f7/ccaf31331f20c91a5bd9bd48ffc3f743f9c81bb5720cc7b2a720ca204f0a/librt-0.16.0-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:fbe4fb8c5445f7496d7f7f6bb0807875d09d47e6771ffa175fb2df2895fb86ba", size = 785783, upload-time = "2026-09-29T00:55:02.938Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/ea/7421d9e6db894cd6cd788b604b3394a163ded6b942052b6f96c23ccf08e1/librt-0.16.0-cp315-cp315t-win32.whl", hash = "sha256:375bfe6b572a8f6cfc398709356046173bf27e64c4c5edaf5f7062f051fb4bf9", size = 104355, upload-time = "2026-09-29T00:55:04.533Z" },
+    { url = "https://files.pythonhosted.org/packages/85/6d/7c31a506eb847bc58aeb2402d58e17605e821f68ab5df5e66fe274a6df41/librt-0.16.0-cp315-cp315t-win_amd64.whl", hash = "sha256:bd3150023d3dc2bc70f3784e59ffa1140d56ddba3d8125b3d6f9f85221279bfc", size = 126134, upload-time = "2026-09-29T00:55:06.017Z" },
+    { url = "https://files.pythonhosted.org/packages/36/69/7a5d10ac409c4da0355e054a14371871da9b5557fcc42772cd00181c6cce/librt-0.16.0-cp315-cp315t-win_arm64.whl", hash = "sha256:8ceafb70f2a4f0826f11031942e59c0728fd98da112dc346d4352bde1e486866", size = 116391, upload-time = "2026-09-29T00:55:07.484Z" },
+]
+
 [[package]]
 name = "markdown-it-py"
 version = "4.2.0"
@@ -492,6 +630,48 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e8/3d/1087453384dbde46a8c7f9356eead2c58be8a7bf156bca40243377c85715/more_itertools-11.1.0-py3-none-any.whl", hash = "sha256:4b65538ae22f6fed0ce4874efd317463a7489796a0939fa66824dd542125a192", size = 72226, upload-time = "2026-05-22T14:14:28.824Z" },
 ]
 
+[[package]]
+name = "mypy"
+version = "2.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "ast-serialize" },
+    { name = "librt", marker = "platform_python_implementation != 'PyPy'" },
+    { name = "mypy-extensions" },
+    { name = "pathspec" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/34/4e/64300736cf0a0373a27b94a91b664ee7382e36f77b0621bae6381da3e180/mypy-2.4.0.tar.gz", hash = "sha256:77bdaebd452f43fcfc4cc3ba94352a3ea537cd01e3f2d0879f48673d2ec00d6e", size = 4064425, upload-time = "2026-10-01T20:40:39.229Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e0/66/924be0b653372ed31ad5c48e26044cc00840e591943a56e61621cf05b60e/mypy-2.4.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:058165f564ccf559c68c70fec2091fca5891110480210c22594635e3f6683437", size = 14234230, upload-time = "2026-10-01T20:39:44.535Z" },
+    { url = "https://files.pythonhosted.org/packages/56/39/c4f176880a4177123576de6cec6309feea8f42fca2bf2f6584e88054f656/mypy-2.4.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9fa247e02b505a45a2775f69df38d360d197e3790bc60f717595db9eda358b6e", size = 14392944, upload-time = "2026-10-01T20:40:05.78Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/1c/26e16977e25ef2494a74f8ffc872a76ec2c3aa43c3156057cbdf88f352c5/mypy-2.4.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:20e9a5cd875837520c43db98dea0b6d0c2197833d95c30127d8f570fb9b1f00b", size = 15441463, upload-time = "2026-10-01T20:40:32.412Z" },
+    { url = "https://files.pythonhosted.org/packages/31/9c/9e4b049f0ecefbfd6817ca2a16eea55dd74a07950268edc6cffd29ccfe98/mypy-2.4.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:9f03a7828cca2b0adcd6662aee8f2711ff8830e1027641fdea3ab0b787483566", size = 15705406, upload-time = "2026-10-01T20:40:34.844Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/5e/e861b5f6c5ef9ee6cd24683aed1edecf82a26dbd536049f9b7850b586267/mypy-2.4.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:9279488933040b638c0ab739084c0ca100efeea6db581bf5d7628d8e89de53fe", size = 7897523, upload-time = "2026-10-01T20:39:39.861Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/87/61ffee58b25a956532a6006fae84918a2de849ed25f397492b2e815fe7b3/mypy-2.4.0-cp314-cp314-win_amd64.whl", hash = "sha256:2106b55105ba5ea9be4f53a24517fc5fa927ff1585edc9bc1a975abb72caef89", size = 11576345, upload-time = "2026-10-01T20:39:41.553Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/88/a331c20698971c2ce8d1c30f317fd61b5be13a85b1f053e12dfa22ac6568/mypy-2.4.0-cp314-cp314-win_arm64.whl", hash = "sha256:528c8744b8b5e3ecb8774f86af38d2376216816e9908317ad055f3c9c2d74799", size = 11172062, upload-time = "2026-10-01T20:38:59.534Z" },
+    { url = "https://files.pythonhosted.org/packages/47/c0/4f7daa73270dced8e86c6f4a911c68082d03a84e6c1ec9bd916028d66131/mypy-2.4.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0bb95cf34899e4619c61ab0a8667804e139e580b30d5df12af2102dfe44d0c97", size = 15711208, upload-time = "2026-10-01T20:39:30.597Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/05/f1afa303c678be24cf7a266d38fb24b3de4599a024c2f9ba0d5905a3efa3/mypy-2.4.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:86d616fe84c6eab8026f8c50ab5bcb90db780d2ccd233d971e34e92bede9b359", size = 15935442, upload-time = "2026-10-01T20:39:22.781Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/d6/6a1a45459b63716e0d035f4892a926d3054f0a8cbfa02551d228a9946083/mypy-2.4.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a3f86fd1313dd69d013e265f1fdcd12ea7a9d606f9875b2a3db946cd334555f3", size = 17240044, upload-time = "2026-10-01T20:39:32.95Z" },
+    { url = "https://files.pythonhosted.org/packages/87/85/ae33bee66c13f98d421964d87bf0888be941063bc75c1204a4cf142cf1cc/mypy-2.4.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:720434d48542ecfe84d32d287b727569d3fc8f5769acd39051130e490a5c295c", size = 17545856, upload-time = "2026-10-01T20:39:08.827Z" },
+    { url = "https://files.pythonhosted.org/packages/df/de/eeff209b65c3e267818d79333bb9f058da6e4e73761461bd94748a2eb628/mypy-2.4.0-cp314-cp314t-win_amd64.whl", hash = "sha256:a6e851b82c0661f69f1630fc16172c68787a6a9cf0991e7c6437d60976cdcd76", size = 12369342, upload-time = "2026-10-01T20:40:10.516Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/43/e62d8d5c1dd737aa248968302ff7d6eabf997c3301773ed8bcb64932ca77/mypy-2.4.0-cp314-cp314t-win_arm64.whl", hash = "sha256:3bd0e340f0ebe65c548210f53be3fd8192e83964760caf0c28bef368e68b0d37", size = 11849099, upload-time = "2026-10-01T20:39:51.834Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/5f/335b8980055118dc131355155883fb676bb2161a0d97e08658e479c776fb/mypy-2.4.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:afa89837d9be67e0cadfa33bca3bb7efdda98c3b07e74dc3b635ebfb1c8a926a", size = 14241302, upload-time = "2026-10-01T20:39:13.227Z" },
+    { url = "https://files.pythonhosted.org/packages/18/37/1482fdc49332b145828912b15f16eee0c4ca70a8bce0f6514ece79b14680/mypy-2.4.0-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fb443e81057896132d3642d6be219e6efd158691ac7883e3ba8fcb469865f05d", size = 14408200, upload-time = "2026-10-01T20:38:52.576Z" },
+    { url = "https://files.pythonhosted.org/packages/04/09/dce2e8f6c1b31053c430ef6963f6f7a38ccb49b90c5e01e37ed0129b7d5a/mypy-2.4.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7f38f57d344f8b6accb40e01c3d83cfc590498231724d16c07ffb7940f157818", size = 15444409, upload-time = "2026-10-01T20:39:18.1Z" },
+    { url = "https://files.pythonhosted.org/packages/43/c5/91b68306da4cd280cb15be35dbb5ffc343cabd67c4b121b6625bf2d13177/mypy-2.4.0-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:e76172710bd4e5eeae061abfd68347e5264632e02778be61784671ae3a2132f5", size = 15731186, upload-time = "2026-10-01T20:40:23.426Z" },
+    { url = "https://files.pythonhosted.org/packages/64/71/2d0340182a8f27352fb1e25531355951108b506097c433937e9eec452ffd/mypy-2.4.0-cp315-cp315-pyemscripten_2026_5_wasm32.whl", hash = "sha256:f83353e47ab520bf6fd4df8f5897d9fe081211f2fbc4b7d37736a3e3c166cbcf", size = 7897838, upload-time = "2026-10-01T20:38:50.779Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/08/32703c117e134c02efa2a82705bb40cee91eaedea10b6530e20eba651b1f/mypy-2.4.0-cp315-cp315-win_amd64.whl", hash = "sha256:970b221ed5842213d98e3c480c08f795ace4b1f81fb21e1b126bd0476bce1c34", size = 11575700, upload-time = "2026-10-01T20:39:53.982Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/08/08bb269feafdaad031046ee2d771528a64467e6a180f962afc28c4a3ccd8/mypy-2.4.0-cp315-cp315-win_arm64.whl", hash = "sha256:502b94b0b331f7dafe32fd6b151797ddbb4f32385b362e722c783a025e5954a3", size = 11172908, upload-time = "2026-10-01T20:40:12.91Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/3f/c5c92626006ca92c7686adfbece47fc6a0daa0e54753952a9ad13ce0561c/mypy-2.4.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:c9de622fd397495695d0598ddc789222bfcfec9d7c9ec3a1e385c855e3bc5e01", size = 15705970, upload-time = "2026-10-01T20:40:17.79Z" },
+    { url = "https://files.pythonhosted.org/packages/10/f3/863365f7997a76a5a1dd42d7902ab05afa4124e8419089cbca1ce2554db1/mypy-2.4.0-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9f459f0b4f0596d9d51fe7716b404b35287b99e77da98a7af90a65dd5fd61141", size = 15942234, upload-time = "2026-10-01T20:40:37.243Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/30/2f45b1f425a2c95dbe1a3f4d076bfd42b76e9615dba5906230703b14e4eb/mypy-2.4.0-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f9b028548b3af480e2b1ed8df14ccaac86f99c9f600d1580770ab7ba3dcd40f0", size = 17218364, upload-time = "2026-10-01T20:39:06.497Z" },
+    { url = "https://files.pythonhosted.org/packages/43/8b/5b2bbfc69e84800b78fa2dba16d995b003f93b573558e412c5490d6e6c37/mypy-2.4.0-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:cb734b2668c1f40d07ce093bbeb4407e9527c67901627b0e1679825be3f09975", size = 17557934, upload-time = "2026-10-01T20:38:46.077Z" },
+    { url = "https://files.pythonhosted.org/packages/df/c0/1a5dc601c22041a7bbfe1ff71cf097fbbd4fb49930867c6789baf5102106/mypy-2.4.0-cp315-cp315t-win_amd64.whl", hash = "sha256:172e30b8fea631fe310f0c665477f52d9ea40bb4e99e0c81dc30118563b13710", size = 12350955, upload-time = "2026-10-01T20:40:01.52Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/bc/697e9e26fc2a86c094ad67ee1e419971b7f01ded66ee66231b09e9f3e12e/mypy-2.4.0-cp315-cp315t-win_arm64.whl", hash = "sha256:5786ef987b3767e51aaa53f20aec104c0252b42ecda7aef8e8b4cbae279b05c5", size = 11842738, upload-time = "2026-10-01T20:40:30.026Z" },
+    { url = "https://files.pythonhosted.org/packages/81/12/46ae8670c98a3cd0286ca5645c2f918f8f6be65edfed81b916010619f668/mypy-2.4.0-py3-none-any.whl", hash = "sha256:d01c5d26a352acc6d5cf3128225477e1e8465e8d3029d4c345807fbf7f3cf093", size = 2800734, upload-time = "2026-10-01T20:39:26.837Z" },
+]
+
 [[package]]
 name = "mypy-extensions"
 version = "1.1.0"
@@ -576,10 +756,12 @@ version = "0.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "black" },
+    { name = "mypy" },
     { name = "openai" },
     { name = "pillow" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
+    { name = "pyexiftool" },
     { name = "pytest" },
     { name = "ruff" },
     { name = "typer" },
@@ -589,14 +771,16 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "black", specifier = ">=26.5.1" },
+    { name = "mypy", specifier = ">=2.4.0" },
     { name = "openai", specifier = ">=3.22.0" },
     { name = "pillow", specifier = ">=12.3.0" },
     { name = "pydantic", specifier = ">=2.13.5" },
     { name = "pydantic-settings", specifier = ">=2.15.0" },
+    { name = "pyexiftool", specifier = ">=0.5.6" },
     { name = "pytest", specifier = ">=9.1.1" },
     { name = "ruff", specifier = ">=0.16.9" },
     { name = "typer", specifier = ">=0.12.0" },
-    { name = "utils", specifier = ">=0.1.2", index = "https://gitea.schneiderserver.site/api/packages/mathias2784/pypi/simple" },
+    { name = "utils", specifier = ">=0.1.3", index = "https://gitea.schneiderserver.site/api/packages/mathias2784/pypi/simple" },
 ]
 
 [[package]]
@@ -746,6 +930,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/30/a4/2bffa9f8e804325a09867f0e9d30795c80ea9f8d62560bd1b6ad6220eb2f/pydantic_settings-2.15.0-py3-none-any.whl", hash = "sha256:0ba092c291c94baceb5eff768aa0d56400a457585bc0175925a5a5510303da42", size = 69413, upload-time = "2026-08-07T09:24:55.839Z" },
 ]
 
+[[package]]
+name = "pyexiftool"
+version = "0.5.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5e/48/406da6691d15abf3c8d399bce8bc588709a5b54e857fd7c22dad2f90c33c/PyExifTool-0.5.6.tar.gz", hash = "sha256:22a972c1c212d1ad5f61916fded5057333dcc48fb8e42eed12d2ff9665b367ae", size = 56365, upload-time = "2023-10-22T23:18:18.819Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fc/b9/175e9a1f8f3f94b22f622f0fcac853ae2c43cb4ac6034f849269c6086dac/PyExifTool-0.5.6-py3-none-any.whl", hash = "sha256:ac7d7836d2bf373f20aa558528f6b2222c4c0d896ed28c951a3ff8e6cec05a87", size = 51243, upload-time = "2023-10-22T23:18:16.614Z" },
+]
+
 [[package]]
 name = "pygments"
 version = "2.21.0"
@@ -1012,7 +1205,7 @@ wheels = [
 
 [[package]]
 name = "utils"
-version = "0.1.2"
+version = "0.1.3"
 source = { registry = "https://gitea.schneiderserver.site/api/packages/mathias2784/pypi/simple" }
 dependencies = [
     { name = "black" },
@@ -1024,9 +1217,9 @@ dependencies = [
     { name = "twine" },
     { name = "uvicorn" },
 ]
-sdist = { url = "https://gitea.schneiderserver.site/api/packages/mathias2784/pypi/files/utils/0.1.2/utils-0.1.2.tar.gz", hash = "sha256:c711755c3e2fabd9cd380e25e45bc19da9b901868a6eb67028968803c725b118" }
+sdist = { url = "https://gitea.schneiderserver.site/api/packages/mathias2784/pypi/files/utils/0.1.3/utils-0.1.3.tar.gz", hash = "sha256:8970a179573a63ab4c546cfd1da8ceca0d915bc4357b49ccffaba9b3d4a0195e" }
 wheels = [
-    { url = "https://gitea.schneiderserver.site/api/packages/mathias2784/pypi/files/utils/0.1.2/utils-0.1.2-py3-none-any.whl", hash = "sha256:f3335ba10bd8eb9f5c000287a6ee41987b188372f3dca2783d99e6e70513a5d7" },
+    { url = "https://gitea.schneiderserver.site/api/packages/mathias2784/pypi/files/utils/0.1.3/utils-0.1.3-py3-none-any.whl", hash = "sha256:c24078ba05f9f5b41fc3909598084b93c6df59f4ca60001e1e0b4fa55797e642" },
 ]
 
 [[package]]