Files
masi f18bdb365c fix: characters keep their own names and faces; portraits match one style; animals drawn as animals
Linking
- An alias is refused when it is another character's name or alias, a shared title or
  kinship word ("Commander", "Master", "Oppa"), or a pasted list; a name resolves through an
  alias only when exactly one character has it, and never becomes a new character if anyone
  uses it. "Weed" had been filed under his sister, so the protagonist had no entry.
- maintain.py --aliases-only applies the same rules to stored data (an alias two characters
  share is dropped from both) and recounts mentions; maintain-job.sh now passes ACCESS_KEY,
  which config.py requires, and the optional Ollama key

Portraits
- A look keeps the description it was drawn from instead of a description of the result,
  so one bad render can no longer rewrite the character
- Animals and creatures (a short text check) get a prompt with no human wording; a colt had
  been drawn as a horse-headed man
- A new look uses the character's earlier non-transformed look for the face (never a later
  one: that copied the whole picture)
- Every portrait matches the art style of one illustration per novel (the first one, or
  "Use as style reference" in the wiki's viewer); a portrait as anchor leaked its costume

Tests cover the alias rules, learning, identity references and the style anchor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 03:07:33 -03:00

27 KiB
Raw Permalink Blame History

novel-illustrator

Illustrations, character and glossary cards, and "previously on" recaps for web novels read in LNReader. Illustrations are drawn in the style of each novel's cover.

  • URL: https://illustrate.marcospaulo.dev.br, public through Cloudflare Tunnel homelab-public (~/manifests/cloudflare-tunnel). The gallery is at /gallery.
  • Who can use it. Sign in with Gitea (git.marcospaulo.dev.br): opening /gallery, /library, /feedback or /me without access sends you to Gitea and back. Only logins in ALLOWED_USERS (manifest; now masi,lucas.maransaldi) get in; removing a name revokes that person at once. Each sign-in gets its own key (only its SHA-256 is stored, table reader_keys). /me creates a personal LNReader snippet and signs out this browser or every other one. The OAuth2 app novel-illustrator belongs to Gitea user masi; its id and secret are in Secret novel-illustrator-gitea-oauth (client-id, client-secret). The code exchange uses the in-cluster Gitea Service.
  • Access key. Every endpoint but /healthz and /auth/* answers 401 without a key. Sources: X-Access-Key header (reader.js), ?key= (the LNReader snippet and image URLs), or the ni_access cookie, set when /gallery or /library is opened once with ?key=. The master key acts as OWNER (masi). It lives in Secret novel-illustrator-access (access-key) and, for the owner, in ~/.config/novel-illustrator/ (lnreader-snippet.js, gallery-link.txt). Rotate: write a new key there, recreate the Secret, restart the Deployment, re-paste the snippet in LNReader. Images are Cache-Control: private so Cloudflare never serves them without the key.
  • Full deploy: rtk ./deploy.sh. All *.py files and reader.js go into ConfigMap novel-illustrator-app, mounted at /app/src. The ComfyUI dispatcher (~/manifests/comfyui/scripts/generate_asset.py) and the Qwen workflow are mounted from their canonical copies, not copied into this repo.
  • Routine operations: rtk ./scripts/ni status, rtk ./scripts/ni logs [--follow], and rtk ./scripts/ni health. For a reader-only update, use rtk ./scripts/ni deploy-reader; it updates just the reader script and verifies the live endpoint.
File Role
server.py HTTP API, input validation, startup
pipeline.py GPU priority queue: scenes, portraits, quality check, prefetch, recaps
store.py SQLite state on the story timeline
llm.py Language-model calls (ordered providers with fallback) and all prompts
auth.py Sign in with Gitea (OAuth2)
style-library/ Style presets, one file per family (manhwa.json, manga.json, american-comics.json, european-comics.json, painterly.json), plus render defaults.json; ConfigMap novel-illustrator-styles
scripts/style-bench.py Style and prompt benchmark for Qwen Image 2.1 (host-side; renders only while the queues are idle)
indexer.py Background pre-reading of Kavita novels
kavita.py Server-side chapter reads
gallery.py Gallery front page, the /v1/wiki JSON behind the wiki, and the /library request page
wiki.html The per-novel wiki (tabs, character sheets with editing, lightbox); renders /v1/wiki
maintain-job.sh Runs maintain.py as a Kubernetes Job, so deploys don't interrupt it
maintain.py One-off knowledge cleanup (prune non-characters, fold looks, drop generic terms)
fetcher-start.sh Entrypoint of the novel-fetcher Deployment (Node)
k8s/backup.yaml Nightly backup CronJob to MinIO
reader.js Runs inside the LNReader reader

One chapter's illustration

  1. Style, once per novel. MiniMax M3 (vision, through Headroom) describes the cover's style, cached in styles/<hash>.json. It describes only how things are drawn: medium, brushwork, palette, lighting. It never names subjects, because it's appended to every prompt and those would reappear in every scene.

  2. Scene. MiniMax M2.7 picks a moment that doesn't spoil the ending and writes a prompt around the image model's weak spots:

    • at most two main figures;
    • calm, grounded poses;
    • no contact between figures;
    • varied, story-led viewpoints: wide landscape and establishing shots, high or low angles, over-the-shoulder, side and rear views, or close shots when the moment calls for them;
    • characters may be small, seen from behind, or absent when the setting is the moment; references preserve identity, not pose or camera angle;
    • restrained gore.

    In the same call it returns:

    • anchor: a few words copied from the sentence where the moment happens;
    • what it learned (see Story knowledge);
    • a 3-sentence summary.
  3. Cast. [[Name]] placeholders become "the character from image N (kind)", with that character's portrait for the look they have in this chapter. Up to 4 are passed as Qwen 2.1 references. Missing portraits are drawn first (lazily). The kind label ("a dragon") stops Qwen blending a human and a creature into one figure.

  4. Render and check. One plain Qwen Image 2.1 pass at 1216×832, with a random seed each time.

    • MiniMax M3 vision then checks for clear defects: cloned or merged figures, a human with creature parts, broken limbs, a malformed foreground face or hand, extra figures, text.
    • On a defect it re-rolls once and keeps the better image. Results are in illustrations.qa and images/<id>.json.
    • A check failure never blocks the image.
  5. Saved as WebP (quality 85) in images/<id>.webp, with a row in illustrations. The status URL carries ?v=<mtime>, so "New image" gets a fresh URL.

Providers. config.DEFAULT_PROVIDERS is an ordered list: MiniMax through Headroom (MINIMAX_API_KEY), then Ollama Cloud (OLLAMA_API_KEY from Secret ollama-cloud, model glm-5.3-flash for text and images). Each request goes to the first provider with a key (and, for images, a vision model). After its retries fail it falls through to the next, and the switch is logged. Set LLM_PROVIDERS to a JSON array of {name, api: anthropic|ollama, url, key_env, text_model, vision_model} to reorder them or add more.

Text and image requests use different MiniMax models to reduce quota use. Chapter reading, scene design, recaps, and other text-only work use MiniMax M2.7. Requests that include an image use MiniMax M3, the only one of these models with image input. MiniMax's current Token Plan prices M2, M2.5, and M2.7 at the same per-token rate; M3 costs twice as much per token. Headroom forwards both through the existing MiniMax gateway. So:

  • pre-reading pauses while illustrations are queued;
  • maintain.py waits between characters until the queue is empty;
  • opening a chapter drops queued work for chapters already passed;
  • prompts send full descriptions only for the active look, plus names of the 80 most recurring other characters (about 17 KB instead of 90 KB).

See MiniMax quota routing and price comparison for provider sources and a per-request cost example.

GPU queue. Pending jobs are persisted in the queue table and resumed in order after a restart or deploy. Failed jobs aren't retried automatically; the reader offers a retry. One job runs at a time, because the GPU is shared. The reader's own requests (USER) run before prefetches (PREFETCH), and a queued prefetch you open is moved up. On CUDA out-of-memory the service calls ComfyUI's /free and retries.

Reading progress is per person (table progress): the spoiler cutoff, recaps and "Up to chapter N" follow whoever is signed in. Characters, images, styles and auto settings are shared. Opening a chapter drops only queued work behind every reader active in the last 14 days. An image painted ahead for one reader is shown to another only once they reach that chapter.

Illustrate up to chapter N. The wiki's Story so far tab queues every chapter without an image up to a chosen chapter (POST /v1/illustrations/batch, Kavita novels only). These jobs (kind backfill) run below the reader's requests and painting ahead, are never dropped as "behind", and don't pause pre-reading. Each chapter costs about 1 to 2 minutes of GPU, one scene-design call and one or two image checks. Cancel drops the queued ones. Each chapter row also has Illustrate / New image, "New image with a note" (a feedback repaint), its characters and all its images.

Painting ahead. When a Kavita chapter is opened, the next PREFETCH_AHEAD (3) chapters auto mode wants are queued as prefetches, nearest first (store.next_dues); in key mode that is the next three key chapters, however far apart. /v1/progress returns their positions (ahead) and the finished images (warm), which the reader downloads into the phone's cache before you get there. Chapters you move past are dropped from the queue.

On-device cache. The reader keeps illustrations and portraits in the phone's IndexedDB (ni-images, newest 400 kept), so a reopened chapter shows them instantly and offline. Image URLs are versioned (?v=), so a repaint is a new entry. Images are Cache-Control: private, so Cloudflare never stores them. reader.js itself is served with stale-while-revalidate, so the phone uses its copy and refreshes it in the background. The wiki's images and style samples use the browser's own HTTP cache (versioned and immutable).

Feedback (/feedback)

The reader has a Feedback button under each illustration, on each card, and next to Recap; feedback is stored in the feedback table with what it is about. MiniMax M2.7 (llm.FEEDBACK_SYSTEM) triages it into one action, checked against the stored data before it runs:

  • repaint: the stored prompt is revised with the fix (REVISE_SYSTEM) and re-rendered with the same references, defect check and re-roll (pipeline.revise_job, no chapter text needed);
  • redraw_portrait, edit_character (name, role, added aliases), merge, edit_term;
  • none: bugs, ideas and anything unclear go to review.

Statuses: new, working, applied, review, failed, then resolved or dismissed from the page. The reader follows its item until it settles and refreshes the image or cards when a fix lands. After a restart, items cut off mid-triage go to review (store.recover_feedback).

Cards and "Same person as"

Cards open as a bottom sheet: Escape, the phone's back button, swiping the handle down or tapping outside close it. The portrait enlarges on tap, and long alias lists collapse. "Same person as…" opens a searchable list with portraits; the top matches that share an uncommon word of a main name are marked "similar name". Before merging you choose which name to keep; the wiki's Split undoes a merge. UI icons are inline SVG in currentColor (no emoji).

Story knowledge (on the timeline)

All tables are keyed by the canonical novel: the same book from different sources (the WeTriedTLS plugin and the Kavita copy) resolves by normalized title to one key (novels table). The first source seen becomes canonical; here it's kavita:3.

  • Characters and looks. A character has named looks, each with its own portrait (looks). A timeline records which look is active from which chapter position (timeline). This handles:

    • transformations and alternate forms (Kim's reconstruction, Seo Ran's dragon and human forms);
    • regression loops, where MiniMax returns to an earlier look instead of inventing one;
    • flashbacks, which apply to the scene only.

    Portraits are drawn lazily, the first time a scene or a card needs them.

  • Identity. The scene and pre-read prompts list every known character by name and aliases, and give full look details for the ones named in the chapter. MiniMax can add aliases it sees ("Director Kim" → Kim Young-hoon). When a duplicate still happens, the card's "Same person as…" merges it:

    • the duplicate's names become aliases;
    • matching look labels are merged;
    • a clashing initial look is renamed initial (<name>);
    • the timeline moves over.
  • Glossary (terms), summaries (summaries) and recaps (recaps) are all placed by position.

  • Nothing past the reader's chapter is shown: cards, their look lists and the gallery are all cut at the chapter position.

Knowledge quality

  • Prompts are strict about categories.

    • A look is only a lasting visual change. Power levels, realms, injuries, one-off outfits and brief disguises don't count.
    • Characters are named individuals only: never groups, descriptions or translators.
    • Terms are recurring proper names only.
  • Mentions (mentions table) record which chapters each character name, alias or term occurs in. They're matched by script, case-sensitive, as whole words, with one compiled pattern of every name and term per novel: a single pass per chapter, about 46 ms instead of about 1.4 s with one search per name. The slow version pinned the CPU, failed the liveness probe and restarted the pod. Cards and prompts leave out anything seen in only one chapter until it recurs (unless it's first met in the current chapter). Terms seen in more than 20 chapters stop being underlined in the reader but stay in the wiki.

  • Aliases stay with one person (store.alias_problem). New aliases are refused when they are another character's name or alias, a shared title or kinship word ("Commander", "Master", "Oppa", "Grandma", with honorifics like "-nim" stripped), or a pasted list. A name is resolved through an alias only when exactly one character has it, and a name anyone already uses never becomes a new character. Before this, "Weed" was filed under his sister and every later mention of him went to her.

  • Portraits keep a character's face across looks. A new look is drawn with the character's earliest non-transformed portrait as an identity reference ("the same person as in image 1"). Transformations ("orc form", "lich form", another person's body) are drawn without one.

  • maintain.py <novel> [--dry-run] [--prune-only|--looks-only|--terms-only|--aliases-only], run inside the pod:

    • prunes non-characters: rules first, then one batched MiniMax M2.7 call for the rest;
    • folds inflated look lists: one MiniMax M2.7 call per character with more than 3 looks, keeping drawn portraits and moving the timeline over;
    • drops generic "terms" by a script test on the chapter texts, then recounts mentions;
    • drops aliases that break the rules above (an alias two characters share is removed from both), then recounts mentions.

    Always read the --dry-run output first. Run it with ./maintain-job.sh <novel> [flags], which starts a Kubernetes Job, so a deploy never kills a long consolidation. Each character is committed on its own, so a MiniMax timeout on one is skipped and doesn't stop the run.

Auto modes

  • Every N chapters (mode=every), or Key moments (mode=key). Key moments illustrates the chapters pre-reading rated at least 7 out of 10 for illustration value (summaries.score). Unrated chapters fall back to every 5th.
  • Chapters rated 9 or more get a second image of a different moment (slot 2, its own anchor).
  • The server decides (/v1/progress returns due, next_due and ahead). Prefetch paints the next three due chapters (see Painting ahead).

Wiki and character editing (/gallery?novel=)

  • Tabs: Characters (ranked by chapters they appear in; Main = 20+ chapters), Illustrations (lightbox with previous/next), Glossary (A–Z), Story so far (summaries in groups of 10 chapters, with thumbnails), Art style. Search filters the open tab. Everything is cut at the furthest chapter read.
  • Tapping a character opens a sheet with its portrait, aliases, role, appearance and look timeline. Edit changes:
    • name, role and aliases (aliases need a capital; descriptive ones like "the young man" are refused);
    • each look's label, appearance and first chapter; redraw (with a correction); upload your own picture (MiniMax M3 then describes it, off the GPU queue); delete a look (its chapters move to another look);
    • merge into another character, split looks and aliases into a new character (for two people mixed into one), delete the character.
  • API: POST /v1/characters with action = edit, edit_look, delete_look, upload (base64 image, at most 6 MB, verified with Pillow), split, delete, merge, redraw, look.
  • Images take ?w=240|480|720 for WebP thumbnails (quality 70). They are made when an image is saved, all three widths from one decode, and a startup pass fills in older images, so viewing a page only reads files. Image conversion runs two at a time (a page of 27 new thumbnails once exceeded the 256 MiB limit), and files are streamed from disk in 64 KB chunks.

Art style picker

The Art style tab of a novel's wiki works from style-library/, a library of manhwa, manga, American and European comic and painterly styles, one JSON file per family. Add a preset by appending it to its family's file; defaults.json holds the render settings every preset starts from. Research and benchmark results are in the style library notes. Each preset has seven reference points (line work, rendering, palette, lighting, texture, composition, mood), a prompt tuned for Qwen Image 2.1, and optional render settings (steps, guidance, negative prompt, hi-res).

  • Library cards show a shared sample (/v1/styles/library/<id>.webp; deploy.sh copies them from docs/research/bench/samples/).
  • /research (signed in, linked from the gallery) shows the research notes, every benchmark contact sheet with its images, and all library samples. The benchmark images are kept out of Git (.gitignore); deploy.sh copies the notes and docs/research/bench/{main,tune} to /data/research on the data volume. Rerun the benchmark with python3 scripts/style-bench.py <run> <stage> (stages a, b, c, d, samples, report), then deploy.
  • "Preview on this novel" renders up to three presets, or a custom style written point by point, on the best-rated moment the reader has already seen. Previews use no character references and a fixed seed. The current style is rendered on the same moment and seed for side-by-side comparison.
  • "Suggest for this novel" has the language model pick three presets that fit, with a reason each.
  • "Use" saves the style (preset or custom in styles/<hash>.json) and clears portrait paths, so each portrait is redrawn in the new style when next needed. Its render settings apply to every later image.
  • Existing illustrations keep their old style until "New image".

Novel requests (/library) and nightly updates

  • The page searches every source (about 30 s; /library?q=Title starts a search directly). Results are grouped by novel. Each source shows its chapter count, free versus locked, and latest chapter, loaded three at a time from GET /info. The novel's cover, author, status, genres and summary come from the first source that answers. Novels already in the library are marked, and "Add" queues a download. It's served by the illustrator and proxied to the novel-fetcher Deployment (internal Service novel-fetcher:8090).
  • The fetcher has its own pod on purpose: a pod is Ready only when all its containers are, so a failing helper must not take the illustrator offline.
  • It keeps a checkout of masi/lnreader-plugins (in-cluster Gitea) on the data volume at fetcher/, and reinstalls node_modules only when the lockfile changes.
  • Searches and downloads run as child processes of scripts/request-server.js. Plugins share node_modules (npm packages are external in the bundle), about 110 MB per child. Bundled standalone, all 165 needed 1.2 GB.
  • Download novels, make sure to search on alternative sites if not found and make sure they land in /srv/hdd/filebrowser/data/library/novels/<Title>/: PV pv-hdd-novel-library, writable, Retain. Kavita picks them up by folder watching (enabled globally; the watcher starts with Kavita, and it scans a changed folder after about 10 minutes).
  • Nightly at 04:17 (America/Sao_Paulo), update-novels.js appends newly free chapters to EPUBs built from a source (urn:lnreader:<plugin>:<path>). Positions never move. Pre-reading re-checks the page count every 6 hours.

Backups

  • k8s/backup.yaml runs nightly at 03:23. It takes a consistent SQLite snapshot (online backup API) plus a tar of characters/, styles/ and images/, and uploads them to MinIO bucket novel-illustrator-backups/<timestamp>/ and latest/, kept 14 days.
  • It uses a least-privilege key in Secret novel-illustrator-backup: MinIO user novel-illustrator-backup, policy scoped to that one bucket.
  • Restore: download latest/illustrator.db and latest/assets.tar (e.g. mc cp inside the minio pod). Scale the illustrator to 0, replace /srv/hdd/novel-illustrator/illustrator.db, untar the assets into the same folder, then scale back to 1. Restore-tested on 2026-09-26: integrity ok, 284 characters, 470 summaries.

Pre-reading (Kavita novels)

The first time a Kavita novel is opened, indexer.py starts reading it server-side in order, one chapter at a time:

  • one text-only MiniMax M2.7 call per chapter, about 5 s apart;
  • it records characters, looks, aliases, terms and a summary;
  • progress and the last error are in index_state.

Cards and recaps are then complete even for chapters that are never illustrated. Chapters come from Kavita through the read-only reader account: Secret novel-illustrator/kavita-reader, a copy of kavita/kavita-reader. For the Kavita plugin, the chapter path is <bookId>/<page> and position equals page.

LNReader setup (once per phone)

Settings → Reader → Custom code → add a JS snippet:

var s=document.createElement('script');s.src='https://illustrate.marcospaulo.dev.br/reader.js';document.head.appendChild(s);

It applies to every source. The hosted loader needs a connection; use the offline setup below to keep local text styling available without one. On each chapter it:

  • Places the illustration inside the text, right after the anchor sentence. It falls back to below the chapter for older images or when the sentence isn't found. "New image" (tap twice) repaints it.
  • Hides promo lines by default: short paragraphs that are only translator credits, Discord/ko-fi/Patreon plugs, or bare links. This is reversible in Reader features for this novel. The rule copies lnreader-plugins/scripts/clean-chapter.js, which novel fetch and novel clean use for EPUBs, so keep the two in sync.
  • Styles game-like text with local, deterministic rules. System panels require clear RPG cues such as a quest result, skill acquisition, or HP/XP status; generic angle-bracket prose, cultivation ranks, and ordinary stat-like lines stay in the novel's normal layout. Character sheets keep profile fields and Abilities, Skills, and Talents sections together in a compact panel. Alerts group adjacent skill unlocks, progression, level-ups, and rewards. Decimal gains, damage, currency, and stat changes receive inline styling. The Reader features for this novel menu independently toggles enhanced styling, system panels, dialogue, thoughts, value highlights, sound effects, footnotes, character/glossary links, and promo hiding. Preferences are saved per canonical novel and recognition uses text cues rather than a title list, so they work for current and future novels. Promo text stays out of illustration prompts even when shown. These features make no server or AI calls, and decorative markup is excluded from illustration text.
  • Underlines known names and terms, at most once every 10 paragraphs each. Tapping one opens a card: portrait, aliases, look, role, appearance. The card's fixes are:
    • Redraw portrait, with an optional correction ("older, with a beard");
    • "Look here", to set which look applies from this chapter;
    • "Same person as…".
  • Shows automation controls below the chapter: Auto Off / every 1, 2, 3, 5, 10 chapters, Pause, and Cancel on a queued chapter (which marks it skipped), plus Recap.
  • Reports progress (POST /v1/progress). For a Kavita novel with Auto on, this prefetches the next due chapter, so its image is ready when you get there. After two days away, the recap opens automatically.

Offline text styling

The one-line loader above needs a network connection to download its script. To keep text styling available offline, while connected open the reader script, copy its entire contents, and replace the one-line loader in LNReader's Custom code with that source. LNReader then stores the code on-device. Do not keep both versions installed.

System panels, dialogue and thought styles, value highlights, sound effects, footnotes, promo hiding, and their toggles run locally. Illustration controls, character/glossary cards, recaps, and automation need the service; while offline, the script shows the local text feature toggles instead. Since the code is stored in LNReader, repeat the copy after a reader script update.

API

novel is always the canonical key from /v1/novels/resolve. The endpoint list is in the server.py docstring. CORS is open (*) because the reader page runs on the source site's origin or file://. Access control is the key (header, ?key= or the ni_access cookie, which is SameSite=Lax).

Storage and secrets

  • pv-hdd-novel-illustrator → /srv/hdd/novel-illustrator (20Gi, hdd-storage, Retain, node kubernets). It holds images/, styles/, characters/ and illustrator.db (SQLite, WAL mode).

  • illustrator.db and characters/ are the only record of characters, looks, the glossary and summaries, so back those up. Images are regenerable but cost GPU time.

  • To restyle a novel: delete styles/<hash>.json, then redraw portraits from the cards.

  • Credentials stay in Kubernetes Secrets. In the novel-illustrator namespace:

    • minimax-headroom (api-key) is copied from agent-remote/headroom-minimax and mounted only into the illustrator server. Refresh this copy when rotating the source key;
    • kavita-reader (username, password);
    • novel-illustrator-backup (ACCESS_KEY, SECRET_KEY).

    Refresh the MiniMax copy without printing its value, then deploy:

    rtk kubectl get secret headroom-minimax -n agent-remote -o json \
      | rtk python3 -c 'import json,sys; s=json.load(sys.stdin); print(json.dumps({"apiVersion":"v1","kind":"Secret","metadata":{"name":"minimax-headroom","namespace":"novel-illustrator","labels":{"app.kubernetes.io/name":"novel-illustrator"}},"type":"Opaque","data":{"api-key":s["data"]["MINIMAX_API_KEY"]}}))' \
      | rtk kubectl apply -f -
    rtk ./deploy.sh
    

Performance notes

  • Qwen Image 2.1 needs about 16.4 GB of VRAM loaded at once. If other GPU users leave less free, ComfyUI swaps models from the HDD on every job (about 135 s instead of about 20 s). After a reboot, the first job pays that load once.
  • A scene takes about 40–110 s: MiniMax M2.7 scene design, the render, the MiniMax M3 image check, and occasionally a re-roll or a new portrait.
  • Pre-reading uses one MiniMax M2.7 text call per chapter and no GPU.