How the AI layer works

One pass, then everything reads from it.

Each image is shown once to a vision model. What comes back — a caption, alt text, tags, a human title, a small set of attributes, and an embedding — is stored per file in an indexed table on your own server.

Every AI feature in the plugin then reads that. Search by meaning, similar images, the folder groups, auto-filing: none of them asks the model a second time. One credit is spent per image, once.

What one description contains #

The attributes are enums rather than free text because their whole purpose is to be queried: kind = document has to mean the same thing on every row or the column is worth nothing. A new enum member ships in the service contract before it ships in a response.

orientation is deliberately not asked for. It is portrait, landscape or square, the plugin already knows the dimensions, and paying a model to measure a rectangle would be absurd.

The three provenance fields matter more than they look. Without them a stored description is unreproducible: nothing says what asked for it, so nothing can decide whether it is worth re-running. The plugin invents none of the three — a hash the client made up would answer the question wrongly rather than not at all.

What you need to turn it on #

1. A licence key, entered under VergeLabs Library → Settings → Licence.
2. Credits. One credit describes one image. See Licences and credits.

That is it. There is no separate plugin to install: the AI ships inside the plugin and is gated by the key.

Demo mode #

Demo mode invents captions locally from filenames and sends nothing anywhere. It exists so you can see the shape of the feature — the screens, the folder groups, the flow — before paying for anything.

Switch it on under VergeLabs Library → Settings → Licence (while no licence is set), or define VERGEML_AI_MOCK in wp-config.php.

Staging and development copies #

Describing is refused on a site whose wp_get_environment_type() is anything other than production. A cloned staging site arrives with the sealed key intact, and on a cloned network that would be every subsite spending the live balance at once.

To describe from a non-production copy anyway:

define( 'VERGEML_AI_ALLOW_NONPROD', true );

How a run behaves #

On screen, the AI screen loops REST calls: each step describes a group of files and reports what is left, so the progress bar is real and the run resumes exactly where it stopped if you reload.

• Up to 24 files per step, 8 in flight at once (vergeml_ai_parallel).
• Anything described in the last ten minutes is held back, so a re-click cannot describe the same file twice.

In the background, the same step function runs on WP-Cron, so you can close the tab. Twenty thousand images no longer need a browser held open.

• 20 seconds of work per tick, in chunks of 8, with a 30-second gap before the next tick is due.
• Single scheduled events, re-scheduled by each tick, so a finished job leaves no repeating hook behind.
• Progress tracks traffic, because WP-Cron fires when somebody visits the site. A site with a real system cron runs it every minute regardless. The screen says so.

It stops by itself when credits run out or the licence is refused, and says which.

Why the queue is on your side and not ours #

A server-side queue would have to hold your images at rest while it worked through them. The retention position this product sells is that nothing is kept — an image is described in the request that carries it and is never written down. Keeping the waiting on your server is what makes that true.

Where descriptions are stored #

One table, {prefix}vergeml_ai_index, one row per attachment, indexed on kind, has_people, has_text, document_type and described_at.

This is the plugin's own data, not yours: your folders are still terms, and alt text is still written into _wp_attachment_image_alt where WordPress keeps it. If you remove the plugin, the alt text stays and the index goes.

Full schema in Data model.

What reads the index #

Describing an image costs a credit, and so do proposing and planning folders; the price list has every figure. The rest is either local arithmetic or a call that is rate-limited but never debited.

Next #

• Descriptions and alt text
• Plan my folders
• Sorting a library nobody ever filed
• Licences and credits
• What leaves your site
• The AI service HTTP API