Multimodal Product Listing Generator

Product catalogues need titles, descriptions, features and SEO keywords at scale. Manual creation does not scale past a few hundred rows, and a vision model can draft all four from a photograph and a catalogue record in one call.

The interesting problem is not the drafting. It is that blindly storing model output creates operational and quality risks: a listing is a database record that a storefront renders and a customer reads, and a response that merely looks plausible is not the same as a response that is safe to store.

This build treats the generation step as the least trustworthy part of the system and puts everything around it under deterministic control.

• Catalogues need four structured fields per row, at volume.
• A model response is a proposal, not a record.
• The engineering question is what happens between the response and the database.

A naive vision-model workflow fails in ways that are individually mundane and collectively expensive. It can return malformed JSON, or JSON wrapped in a markdown fence. It can exceed a field limit that a storefront silently truncates. It can fail on a transient provider error, or retry a request that can never succeed and burn budget doing it.

Two failures are worse than the rest because they are invisible. Image payloads leaking into logs turn a debugging aid into a data-retention problem. And a model can produce claims that neither the image nor the catalogue metadata establishes — a fibre content, a certification, a performance figure — which a reviewer would catch and an automated pipeline would not.

• Malformed or fenced JSON that a naive parser rejects or a lenient one mis-reads.
• Field limits exceeded: a title over 60 characters, a description outside 150–200 words.
• Transient provider errors, and retries on requests that can never succeed.
• Image payloads leaking into logs.
• Claims the image and metadata do not establish.

The pipeline is a fixed sequence, not an agent loop. Every step is deterministic except the one model call, and each step can refuse to pass work forward.

Validation happens first and last: the input row is validated before a prompt is built, and the output is validated before anything is written. Between them, the model call is isolated behind an injectable transport so the entire pipeline is testable without a network.

• Nothing reaches the model until the catalogue row and image have passed validation.
• Nothing reaches storage until the response has passed the strict schema.
• Only safe output and metadata are written; the image payload is not logged.

The canonical implementation is a Python package with clean layer separation: pure validation, prompt construction, parsing, quality, claims, pipeline and transport. The pure layers perform no I/O, import no provider SDK and make no network calls, which is why they can be exhaustively tested and why the constants they enforce cannot drift from the prompt that requests them.

The prompt interpolates its numeric requirements from the same module the validators read, so the text asking for a 60-character title and the check rejecting a 61-character title can never disagree.

The portfolio implementation on this site is a TypeScript presentation adapter. It ports the deterministic layers — schema validation, quality scoring, claim extraction — faithfully enough to run in the browser-facing route, and nothing more. The Python repository remains the canonical implementation; the transport, retry classification, defensive parsing, safe logging, evaluation harness and review workflow all live there.

The public showcase is deterministic by default, and that default is the control. No API key is needed, no live model call is made from this site, and the uploaded image is previewed in the browser and never transmitted.

The honest counterpart to that safety is a limitation stated plainly in the UI: deterministic output is not evidence of live model quality. A fixture that passes every check demonstrates that the validation layer works, not that a vision model would.

• Deterministic mode is the public default; no API key is needed for the public showcase.
• The portfolio demo makes no live model calls.
• Uploaded images are previewed locally only in deterministic mode, and no image is persisted.
• The UI explains that deterministic output is not evidence of live model quality.
• The Python implementation validates file type, size, dimensions and EXIF handling.
• Live mode remains opt-in and must not be enabled in this public deployment.
• Claim candidates are review prompts, not hallucination findings.
• Unknown output fields are rejected.
• Credentials are never rendered, logged, or returned to the browser.

The measured evidence is about the engineering, not the model. The package has 514 tests passing at 98.26% core-package coverage, with CI enforcing a 90% floor on every push so the figure cannot silently become an unenforced claim. The deterministic evaluation passes 3 of 3 quality checks.

What that 3/3 means is narrow and worth stating precisely: it is a property of the deterministic fixture, not a model result. It shows the validation layer accepts conforming output and the pipeline runs end to end without a network. It says nothing about live model quality.

The constraints the validators enforce are fixed: a title of at most 60 characters, a description of 150–200 words, 5–7 features, and 10–15 distinct keyword terms.

Four things are explicitly not measured: live model quality, human review, hallucination rate, and user or business impact. No live benchmark has been run and no reviewer has adjudicated a claim, so no rate is reported — an unmeasured number is left unmeasured rather than estimated.

• Title maximum: 60 characters.
• Description range: 150–200 words.
• Features: 5–7.
• Keywords: 10–15 distinct terms.

The phases are ordered so that nothing is claimed before it can be measured. Phase 1 is what exists and is public; phases 2 and 3 are what would be needed before any claim about live quality could honestly be made.

The project is about engineering around the model rather than treating the model response as a trusted database record. Almost everything that makes it worth showing sits outside the generation call: the validator that rejects a 61-character title, the retry classifier that refuses to re-send a request that can never succeed, the parser that handles a fenced response without becoming permissive, the logger that never sees an image payload.

The second lesson is about evidence discipline. It would be easy to present a 3/3 deterministic pass rate as a quality result, and easier still to leave the ambiguity uncorrected. Naming what is not measured — live model quality, human review, hallucination rate, business impact — costs a more impressive-looking page and buys the only thing that makes the measured numbers worth reading.