Realist: An Open-Source Product Listing Audit Tool That Helps Sellers Catch Description Contradictions Early

E-commerce sellers fear one thing above all: a buyer receiving the product and saying it "doesn't match the description." A listing whose title says "Bluetooth 5.3" while the spec sheet says "5.0" is enough to earn you a return, a refund, or a one-star review. The problem is that sellers themselves struggle to spot these contradictions — because you already know what you meant, and your brain automatically fills in the gaps when you re-read it.

Realist is an open-source product listing audit tool, and its approach runs counter to most AI tools on the market: it doesn't help you write more listings — it runs a quality check on the listings you already have and tells you where the problems are.

What Realist Can Find

You paste in the title, description, and spec list, upload up to eight photos, and Realist returns a series of findings. Each finding indicates the field or photo involved, a confidence level, and what to do next.

For example, a test listing returned:

🔴 Contradiction · bluetooth_version · high · confidence 100%
 - title: Bluetooth 5.3
 - specifications.Bluetooth Version: 5.0
Next: Check the manufacturer's documentation and make every field agree.

Findings fall into four categories, and distinguishing between them is the tool's core design decision:

Type	Meaning
text_conflict	Two fields contradict each other. This is a fact about the listing.
image_mismatch	A photo appears to disagree with the text. This is an observation, with uncertainty attached.
possible_omission	Something visible isn't accounted for, such as an accessory in a photo.
unverified_claim	No provided material supports the claim. This is not an accusation.

A photo that doesn't show IP67 certification doesn't prove the product lacks IP67. Realist only ever says "please verify" — it never says "this is fake."

Design Choice: Not Handing Every Judgment to an LLM

The author's initial idea was to throw the entire listing at a model and ask whether it looked right. That path was ultimately rejected, and the reasoning runs through the entire project: for anything that can be compared precisely, a model's judgment is the wrong tool.

So the work was split into two halves.

Pure Python Handles the Comparison

Python code extracts Bluetooth version, IP rating, weight, quantity, battery capacity, and color from the title, description, and specs, normalizes them, and compares them against each other. 1.5 kg and 1500 g are consistent, because weight is first converted to grams. 5.3 versus 5.0 is always a conflict — no sampling involved, no temperature parameter involved. This is why text conflicts carry a confidence of 1.0 — it represents confidence that "these two fields really are inconsistent," not confidence about "which field is correct."

The Vision Model Only Reports What It Sees

The vision model returns structured observations per photo (colors, visible accessories, readable text, item counts) and never makes judgments. Python then compares these observations against the listing. A model saying "I see a USB cable" is far easier to trust and verify than "this listing looks incomplete."

The same split also determines how much each finding can be trusted. Color mismatches based on photos are capped at a confidence of 0.8, because lighting and image processing can alter colors. When OCR-recognized model numbers are close to but not identical to those in the listing, confidence is 0.5, because OCR misreads characters.

The temperature parameter is a setting that controls randomness when a large language model generates text. When temperature is set to 0, the model picks the highest-probability next token at every step, making output almost fully deterministic; the higher the temperature, the more random the sampling, and the same input can produce different outputs. This is why the author stresses that deterministic comparisons "involve no sampling and no temperature parameter" — handing Bluetooth version comparison to an LLM means that even with completely correct logic, sampling could produce different conclusions across two runs, whereas pure Python string and numeric comparisons always return the same result. For use cases like listing audits that need to be reproducible and explainable, determinism matters far more than flexibility, because what sellers need is a quality checker they can trust to produce the same findings on every run.

Qwen2.5-VL-7B is a vision-language model released by Alibaba's Qwen team, with roughly 7 billion parameters, capable of understanding both images and text and producing structured descriptions. At 7B, it falls into a size that can run locally on consumer-grade hardware, which is why Realist chose it: the author spins up this model locally via Ollama, sidestepping any dependence on cloud vision APIs. Ollama is a runtime that packages open-source large models as local services, offering simple command-line pulls and an HTTP interface so applications can call models like local functions, with photos never leaving 127.0.0.1. PaddleOCR is Baidu's open-source OCR tool for extracting visible text from photos; Realist uses it as an optional OCR layer to convert text such as model numbers and labels in images into text that can be compared against the listing, and it too uses the Apache-2.0 license, making commercial-use verification easy.

Why Open-Source Models Matter Here

This is the part where the open-source self-hosted approach genuinely earns its keep, rather than just going through the motions.

