No description
  • Python 71.7%
  • HTML 17.6%
  • Makefile 10.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-03 15:16:39 +01:00
plugins/tagger first commit 2026-11-03 15:16:39 +01:00
scripts first commit 2026-11-03 15:16:39 +01:00
ui first commit 2026-11-03 15:16:39 +01:00
vski/gallery first commit 2026-11-03 15:16:39 +01:00
.env.example first commit 2026-11-03 15:16:39 +01:00
.gitignore first commit 2026-11-03 15:16:39 +01:00
docker-compose.yml first commit 2026-11-03 15:16:39 +01:00
Dockerfile.minio first commit 2026-11-03 15:16:39 +01:00
Dockerfile.vski first commit 2026-11-03 15:16:39 +01:00
Makefile first commit 2026-11-03 15:16:39 +01:00
README.md first commit 2026-11-03 15:16:39 +01:00

example_gallery_tagger

An image gallery that tags itself. Upload a photo and a collection trigger wakes a Python plugin that captions and tags the image with a local Ollama vision model, embeds the caption, and writes everything back, so the gallery becomes searchable by meaning, not just by tag. All files live in S3-compatible object storage (MinIO), which also makes this project the end-to-end exercise of vski's S3 file storage mode.

            upload (multipart)
                  |
                  v
   +------------------------------+
   | vski :3102                   |      S3 bucket "gallery"
   |  photos collection           |----> photos/{recordId}/{file}
   |  trigger on update           |      (MinIO :9000, console :9001)
   +------------------------------+
          | plugin://tagger/on_photo
          v
   +------------------------------+     +---------------------+
   | tagger plugin (in container) |---->| Ollama on the host  |
   | 1. download image via /files |     | gemma4:12b  caption |
   | 2. caption + tags (vision)   |     | nomic-embed-text    |
   | 3. embed caption             |     +---------------------+
   | 4. write caption/tags back   |
   +------------------------------+
          |                     |
          v                     v
   photos.caption/tags    photos embeddings (vector search)

Layout

docker-compose.yml    MinIO + vski (S3 mode, plugin runtime in-container)
Dockerfile.vski       vski image + Python + vski SDK (plugin runtime)
Dockerfile.minio      local MinIO image, only for networks that cannot
                      pull minio/minio from Docker Hub
vski/gallery/         IaC: photos collection (+ trigger), tagger instance
plugins/tagger/       the tagger plugin (manifest + package)
scripts/              setup (bucket, admin, keys), seed, retag, status,
                      search, lsbucket
ui/                   single-file gallery UI (needs config.js from setup)

Requirements

  • Docker with the compose plugin
  • Ollama on the host with a vision model and a text embedding model. Defaults expect gemma4:12b and nomic-embed-text (ollama pull each). Any vision model works; change caption_model in vski/gallery/plugins.yaml.
  • Port 3102 (vski), 9000/9001 (MinIO), 8090 (UI) free on 127.0.0.1

Quick start

cp .env.example .env
make up            # MinIO + vski in S3 mode
make setup         # S3 bucket, first admin, admin + viewer API keys
make iac-apply     # gallery db, photos collection, tagger plugin instance
make seed          # download 12 photos and upload them
make status        # watch captions arrive (about a minute per photo)
make ui            # gallery at http://127.0.0.1:8090

Browse the bucket itself at http://127.0.0.1:9001 (console credentials are the MINIO_ROOT_USER / MINIO_ROOT_PASSWORD from .env).

Semantic search from the terminal:

make search q="misty mountain ruins"

The query is embedded with the same model the tagger used and matched against the stored caption vectors, so it finds photos whose captions are close in meaning even when no tag matches.

How the pieces work

Storage (the S3 part). With S3_BUCKET set, vski stores every uploaded file as an object keyed {collection}/{recordId}/{filename}, mirroring the local-disk layout, and the /files/{collection}/{recordId}/{filename} download route streams objects straight from the bucket. The replica file journal is off in S3 mode: the bucket is the shared storage. Deleting a record deletes its objects.

Uploads. A photo upload is one multipart POST: form fields become the record, each file part lands in storage under its field name, and the filename is stored in the image field. File parts are merged into the record before validation, so image can be (and is) required.

The trigger loop, without a loop. The multipart save publishes an update event, the collection trigger hands the record to plugin://tagger/on_photo, and the plugin writes its results back, which fires the same trigger again. The taggedFile field records which file the current tags describe: when it equals image, the plugin skips (that is also why re-uploading a new image to an existing record re-triggers tagging). Replace the image or run make retag to force a re-run.

Slow work, fast ack. Captioning a photo with a local vision model takes tens of seconds, longer than a trigger invocation may run, so on_photo acknowledges immediately and processes in a background task, one photo at a time (a semaphore keeps Ollama un-thrashed). Failures are written to the record's state/error fields, never thrown at the trigger.

Access. The gallery UI reads records with a viewer-role API key (read rules on photos allow viewer; the tagger plugin's service role plugin can update; writes and uploads use an admin key). Note that the /files/... download route is public by design: anyone with the URL can fetch a file.

Restricted networks

Docker Hub org images (minio/minio) are unreachable on some networks. This repo can build MinIO from source instead (needs Go >= 1.26):

make minio-binary   # compiles bin/minio
make minio-image    # builds image minio-local:dev
# then set in .env:  MINIO_IMAGE=minio-local:dev

The same override exists for the vski image itself (VSKI_IMAGE in .env, defaulting to a build with S3 support; the demo image adds Python for the plugin runtime).

Making it yours

  • Point PHOTOS in scripts/seed.py at your own images, or upload from the dashboard (records view supports file fields) or any SDK client.
  • Swap the vision or embedding model in vski/gallery/plugins.yaml and make retag (with a new embed model, tag fresh records or delete the old vectors first; a collection pins its embedding model and dimensions on first write).
  • Change the prompt in plugins/tagger/tagger/main.py to extract different metadata (colors, subjects, license plates, whatever your gallery needs).
  • The plugin only demonstrates local Ollama; any OpenAI-compatible vision endpoint works with the same code shape.

Teardown

make down       # stop containers
make clean      # also wipe volumes, venv, cached assets