ShelfReady: a private Amazon KDP listing studio running Gemma 3 4B on a CPU

What they built

Cody Topp is a designer and independent publisher who sells colouring books on Amazon KDP. The slowest part of each launch isn't the artwork but the listing: a title, subtitle, description and seven keyword boxes, each with its own limits and rules.

General AI tools speed that up but often produce phrases like 'Bestselling' or 'Free Bonus Pages' that break KDP's metadata guidelines and can get a listing flagged or suppressed. ShelfReady takes the book's facts (theme, audience, style, number of designs, trim size, marketplace) and in about 40 seconds returns a title and subtitle with a live 199-character meter, seven keyword phrases checked against the 50-character box, an HTML description using only KDP-supported tags, and a readiness score with every issue explained.

The design rule is that the model writes and the code decides. Gemma drafts the copy; a deterministic rules engine enforces the limits and banned language, and the app binds to localhost so unreleased books never leave the machine.

Setup

• Gemma 3 4B (about 2.5 GB quantised) running in Ollama
• An ordinary 8-core CPU with no GPU
• Pure Python standard library plus vanilla HTML, CSS and JS, MIT-licensed, no pip install or build step
• Model swappable with one environment variable, e.g. SHELFREADY_MODEL=gemma3:12b

How it works

1. It calls Ollama's /api/chat with structured outputs: a JSON schema that forces exactly four fields and exactly seven keywords, so the model can't return prose instead of JSON.
2. kdp_rules.py is a deterministic rules engine mapped to KDP's public help pages: title length, promotional and time-sensitive language, Amazon program names, a trademark tripwire, keyword duplicates, the 4,000-character description limit and allowed HTML tags. It has 27 unit tests.
3. Mechanical fixes (unclosed tags, bare paragraphs, 'colouring' vs 'coloring' for Amazon.com) are applied automatically and disclosed; judgement calls are flagged for the user instead.
4. If blocking errors remain, the exact error messages go back to Gemma for one targeted repair pass rather than a full regeneration.
5. Progress streams as NDJSON so the UI shows a real progress bar, and Cancel stops the model on the server.

Results & numbers

• A full listing in about 40 seconds on a CPU-only machine
• Typing 'Bestselling Edition' into the title drops the readiness score from 100 to 80 and flags it as prohibited sales-rank language
• Marginal cost per listing is zero, which the author says lets a one-time licence in the $19 to $29 range stay viable

Gotchas

• On a CPU-only machine a listing takes around 40 seconds instead of a few; the author accepts that for a once-per-book task
• Don't trust the model to enforce character limits or banned terms; that's why the rules live in code
• The author discloses that an AI coding agent wrote the code and drafted the write-up to his brief

“For a task you do once per book, I'll take private, free and permanent over instant.”— Cody Topp

Do it yourself

1. Install Ollama and pull Gemma 3 4B with ollama pull gemma3:4b.
2. Clone the ShelfReady repository from GitHub (ctopp11/shelfready).
3. Start it with python3 -m shelfready and open http://127.0.0.1:8787.
4. Enter your book's theme, audience, style, number of designs, trim size and marketplace, then generate.
5. Fix anything the readiness checks flag, then copy each field into KDP or export the listing as a text file.

ollama pull gemma3:4b
python3 -m shelfready      # http://127.0.0.1:8787