Program flow plan for ai-rating.py

1. Initialization and Configuration

  • Load imports and dependencies: The script imports modules like Flask, Pandas, Threading, Queue and a utility file (ai_rating_utils.py), which contains common functions.
  • Set configuration: a global config-Variable is initialized with default values (e.g. image size 896×896, temperature 0.1) and can be overwritten by arguments or web inputs.
  • Initialize global variables: Logging, progress tracking queues, parallel processing threads, and thread security locks are set up.
  • load promptly: System and user prompts are loaded from files or default values.

2. Mode Selection and Start

  • Parsing arguments: The command line (ArgParse) reads options such as folder path, host/port, API URL, model tag, subfolder inclusion, skip options and output formats (CSV/XMP).
  • Decision Console vs Web Mode:
    • Console Mode: If a folder_path is specified, the process_imagesfunction called.
    • Web Mode: if no folder_path is specified, the Flask app starts on the specified host/port (default: 127.0.0.1:5000). The app is waiting for web requests.
  • validation: Console mode checks if the folder path is valid and at least one output format (CSV or XMP) has been selected.

3. Main Processing (Process_Images Function)

This is the central process for the image evaluation. The function runs in a separate thread (in web mode) and processes images incrementally.

  • Preparation:
    • check on Darktable CLI: If not found, the process is aborted (fatal error).
    • Start logging: Status messages are sent via a log_func (console or web queue) output.
    • CSV Preparation: If CSV Output is enabled, the file name is generated (e.g.. ai_rating_results_{model_tag}.csv). Existing CSV files are read to skip already processed images (if skip_existing=true).
    • Collect images: The folder is searched (with or without a subfolder). Supported formats (e.g., JPG, PNG) are filtered. Images are only added if they have not yet been processed (based on XMP/CSV existence).
  • Main processing loop (for each picture):
    • Progress Update: In Web mode, the progress is updated (e.g. “Process Image X of Y”).
    • Image Conversion: The picture will be Darktable CLI Converted to a JPEG (size: 896×896, quality from config). If failed, skipping is skipped.
    • AI API Call: The converted JPEG is sent to the AI API (e.g., LM Studio) as a Base64 data URL. The answer contains ratings, keywords and metadata (tokens, duration).
    • answer parsing: The AI answer is broken down into a dictionary (ratings per criterion), keywords and overall rating.
    • Logging and Display: Detailed logs are created (e.g. “Total Rating: X”, Criteria List, Keywords). In Web mode, these are sent to the queue as JSON; output directly in the console.
    • Create Result Dictionary: A dictionary with all data (path, rating, keywords, timestamp, model tag, API metrics, prompts) is compiled.
    • Save:
      • XMP: If enabled, an XMP sidecar file is written next to the original image.
      • CSV: If enabled and the image is new, the result is added to the list (not immediately written to save performance).
  • Post processing:
    • CSV letter: After the loop, the CSV file is written or updated (with pandas). Existing data will be retained and new ones attached.
    • Close: Set status to “Completed”, exit thread. In Web mode, “###end_of_process###” is sent.

4. Web Mode (Flask App)

  • Routes and Functions:
    • /: shows the HTML template (from template.html).
    • /start_processing (POST): Starts processing with passed parameters (folders, options). validates inputs and starts a thread for process_images.
    • /stop_processing (Post): Stops ongoing processing.
    • /status: Returns current progress and CSV status.
    • /log: Get new log messages from the queue.
    • /get_prompts / /save_prompts: Loads/saves prompts/in files.
    • /download_last_csv: Downloads the last generated CSV.
    • /image_proxy: Image display proxy (e.g. converted JPEGs).
  • threading: Processing runs in a daemon thread so as not to block the web app. Locks prevent race conditions.

5. Troubleshooting and Closing

  • exceptions: Errors (e.g. API errors, file reading problems) are logged and lead to skipping or canceling.
  • Resources: Threads and queues are finished cleanly.
  • Output: In console mode, the script ends with a confirmation; The app continues to run in web mode.