# 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

Copyright (C) 2026 Danilo M. <danix@danix.xyz>

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.