fanfictioner

Turn a story idea into a text-free illustrated book. A local Gemma model (llama-server) plans the pages and writes the image prompts; sd-cli (stable-diffusion.cpp) draws them. You pick among three candidates at every image stage. Pages land in the book-reader library as NNN.png.

Requirements

Python 3, stdlib only
llama-server in router mode on localhost:8181 serving Gemma4-12B-qat-mtp
sd-cli with Vulkan, models under /data/LLM-models/SD
ImageMagick 7 (magick), $EDITOR, notify-send (libnotify), and kitty for inline previews (elsewhere candidates open with xdg-open); with --preview, a live view of the candidate being rendered opens in magick display, floated under Hyprland
~/.config/book-reader.conf with a LIBRARY="..." line

Usage

A story file is free prose. An optional frontmatter at the top sets the names instead of letting Gemma invent them; every key is optional:

---
series: A new life
book: Life as Daniel
chapter: 1
title: Meet Daniel
style: shoujo manga, soft pastel cel shading
---

series and book name the library folders, title is the lettering on the chapter's page 1, style is the art style of every page and reference sheet. With chapter, pages are saved as 01-001.png, 01-002.png, so every chapter of a book (one story file each) reads as one continuous book in book-reader. These values always override what Gemma writes in plan.md.

Editing the story after plan.md exists asks whether Gemma should revise the plan to match it, draft a new one (the old one is kept as plan.md.bak), or keep the plan as it is. Editing only the frontmatter is applied without Gemma.

fanfictioner story.md [--base zimage|krea2] [--preview]
fanfictioner --selftest

Work files go to a directory named after the story (stories/rooftop.md -> stories/rooftop/): plan.md, plan.json, refs/, cand/ and run.log. run.log records every generation, pick (with its seed), regeneration, prompt edit, skip and plan decision with a timestamp. Each sd-cli call also leaves its own log next to its candidates in cand/. Quit any time with q or Ctrl-C; the next run resumes from what is on disk.

Plan review keys: c confirm, e edit in $EDITOR, g ask Gemma to revise, q quit. Image review keys: 1-3 pick, r regenerate, p edit prompt, s skip edit (edit stage only), q quit.

Page 1 is the cover: its Title: line in plan.md is drawn as title lettering, the only text in the book. Remove the line for a cover without text. A page can override the base model with a Model: krea2 line in plan.md. To redo a page, delete NNN.png from the library and its cand/pNNN_* folder. To redo a reference sheet, delete refs/<Name>.png; pages already done keep the old look. A prompt edited with p applies until you pick and is not written back to plan.json.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. See LICENSE.

Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.