WORK IN PROGRESS

This repo is in the process of being cleaned up and conformant to Nextcloud app guidelines

Tagger

An automated image tagging application for Nextcloud that uses AI (LLM) and EXIF metadata to organize your photos.

Features

• AI-Powered Tagging: Automatically generates descriptive tags and descriptions using a configurable LLM service (e.g., llama.cpp).
• EXIF Integration: Extracts existing keywords from image metadata and can write new tags/descriptions back into the EXIF data.
• Automated Workflow:
  • Listens for new file uploads via Nextcloud Webhooks.
  • Processes files through a persistent priority queue.
• Manual Control: Allows users to trigger tagging via the Nextcloud file dropdown menu.
• Persistence: Uses a priority queue that survives application restarts, ensuring no task is lost.
• Smart Prevention: Uses a specialized marker (AutoTaggedByTagger) to prevent redundant processing.

Architecture

The application follows a producer-consumer model:

1. Producers:
   • Webhook Listener: Captures NodeCreatedEvent from Nextcloud.
   • UI Actions: Captures manual requests from the Nextcloud user interface.
2. Queue: A PersistentQueue stores QueueItem objects, prioritizing manual requests over automated ones.
3. Consumer: A background worker processes the queue, performing:
   • EXIF extraction.
   • LLM analysis.
   • Tag application (to both Nextcloud and EXIF).

Development

#* AI-Powered Tagging: Automatically generates descriptive tags and descriptions using a configurable LLM service (e.g., llama.cpp).

Prerequisites

• Python 3
• exiftool (required for EXIF operations)
• A running LLM service (e.g., llama-server)

Running llama-server Example

To run a compatible server, you can use the following command:

llama-server -fa on -c 32768 -cram 0 --no-cache-prompt --models-max 1 --mmproj-auto --media-path /tmp --no-webui --host 0.0.0.0 --port 11434 --jinja

Key Parameters:

• -cram 0: Disables cache to prevent host memory exhaustion.
• --mmproj-auto: Enables automatic multi-modal projection, which is necessary for the model to parse images.
• --media-path /tmp: By mounting this path in the container, you can minimize data transfers between the app and the server.

Setup

1. Clone the repository.
2. Install dependencies:

   pip install -r requirements.txt
   

Running the App

To start the application for development:

make run

Testing

To verify the LLM integration and tag generation, run the test script with a sample image:

python3 test_tagging.py <path_to_image>

Viewing Results

The best way to see the added EXIF tags and descriptions within Nextcloud is by using the Memories app. Memories provides a beautiful gallery view that displays:

• EXIF Tags: All the automatically extracted and added keywords
• Descriptions: The AI-generated image descriptions
• Smart Organization: Photos organized by tags, dates, and locations

Install the Memories app from the Nextcloud App Store to get the full benefit of the Tagger's automatic tagging features.

Quality Assurance

Before committing, ensure code quality by running:

# Check Python syntax
python3 -m py_compile ex_app/lib/main.py
# Run linter
pylint ex_app/lib/main.py

License

This project is dedicated to the public domain under CC0 1.0 Universal.