Instructions for “AI Rating & Tagging (for Darktable) v3.1”

This guide explains how to install, configure and use the Lua script “AI Rating & Tagging (for Darktable) V3.1”. The script integrates with DarkTable and enables AI-supported evaluation and tagging of images using a local LLM (e.g. LMStudio API). It is intended for personal, non-commercial use.

1. Introduction

The script analyzes images with a local AI (e.g. via LMStudio), generates ratings (ratings) and tags (tagging) and writes them to Darktable and optional XMP sidecar files. It uses a central JSON configuration file for settings such as API parameters, image processing, and Prompts.

Important notes:

The script requires a working local LMStudio installation with a compatible LLM (e.g. vision-enabled models like GPT-4V-like).
Darktable version 9.0.0 or later compatible.
First test the script with a few images to validate the configuration.

2. Requirements

Before installing the script, make sure the following components are present:

Darktable: Version 9.0.0 or newer (available for free at darktable.org).
Lua support: Darktable includes Lua by default. Make sure that LUA modules like JSON, socket.http and LTN12 are available (usually pre-installed).
LMStudio: A local installation of LMStudio (free of charge under lmstudio.ai). You need a vision-enabled model (e.g. a model that can handle images like Llava or similar).
Local LLM Server: Start LmStudio and load a compatible model. The server must be on a local port (e.g.. http://localhost:1234) Run and support the OpenAI compatible API.
Operating system: Linux, Windows or macOS (tested on Linux).
Hardware: Sufficient RAM and GPU for the LLM (recommended: at least 16 GB RAM, GPU with 8 GB VRAM).

3. Installation

Download script:
- Save the LUA script as ai_rating_tagging.lua in your Darktable Lua Script directory. By default this is:
  - Linux: ~/.config/darktable/lua/
  - Windows: %AppData%\DarkTable\lua\
  - macOS: ~/Library/Application Support/DarkTable/LUA/
- Create the directory if it doesn’t exist.
Create your own configuration file (optional):
- Create a file named ai_config.json in the same directory as the script.
- Use the following example configuration as a template (copy and customize it):
  jsoncopy{“api_settings”:{“lmstudio_api_url”:”http://localhost:1234/ v1/chat/completions”,”model_tag”:”local-model”,”max_tokens”:800,”tem . perature”:0.2,“retry_attempts”:3,“retry_delay”:2},“image_settings”: {“max_width”:800,”max_height”:600,”jpeg_quality”:85},”rating_scale”:[{„score“:0,“rating“:0},{„score“:20,“rating“:1},{„score“:40,“rating“:2},{„score“:60,“rating“:3},{„score“:80,“rating“:4},{„score“:100,“rating“:5}]”System_Prompt”:”You are an AI image rating assistant. Analyze the image and give a rating of 0-100 as well as relevant tags.”,”user_prompt”:”Rate this image on a scale of 0-100 based on composition, exposure and aesthetics, also give 3-5 relevant tags in a comma-separated list after ‘### keywords:’.}
- Explanation of the fields:
  - api_settings: URL and parameters for the LMStudio API.
  - image_settings: Maximum size and quality for image exports (to reduce the amount of data).
  - rating_scale: Mapping from AI scores to Darktable stars (0-5 stars).
  - system_prompt and user_prompt: Instructions for the AI (adjust it to your needs).
Enable script:
- Restart Darktable.
- The script should load automatically. Check the console for error messages (e.g. “Script loaded successfully – version 3.1”).
- In LightTable mode, a new panel “AI Rating & Tagging V3.1” should appear on the right.

4. Configuration

ai_config.json Customize: Edit the file with a text editor. Change the Prompts to optimize AI spending (e.g. for specific genres such as portraits or landscapes).
Rating Scale: fit the rating_scale to change the star ratings (e.g. stricter criteria).
API Tests: Make sure LMStudio is running and the URL is correct. The script automatically checks the accessibility.

5. Use

Select pictures:
- Open Darktable in LightTable mode.
- Select one or more images (e.g. with Ctrl+click).
Customize settings:
- Checkboxes are available in the AI Rating & Tagging V3.1 panel:
  - Overwrite rating: Enables/Disables AI Rating (Stars) in Darktable.
  - Overwrite description: Enables/disables writing the AI description.
  - Overwrite tagging: Enables/disables adding AI tags.
  - Overwrite XMP rating: Allows overwriting existing .rate.xmp files.
  - Show progress on screen: Displays detailed outputs directly in Darktable.
- These settings will be saved and restored at the next start.
Start AI Rating:
- Click on “AI Rating”.
- The script exports images (if necessary), sends them to the AI and applies the results.
- Progress is displayed in the console and optionally on the screen.
- Use STOP to cancel the process.
Check results:
- Reviews (stars) and tags appear in the image metadata.
- Descriptions are written in the description field.
- XMP files are created in the image directory (e.g.. Image.jpg.rate.xmp).
Troubleshooting:
- API not available: Check if LMStudio is running and the URL in ai_config.json is correct.
- Invalid answer: Customize the prompts to ensure the AI delivers the expected format (e.g. “### Keywords: Tag1, Tag2”).
- Script does not load: Make sure the file is in the correct directory and darktable has been restarted.
- Storage error: reduce max_width/Max_Height in the configuration for large images.
- Debug Outputs: Enable verbose_debug in script code for detailed logs.

6. License

The script is published under a custom license that allows free personal use but prohibits commercial use. The full license text is included in the script code. For commercial inquiries, contact the author.

7. Support and Updates

Documentation: visits www.net-fx.de For detailed help and examples.
Report error: Contact the author (Christoph Fischer) via the website.