How Images Are Found, Made and Checked
The image pipeline on Kugel Platform in plain language: search before generation, licence rules, model routing, deterministic measurement and repair, zero-cost edits, storage addresses and the size budget.
4 min read By Platform Documentation Guide #Architecture #Publishing
Media
Every image is an artifact with an owner
Every image on a Kugel Platform site, whether a hero, an inline photo, a diagram or a PDF cover, is an artifact: a file the platform found or made for one article or page, stored under that owner and loaded from a fixed public address.
The pipeline is designed to spend money only when it has to, to measure images rather than trust them, and to make every image traceable to the request that produced it.
Search first
Before anything is generated, the platform searches. It checks the site's own media library, then open-licence sources, and scores each candidate on cost, relevance, quality and licence. On this site the library and Openverse are switched on; Pexels, Unsplash and Google image search are switched off, and paid imports are capped at zero.
Only images whose licence allows commercial use are accepted, and an image with an unknown licence is excluded. Candidates smaller than 640 by 480 pixels are filtered out. Up to five scored candidates are kept for review before one is chosen.
An editor can also import an image from a specific web address. The editor is then responsible for confirming its licence.
Generate only when nothing fits
When search finds nothing suitable, the platform generates an image. The model depends on where the image will appear: on this site, article headers, inline article images and category pages all route to a fast model that supports fixed seeds, and a model named explicitly on a job always overrides that routing. Edits use separate edit models, one for whole-image variations and one for repainting a masked area.
Generation runs as a background job that can return several candidates at once. The job records what was asked for, which model answered, the seed and the timing, so a result can be traced and, where the model allows, reproduced.
Measure, then repair
Nothing is trusted just because it came back. Deterministic tools measure each candidate: contrast for any text on it, how closely its colours match the site's palette, whether important content stays inside a safe zone, its size and sharpness, its similarity to a reference image, and whether any lettering in it is legible.
In the CMS-Agent image loop, a model also judges each candidate against the brief, but when the measurements and the model disagree, the measurements win. A failing candidate can be repaired, for example with a masked edit, within the step's budget, and the best candidate is kept.
These measurements report problems; on their own they never block a publish. A person or an agent still decides.
Many edits need no model
Cropping to a focal point, resizing into responsive widths, splitting or composing images, adding a caption, badge or logo, rendering a styled headline as word art, and placing an image onto a flat surface in a photo all run as deterministic operations. The same input gives the same output, and there is no model cost.
A model edit is needed only when new pixels have to be invented, such as relighting a scene or replacing an object.
Where an image lives
Each artifact is stored under the id of the article or page it was made for. Readers load it from a public address that starts with /img/, followed by that id and a fingerprint of the file. Because the address is derived from the file's content, a new image always gets a new address and nothing needs cache-busting.
Pages may use only these verified addresses. A raw storage key, a data URI or a link to another website is refused when the object is saved. An artifact belongs to the request that produced it and cannot be copied into a different article; another article gets its own.
The size budget
Each site sets an image budget. On this site an image should be WebP and at most 150 KB. An image over budget is stored but flagged, with the expectation that it is shrunk unless a person asks for a larger one.
What the pipeline does not decide
It does not decide whether an image persuades. That judgement stays with the editor and the CMS-Agent reviewers. Paid stock stays off on this site until someone switches it on. And a passing measurement is evidence about the file, not proof that the image will help a page convert.