Seller data stays on the seller's own machine. Supplier photos, unreleased products, spec sheets with costs — to a seller, a listing draft is business data. Realist runs Qwen2.5-VL-7B (default qwen2.5vl:7b) through a local Ollama server. Photos are scaled down and stripped of metadata, then sent only to 127.0.0.1, nowhere else. The author also reminds users to verify the telemetry settings in their own environment and, for this reason, disabled Streamlit's usage statistics.

The model is a swappable component. The audit relies on a three-line VisionBackend interface. If a better vision model comes along, or if 7B is too slow, you change one class. With a hosted API, you'd have to rewrite your code around someone else's pricing and deprecation schedule.

The cost per audit is close to zero. A seller auditing hundreds of listings pays for electricity rather than tokens. This directly determines whether a $9/month plan is a business or a loss. Of course, it isn't free — a 7B vision model is slow on a pure-CPU machine, and the author hasn't run benchmarks yet.

The code is readable. The model and PaddleOCR (the optional OCR layer) both use the Apache-2.0 license, so the author can inspect commercial-use terms directly rather than trusting a terms page.

Streamlit is an open-source framework for rapidly building data apps and interactive UIs in pure Python, letting developers turn a script into a runnable web app without writing frontend code — Realist's paste-and-upload interface is built with it. Streamlit collects anonymous usage statistics by default, which is the privacy action referenced by "disabled Streamlit's usage statistics" in the article; for a tool that emphasizes data never leaving the local machine, turning off telemetry is a necessary detail for keeping that promise consistent. VisionBackend is a three-line abstract interface that decouples "who performs the visual observation" from business logic: as long as you implement this interface, you can swap Qwen2.5-VL for any other vision model or service without touching the comparison logic, finding categories, or confidence rules. This swappable design keeps the project from being tied to any single model's pricing or lifecycle.

What Was Tested, and What Wasn't

The author wrote a dedicated "honesty section."

Tested: The deterministic engine, with 10 unit tests. These cover that matching listings produce zero findings, that deliberately constructed problematic listings produce exactly the planted conflicts (Bluetooth version, color, weight, quantity), that unit equivalents aren't flagged, that claims supported by specs aren't flagged, that claims contradicted by specs are caught, and that HTML exports escape malicious input. The Streamlit UI also runs headless end-to-end.

Not tested: Photo checks used hand-written observations, so it's still impossible to say how accurate the model's actual observations are.

Not built: A labeled evaluation set with precision, recall, and false-positive rates, plus a pure-model baseline for comparison. The author's hypothesis is that the hybrid approach produces fewer false positives and more actionable findings than "asking an LLM whether it looks right." That's a hypothesis, not yet measured.

What's Next

1. Build an evaluation set of 30–50 listings and publish the numbers, including a baseline comparison.
2. Add more rule families: dimensions, voltage and wattage, compatibility claims, material claims.
3. Offer batch auditing and downloadable reports for agencies managing hundreds of listings. Five audits free, then roughly $9 to $29 per month. These prices are guesses awaiting validation, not market rates.

How to Get Started

The project is on GitHub (repo: rafayet-git/realist). To install:

python -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/streamlit run app.py

Photo analysis is optional: install Ollama and run ollama pull qwen2.5vl:7b. Without it, Realist runs text checks only and clearly tells you that photos weren't analyzed.

One-line Summary

Realist uses deterministic pure-Python comparisons plus local vision-model observations to QA e-commerce listings, avoiding false positives and protecting seller data.

Paragraph Summary

Realist is an open-source e-commerce product listing audit tool that doesn't help you write more listings but instead runs a quality check on existing titles, descriptions, specs, and photos, producing findings. Its core design splits the work in two: fields that can be compared precisely (Bluetooth version, weight, quantity, etc.) go to pure Python for normalization and comparison, with a confidence of 1.0; the vision model only returns structured observations per photo — colors, accessories, readable text — without judging truth or falsity, and then Python compares them against the listing. Findings fall into four categories — text_conflict, image_mismatch, possible_omission, and unverified_claim — clearly distinguishing facts from observations and never accusing anyone of fraud. The tool runs Qwen2.5-VL-7B locally via Ollama, so photos and drafts never leave the seller's machine, and each audit costs close to the price of electricity. The author candidly admits the deterministic engine has tests, but photo checks haven't been validated with a real model, and there's still no metrics-based evaluation set or baseline comparison.