Files
masi ad9b78f9f4 feat: a rich novel gets two to five images a chapter, moments and scenery
Slots now run 1..6. A novel set to density rich wants images_for(score) images per
chapter; every even slot is a place with no faces (placed at the sentence that
describes it), the rest are moments that avoid every earlier caption. Backfill
queues the missing slots in order. Other novels keep the old one-or-two behaviour.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-04 16:22:37 -03:00

1424 lines
66 KiB
Python

"""GPU work: scene illustrations, character portraits and their redraws, all through one
priority queue (a chapter the reader asked for beats a prefetch). Qwen Image 2.1 renders
via the shared generate_asset.py dispatcher; the language model (llm.py) designs scenes and
checks the results."""
import base64
from contextlib import contextmanager
import itertools
import json
import queue
import re
import shutil
import subprocess
import sys
import threading
import traceback
import urllib.request
from concurrent.futures import ThreadPoolExecutor
from PIL import Image
import kavita
import llm
import store
from config import CHARACTERS, COMFYUI_URLS, DATA, DISPATCHER, IMAGES, MAX_TEXT, STYLE_LIBRARY, STYLES, WEBP_QUALITY, key
USER, PREFETCH, BACKFILL = 0, 1, 2 # queue priorities: asked for, painting ahead, "illustrate up to N"
MAX_ALIASES = 4 # per character in prompts
MAX_OTHERS = 80 # not-mentioned characters listed by name in prompts
MAX_REFS = 4 # characters conditioned per scene (<= 2 main figures + margin)
# Plain single pass for scenes and portraits: an upscaler added halos/artifacts.
SCENE_ARGS = ["--width", "1216", "--height", "832"]
PORTRAIT_ARGS = ["--width", "832", "--height", "1216"]
# An interstitial is a place, not a face: a wider frame than a scene's.
SPLASH_ARGS = ["--width", "1344", "--height", "768"]
jobs = {} # id -> {"status", "kind", "priority", "error"?}; images on disk are the truth
jobs_lock = threading.Lock()
_work = queue.PriorityQueue()
_seq = itertools.count()
# ---- queue ------------------------------------------------------------------------
def submit(job_id, kind, priority, fn, *args):
"""Queue a job once (persisted, so restarts resume it). A queued prefetch the reader
now waits for is moved up."""
with jobs_lock:
job = jobs.get(job_id)
if job and job["status"] in ("queued", "running"):
if job["status"] == "queued" and priority < job["priority"]:
job["priority"], job["kind"] = priority, kind # a backfill chapter the reader now wants
store.queue_put(job_id, kind, priority, fn.__name__, list(args))
_work.put((priority, next(_seq), job_id, fn, args)) # stale entry is skipped
return False
jobs[job_id] = {"status": "queued", "kind": kind, "priority": priority}
store.queue_put(job_id, kind, priority, fn.__name__, list(args))
_work.put((priority, next(_seq), job_id, fn, args))
return True
def run_now(job_id, kind, fn, *args):
"""Jobs that only call MiniMax M3 (describing an uploaded picture) run on their own thread
instead of waiting behind GPU renders; tracked like queued jobs."""
with jobs_lock:
if jobs.get(job_id, {}).get("status") in ("queued", "running"):
return False
jobs[job_id] = {"status": "running", "kind": kind, "priority": USER}
def work():
try:
fn(job_id, *args)
with jobs_lock:
jobs[job_id] = {"status": "done", "kind": kind, "priority": USER}
except Exception as e:
traceback.print_exc()
with jobs_lock:
jobs[job_id] = {"status": "failed", "kind": kind, "priority": USER, "error": str(e)[:300]}
threading.Thread(target=work, daemon=True).start()
return True
def resume():
"""Re-queue jobs pending when the service last stopped, in their original order."""
for row in store.queue_pending():
fn = globals().get(row["fn"])
if row["fn"] in JOB_FUNCTIONS and callable(fn):
submit(row["id"], row["kind"], row["priority"], fn, *row["args"])
if row["kind"] == "backfill":
with jobs_lock:
batch = batches.setdefault(row["args"][0], {"ids": set(), "upto": row["args"][3]})
batch["ids"].add(row["id"])
batch["upto"] = max(batch["upto"], row["args"][3])
else:
store.queue_done(row["id"])
def cancel(job_id):
"""Drop a queued job; False if it is already running."""
with jobs_lock:
job = jobs.get(job_id)
if job and job["status"] == "running":
return False
jobs.pop(job_id, None)
store.queue_done(job_id)
return True
def job_status(job_id):
with jobs_lock:
job = jobs.get(job_id)
if not job:
return None
ahead = sum(1 for other_id, j in jobs.items()
if other_id != job_id and j["status"] == "queued" and j["priority"] <= job["priority"])
running = any(j["status"] == "running" for j in jobs.values())
out = {k: v for k, v in job.items() if k != "priority"}
if job["status"] == "queued":
out["queued_ahead"] = ahead + int(running)
return out
def worker():
# One job at a time: generation shares the single GPU with everything else.
while True:
_, _, job_id, fn, args = _work.get()
with jobs_lock:
job = jobs.get(job_id)
if not job or job["status"] != "queued":
continue # cancelled, or a stale entry of a job moved up the queue
job["status"] = "running"
try:
fn(job_id, *args)
store.queue_done(job_id)
with jobs_lock:
if job["kind"] in ("illustration", "backfill"):
jobs.pop(job_id, None)
else:
jobs[job_id] = {"status": "done", "kind": job["kind"], "priority": job["priority"]}
except Exception as e:
detail = (e.stdout + e.stderr)[-2000:] if isinstance(e, subprocess.CalledProcessError) else str(e)
print(f"job {job_id} failed: {detail}", file=sys.stderr)
traceback.print_exc()
store.queue_done(job_id) # failed jobs are retried by the reader, not on restart
with jobs_lock:
jobs[job_id] = {"status": "failed", "kind": job["kind"], "priority": job["priority"],
"error": "image generation failed" if isinstance(e, subprocess.CalledProcessError)
else str(e)[:300]}
# ---- rendering --------------------------------------------------------------------
def render(prompt, out, size_args, refs=(), attempts=3, extra=(), edit=None):
"""Run Qwen Image 2.1 via the shared dispatcher (random seed per call unless `extra` has
--seed; `extra` also carries the style's steps/guidance/negative). With `edit` (an image
path) the prompt is an instruction applied to that image instead.
The dispatcher is given every box in `COMFYUI_URLS` and owns the choice: it steps over a
box that is not answering and frees a box that runs out of memory. Deciding which card to
spend belongs with the thing that talks to ComfyUI, so that running the dispatcher by hand
on a laptop gets the same behaviour the service does.
"""
ref_args = [arg for ref in refs for arg in ("--ref", str(ref))] + list(extra)
mode = ["--mode", "edit", "--reference", str(edit)] if edit else ["--mode", "t2i"]
subprocess.run([sys.executable, DISPATCHER, "--model", "qwen-image-2.1", *mode,
"--servers", ",".join(COMFYUI_URLS), "--attempts", str(attempts),
"--prompt", prompt, *size_args, *ref_args,
"--output", str(out), "--timeout", "900"],
check=True, capture_output=True, text=True, timeout=960 * attempts)
def to_webp(png, out):
with Image.open(png) as im:
im.convert("RGB").save(out, "WEBP", quality=WEBP_QUALITY, method=6)
# ---- served copies: thumbnails and portrait WebPs ------------------------------------
# Made when an image is saved (and by a startup pass for older ones), so a page view only
# reads files. Decoding a full image takes tens of MB: 27 at once on one page exceeded the
# pod's 256 MiB and got it OOM-killed, so conversions run two at a time.
THUMB_WIDTHS = ("240", "480", "720") # fixed, so thumbnails cannot fill the disk
THUMB_NAME = re.compile(r"\.w\d+\.webp$")
IMAGE_WORK = threading.BoundedSemaphore(2)
def stale(out, source):
return not out.exists() or out.stat().st_mtime < source.stat().st_mtime
def thumb_path(file, width):
return file.with_name(f"{file.stem}.w{width}.webp")
def make_thumbnails(file):
"""Every thumbnail width of an image from one decode; only the missing or outdated ones."""
if not file.exists() or not any(stale(thumb_path(file, w), file) for w in THUMB_WIDTHS):
return
with IMAGE_WORK, Image.open(file) as im:
im = im.convert("RGB")
for width in THUMB_WIDTHS:
thumb = thumb_path(file, width)
if not stale(thumb, file): # another thread may have made it meanwhile
continue
small = im.copy()
small.thumbnail((int(width), int(width) * 2))
tmp = thumb.with_name(f"{thumb.stem}.{threading.get_ident()}.tmp")
# q70 with the slowest, best encoder: about 28% smaller than q80/method 4 on the
# style samples at no visible cost at thumbnail size.
small.save(tmp, "WEBP", quality=70, method=6)
tmp.replace(thumb)
def thumbnail(file, width):
"""The served file for ?w=: a thumbnail (made now if the image predates them) or the original."""
if not file or width not in THUMB_WIDTHS:
return file
make_thumbnails(file)
return thumb_path(file, width)
def portrait_webp(png):
"""Portraits are stored as lossless PNG (they are Qwen references); phones get a WebP and
its thumbnails, remade whenever the PNG is redrawn. None if the portrait isn't drawn."""
if not png.exists():
return None
webp = png.with_suffix(".webp")
if stale(webp, png):
with IMAGE_WORK:
if stale(webp, png):
tmp = webp.with_name(f"{webp.stem}.{threading.get_ident()}.tmp")
to_webp(png, tmp)
tmp.replace(webp)
make_thumbnails(webp)
return webp
def warm_thumbnails():
"""Startup pass: served copies for images saved before they were made at save time."""
made = 0
for file in [*IMAGES.glob("*.webp"), *STYLES.glob("*.webp"), *(STYLES / "library").glob("*.webp")]:
if not THUMB_NAME.search(file.name) and any(stale(thumb_path(file, w), file) for w in THUMB_WIDTHS):
make_thumbnails(file)
made += 1
for png in CHARACTERS.glob("*/*.png"):
if not any(t in png.name for t in (".tmp", ".upload", ".bust")) and (stale(png.with_suffix(".webp"), png)
or any(stale(thumb_path(png.with_suffix(".webp"), w), png)
for w in THUMB_WIDTHS)):
portrait_webp(png)
made += 1
if made:
print(f"thumbnails: made served copies for {made} images", file=sys.stderr)
def novel_style(novel, title="", cover="", genres=""):
path = STYLES / f"{key(novel)}.json"
if path.exists():
return json.loads(path.read_text())["style"]
image = fetch_cover(cover)
if image:
style = llm.chat(llm.STYLE_SYSTEM, f"Novel: {title}. Genres: {genres}.", image)["style"]
else:
style = llm.chat(llm.STYLE_SYSTEM, "No cover is available. Propose a fitting illustration style for "
f"the novel {title or novel} (genres: {genres}).")["style"]
path.write_text(json.dumps({"title": title, "style": style, "from_cover": bool(image)}))
return style
MAX_COVER = 5 * 1024 * 1024
def fetch_cover(url):
if not url or not url.startswith(("http://", "https://")):
return None
try:
req = urllib.request.Request(url, headers={"User-Agent": "novel-illustrator"})
with urllib.request.urlopen(req, timeout=20) as res:
if not res.headers.get_content_type().startswith("image/"):
return None
data = res.read(MAX_COVER + 1)
if len(data) > MAX_COVER:
return None
return base64.b64encode(data).decode()
except Exception:
return None
# ---- portraits ----------------------------------------------------------------------
TRANSFORMED = store.TRANSFORMED # a changed body, so a face reference from another look is wrong
def identity_reference(novel, name, label, description):
"""An earlier drawn look of the same character to keep their face consistent: the
earliest one in the story that is not itself a transformation. Never a later look (a
character's first look drawn from a later portrait copied that portrait whole, outfit
included), and none for transformations."""
if TRANSFORMED.search(label) or TRANSFORMED.search(description[:120]):
return None
with store.connect() as conn:
since = store.first_seen(conn, novel, name, label)
drawn = []
for l in store.looks_of(conn, novel, name):
first = store.first_seen(conn, novel, name, l["label"])
if (l["label"] != label and l["portrait"] and (DATA / l["portrait"]).exists()
and not TRANSFORMED.search(l["label"]) and first is not None
and (since is None or first < since)):
drawn.append((first, l["portrait"]))
return DATA / min(drawn)[1] if drawn else None
def anchor_path(novel):
return STYLES / f"{key(novel)}-anchor.png"
def style_anchor(novel):
"""The illustration every portrait of the novel matches in style. Seeds alone gave one cast
both painted and flat cel-shaded portraits from the same style text. It is a scene, not a
portrait: a portrait anchor in the same standing pose lent its robe and medallion to
characters whose clothing the text left vague."""
path = anchor_path(novel)
return path if path.exists() else None
def set_style_anchor(novel, illustration_id):
"""Make an illustration the novel's style anchor (a PNG copy, so repainting that chapter
doesn't silently change it)."""
source = image_path(illustration_id)
row = store.illustration(illustration_id)
if not source.exists() or not row or row["novel"] != novel:
raise ValueError("that illustration does not exist in this novel")
tmp = anchor_path(novel).with_suffix(".tmp.png")
with Image.open(source) as im:
im.convert("RGB").save(tmp, "PNG")
tmp.replace(anchor_path(novel))
anchor_path(novel).with_suffix(".json").write_text(json.dumps({"illustration": illustration_id}))
def portrait_body(description):
""""person" or "creature", from a short text call; a person when unsure."""
try:
return "creature" if llm.chat(llm.BODY_SYSTEM, description[:600]).get("body") == "creature" else "person"
except Exception:
return "person"
def draw_portrait(novel, style, name, label, description):
"""Render a look's reference portrait. The look keeps the description it was drawn from:
replacing it with a description of the result let one bad render (a colt drawn with arms)
rewrite the character for good. Returns (description, stored path)."""
folder = store.characters_dir(key(novel))
with store.connect() as conn:
row = conn.execute("SELECT portrait FROM looks WHERE novel = ? AND name = ? AND label = ?",
(novel, name, label)).fetchone()
# Keep an existing file name (redraws); new looks get "<name>-<label>".
portrait = DATA / row["portrait"] if row and row["portrait"] else folder / f"{key(name)}-{key(label)[:8]}.png"
tmp = portrait.with_suffix(".tmp.png")
creature = portrait_body(description) == "creature"
prompt = (llm.CREATURE_PORTRAIT_PROMPT if creature else llm.PORTRAIT_PROMPT).format(
description=description, style=style)
refs, notes = [], []
same = None if creature else identity_reference(novel, name, label, description)
if same:
refs.append(same)
notes.append(f"The same person as in image {len(refs)}: keep their face, hair, skin, age and build "
"exactly; only the clothing and equipment follow the description.")
anchor = style_anchor(novel)
if anchor:
refs.append(anchor)
notes.append(f"Image {len(refs)} is only a reference for the art style: match its exact rendering, "
"brushwork, shading, line quality, colour palette and lighting. Do not copy its "
"character, face, clothing, accessories or pose.")
render(" ".join([*notes, prompt]), tmp, PORTRAIT_ARGS, refs=refs, extra=render_extra(novel, seed=False))
tmp.replace(portrait)
portrait_webp(portrait)
relative = str(portrait.relative_to(DATA))
store.set_look_portrait(novel, name, label, description, relative)
return description, relative
def ensure_portrait(novel, style, character):
"""The character (at its current look) with a portrait, drawing it the first time."""
if character["portrait"] and (DATA / character["portrait"]).exists():
return character
description, portrait = draw_portrait(novel, style, character["name"], character["look"], character["description"])
return {**character, "description": description, "portrait": portrait}
def redraw_job(job_id, novel, name, label, hint, fid=None):
"""Reader asked for a new portrait of a look, optionally with a correction (from a card,
or from feedback `fid`, which is marked applied or failed)."""
with feedback_outcome(fid):
_redraw(novel, name, label, hint)
def _redraw(novel, name, label, hint):
with store.connect() as conn:
row = conn.execute("SELECT description FROM looks WHERE novel = ? AND name = ? AND label = ?",
(novel, name, label)).fetchone()
if not row:
raise ValueError("unknown look")
description = row["description"]
if hint:
description = llm.chat(llm.REDRAW_SYSTEM, f"Current description: {description}\n"
f"Reader's correction: {hint}")["description"]
draw_portrait(novel, novel_style(novel, store.novel_title(novel)), name, label, description)
# ---- scenes -----------------------------------------------------------------------
def roster_text(conn, novel, position, text):
"""Known characters and terms for a chapter prompt: the characters named in the text
with their looks, every other one by name and aliases only (so "Director Kim" can be
matched to a character known by full name without sending every description)."""
everyone = store.known_characters(conn, novel)
detailed = store.mentioned(everyone, text)
known = [store.with_look(conn, c, position) for c in detailed]
# Full description only for the active look; other looks by label (every MiniMax call
# pays for prompt size, and a 90 KB roster made each one minutes slower).
roster = "\n".join(
f"- {c['name']} (aliases: {', '.join(c['aliases'][:MAX_ALIASES]) or 'none'}); active look before this "
f"chapter: \"{c['look']}\": {c['description']}"
+ (f"; other looks: {', '.join(repr(l['label']) for l in c['looks'] if l['label'] != c['look'])}"
if len(c["looks"]) > 1 else "")
for c in known) or "none yet"
# Names only for the rest: the most recurring ones, so "Director Kim" can still be
# matched to a character known by full name.
counts = store.mention_counts(conn, novel)
others = sorted((c for c in everyone if c not in detailed
and (not counts or counts.get(("c", c["name"]), 0) >= store.RECURRING)),
key=lambda c: -counts.get(("c", c["name"]), 0))[:MAX_OTHERS]
if others:
roster += "\n\nOther known characters (name; aliases):\n" + "\n".join(
f"- {c['name']}" + (f"; {', '.join(c['aliases'][:MAX_ALIASES])}" if c["aliases"] else "")
for c in others)
terms = [r["term"] for r in conn.execute("SELECT term FROM terms WHERE novel = ?", (novel,))
if store.occurs(r["term"], text)]
return f"Known characters:\n{roster}\n\nKnown terms: {', '.join(terms) or 'none yet'}"
BUST = 0.42 # of a portrait's height: head and shoulders, the face and the outfit's top
def bust(portrait):
"""Head and shoulders of a portrait, as the scene reference. Given the whole standing figure,
Qwen copied its stiff pose into scenes and sometimes pasted it in as a second figure."""
out = portrait.with_name(f"{portrait.stem}.bust.png")
if stale(out, portrait):
with IMAGE_WORK, Image.open(portrait) as im:
tmp = out.with_name(f"{out.stem}.{threading.get_ident()}.tmp.png")
im.crop((0, 0, im.width, int(im.height * BUST))).save(tmp)
tmp.replace(out)
return out
def cast(req, style, scene, chapter_looks):
"""Resolve the scene's [[Name]] placeholders to reference portraits (drawing any that
are missing) and return the final prompt text and refs."""
refs, labels = [], {}
distant = {n.strip().casefold() for n in scene.get("distant") or [] if isinstance(n, str)}
for entry in scene.get("characters") or []:
name = (entry.get("name") or "").strip() if isinstance(entry, dict) else ""
if not name or name.casefold() in labels or len(refs) >= MAX_REFS:
continue
if name.casefold() in distant:
labels[name.casefold()] = "a small distant figure" # a reference got pasted in large
continue
with store.connect() as conn:
character = store.find_character(store.known_characters(conn, req["novel"]), name)
if character:
character = store.with_look(conn, character, req["position"], chapter_looks.get(character["name"]))
if not character:
continue
character = ensure_portrait(req["novel"], style, character)
refs.append(bust(DATA / character["portrait"]))
# Name what each reference is ("a young man", "a dragon"): with a human and a
# creature referenced together, Qwen otherwise blends them into one figure.
kind = re.split(r"[.,;]", character["description"], maxsplit=1)[0].strip()[:60]
label = f"the character from image {len(refs)} ({kind})" if kind else f"the character from image {len(refs)}"
for alias in [name, character["name"], *character["aliases"]]:
labels[alias.casefold()] = label
prompt = re.sub(r"\[\[([^\]]+)\]\]",
lambda m: labels.get(m.group(1).strip().casefold(), "a figure"), scene["prompt"])
if refs:
prompt += (" Use each reference image only to preserve that character's identity and visual design"
" (face, hair, skin tone, build and clothing). Follow the scene prompt for pose, body"
" orientation, gaze, camera angle and framing; do not copy the reference portrait's pose"
" or viewpoint. Each reference image shows a different individual: never mix features"
" between them, and never give a human the skin colour of a creature in the same scene.")
return prompt, refs
def check(png, description):
"""MiniMax M3 looks at the image for clear defects. A failing check never blocks the image."""
try:
verdict = llm.chat(llm.QA_SYSTEM, f"Scene description:\n{description}", llm.image_b64(png))
return {"ok": bool(verdict.get("ok", True)), "problems": [str(p)[:200] for p in verdict.get("problems") or []]}
except Exception as e:
return {"ok": True, "problems": [], "error": str(e)[:200]}
CLONES = re.compile(r"duplicat|clone|extra|additional|two (main )?figures|more (main )?figures|multiple", re.I)
REF_NOTE = re.compile(r" Use each reference image only.*$", re.S)
def without_refs(prompt):
"""The scene prompt for a render without reference images: "the character from image 1
(Human male)" becomes "a human male", and the note about references goes."""
prompt = REF_NOTE.sub("", prompt)
return re.sub(r"the character from image \d+(?: \(([^)]*)\))?",
lambda m: f"a {m.group(1).lower()}" if m.group(1) else "a figure", prompt)
def repair_instruction(problems):
"""An edit instruction from the image check's findings: fix those, change nothing else."""
listed = "; ".join(p.rstrip(".") for p in problems[:4])
return (f"Fix only these problems in this illustration: {listed}. Keep everything else exactly the "
"same: every character's face, hair, clothing and pose, the composition and framing, the "
"background, the lighting and the art style.")
def checked_render(prompt, description, refs, png, extra=(), args=SCENE_ARGS):
"""Render and check. A failed check gets one targeted repair first: the edit model fixes
the problems the check named and keeps everything that was right, instead of a fresh roll
discarding it. Then re-rolls (new seed); when the failures are duplicated or extra
figures, which references cause, the re-roll goes without them. At most three renders;
keeps the attempt with the fewest problems. Returns the check results."""
render(prompt, png, args, refs, extra=extra)
results = [check(png, description)]
if results[0]["ok"]:
return results
best = png
for n in (1, 2):
clones = all(any(CLONES.search(p) for p in r["problems"]) for r in results)
alt = png.with_name(f"{png.stem}.alt{n}.png")
if n == 1 and not clones and results[0]["problems"]:
try:
render(repair_instruction(results[0]["problems"]), alt, args, extra=extra, edit=png)
except subprocess.CalledProcessError as e: # no edit workflow: re-roll instead
print(f"repair edit failed, re-rolling: {(e.stdout + e.stderr)[-300:]}", file=sys.stderr)
render(prompt, alt, args, refs, extra=extra)
elif clones and refs:
render(without_refs(prompt), alt, args, (), extra=extra)
else:
render(prompt, alt, args, refs, extra=extra)
results.append(check(alt, description))
if results[-1]["ok"] or len(results[-1]["problems"]) < min(len(r["problems"]) for r in results[:-1]):
if best != png:
best.unlink()
best = alt
else:
alt.unlink()
if results[-1]["ok"]:
break
if best != png:
best.replace(png)
return results
def image_path(job_id):
return IMAGES / f"{job_id}.webp"
def slot_id(novel, chapter, slot=1):
"""Job/image id of a chapter's illustration; slot 2 is the second image of a chapter
rated highly enough for two."""
return key(novel, chapter) if slot == 1 else key(novel, chapter, str(slot))
MAX_SLOTS = 6 # a chapter's own images; slot 0 is the establishing shot before it
def slot_kind(novel, slot):
"""What a chapter's slot holds. Slot 1 is always the key moment. In a "rich" novel every
even slot after it is a place with no faces (fast to paint, and a rest between the
scenes); otherwise every slot is a moment, as before."""
return "scenery" if slot % 2 == 0 and store.get_settings(novel)["density"] == "rich" else "moment"
def earlier_moments(novel, chapter, slot):
"""The captions of the chapter's earlier images, so a new one does not repeat a beat."""
rows = [store.illustration(slot_id(novel, chapter, n)) for n in range(1, slot)]
return [r["moment"] for r in rows if r and r["moment"]]
def splash_id(novel, chapter):
"""Job/image id of the establishing shot printed before a chapter (slot 0). Its own
namespace, so it never collides with the chapter's own illustrations."""
return key(novel, "splash", chapter)
def generate(job_id, req, slot=1):
style = novel_style(req["novel"], req["title"], req.get("cover", ""), req.get("genres", ""))
text = req["text"][:MAX_TEXT]
avoid = ""
seen = earlier_moments(req["novel"], req["chapter"], slot)
if seen:
avoid = ("\n\nThis chapter already has illustrations of these moments; pick a clearly different one "
"(another scene, place or time in the chapter) and use a distinctly different "
"viewpoint or framing:\n- " + "\n- ".join(seen))
if slot_kind(req["novel"], slot) == "scenery":
return place_shot(job_id, req, llm.SCENERY_SYSTEM, avoid, slot)
with store.connect() as conn:
context = roster_text(conn, req["novel"], req["position"], text)
scene = llm.chat(llm.SCENE_SYSTEM, f"Novel: {req['title']}\nChapter: {req['chapter_title']}\n"
f"Genres: {req.get('genres') or 'unspecified'}\n\n"
f"{context}\n\nChapter text:\n{text}{avoid}")
with store.connect() as conn:
chapter_looks = store.learn(conn, req["novel"], req["position"], scene, text)
prompt, refs = cast(req, style, scene, chapter_looks)
png = image_path(job_id).with_suffix(".tmp.png")
qa = checked_render(styled(prompt, style, req["novel"]), prompt, refs, png, render_extra(req["novel"]))
# Served to phones: store only a compressed WebP. Portraits stay lossless PNG,
# since they are fed back to Qwen as references.
out = image_path(job_id).with_suffix(".tmp.webp")
to_webp(png, out)
png.unlink()
(IMAGES / f"{job_id}.json").write_text(json.dumps(
{"novel": req["novel"], "chapter": req["chapter"], "slot": slot, "kind": "moment",
"moment": scene.get("moment"), "anchor": scene.get("anchor"), "characters": [c.get("name") for c in scene.get("characters") or []
if isinstance(c, dict)],
"looks": chapter_looks, "position": req["position"], "qa": qa,
"references": [str(r.relative_to(DATA)) for r in refs], "prompt": prompt}, ensure_ascii=False))
store.record_illustration(job_id, req, scene, qa)
out.rename(image_path(job_id))
make_thumbnails(image_path(job_id))
if not style_anchor(req["novel"]):
set_style_anchor(req["novel"], job_id) # the novel's first illustration sets its look
def splash(job_id, req):
"""The establishing shot printed before a chapter. No character references: an
interstitial that pastes a portrait in becomes a close-up of a face, which is the one
thing it must not be. The QA check still runs, for clones and malformed shapes."""
previous = ""
with store.connect() as conn:
row = conn.execute("SELECT summary FROM summaries WHERE novel = ? AND position = ?",
(req["novel"], req["position"] - 1)).fetchone()
if row and row["summary"]:
previous = f"\n\nThe chapter before ended like this, so this shot is somewhere else: {row['summary']}"
place_shot(job_id, req, llm.SPLASH_SYSTEM, previous, 0)
def place_shot(job_id, req, system, extra, slot):
"""A picture of a place, with no character in it: the establishing shot (slot 0, printed
before the chapter) or a scenery slot (placed where the text describes it)."""
style = novel_style(req["novel"], req["title"], req.get("cover", ""), req.get("genres", ""))
text = req["text"][:MAX_TEXT]
scene = llm.chat(system, f"Novel: {req['title']}\nChapter: {req['chapter_title']}\n\n"
f"Chapter text:\n{text}{extra}")
if not scene.get("prompt"):
return
png = image_path(job_id).with_suffix(".tmp.png")
qa = checked_render(styled(scene["prompt"], style, req["novel"]),
"A wide view of a place, with no named character in it.",
(), png, render_extra(req["novel"]), args=SPLASH_ARGS)
out = image_path(job_id).with_suffix(".tmp.webp")
to_webp(png, out)
png.unlink()
record = {"novel": req["novel"], "chapter": req["chapter"], "slot": slot, "kind": "scenery",
"moment": scene.get("moment"), "anchor": scene.get("anchor"), "characters": [],
"position": req["position"], "qa": qa, "references": [], "prompt": scene["prompt"]}
if slot == 0:
record["splash"] = True
(IMAGES / f"{job_id}.json").write_text(json.dumps(record, ensure_ascii=False))
store.record_illustration(job_id, req, scene, qa)
out.rename(image_path(job_id))
make_thumbnails(image_path(job_id))
def illustration_status(job_id):
if image_path(job_id).exists():
row = store.illustration(job_id) or {}
version = int(image_path(job_id).stat().st_mtime) # "New image" reuses the id
return {"id": job_id, "status": "done", "image": f"/v1/illustrations/{job_id}.webp?v={version}",
"anchor": row.get("anchor") or "", "moment": row.get("moment") or ""}
job = job_status(job_id)
if job:
return {"id": job_id, **job}
return {"id": job_id, "status": "skipped" if store.is_skipped(job_id) else "missing"}
def chapter_status(novel, chapter):
"""The chapter's main illustration status, with its other images under "extra"."""
status = illustration_status(slot_id(novel, chapter))
others = [{**illustration_status(slot_id(novel, chapter, n)), "slot": n} for n in range(2, MAX_SLOTS + 1)]
status["extra"] = [o for o in others if o["status"] not in ("missing", "skipped")]
return status
def request_chapter(req, priority, images=1):
"""Queue a chapter's illustration(s); the second runs after the first, whose moment it avoids."""
for slot in range(1, images + 1):
job_id = slot_id(req["novel"], req["chapter"], slot)
if not image_path(job_id).exists():
submit(job_id, "illustration", priority, generate, req, slot)
# ---- prefetch ---------------------------------------------------------------------
def _job_place(row):
"""(novel, position) of a persisted illustration job."""
if row["fn"] == "generate":
req = row["args"][0]
return req.get("novel"), req.get("position")
if row["fn"] == "prefetch_job":
return row["args"][0], row["args"][3]
return None, None
def drop_behind(novel, position):
"""Every recent reader of the novel has moved past these chapters: queued (not running)
illustrations for them would only delay the ones ahead. Reopening a chapter requests it
again. "Illustrate up to N" chapters are behind on purpose and stay."""
slowest = store.slowest_position(novel)
position = min(position, slowest) if slowest is not None else position
dropped = 0
for row in store.queue_pending():
if row["kind"] == "backfill":
continue
job_novel, job_position = _job_place(row)
if job_novel == novel and job_position is not None and job_position < position and cancel(row["id"]):
dropped += 1
return dropped
def busy():
"""Illustrations are waiting: background MiniMax M2.7 work (pre-reading) should hold off."""
with jobs_lock:
return any(j["status"] in ("queued", "running") and j["kind"] == "illustration" for j in jobs.values())
PREFETCH_AHEAD = 3 # chapters auto mode wants that are painted ahead of the reader
def prefetch_next(novel, source, chapter_path, position, title):
"""The reader opened a chapter of a Kavita novel with auto on: paint the next chapters
auto mode wants (every N, or the next key moments), nearest first, so they are ready
when the reader gets there. Returns [{"position", "chapter"}] for those chapters."""
parsed = kavita.parse_chapter_path(chapter_path)
if not kavita.enabled() or not source.startswith("kavita:") or not parsed or position is None:
return []
book, page = parsed
ahead = []
for target in store.next_dues(novel, position, PREFETCH_AHEAD):
chapter = f"{book}/{page + target - position}"
for slot in range(1, store.images_due(novel, target) + 1):
job_id = slot_id(novel, chapter, slot)
if not image_path(job_id).exists() and not store.is_skipped(job_id):
submit(job_id, "illustration", PREFETCH, prefetch_job, novel, book, page + target - position,
target, title, slot)
ahead.append({"position": target, "chapter": chapter})
return ahead
def prefetch_job(job_id, novel, book, page, position, title, slot=1):
got = kavita.chapter(book, page)
if not got:
return # past the last chapter
chapter_title, text = got
generate(job_id, {"novel": novel, "chapter": f"{book}/{page}", "position": position, "title": title,
"chapter_title": chapter_title, "text": text}, slot)
# ---- illustrate from the server's copy (Kavita) ----------------------------------------
MINUTES_PER_CHAPTER = 1.5 # scene design, render, check, sometimes a re-roll or a portrait
batches = {} # novel -> {"ids": set of job ids, "upto": position}; under jobs_lock
def kavita_book(novel):
"""(book, chapter count) of the novel's Kavita copy, or None when the server can't read it."""
if not kavita.enabled():
return None
with store.connect() as conn: # pre-reading registers only Kavita copies here
row = conn.execute("SELECT book, total FROM index_state WHERE novel = ?", (novel,)).fetchone()
return (row["book"], row["total"]) if row else None
def illustrate_position(novel, position, regenerate=False):
"""The reader asked for one chapter from the wiki: paint it from the Kavita copy (position
equals page there), ahead of prefetches. Returns the job id."""
book = kavita_book(novel)
if not book:
raise ValueError("this novel has no server-side copy (Kavita); illustrate it from the reader")
if not 0 <= position < book[1]:
raise ValueError(f"'position' must be 0..{book[1] - 1}")
job_id = slot_id(novel, f"{book[0]}/{position}")
store.set_skipped(job_id, False)
if regenerate and job_status(job_id) is None:
for suffix in (".webp", ".json"):
(IMAGES / f"{job_id}{suffix}").unlink(missing_ok=True)
store.forget_illustration(job_id)
if not image_path(job_id).exists():
submit(job_id, "illustration", USER, prefetch_job, novel, book[0], position, position,
store.novel_title(novel), 1)
return job_id
MINUTES_PER_SCENERY = 0.6 # no cast to look up and no portraits to paint
def backfill(novel, upto, start=0):
"""Illustrate every chapter from `start` to `upto` (positions, inclusive) that has no image
yet, below the reader's own requests and painting ahead. Pre-reading keeps running. A "rich"
novel gets every missing image of each chapter (images_for), in slot order because each
one avoids the moments of the ones before it; otherwise just the chapter's first."""
book = kavita_book(novel)
if not book:
raise ValueError("this novel has no server-side copy (Kavita), so chapters can't be illustrated in bulk")
upto = min(upto, book[1] - 1)
if not 0 <= start <= upto:
raise ValueError(f"'start' and 'upto' must satisfy 0 <= start <= upto <= {book[1] - 1}")
title = store.novel_title(novel)
rich = store.get_settings(novel)["density"] == "rich"
queued = existing = 0
ids, minutes = set(), 0.0
for position in range(start, upto + 1):
slots = store.images_for(store.chapter_score(novel, position)) if rich else 1
for slot in range(1, slots + 1):
job_id = slot_id(novel, f"{book[0]}/{position}", slot)
if image_path(job_id).exists() or store.is_skipped(job_id):
existing += 1
continue
ids.add(job_id)
minutes += MINUTES_PER_SCENERY if slot_kind(novel, slot) == "scenery" else MINUTES_PER_CHAPTER
if submit(job_id, "backfill", BACKFILL, prefetch_job, novel, book[0], position, position, title, slot):
queued += 1
with jobs_lock:
batch = batches.setdefault(novel, {"ids": set(), "upto": upto})
batch["ids"] |= ids
batch["upto"] = max(batch["upto"], upto)
return {"queued": queued, "existing": existing, "estimate_minutes": round(minutes)}
# ---- interstitials: an establishing shot where the story moves somewhere new ------------
ARC_SPACING = 4 # chapters between two establishing shots at least
ARC_STRETCH = 25 # chapters the arc editor is asked about at a time
_splashes = {} # novel -> [positions], so the arc editor is asked once per range
def splash_positions(novel, start, upto):
"""The chapters in [start, upto] where an establishing shot belongs, asked from the stored
summaries a stretch at a time: given a hundred chapters at once the editor names the three
biggest arcs and nothing else, while twenty-five at a time it marks every time the story
moves. Returns a list of positions."""
with jobs_lock:
if (novel, start, upto) in _splashes:
return _splashes[(novel, start, upto)]
with store.connect() as conn:
rows = list(conn.execute("SELECT position, summary FROM summaries WHERE novel = ? AND position BETWEEN ? AND ? "
"AND summary != '' ORDER BY position", (novel, start, upto)))
stretches = [rows[first:first + ARC_STRETCH] for first in range(0, len(rows), ARC_STRETCH)]
stretches = [s for s in stretches if len(s) >= ARC_SPACING]
title = store.novel_title(novel)
def marked(stretch):
listing = "\n".join(f"{r['position']}: {' '.join(r['summary'].split()[:45])}" for r in stretch)
try:
answer = llm.chat(llm.ARC_SYSTEM, f"Chapters of {title}:\n{listing}")
except Exception as e: # one slow or odd answer must not stop the batch
print(f"arc editor failed: {e}", file=sys.stderr)
return stretch, set()
wanted = {r["position"] for r in stretch}
return stretch, {p for p in answer.get("chapters") or [] if type(p) is int and p in wanted}
# The stretches are asked side by side: one after another a hundred chapters takes longer
# than the gateway in front of the server will wait for the reply.
with ThreadPoolExecutor(max_workers=min(4, len(stretches)) or 1) as pool:
answers = list(pool.map(marked, stretches))
positions = []
for stretch, marked_positions in answers:
for p in sorted(marked_positions):
if positions and p - positions[-1] < ARC_SPACING:
continue # never two close together
positions.append(p)
with jobs_lock:
_splashes[(novel, start, upto)] = positions
return positions
def splashes(novel, upto, start=0):
"""Queue the establishing shots for the arcs in [start, upto]. Returns how many were
queued and which chapters they were placed at."""
book = kavita_book(novel)
if not book:
raise ValueError("this novel has no server-side copy (Kavita), so it has no chapters to set")
if start > upto:
raise ValueError(f"'start' ({start}) must not be past 'upto' ({upto})")
upto = min(upto, book[1] - 1)
title = store.novel_title(novel)
positions, queued, existing, ids = [], 0, 0, set()
for position in splash_positions(novel, start, upto):
job_id = splash_id(novel, f"{book[0]}/{position}")
if image_path(job_id).exists() or store.is_skipped(job_id):
existing += 1
continue
ids.add(job_id)
positions.append(position)
if submit(job_id, "backfill", BACKFILL, splash_job, novel, book[0], position, title):
queued += 1
with jobs_lock:
batch = batches.setdefault(novel, {"ids": set(), "upto": upto})
batch["ids"] |= ids
batch["upto"] = max(batch["upto"], upto)
return {"queued": queued, "existing": existing, "positions": positions,
"estimate_minutes": round(len(ids) * MINUTES_PER_CHAPTER)}
def illustrate_splash(novel, position, regenerate=False):
"""The reader asked for the establishing shot of one chapter. Returns the job id."""
book = kavita_book(novel)
if not book:
raise ValueError("this novel has no server-side copy (Kavita); it has no chapters to set")
if not 0 <= position < book[1]:
raise ValueError(f"'position' must be 0..{book[1] - 1}")
job_id = splash_id(novel, f"{book[0]}/{position}")
store.set_skipped(job_id, False)
if regenerate and job_status(job_id) is None:
for suffix in (".webp", ".json"):
(IMAGES / f"{job_id}{suffix}").unlink(missing_ok=True)
store.forget_illustration(job_id)
if not image_path(job_id).exists():
submit(job_id, "illustration", USER, splash_job, novel, book[0], position,
store.novel_title(novel))
return illustration_status(job_id)
def splash_job(job_id, novel, book, position, title):
got = kavita.chapter(book, position)
if not got:
return
chapter_title, text = got
splash(job_id, {"novel": novel, "chapter": f"{book}/{position}", "position": position, "title": title,
"chapter_title": chapter_title, "text": text})
def batch_status(novel):
with jobs_lock:
batch = batches.get(novel)
if not batch:
return {"queued": 0, "running": 0, "done": 0, "failed": 0, "upto": None}
counts = {"queued": 0, "running": 0, "done": 0, "failed": 0}
for job_id in batch["ids"]:
status = (jobs.get(job_id) or {}).get("status")
if status in counts:
counts[status] += 1
elif image_path(job_id).exists():
counts["done"] += 1
return {**counts, "upto": batch["upto"]}
def cancel_batch(novel):
with jobs_lock:
ids = list(batches.get(novel, {}).get("ids", ()))
cancelled = 0
for job_id in ids:
with jobs_lock:
job = jobs.get(job_id)
waiting = job and job["status"] == "queued" and job["kind"] == "backfill"
if waiting and cancel(job_id):
cancelled += 1
with jobs_lock:
batches.pop(novel, None)
return {"cancelled": cancelled}
# ---- style picker -------------------------------------------------------------------
STYLE_OPTIONS = 3
POINTS = ("line_work", "rendering", "palette", "lighting", "texture", "composition", "mood")
POINT_NAMES = {"line_work": "Line work", "rendering": "Rendering", "palette": "Palette", "lighting": "Lighting",
"texture": "Texture", "composition": "Composition", "mood": "Mood"}
LIBRARY_DIR = STYLE_LIBRARY # defaults.json + one file of presets per family
LIBRARY_SAMPLES = STYLES / "library"
PREVIEW_SEED = 20261003 # previews share one seed, so they differ only in style
_library = {"mtime": None, "data": {"defaults": {}, "presets": []}}
def library():
"""The curated style presets (style-library/, researched and benchmarked for Qwen Image 2.1):
render defaults in defaults.json, presets in one file per family, families in file order."""
files = sorted(LIBRARY_DIR.glob("*.json")) if LIBRARY_DIR.is_dir() else []
mtime = max((f.stat().st_mtime for f in files), default=None)
if mtime != _library["mtime"]:
defaults, presets = {}, []
for f in files:
data = json.loads(f.read_text())
defaults.update(data.get("defaults") or {})
presets += [p for p in data.get("presets") or [] if p.get("id")]
_library.update(mtime=mtime, data={"defaults": defaults, "presets": presets})
return _library["data"]
def preset(preset_id):
return next((p for p in library()["presets"] if p["id"] == preset_id), None)
def custom_prompt(custom):
"""A custom style from the seven reference points the reader filled in."""
parts = [f"{POINT_NAMES[k]}: {str(custom.get(k) or '').strip().rstrip('.')}." for k in POINTS
if str(custom.get(k) or "").strip()]
if not parts:
raise ValueError("describe at least one reference point")
return " ".join(parts)[:900]
def clean_custom(custom):
if not isinstance(custom, dict):
raise ValueError("'custom' must be an object of reference points")
return {k: str(custom.get(k) or "").strip()[:300] for k in POINTS}
def _anchor_url(novel):
meta = anchor_path(novel).with_suffix(".json")
if not style_anchor(novel) or not meta.exists():
return None
illustration = json.loads(meta.read_text())["illustration"]
return {"illustration": illustration, "image": f"/v1/illustrations/{illustration}.webp"}
def style_files(novel):
base = STYLES / key(novel)
return base.with_suffix(".json"), base.with_name(base.name + ".options.json")
def current_style(novel):
current, _ = style_files(novel)
return json.loads(current.read_text()) if current.exists() else None
def _settings(chosen):
"""Render settings for a chosen style: the benchmark's defaults, then the preset's own."""
lib = library()
settings = {"steps": None, "guidance": None, "negative": "", "hires": False, "order": "suffix", "append": "",
**lib["defaults"]}
found = preset(chosen.get("preset")) if chosen else None
if found:
settings.update(found.get("params") or {})
if found.get("negative"):
settings["negative"] = found["negative"]
return settings
def _extra(settings, seed=None):
extra = []
if settings.get("steps"):
extra += ["--steps", str(int(settings["steps"]))]
if settings.get("guidance"):
extra += ["--guidance", str(float(settings["guidance"]))]
if float(settings["guidance"]) > 1 and settings.get("negative"):
extra += ["--negative-prompt", settings["negative"]]
if settings.get("hires"):
extra.append("--hires")
if seed is not None:
extra += ["--seed", str(seed)]
return extra
def render_extra(novel, seed=False):
"""Dispatcher arguments for the novel's chosen style (steps, guidance, negative, hi-res)."""
return _extra(_settings(current_style(novel)), PREVIEW_SEED if seed is True else None)
def _styled(prompt, style, settings):
text = f"Art style: {style}." if settings.get("order") == "prefix" else None
out = f"{text} {prompt}" if text else f"{prompt} Art style: {style}"
return f"{out} {settings['append']}" if settings.get("append") else out
def styled(prompt, style, novel):
"""A scene prompt with the novel's style placed where the benchmark found it works best."""
return _styled(prompt, style, _settings(current_style(novel)))
def _points(chosen):
if not chosen:
return None
if chosen.get("custom"):
return chosen["custom"]
found = preset(chosen.get("preset"))
return found.get("reference_points") if found else None
def sample_url(preset_id):
file = LIBRARY_SAMPLES / f"{preset_id}.webp"
return f"/v1/styles/library/{preset_id}.webp?v={int(file.stat().st_mtime)}" if file.exists() else None
def styles(novel):
"""The novel's current style, rendered previews, the comparison baseline and the library."""
current_path, options_path = style_files(novel)
chosen = current_style(novel)
saved = json.loads(options_path.read_text()) if options_path.exists() else []
if isinstance(saved, list): # before previews had a baseline
saved = {"options": saved, "baseline": None}
found = preset(chosen.get("preset")) if chosen else None
return {"current": chosen["style"] if chosen else None,
"current_preset": found["id"] if found else None,
"current_name": chosen.get("chosen") if chosen else None,
"current_points": _points(chosen),
"options": [{"preset": None, "why": None, "custom": None, **o} for o in saved["options"]],
"baseline": saved.get("baseline"),
"anchor": _anchor_url(novel),
"library": [{k: p.get(k) for k in ("id", "name", "family", "inspired_by", "reference_points", "prompt")}
| {"sample": sample_url(p["id"])} for p in library()["presets"]]}
def _candidate(preset_id=None, custom=None, why=None, tweak=""):
if custom is not None:
custom = clean_custom(custom)
return {"name": "Custom", "style": custom_prompt(custom), "preset": None, "why": why, "custom": custom}
found = preset(preset_id)
if not found:
raise ValueError(f"unknown style preset {preset_id!r}")
style = found["prompt"] + (f" {tweak.strip()[:200]}" if tweak and tweak.strip() else "")
return {"name": found["name"], "style": style, "preset": found["id"], "why": why, "custom": None}
def _best_moment(novel, reader):
"""A moment this reader has already seen (the best-rated chapter so far), for samples."""
limit = store.max_position(reader, novel)
with store.connect() as conn:
context = [dict(r) for r in conn.execute(
"SELECT position, summary, key_moment, score FROM summaries WHERE novel = ? AND position <= ? "
"ORDER BY position", (novel, store.FOREVER if limit is None else limit))]
rated = [c for c in context if c["key_moment"]]
best = max(rated, key=lambda c: c["score"] or 0) if rated else None
return context, (best["key_moment"] if best else f"A defining moment of {store.novel_title(novel)}")
def preview_styles_job(job_id, novel, reader, candidates):
"""Render each candidate style on the same moment and seed, without character references
(so the sample shows the style, not the portraits), plus the current style as a baseline."""
_, moment = _best_moment(novel, reader)
scene = (f"Medium shot, slightly low angle. {moment} Clear, readable poses with weight and direction, "
"faces visible, one clear focal point, layered foreground and background.")
base = key(novel)
def draw(name, style, settings):
png = STYLES / f"{base}-{name}.png"
render(_styled(scene, style, settings), png, SCENE_ARGS, extra=_extra(settings, PREVIEW_SEED))
webp = png.with_suffix(".webp")
to_webp(png, webp)
png.unlink()
make_thumbnails(webp)
return f"/v1/styles/{base}-{name}.webp?v={int(webp.stat().st_mtime)}"
out = []
for i, c in enumerate(candidates[:STYLE_OPTIONS]):
image = draw(f"option{i}", c["style"], _settings({"preset": c.get("preset")}))
out.append({**c, "name": str(c["name"])[:40], "style": str(c["style"])[:900], "image": image})
chosen = current_style(novel)
baseline = {"image": draw("baseline", chosen["style"], _settings(chosen))} if chosen else None
style_files(novel)[1].write_text(json.dumps({"options": out, "baseline": baseline}))
def propose_styles_job(job_id, novel, reader=None):
"""The language model picks the presets that fit the novel best; they are rendered as previews."""
from config import OWNER
reader = reader or OWNER
presets = library()["presets"]
if not presets:
raise ValueError("the style library (style-library/) is missing")
context, _ = _best_moment(novel, reader)
title = store.novel_title(novel)
story = "\n".join(f"- {c['summary']}" for c in context[:15] if c["summary"])
chosen = current_style(novel)
listing = "\n".join(f"{p['id']} | {p['name']} | {p.get('family', '')} | {p.get('inspired_by', '')}"
for p in presets)
picks = llm.chat(llm.STYLE_OPTIONS_SYSTEM, f"Novel: {title}"
f"\nCurrent style: {chosen['style'] if chosen else 'none'}\nStory so far:\n{story or 'unknown'}"
f"\n\nPresets (id | name | family | inspired by):\n{listing}")["options"]
candidates = []
for pick in picks:
if isinstance(pick, dict) and preset(pick.get("id")) and len(candidates) < STYLE_OPTIONS:
candidates.append(_candidate(pick["id"], why=str(pick.get("why") or "")[:300],
tweak=str(pick.get("tweak") or "")))
if not candidates:
raise ValueError("no usable style suggestion came back")
preview_styles_job(job_id, novel, reader, candidates)
def _adopt(novel, candidate):
"""Make a style the novel's. Portraits drawn in the old style are cleared so each is
redrawn in the new one the next time a scene or card needs it; existing illustrations
keep their style until repainted."""
current, _ = style_files(novel)
current.write_text(json.dumps({"title": store.novel_title(novel), "style": candidate["style"],
"from_cover": False, "chosen": candidate["name"],
"preset": candidate.get("preset"), "custom": candidate.get("custom")}))
with store.connect() as conn:
conn.execute("UPDATE looks SET portrait = '' WHERE novel = ?", (novel,))
anchor_path(novel).unlink(missing_ok=True) # the next illustration, in the new style, sets it
return styles(novel)
def choose_style(novel, index):
"""Adopt a rendered preview."""
options = styles(novel)["options"]
if not 0 <= index < len(options):
raise ValueError("unknown style option")
return _adopt(novel, options[index])
def use_style(novel, preset_id=None, custom=None):
"""Adopt a preset or a custom style without a preview."""
return _adopt(novel, _candidate(preset_id, custom))
def preview_candidates(preset_ids=None, custom=None):
if custom is not None:
return [_candidate(custom=custom)]
if not isinstance(preset_ids, list) or not 1 <= len(preset_ids) <= STYLE_OPTIONS:
raise ValueError(f"'presets' must list 1 to {STYLE_OPTIONS} preset ids")
return [_candidate(p) for p in preset_ids if isinstance(p, str)]
def save_upload(novel, name, label, data):
"""A reader-supplied portrait (base64 image) for a look: verified with Pillow and
stored as the look's PNG reference. Returns the relative path."""
import io
raw = base64.b64decode(data.split(",", 1)[-1], validate=False)
try:
with Image.open(io.BytesIO(raw)) as im:
im.verify()
with Image.open(io.BytesIO(raw)) as im:
im = im.convert("RGB")
im.thumbnail((1216, 1216))
folder = store.characters_dir(key(novel))
with store.connect() as conn:
row = conn.execute("SELECT portrait FROM looks WHERE novel = ? AND name = ? AND label = ?",
(novel, name, label)).fetchone()
portrait = DATA / row["portrait"] if row and row["portrait"] else folder / f"{key(name)}-{key(label)[:8]}.png"
tmp = portrait.with_suffix(".upload.png")
im.save(tmp, "PNG")
except Exception as e:
raise ValueError(f"not a readable image: {e}")
tmp.replace(portrait)
portrait_webp(portrait)
return str(portrait.relative_to(DATA))
def describe_job(job_id, novel, name, label, portrait):
"""After an upload: describe the picture so scenes and cards follow it."""
features = llm.chat(llm.FEATURES_SYSTEM, f"Character: {name} ({label})", llm.image_b64(DATA / portrait))["description"]
store.set_look_portrait(novel, name, label, features, portrait)
# ---- feedback ---------------------------------------------------------------------
@contextmanager
def feedback_outcome(fid):
"""Record whether the fix that feedback `fid` asked for went through (no-op without fid)."""
try:
yield
except Exception:
if fid:
store.set_feedback(fid, "failed", reply="The fix could not be applied; it is listed for review.")
raise
if fid:
store.set_feedback(fid, "applied")
def feedback_facts(item):
"""What the reader saw, for the triage model."""
novel, kind, target = item["novel"], item["kind"], item["target"]
facts = [f"Novel: {store.novel_title(novel) or novel}", f"Chapter: {item['chapter'] or 'unknown'}"]
with store.connect() as conn:
if kind == "image":
meta = IMAGES / f"{target}.json"
if meta.exists():
info = json.loads(meta.read_text())
facts += [f"Illustrated moment: {info.get('moment')}",
f"Characters in it: {', '.join(n for n in info.get('characters') or [] if n)}",
f"Their looks: {json.dumps(info.get('looks') or {}, ensure_ascii=False)}"]
if kind == "term":
row = conn.execute("SELECT meaning FROM terms WHERE novel = ? AND term = ?", (novel, target)).fetchone()
facts.append(f"Term: {target} = {row['meaning'] if row else 'unknown'}")
known = store.known_characters(conn, novel)
if kind == "character":
c = store.find_character(known, target)
if c:
looks = [f"{l['label']}: {l['description']}" for l in store.looks_of(conn, novel, c["name"])]
facts += [f"Character: {c['name']} (aliases: {', '.join(c['aliases']) or 'none'}; "
f"role: {c.get('role') or 'unknown'})", "Looks:\n" + "\n".join(looks)]
facts.append("Known characters: " + ", ".join(c["name"] for c in known[:150]))
return "\n".join(facts)
def feedback_job(job_id, fid):
"""Triage feedback with MiniMax M2.7 and apply the fix it picks when it is safe; the rest
waits on the /feedback page."""
item = store.feedback(fid)
if not item:
return
store.set_feedback(fid, "working")
try:
plan = llm.chat(llm.FEEDBACK_SYSTEM, f"About: {item['kind']} {item['target']}\n"
f"Feedback: {item['text']}\n\nFacts:\n{feedback_facts(item)}")
action, reply = str(plan.get("action") or "none"), str(plan.get("reply") or "")[:300]
store.set_feedback(fid, "working", action=action, reply=reply)
if not apply_feedback(item, action, plan):
store.set_feedback(fid, "review", action=action if action != "none" else "")
except Exception:
store.set_feedback(fid, "review", reply="Saved; it will be looked at.")
raise
def apply_feedback(item, action, plan):
"""Run the triaged fix after checking it against the stored data. False when there is
nothing safe to do automatically."""
novel, fid = item["novel"], item["id"]
text = lambda k, n=300: str(plan.get(k) or "").strip()[:n]
with store.connect() as conn:
known = store.known_characters(conn, novel)
if action == "repaint" and item["kind"] == "image" and image_path(item["target"]).exists() and text("fix"):
submit(item["target"], "illustration", USER, revise_job, fid, text("fix"))
return True
if action == "redraw_portrait":
c = store.find_character(known, text("name", 80))
with store.connect() as conn:
labels = {l["label"] for l in store.looks_of(conn, novel, c["name"])} if c else set()
label = text("label", 60) if text("label", 60) in labels else store.INITIAL_LOOK if len(labels) == 1 else ""
if not c or label not in labels:
return False
submit(key(novel, c["name"], label, "portrait"), "portrait", USER, redraw_job, novel, c["name"], label,
text("hint") or item["text"][:300], fid)
return True
if action == "edit_character":
c = store.find_character(known, text("name", 80))
if not c:
return False
extra = [a.strip()[:80] for a in plan.get("add_aliases") or [] if isinstance(a, str) and a.strip()]
store.edit_character(novel, c["name"], text("new_name", 80) or None, text("role", 400) or None,
(c["aliases"] + [a for a in extra if a not in c["aliases"]])[:40] if extra else None)
elif action == "merge":
if not store.merge_characters(novel, text("into", 80), text("name", 80)):
return False
elif action == "edit_term":
if not text("meaning", 600) or not store.edit_term(novel, text("term", 80), text("meaning", 600)):
return False
else:
return False
store.set_feedback(fid, "applied")
return True
def edit_fix(job_id, instruction, description, extra=()):
"""Apply a local fix to the existing picture with the edit model, keeping everything else.
Returns (png, check) when the result passes the image check, else None."""
source = image_path(job_id).with_suffix(".src.png")
png = image_path(job_id).with_suffix(".edit.png")
with Image.open(image_path(job_id)) as im:
im.convert("RGB").save(source)
try:
render(f"{instruction.rstrip('.')}. Keep everything else exactly the same: every character's face, "
"hair, clothing and pose, the composition and framing, the background, the lighting and "
"the art style.", png, SCENE_ARGS, extra=extra, edit=source)
finally:
source.unlink(missing_ok=True)
verdict = check(png, description)
if verdict["ok"]:
return png, verdict
png.unlink()
return None
def revise_job(job_id, fid, fix):
"""Apply the reader's fix to an illustration (no chapter text needed). A local fix ("the
sword has two blades") edits the existing picture and keeps everything that was right; a
larger one, or an edit that fails the image check, repaints from the stored prompt with
the fix applied, with the same references, check and re-rolls as a new image."""
with feedback_outcome(fid):
info = json.loads((IMAGES / f"{job_id}.json").read_text())
revised = llm.chat(llm.REVISE_SYSTEM, f"Prompt:\n{info['prompt']}\n\nReader feedback: {fix}")
prompt = revised["prompt"]
style = novel_style(info["novel"], store.novel_title(info["novel"]))
refs = [DATA / r for r in info.get("references") or [] if (DATA / r).exists()]
png = image_path(job_id).with_suffix(".tmp.png")
edited = None
if revised.get("local") is True and isinstance(revised.get("edit"), str) and revised["edit"].strip():
try:
edited = edit_fix(job_id, revised["edit"].strip(), prompt, render_extra(info["novel"]))
except Exception as e: # the full repaint below still applies the fix
print(f"edit fix for {job_id} failed, repainting instead: {str(e)[:300]}", file=sys.stderr)
if edited:
edited[0].replace(png)
qa = [{**edited[1], "edit": revised["edit"].strip()[:300]}]
else:
qa = checked_render(styled(prompt, style, info["novel"]), prompt, refs, png, render_extra(info["novel"]))
out = image_path(job_id).with_suffix(".tmp.webp")
to_webp(png, out)
png.unlink()
info.update(prompt=prompt, qa=qa, fixes=[*info.get("fixes", []), fix])
(IMAGES / f"{job_id}.json").write_text(json.dumps(info, ensure_ascii=False))
out.replace(image_path(job_id))
make_thumbnails(image_path(job_id))
# Functions a persisted queue row may name (resume() refuses anything else).
JOB_FUNCTIONS = {"generate", "prefetch_job", "splash_job", "redraw_job", "propose_styles_job", "preview_styles_job",
"describe_job", "revise_job"}
# ---- recap ------------------------------------------------------------------------
RECAP_CHAPTERS = 12
def recap(novel, position):
"""'Previously on…' from the stored summaries of the chapters before this one."""
cached = store.cached_recap(novel, position)
if cached:
return cached
summaries = store.summaries_before(novel, position, RECAP_CHAPTERS)
if not summaries:
return None
text = llm.chat(llm.RECAP_SYSTEM, "\n".join(f"Chapter {s['position'] + 1}: {s['summary']}"
for s in summaries))["recap"]
store.save_recap(novel, position, text)
return text