Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(prompt): every engine sentence goes on through one place, and none is said twice
Soohong Kim25f33bd5c705
diff --git a/sprite_gen/gen/__init__.py b/sprite_gen/gen/__init__.pyindex 52ac9ce..4138ae8 100644--- a/sprite_gen/gen/__init__.py+++ b/sprite_gen/gen/__init__.py@@ -49,6 +49,7 @@ from sprite_gen.spec.runio import atomic_write_textfrom . import chroma as chroma_modfrom . import facing as facing_modfrom . import handedness as handed_mod+from . import prompt_partsfrom .base import (QUALITIES,RESOLUTIONS,@@ -142,21 +143,33 @@ def layout_guide_size(aspect_ratio: str | None) -> tuple[int, int]:return round(width * scale), round(height * scale)-def draw_layout_guide(path: Path, aspect_ratio: str | None) -> dict[str, Any]:- """Draws the one-slot guide at `path` and answers its cell (size and safe margins)."""+def layout_guide_cell(aspect_ratio: str | None) -> dict[str, Any]:+ """The one-slot guide's cell for the requested ratio: its size, safe margins and the two anatomy lines,+ one margin inside the safe box's top and bottom edges. What `layout_guide_text` says and+ `draw_layout_guide` draws."""# Imported here: `prepare` owns the row guide and pulls in the row machinery.- from .prepare import draw_guide, normalize_cell-- from PIL import Image, ImageDraw+ from .prepare import normalize_cellwidth, height = layout_guide_size(aspect_ratio)cell = normalize_cell({"width": width, "height": height}, width, None)- draw_guide(path, 1, cell)- # The anatomy lines one margin inside the safe box's top and bottom edges, as the row experiments- # drew them on a 256 px cell (5 px lines, 16 px x 7 px centre marks), scaled to this guide.+ margin_y = int(cell["safe_margin_y"])+ return {**cell, "crown_y": 2 * margin_y, "floor_y": height - 1 - 2 * margin_y}+++def draw_layout_guide(path: Path, aspect_ratio: str | None) -> dict[str, Any]:+ """Draws the one-slot guide at `path` and answers its cell (`layout_guide_cell`)."""+ from .prepare import draw_guide++ from PIL import Image, ImageDraw++ cell = layout_guide_cell(aspect_ratio)+ width, height = int(cell["width"]), int(cell["height"])+ draw_guide(path, 1, {key: value for key, value in cell.items() if key not in ("crown_y", "floor_y")})+ # The anatomy lines as the row experiments drew them on a 256 px cell (5 px lines, 16 px x 7 px+ # centre marks), scaled to this guide.scale = height / 256- margin_x, margin_y = int(cell["safe_margin_x"]), int(cell["safe_margin_y"])- crown_y, floor_y = 2 * margin_y, height - 1 - 2 * margin_y+ margin_x = int(cell["safe_margin_x"])+ crown_y, floor_y = int(cell["crown_y"]), int(cell["floor_y"])center = width // 2line, mark, half = max(1, round(5 * scale)), max(1, round(7 * scale)), round(8 * scale)image = Image.open(path).convert("RGB")@@ -165,7 +178,7 @@ def draw_layout_guide(path: Path, aspect_ratio: str | None) -> dict[str, Any]:draw.line((margin_x, y, width - 1 - margin_x, y), fill=colour, width=line)draw.line((center - half, y, center + half, y), fill=accent, width=mark)image.save(path)- return {**cell, "crown_y": crown_y, "floor_y": floor_y}+ return celldef _make_provider(name: str, *, keep_session: bool):@@ -361,23 +374,18 @@ def generate_image(raise SystemExit("gen: empty prompt; pass --prompt or --prompt-file")if facing is not None:facing_mod.validate(facing, facing_fix)- view_text = _view_text(view, facing, facing_fix, handed)+ _check_view(view, facing, facing_fix, handed)out = out.expanduser().resolve()refs = [Path(r).expanduser().resolve() for r in (refs or [])]for ref in refs:if not ref.is_file():raise SystemExit(f"gen: reference image not found: {ref}")- if view_text:- prompt += "\n\n" + view_text- if refs and facing is not None:- prompt += "\n\n" + facing_mod.prompt_suffix(facing)backend = _make_provider(provider, keep_session=keep_session)# Decided before the model runs: the strategy shapes the transport prompt# (native asks for alpha) and the post-process (chroma keys it out).strategy: str | None = Nonestrategy_source: str | None = None- key_background: dict[str, Any] | None = Noneif transparent:# The layout guide is an attached image as much as a --ref is: the same step down applies.attached_for_strategy = [*refs, Path(LAYOUT_GUIDE_NAME)] if layout_guide else refs@@ -386,23 +394,27 @@ def generate_image(# before the provider is called: a paid generation must not end in this refusalraise SystemExit(f"gen: --decontam removes a chroma key; this image would use {strategy} alpha ""(pass --alpha-mode chroma to key it instead)")- if strategy_source == STRATEGY_SOURCE_REFS:- # The key is the engine's plan, so the engine asks for it: a ref prompt with no key- # background is answered on white or another light ground, and keying that takes the- # outline and light fills with it (2026-10-04). A key the prompt already names stays.- named_key = chroma_mod.named_key_background(prompt)- if named_key is None:- prompt += "\n\n" + chroma_mod.KEY_BACKGROUND_TEXT[chroma_key]- key_background = {"injected": named_key is None, "key": named_key or chroma_key}- print(- f"[gen] {len(refs)} reference image(s) attached — using chroma keying instead of "- f"{backend.name}'s native alpha (native output with refs is unstable, 2026-09-08); "- + (f"added a {chroma_key} key background line to the prompt; " if named_key is None- else f"the prompt already asks for a {named_key} key background; ")- + "a result that already has a transparent background keeps its own alpha. "- "Pass --alpha-mode native to force it.",- file=sys.stderr,- )+ # The key is the engine's plan when `auto` stepped down for the refs, so the engine asks for it: a+ # ref prompt with no key background is answered on white or another light ground, and keying that+ # takes the outline and light fills with it (2026-10-04). A key the prompt already names stays.+ parts = still_prompt(prompt, view=view, facing=facing, handed=handed, refs=bool(refs),+ key=chroma_key if strategy_source == STRATEGY_SOURCE_REFS else None,+ layout=layout_guide_cell(aspect_ratio) if layout_guide else None)+ prompt = parts.text+ for line in prompt_parts.note_lines(parts):+ print(f"[gen] {line}", file=sys.stderr)+ key_background: dict[str, Any] | None = None+ if (key_piece := parts.piece("key-background")) is not None:+ key_background = {"injected": key_piece.added, "key": key_piece.found or chroma_key}+ print(+ f"[gen] {len(refs)} reference image(s) attached — using chroma keying instead of "+ f"{backend.name}'s native alpha (native output with refs is unstable, 2026-09-08); "+ + (f"added a {chroma_key} key background line to the prompt; " if key_piece.added+ else f"the prompt already asks for a {key_piece.found} key background; ")+ + "a result that already has a transparent background keeps its own alpha. "+ "Pass --alpha-mode native to force it.",+ file=sys.stderr,+ )owns_workdir = workdir is Noneworkdir = Path(workdir).expanduser().resolve() if workdir else Path(tempfile.mkdtemp(prefix="sprite-gen-gen-"))workdir.mkdir(parents=True, exist_ok=True)@@ -416,7 +428,6 @@ def generate_image(guide_cell = draw_layout_guide(guide, aspect_ratio)# Last, so "the last attached image" in the prompt is the guide whatever the caller attached.attached.append(guide)- prompt += "\n\n" + layout_guide_text(guide_cell)request = GenRequest(prompt=prompt,raw=raw,@@ -437,8 +448,10 @@ def generate_image(verify_png(raw)facing_report = Noneif refs and facing is not None:+ retry = parts.replaced("facing", facing_mod.prompt_suffix(facing, retry=True, view=view is not None))request, run, facing_report = facing_mod.prepare_correction(- backend, request, run, workdir, facing=facing, fix=facing_fix, mirror_ok=not handed)+ backend, request, run, workdir, facing=facing, fix=facing_fix, retry_prompt=retry.text,+ mirror_ok=not handed)raw = request.rawraw_bytes = verify_png(raw)@@ -529,34 +542,58 @@ def generate_image(**({"facing": facing_report} if facing_report else {}),**({"view": {"direction": view, "facing": facing if view in handed_mod.LATERAL_VIEWS else None,"handed": [vars(h) for h in handed or []]}} if view else {}),- **({"layout_guide": guide_cell} if guide_cell else {})},+ **({"layout_guide": guide_cell} if guide_cell else {}),+ **({"prompt_notes": parts.notes} if parts.notes else {})},)finally:if owns_workdir:shutil.rmtree(workdir, ignore_errors=True)-def _view_text(view: str | None, facing: str | None, facing_fix: str, handed: list[handed_mod.Handed] | None) -> str:- """`--direction`: the engine's sentence for drawing the still at that view, turned to `facing` (the side- and diagonal views), then where each `--handed` item is in it (`handedness.text`)."""+def _check_view(view: str | None, facing: str | None, facing_fix: str, handed: list[handed_mod.Handed] | None) -> None:+ """Refuse a `--direction` / `--facing` / `--handed` combination that cannot be drawn, before anything runs."""if view is None:if handed:raise SystemExit("gen: --handed needs --direction: where an item shows depends on the view")- return ""+ returnhanded_mod.validate_view(view, facing)if view not in handed_mod.LATERAL_VIEWS and facing is not None:raise SystemExit(f"gen: the {view} view is not turned to a side; drop --facing")if handed and facing_fix == "mirror":raise SystemExit("gen: --facing-fix mirror turns the picture over and moves every --handed item to the other ""side; use regen (it never mirrors with --handed) or none")- # The view sentences are the video pipeline's (a still is drawn for the clip that starts from it).- from sprite_gen.video.batch import still_view_text-- text = still_view_text(view, facing or "right")- text = text[0].upper() + text[1:] + "."- if handed:- text += " " + handed_mod.text(handed, view, facing)- return text+++def still_prompt(prompt: str, *, view: str | None = None, facing: str | None = None,+ handed: list[handed_mod.Handed] | None = None, refs: bool = False, key: str | None = None,+ layout: dict[str, Any] | None = None) -> prompt_parts.Prompt:+ """The prompt a still is drawn from: the caller's text, then the engine's pieces, each said once+ (`prompt_parts.Prompt.add`). In order:++ - `view` (`--direction`): the sentence for drawing the still at that view, turned to `facing` (the side and+ diagonal views), then where each `handed` item is in it (`handedness.text`);+ - with `refs` and a `facing`: the turn over the reference (`facing.prompt_suffix`) — only which edge of the+ image the side is when the view sentence already said the turn;+ - `key` (green / magenta, a ref run `auto` planned to key): the key background line, unless the prompt+ names a key background already;+ - `layout` (the `--layout-guide` cell): where the guide's lines are.+ """+ parts = prompt_parts.Prompt(prompt)+ if view is not None:+ # The view sentences are the video pipeline's (a still is drawn for the clip that starts from it).+ from sprite_gen.video.batch import still_view_text++ text = still_view_text(view, facing or "right")+ parts.add("view", text[0].upper() + text[1:] + ".", facing=facing or prompt_parts.NO_TURN)+ if handed:+ parts.add("handed", handed_mod.text(handed, view, facing), sep=" ", handed=handed)+ if refs and facing is not None:+ parts.add("facing", facing_mod.prompt_suffix(facing, view=view is not None), facing=facing)+ if key is not None:+ parts.add("key-background", chroma_mod.KEY_BACKGROUND_TEXT[key], key=key)+ if layout is not None:+ parts.add("layout", layout_guide_text(layout))+ return partsdef _run(args: argparse.Namespace) -> int:diff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.pyindex 21af241..9d94beb 100644--- a/sprite_gen/gen/chroma.py+++ b/sprite_gen/gen/chroma.py@@ -41,23 +41,61 @@ KEY_BACKGROUND_TEXT = {}+# Words a prompt puts between a key's name and "background", either way round: "a pure magenta flat+# background", "a background of solid green".+_KEY_FILLER = r"(?:(?:an?|the|one|single|pure|solid|flat|plain|uniform|bright|vivid|perfectly|completely|entirely|fully)[\s,]+)*"+_KEY_GROUND = r"(?:background|backdrop|screen|chroma[- ]?key)"+# What rules a key out: a negation right before the key's name, with nothing between them but small+# words ("no green screen", "without a magenta background", "never on #00FF00"). A negation of+# something else in the same clause does not ("no shadow, on a magenta background").+_KEY_NEGATION = re.compile(+ r"\b(?:no|not|never|without|avoid(?:ing|s)?|instead of|rather than|\w+n't)\s+"+ r"(?:(?:an?|the|any|on|in|against|over|with|use|using|be|to|pure|solid|flat|plain|uniform|bright)\s+){0,4}$",+ re.IGNORECASE)++def _key_background_pattern(key: str) -> re.Pattern[str]:hex_code = "".join(f"{channel:02x}" for channel in KEYS[key]["target"])- return re.compile(rf"(?<![0-9a-z])#?{hex_code}(?![0-9a-z])"- rf"|\b{key}\s+(?:chroma[- ]?key|key|screen|background|backdrop)\b", re.IGNORECASE)+ name = rf"{key}(?:[- ]colou?red)?"+ return re.compile(+ rf"(?<![0-9a-z])#?{hex_code}(?![0-9a-z])"+ # the name, then the ground: "green screen", "magenta-colored background", "magenta chroma-key fill"+ rf"|\b{name}[\s,]+(?:(?:flat|solid|plain|uniform|pure|key)[\s,]+)*{_KEY_GROUND}\b(?!-)"+ # the ground, then the name: "background of pure magenta", "backdrop: solid green"+ rf"|\b(?:background|backdrop)\s*(?:is|of|in|as|[:=])?\s+{_KEY_FILLER}{name}\b"+ # "keyed on magenta", "on a green key"+ rf"|\bkeyed\s+(?:on|to|against)\s+{_KEY_FILLER}{name}\b"+ rf"|\b(?:on|against|over)\s+{_KEY_FILLER}{name}\s+key\b",+ re.IGNORECASE)+++def _key_backgrounds(prompt: str) -> list[tuple[int, str, bool]]:+ """(where, key, ruled out) for every place `prompt` names a key as its background."""+ found = []+ for key in KEYS:+ for match in _key_background_pattern(key).finditer(prompt):+ found.append((match.start(), key, bool(_KEY_NEGATION.search(prompt[:match.start()]))))+ return sorted(found)def named_key_background(prompt: str) -> str | None:"""The key a prompt already asks for as its background, or None.- A prompt names a key when it carries the key's hex code (`#FF00FF`, `00ff00`) or the key's- name right before "background", "backdrop", "chroma key", "key" or "screen" ("a green- screen", "magenta chroma-key background"). A colour in the subject ("a green frog on- white") is not a key. The first key named wins; the matte reads the key off the borders,- so a prompt naming the other key than `--chroma-key` is keyed on the one drawn.+ A prompt names a key when it carries the key's hex code (`#FF00FF`, `00ff00`), the key's name+ before "background", "backdrop", "screen" or "chroma key" ("a green screen", "a magenta-colored+ background", "magenta chroma-key fill"), the name after one ("a background of pure magenta"), or+ "keyed on magenta" / "on a green key". A colour in the subject ("a green frog on white", "holding+ a green key") is not a key, and neither is one the prompt rules out ("no green screen", "without+ a magenta background": `ruled_out_key_backgrounds`). The first key asked for wins; the matte+ reads the key off the borders, so a prompt naming the other key than `--chroma-key` is keyed on+ the one drawn."""- found = [(match.start(), key) for key in KEYS if (match := _key_background_pattern(key).search(prompt))]- return min(found)[1] if found else None+ return next((key for _, key, ruled_out in _key_backgrounds(prompt) if not ruled_out), None)+++def ruled_out_key_backgrounds(prompt: str) -> set[str]:+ """The keys a prompt says its background is not ("no green screen")."""+ return {key for _, key, ruled_out in _key_backgrounds(prompt) if ruled_out}# What a generated raw is, before a planned chroma key runs on it (`classify_raw_alpha`).diff --git a/sprite_gen/gen/facing.py b/sprite_gen/gen/facing.pyindex c58453e..0846c81 100644--- a/sprite_gen/gen/facing.py+++ b/sprite_gen/gen/facing.py@@ -44,10 +44,22 @@ def validate(facing: str, fix: str = "none") -> None:raise SystemExit(f"facing: expected mirror, regen or none, got {fix!r}")-def prompt_suffix(facing: str, *, retry: bool = False) -> str:+def prompt_suffix(facing: str, *, retry: bool = False, view: bool = False) -> str:+ """The sentence that turns a subject drawn from a reference: which way, whatever way the reference is turned.++ `view`: the prompt already carries a view sentence that says the turn (`gen --direction`). The piece then+ says only what that sentence does not — which edge of the image the side is, over the reference — instead+ of the turn a second time; "facing left (toward the left edge)" after a three-quarter view sentence also+ asked for a full profile. `retry` is the correction after a drawing that came out turned the other way:+ it takes the first sentence's place in the prompt (`prompt_parts.Prompt.replaced`), not a line after it.+ """validate(facing)+ lead = "CORRECTION REQUIRED: redraw the subject's orientation. " if retry else ""+ if view:+ return (lead + f"{facing.capitalize()} here means toward the {facing} edge of the image, regardless of the "+ "reference image's orientation. Preserve the subject's design.")return (- ("CORRECTION REQUIRED: redraw the subject's orientation. " if retry else "")+ lead+ f"The subject must be facing {facing} (toward the {facing} edge of the image), ""regardless of the reference image's orientation. Preserve the subject's design.")@@ -101,9 +113,13 @@ def inspect(backend, path: Path, workdir: Path) -> dict:return observation-def prepare_correction(backend, request, run, workdir: Path, *, facing: str, fix: str, mirror_ok: bool = True):+def prepare_correction(backend, request, run, workdir: Path, *, facing: str, fix: str, retry_prompt: str,+ mirror_ok: bool = True):"""Observe raw; recheck one regeneration and mirror a remaining opposite.+ `retry_prompt` is the whole prompt of the regeneration: the request's, with its facing sentence+ replaced by the correction (`prompt_suffix(retry=True)`).+A non-lateral or failed recheck preserves the regenerated image with anexplicit reason. At most two vision calls and one regeneration are made.`mirror_ok=False` (a character with a handed item) never mirrors: a still-opposite@@ -122,8 +138,7 @@ def prepare_correction(backend, request, run, workdir: Path, *, facing: str, fixelse:regenerated = workdir / "facing-regen.png"regenerated.unlink(missing_ok=True)- retry_request = replace(request, raw=regenerated,- prompt=request.prompt + "\n\n" + prompt_suffix(facing, retry=True))+ retry_request = replace(request, raw=regenerated, prompt=retry_prompt)retry_run = backend.generate(retry_request, workdir)verify_png(regenerated)# Keep both calls' billing evidence; top-level usage still describes thediff --git a/sprite_gen/gen/prompt_parts.py b/sprite_gen/gen/prompt_parts.pynew file mode 100644index 0000000..6cd897b--- /dev/null+++ b/sprite_gen/gen/prompt_parts.py@@ -0,0 +1,193 @@+# SPDX-License-Identifier: Apache-2.0+"""Attaching the engine's sentences to a prompt: the one place that checks what is already said.++A prompt is the caller's own text and then the engine's pieces: the view sentence, the turn over a+reference, where a handed item is, the key background line, the layout guide; for a clip the hold, the+frame and camera rules, a Lite model's sentences and the side view's hold. Every piece goes on through+`Prompt.add`, and a piece the prompt already says is not said again:++- a sentence the prompt already carries, word for word, is dropped from the piece (a start still's prompt+ handed back to `gen --direction --handed`, a caller's motion paragraph that quotes an engine rule, two+ items whose sentences come out the same);+- a piece whose topic the prompt already covers is left out whole (`ALREADY_SAID`: a key background the+ caller named, a side view the clip prompt already holds), and one the prompt rules out is refused.++The caller's text is never edited. Where it and a piece disagree (`facing left` in the text, `--facing+right` on the command) or it repeats what a piece says, `Prompt.notes` says which words, and the verb+prints them: the engine cannot tell which of the two the caller meant.+"""++from __future__ import annotations++import re+from dataclasses import dataclass, field+from typing import Any, Callable++from .chroma import named_key_background, ruled_out_key_backgrounds++_SENTENCE_END = re.compile(r"(?<=[.!?])\s+")+++def sentences(text: str) -> list[str]:+ """`text` cut into sentences, each as written."""+ return [part for part in _SENTENCE_END.split(" ".join(text.split())) if part]+++def _same(sentence: str) -> str:+ """What makes two sentences the same one: their words, whatever the case or the closing mark."""+ return sentence.lower().rstrip(".!? ")+++# Words that turn a subject to one side of the picture, as a caller writes them.+_TURN = re.compile(+ r"\b(?:fac(?:ing|es?)|look(?:ing|s)?|turn(?:ed|ing|s)?|head(?:ing|s)?|walk(?:ing|s)?|run(?:ning|s)?|mov(?:ing|es?))"+ r"\s+(?:to(?:wards?)?\s+)?(?:the\s+)?(left|right)\b", re.IGNORECASE)+_SIDE = re.compile(r"\b(left|right)\b", re.IGNORECASE)+_ARTICLE = re.compile(r"^(?:the|a|an|its|his|her|their)\s+", re.IGNORECASE)+_CLAUSE_END = re.compile(r"[.;:!?\n]+")+++# `facing` of a piece whose view is turned to neither side (front, back).+NO_TURN = "neither"+++def turns_said(text: str) -> list[tuple[str, str]]:+ """(the words, left|right) for every place `text` turns the subject to a side."""+ return [(match.group(0), match.group(1).lower()) for match in _TURN.finditer(text)]+++def _key_said(prompt: "Prompt", *, key: str | None = None, **_: Any) -> tuple[str, str] | None:+ named = named_key_background(prompt.text)+ if named:+ return f"the prompt already asks for a {named} key background", named+ if key is not None and key in ruled_out_key_backgrounds(prompt.text):+ raise SystemExit(f"prompt: the text rules out a {key} key background and the engine would ask for one; "+ "choose the other key or drop the line from the prompt")+ return None+++_SIDE_VIEW = re.compile(r"\bseen from the exact side, facing (left|right)\b", re.IGNORECASE)+++def _side_view_said(prompt: "Prompt", *, facing: str | None = None, **_: Any) -> tuple[str, str] | None:+ held = {match.group(1).lower() for match in _SIDE_VIEW.finditer(prompt.text)}+ if not held:+ return None+ if facing in ("left", "right") and held != {facing}:+ raise SystemExit(f"prompt: the text says the side view faces {' and '.join(sorted(held))} and the engine "+ f"would hold it facing {facing}; ask for the prompt and the clip with the same facing")+ return "the prompt already says the side view and its facing", facing or ""+++# topic -> what in the prompt makes a piece on that topic unnecessary: (why, what was found), or None.+# A check raises SystemExit where the prompt says the opposite of the piece in the engine's own words.+ALREADY_SAID: dict[str, Callable[..., tuple[str, str] | None]] = {+ "key-background": _key_said,+ "side-view": _side_view_said,+}+++@dataclass(frozen=True)+class Piece:+ """One engine piece and what became of it: attached whole, attached without the sentences the prompt+ already had (`why`), or left out (`added` False, `why`, and `found` — the key the prompt named)."""++ topic: str+ text: str+ sep: str+ added: bool+ why: str = ""+ found: str = ""+ asked: str = ""+ params: dict[str, Any] = field(default_factory=dict, compare=False)+++class Prompt:+ """A prompt being put together: `own` (the first text, the caller's or a template's) and then the pieces.+ `caller` is the part of it the caller wrote, which the notes read; by default all of `own`."""++ def __init__(self, own: str, *, caller: str | None = None, sep: str = "\n\n") -> None:+ self.own = own+ self.caller = own if caller is None else caller+ self.sep = sep+ self.pieces: list[Piece] = []+ self.notes: list[dict[str, str]] = []++ @property+ def text(self) -> str:+ return self.own + "".join(piece.sep + piece.text for piece in self.pieces if piece.added)++ def piece(self, topic: str) -> Piece | None:+ return next((piece for piece in self.pieces if piece.topic == topic), None)++ def add(self, topic: str, text: str, *, sep: str | None = None, **params: Any) -> Piece:+ """Attach `text` as the piece on `topic` unless the prompt already says it. `params` are what the piece+ claims (`facing`, `key`, `handed`): they feed `ALREADY_SAID` and the notes on the caller's text."""+ sep = self.sep if sep is None else sep+ asked = text+ why = found = ""+ said = ALREADY_SAID[topic](self, **params) if topic in ALREADY_SAID else None+ if said:+ why, found = said+ text = ""+ elif text:+ have = {_same(sentence) for sentence in sentences(self.text)}+ kept = []+ for sentence in sentences(text):+ if _same(sentence) not in have:+ kept.append(sentence)+ have.add(_same(sentence))+ if len(kept) != len(sentences(text)):+ why = "the prompt already has " + ("these sentences" if not kept else "some of these sentences")+ text = " ".join(kept)+ piece = Piece(topic=topic, text=text, sep=sep, added=bool(text), why=why, found=found, asked=asked, params=params)+ self.pieces.append(piece)+ if piece.added:+ self.note(**params)+ return piece++ def replaced(self, topic: str, text: str, **params: Any) -> "Prompt":+ """The same prompt with the piece on `topic` taken out and `text` said last in its place (a correction+ of a sentence replaces it; said after it, the prompt would carry the sentence twice)."""+ out = Prompt(self.own, caller=self.caller, sep=self.sep)+ old = self.piece(topic)+ for piece in self.pieces:+ if piece.topic != topic:+ out.add(piece.topic, piece.asked, sep=piece.sep, **piece.params)+ out.add(topic, text, **{**(old.params if old else {}), **params})+ return out++ def note(self, *, facing: str | None = None, handed: list[Any] | None = None, **_: Any) -> None:+ """Note what the caller's text says against, or again after, a piece that turns the subject to `facing`+ (right, left, or `NO_TURN` for a front or back view) or puts the `handed` items on their sides. `add` calls it for the piece it attaches; a template that+ carries the turn in its own first text calls it itself."""+ if facing is not None:+ for words, side in turns_said(self.caller):+ if facing == NO_TURN:+ self._say("conflict", "facing", f'the text says "{words}" and the engine\'s sentence is a view '+ "turned to neither side")+ elif side == facing:+ self._say("repeat", "facing", f'the text says "{words}" and so does the engine\'s sentence; it is said twice')+ else:+ self._say("conflict", "facing", f'the text says "{words}" and the engine\'s sentence says {facing}')+ for item in handed or []:+ name = _ARTICLE.sub("", item.item).lower()+ for clause in _CLAUSE_END.split(self.caller):+ if name not in clause.lower():+ continue+ sides = {side.lower() for side in _SIDE.findall(_TURN.sub(" ", clause))}+ if item.side in sides:+ self._say("repeat", "handed", f"the text already says which side {item.item} is on; it is said twice")+ elif item.other in sides:+ self._say("conflict", "handed", f'the text has {item.item} with "{item.other}" ("{clause.strip()}") '+ f"and the engine's sentence puts it on the {item.where()}")++ def _say(self, kind: str, about: str, text: str) -> None:+ note = {"kind": kind, "about": about, "text": text}+ if note not in self.notes:+ self.notes.append(note)+++def note_lines(prompt: Prompt) -> list[str]:+ """`prompt.notes` as lines for stderr: a conflict is a warning, a repeat a note."""+ return [("warning: " if note["kind"] == "conflict" else "note: ") + note["text"] for note in prompt.notes]diff --git a/sprite_gen/gen/video.py b/sprite_gen/gen/video.pyindex 18e0871..9aa3f68 100644--- a/sprite_gen/gen/video.py+++ b/sprite_gen/gen/video.py@@ -55,7 +55,7 @@ from pathlib import Pathfrom typing import Any, Callablefrom sprite_gen.spec.runio import atomic_write_text-from . import refusal+from . import prompt_parts, refusalfrom .base import announce_api_billingfrom .facing import FACINGS, validate as validate_facingfrom sprite_gen.video import facing as facing_mod@@ -482,6 +482,15 @@ def _submit_poll_publish()+def side_view_prompt(prompt: str, facing: str) -> prompt_parts.Prompt:+ """`--direction side`: the prompt with the side view held for the whole clip. A prompt that already says+ the side view and this facing (`video-prompt`'s, `video-set`'s) is left as it is; one that says the other+ facing is refused."""+ parts = prompt_parts.Prompt(prompt)+ parts.add("side-view", f"The subject stays in exact side view, facing {facing}. No turning around.", facing=facing)+ return parts++def generate_video(request: VideoRequest,*,@@ -506,12 +515,15 @@ def generate_video(facing_report = Noneif request.direction == "side":+ # before the facing inspection: a prompt that holds the other facing is refused unpaid+ parts = side_view_prompt(request.prompt, request.facing)+ for line in prompt_parts.note_lines(parts):+ print(f"[video] {line}", file=sys.stderr)+ request = replace(request, prompt=parts.text)corrected = out.with_suffix(".facing.png")facing_report = facing_mod.prepare_still(image, corrected, facing=request.facing,fix=request.facing_fix, credential=credential, call=call)image = corrected- request = replace(request, prompt=request.prompt +- f"\n\nThe subject stays in exact side view, facing {request.facing}. No turning around.")body = _build_generation_body(request, image, last_frame, references)published = _submit_poll_publish(verb="video", endpoint="generations", body=body, out=out, credential=credential,diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.pyindex d571080..f09756d 100644--- a/sprite_gen/video/batch.py+++ b/sprite_gen/video/batch.py@@ -28,6 +28,7 @@ from sprite_gen.spec.runio import atomic_write_textfrom sprite_gen.gen.chroma import KEY_BACKGROUND_TEXTfrom sprite_gen.gen.facing import FACINGS, validate as validate_facingfrom sprite_gen.gen import handedness as handed_mod+from sprite_gen.gen import prompt_partsfrom sprite_gen.gen.handedness import Handedfrom sprite_gen.video import facing as facing_modfrom sprite_gen.video import canvas as canvas_mod@@ -278,13 +279,22 @@ def _staggered_start(gap: float) -> None:def build_prompt(direction: str, state: str, character: str | None, facing: str = "right", motion: str | None = None,pinned: bool | None = None, model: str | None = None, handed: list[Handed] | None = None) -> str:- """The clip prompt for one (direction, state).+ """The clip prompt for one (direction, state): `clip_prompt_parts(...).text`."""+ return clip_prompt_parts(direction, state, character, facing=facing, motion=motion, pinned=pinned, model=model,+ handed=handed).text+++def clip_prompt_parts(direction: str, state: str, character: str | None, facing: str = "right", motion: str | None = None,+ pinned: bool | None = None, model: str | None = None,+ handed: list[Handed] | None = None) -> prompt_parts.Prompt:+ """The clip prompt for one (direction, state), as its pieces (`prompt_parts.Prompt`: `.text` is the+ prompt, `.notes` what the caller's own words say against or again after the engine's).`motion` replaces the built-in state sentence with the caller's own description of themotion, written as whole sentences about the subject (a request interpreter's output, forinstance). What stays put (`HOLD_TEXT`; for a walk or run, in place and facing the image's way,`GAIT_HOLD_TEXT`), the repeat count (`REPEAT_TEXT`) and the frame, camera, background and- design rules stay the engine's.+ design rules stay the engine's, and a rule the paragraph already quotes is not said again.`pinned` says the clip is pinned to end on its first frame (`video --last-frame`): it then asksfor the return to the first pose instead of an evenly paced repeat (`PINNED_LOOP_TEXT`). None@@ -296,10 +306,11 @@ def build_prompt(direction: str, state: str, character: str | None, facing: strwritten), and a Lite walk in a view where its head sways gets `LITE_HEAD_TEXT`.`handed` lists the character's asymmetric items (`handedness.parse`): the prompt ends with where each- one stays, anchored to the first frame and never named where it is hidden (`handedness.text(clip=True)`).+ one stays, anchored to the first frame (`handedness.text(clip=True)`)."""validate_facing(facing)view = VIEW_TEXT.get(direction, f"seen from the {direction}").format(facing=facing)+ turned = facing if direction in handed_mod.LATERAL_VIEWS else Noneif state in ACTION_TEXT_STATES:template = ACTION_COMMON_TEXTelif (state in PINNED_LOOP_STATES or (state in GAIT_STATES and direction in PINNED_GAIT_VIEWS)) if pinned is None else pinned:@@ -311,35 +322,35 @@ def build_prompt(direction: str, state: str, character: str | None, facing: strif not motion:raise SystemExit("video: motion description is empty")head = "2D game sprite animation. The character {motion} The character is {view}."- hold = f" {HOLD_TEXT[state]}" if state in HOLD_TEXT else ""- if state in GAIT_STATES and direction in GAIT_HOLD_TEXT:- hold += f" {GAIT_HOLD_TEXT[direction].format(facing=facing)}"- repeat = f" {REPEAT_TEXT[state]}" if state in REPEAT_TEXT else ""subject = character.strip().rstrip(".") if character else "The character"- return (f"2D game sprite animation. {motion}{hold}{repeat} {subject} is {view}." + template[len(head):]- + _lite_text(state, direction, model, built_in=False) + _handed_text(handed, direction, facing))- built_in = (VIEW_MOTION_TEXT[(state, direction)].format(facing=facing) if (state, direction) in VIEW_MOTION_TEXT- else MOTION_TEXT.get(state, f"performs the '{state}' action in place, repeating at an even rhythm."))- text = template.format(motion=built_in, view=view)- return ((text.replace("The character", character, 1) if character else text)- + _lite_text(state, direction, model, built_in=True) + _handed_text(handed, direction, facing))---def _handed_text(handed: list[Handed] | None, direction: str, facing: str) -> str:- """Where each asymmetric item is in this view, said last (`handedness.text`); nothing without one."""- if not handed:- return ""- return " " + handed_mod.text(handed, direction, facing if direction in handed_mod.LATERAL_VIEWS else None, clip=True)+ parts = prompt_parts.Prompt(f"2D game sprite animation. {motion}", caller=f"{motion} {character or ''}", sep=" ")+ if state in HOLD_TEXT:+ parts.add("hold", HOLD_TEXT[state])+ if state in GAIT_STATES and direction in GAIT_HOLD_TEXT:+ parts.add("gait-hold", GAIT_HOLD_TEXT[direction].format(facing=facing))+ if state in REPEAT_TEXT:+ parts.add("repeat", REPEAT_TEXT[state])+ parts.add("frame", f"{subject} is {view}." + template[len(head):], facing=turned or prompt_parts.NO_TURN)+ else:+ built_in = (VIEW_MOTION_TEXT[(state, direction)].format(facing=facing) if (state, direction) in VIEW_MOTION_TEXT+ else MOTION_TEXT.get(state, f"performs the '{state}' action in place, repeating at an even rhythm."))+ text = template.format(motion=built_in, view=view)+ parts = prompt_parts.Prompt(text.replace("The character", character, 1) if character else text,+ caller=character or "", sep=" ")+ parts.note(facing=turned or prompt_parts.NO_TURN)+ for topic, text in _lite_pieces(state, direction, model, built_in=motion is None):+ parts.add(topic, text)+ if handed:+ parts.add("handed", handed_mod.text(handed, direction, turned, clip=True), handed=handed)+ return parts-def _lite_text(state: str, direction: str, model: str | None, *, built_in: bool) -> str:+def _lite_pieces(state: str, direction: str, model: str | None, *, built_in: bool) -> list[tuple[str, str]]:"""What a Lite walk adds after the prompt, in the order it was measured: the calm walk, then the head."""if state != "walk" or not is_lite(model):- return ""- text = f" {LITE_WALK_TEXT}" if built_in else ""- if direction in LITE_HEAD_TEXT:- text += f" {LITE_HEAD_TEXT[direction]}"- return text+ return []+ return ([("lite-walk", LITE_WALK_TEXT)] if built_in else []) + (+ [("lite-head", LITE_HEAD_TEXT[direction])] if direction in LITE_HEAD_TEXT else [])# A walk seen from the front or from behind starts from a still redrawn mid-step. From a standing@@ -381,14 +392,14 @@ def walk_start_prompt(direction: str, key: str | None = None, handed: list[Handethen with `handed` where each asymmetric item is in this view (`handedness.text`, the still's sentences)."""if direction not in WALK_START_TEXT:raise SystemExit(f"video: no mid-step start still for the {direction} view (only {', '.join(WALK_START_TEXT)})")- text = WALK_START_TEXT[direction]+ parts = prompt_parts.Prompt(WALK_START_TEXT[direction], caller="", sep=" ")if key is not None:if key not in KEY_BACKGROUND_TEXT:raise SystemExit(f"video: a mid-step start still is drawn on a green or magenta key, not {key!r}")- text += f" {KEY_BACKGROUND_TEXT[key]}"+ parts.add("key-background", KEY_BACKGROUND_TEXT[key], key=key)if handed:- text += " " + handed_mod.text(handed, direction)- return text+ parts.add("handed", handed_mod.text(handed, direction), handed=handed)+ return parts.textdef run_video_cli(image: Path, prompt: str, out: Path, report: Path, *, duration: int, resolution: str, log: Path, last_frame: Path | None = None) -> int:@@ -480,7 +491,10 @@ def run_item(if direction in handed_mod.LATERAL_VIEWS:result["turned"] = facingtry:- prompt = build_prompt(direction, state, character, facing=facing, handed=handed)+ parts = clip_prompt_parts(direction, state, character, facing=facing, handed=handed)+ prompt = parts.text+ if parts.notes:+ result["prompt_notes"] = parts.notesclip = item_dir / "clip.mp4"clip_report = item_dir / "clip.report.json"reuse_clip = clip.exists() and clip_report.exists() and not forcediff --git a/sprite_gen/video/clip_prompt.py b/sprite_gen/video/clip_prompt.pyindex c1dbdf5..8ef579a 100644--- a/sprite_gen/video/clip_prompt.py+++ b/sprite_gen/video/clip_prompt.py@@ -55,8 +55,11 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:pinned = Falsewarnings.append(f"{direction} {state} filmed without its end-frame pin: the loop is searched, not cut whole, and may not close")pins = wants_pin and last_frame- prompt = batch_mod.build_prompt(direction, state, character, facing=facing, motion=motion, pinned=pinned, model=model,- handed=handed)+ parts = batch_mod.clip_prompt_parts(direction, state, character, facing=facing, motion=motion, pinned=pinned,+ model=model, handed=handed)+ prompt = parts.text+ # the caller's own words (--character, --motion) against the engine's: a conflict is a warning+ warnings += [note["text"] for note in parts.notes if note["kind"] == "conflict"]cycle = "pinned" if pins and state in batch_mod.PINNED_LOOP_STATES else "auto"# as video-set places and cuts: a side or diagonal view takes the facing, front and back face rightcanvas_facing = loop_facing = facing if direction in handed_mod.LATERAL_VIEWS else "right"@@ -82,6 +85,7 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:"loop": f"sprite-gen video-loop --frames-dir <dir>/frames/keyed --out-dir <dir>/loop --fps <fps in frames.report.json> --state {state} --cycle {cycle} --facing {loop_facing} --name {direction}-{state}",},"warnings": warnings,+ **({"notes": parts.notes} if parts.notes else {}),}if mid_step:record["start_still"] = {diff --git a/tests/gen/test_prompt_assembly.py b/tests/gen/test_prompt_assembly.pynew file mode 100644index 0000000..437014d--- /dev/null+++ b/tests/gen/test_prompt_assembly.py@@ -0,0 +1,281 @@+# SPDX-License-Identifier: Apache-2.0+"""Every prompt the engine puts together, over the whole option table, drawn as text only.++A prompt is the caller's text plus the engine's pieces (`sprite_gen.gen.prompt_parts`). The table below+is every still, clip, start-still and correction prompt the options can make; each one is checked for a+sentence said twice, for words that turn the subject both ways, and for more than one key background.+A new option is a new row in a table here, not a new test.++The checks are written here, apart from the engine's own (`prompt_parts`), so they do not agree with it+by construction.+"""++from __future__ import annotations++import itertools+import re++import pytest++from sprite_gen import gen+from sprite_gen.gen import chroma, facing as facing_mod, handedness as h, prompt_parts+from sprite_gen.gen import video as video_mod+from sprite_gen.video import batch, clip_prompt++FACINGS = ("right", "left")+# --handed: none, one item, two on one wrist, one on each wrist+HANDED = {+ "none": None,+ "watch": ["the black smartwatch=left wrist"],+ "watch+bracelet": ["the black smartwatch=left wrist", "the gold bracelet=left wrist"],+ "watch+ribbon": ["the black smartwatch=left wrist", "the red ribbon=right wrist"],+}+SUBJECT = "A small rabbit mascot, 2D game sprite, full body"+# The caller's own text: what it already says about the key, the turn and the item. `turn` / `item` is+# the side its words name, to tell an agreeing repeat from a conflict with the options.+USER_TEXT = {+ "plain": {"text": f"{SUBJECT}."},+ "names-key": {"text": f"{SUBJECT}, on a background of pure magenta.", "key": "magenta"},+ "names-key-coloured": {"text": f"{SUBJECT}, magenta-colored background.", "key": "magenta"},+ "names-key-hex": {"text": f"{SUBJECT} on a flat #FF00FF background.", "key": "magenta"},+ "rules-out-other-key": {"text": f"{SUBJECT}, no green screen."},+ "says-turn": {"text": f"{SUBJECT}, facing right.", "turn": "right"},+ "says-item-side": {"text": f"{SUBJECT}, wearing a black smartwatch on its left wrist.", "item": "left"},+ "says-other-item-side": {"text": f"{SUBJECT}, wearing a black smartwatch on its right wrist.", "item": "right"},+}+STATES = ("idle", "walk", "run", "jump", "attack", "cheer")+MODELS = {"pro": "grok-imagine-video-1.5", "lite": "grok-imagine-video-1.5-lite"}+# --motion: the built-in sentence, the caller's own, one that quotes an engine rule, one that walks the other way+MOTION = {+ "built-in": {"text": None},+ "own": {"text": "The rabbit walks with a cheerful bounce, swinging both arms."},+ "quotes-engine": {"text": "The rabbit walks with a cheerful bounce. Camera completely locked, no zoom, no pan, no reframing."},+ "says-turn": {"text": "The rabbit walks to the right with a cheerful bounce.", "turn": "right"},+}+++def _items(key: str) -> list[h.Handed] | None:+ return h.parse_all(HANDED[key]) or None+++def _views() -> list[tuple[str, str | None]]:+ """(view, facing): a turned view both ways, front and back once."""+ return [(view, facing) for view in h.VIEWS for facing in (FACINGS if view in h.LATERAL_VIEWS else (None,))]+++def _still_rows():+ for user, (view, facing), handed, refs in itertools.product(USER_TEXT, _views(), HANDED, (False, True)):+ parts = gen.still_prompt(USER_TEXT[user]["text"], view=view, facing=facing, handed=_items(handed), refs=refs,+ key="magenta" if refs else None)+ row = {"user": user, "facing": facing, "handed": handed}+ yield f"still/{user}/{view}@{facing}/{handed}/{'refs' if refs else 'text'}", parts, row+ if refs and facing: # the facing correction's regeneration+ retry = parts.replaced("facing", facing_mod.prompt_suffix(facing, retry=True, view=True))+ yield f"still-retry/{user}/{view}@{facing}/{handed}", retry, row+ # a reference run turned with --facing alone, no --direction, and its correction+ for user, facing in itertools.product(USER_TEXT, FACINGS):+ parts = gen.still_prompt(USER_TEXT[user]["text"], facing=facing, refs=True, key="magenta")+ row = {"user": user, "facing": facing, "handed": "none"}+ yield f"still/{user}/ref@{facing}", parts, row+ yield f"still-retry/{user}/ref@{facing}", parts.replaced("facing", facing_mod.prompt_suffix(facing, retry=True)), row+++def _clip_rows():+ for (view, facing), handed, state, model, motion in itertools.product(_views(), HANDED, STATES, MODELS, MOTION):+ if MOTION[motion]["text"] and state != "walk":+ continue+ parts = batch.clip_prompt_parts(view, state, "The rabbit mascot", facing=facing or "right",+ motion=MOTION[motion]["text"], model=MODELS[model], handed=_items(handed))+ row = {"user": None, "motion": motion, "facing": facing, "handed": handed, "state": state}+ yield f"clip/{view}@{facing}/{state}/{model}/{motion}/{handed}", parts, row+ if view == "side": # handed on to `sprite-gen video --direction side`+ yield (f"clip+video/{view}@{facing}/{state}/{model}/{motion}/{handed}",+ video_mod.side_view_prompt(parts.text, facing), row)+++def _start_still_rows():+ for view, key, handed in itertools.product(batch.WALK_START_TEXT, chroma.KEY_BACKGROUND_TEXT, HANDED):+ text = batch.walk_start_prompt(view, key, _items(handed))+ row = {"user": None, "facing": None, "handed": handed}+ yield f"start-still/{view}/{key}/{handed}", prompt_parts.Prompt(text, caller=""), row+ # handed back to `gen --ref --transparent --direction --handed`, as an agent reading `video-prompt` may+ again = gen.still_prompt(text, view=view, handed=_items(handed), refs=True, key=key)+ yield f"start-still+gen/{view}/{key}/{handed}", again, row+++ROWS = [*_still_rows(), *_clip_rows(), *_start_still_rows()]++# -- the checks ------------------------------------------------------------------------------------++_TURN_WORDS = re.compile(+ r"\bfac(?:ing|es?) (right|left)\b|\bto the (right|left)\b|\btoward the (?:upper |lower )?(right|left)\b"+ r"|\bthe (right|left) edge\b|\b(right|left) here means\b", re.IGNORECASE)+_KEY_ASK = re.compile(+ r"#(?:ff00ff|00ff00)\b|\b(?:magenta|green)(?:[- ]colou?red)? (?:chroma-key )?(?:background|backdrop|screen)\b"+ r"|\bbackground of pure (?:magenta|green)\b", re.IGNORECASE)+_KEY_RULED_OUT = re.compile(r"\bno (?:magenta|green) (?:background|screen)\b", re.IGNORECASE)+++def _sentences(text: str) -> list[str]:+ return [" ".join(part.split()).lower().rstrip(".!?") for part in re.split(r"(?<=[.!?])\s+|\n+", text) if part.strip()]+++def _turns(text: str) -> set[str]:+ return {next(side for side in match.groups() if side).lower() for match in _TURN_WORDS.finditer(text)}+++def _key_asks(text: str) -> int:+ return len(_KEY_ASK.findall(_KEY_RULED_OUT.sub(" ", text)))+++def test_the_table_covers_every_place_a_prompt_is_put_together() -> None:+ kinds = {name.split("/")[0] for name, _, _ in ROWS}+ assert kinds == {"still", "still-retry", "clip", "clip+video", "start-still", "start-still+gen"}+ assert len(ROWS) > 1000++[email protected]("name,parts,row", ROWS, ids=[name for name, _, _ in ROWS])+def test_no_prompt_says_a_sentence_twice_turns_both_ways_or_asks_for_two_keys(name, parts, row) -> None:+ text = parts.text+ said = _sentences(text)+ assert len(said) == len(set(said)), sorted({s for s in said if said.count(s) > 1})++ assert _key_asks(text) <= 1, text++ caller = {**USER_TEXT.get(row["user"] or "", {}), **MOTION.get(row.get("motion") or "", {})}+ facing = row["facing"]+ conflicts = {note["about"] for note in parts.notes if note["kind"] == "conflict"}+ if name.startswith("clip+video"):+ # the clip prompt handed on: its notes were the clip row's, and the side view is not held a second time+ assert parts.piece("side-view").added is False and parts.notes == []+ return+ if caller.get("turn") not in (None, facing):+ # the caller's own words turn another way than the view: they are left as written, and the notes say so+ assert "facing" in conflicts, name+ assert _turns(text.replace(caller["text"], "")) <= ({facing} if facing else set())+ else:+ assert _turns(text) <= ({facing} if facing else set()), (name, _turns(text))+ assert "facing" not in conflicts++ if row["handed"] != "none" and caller.get("item") == "right":+ assert "handed" in conflicts, name # the smartwatch is --handed left+ else:+ assert "handed" not in conflicts, parts.notes++[email protected]("name,parts,row", [r for r in ROWS if r[0].startswith("still")], ids=[r[0] for r in ROWS if r[0].startswith("still")])+def test_a_still_carries_the_key_line_unless_its_text_names_a_key(name, parts, row) -> None:+ piece = parts.piece("key-background")+ if piece is None:+ return+ named = USER_TEXT[row["user"]].get("key")+ assert piece.added is (named is None) and piece.found == (named or "")+ assert (chroma.KEY_BACKGROUND_TEXT["magenta"] in parts.text) is (named is None)+++# -- the known cases ---------------------------------------------------------------------------------+[email protected]("prompt,named", [+ ("a rabbit on a background of pure magenta", "magenta"),+ ("a rabbit, magenta-colored background", "magenta"),+ ("a rabbit, magenta coloured backdrop", "magenta"),+ ("background: solid green", "green"),+ ("a rabbit keyed on pure magenta", "magenta"),+ ("a rabbit drawn on a green key", "green"),+ ("a rabbit, no green screen", None),+ ("a rabbit without a green background", None),+ ("a rabbit, not on a magenta background", None),+ ("no green screen; use a magenta background", "magenta"),+ ("a rabbit with no shadow, on a magenta background", "magenta"),+ ("a knight holding a green key", None),+ ("a background of trees with green leaves", None),+ ("a hero in a green screen-printed shirt", None),+])+def test_a_key_background_is_read_however_it_is_worded_and_not_when_ruled_out(prompt: str, named: str | None) -> None:+ """2.22.0 missed "background of pure magenta" and "magenta-colored background", so the key line went on a+ second time, and read "no green screen" as asking for green, so no line went on at all."""+ assert chroma.named_key_background(prompt) == named+ key = "green" if "magenta" in chroma.ruled_out_key_backgrounds(prompt) else "magenta"+ parts = gen.still_prompt(prompt, refs=True, key=key)+ assert parts.piece("key-background").added is (named is None)+ assert parts.text.count("chroma-key fill (#") == (1 if named is None else 0)+++def test_a_key_the_text_rules_out_is_not_the_one_the_engine_asks_for() -> None:+ assert chroma.ruled_out_key_backgrounds("a rabbit, no green screen") == {"green"}+ with pytest.raises(SystemExit, match="rules out a green key background"):+ gen.still_prompt("a rabbit, no green screen", refs=True, key="green")+ # the text names the other key itself: nothing is added, so nothing is refused+ named = gen.still_prompt("no green screen; use a magenta background", refs=True, key="green")+ assert named.piece("key-background").found == "magenta" and not named.piece("key-background").added+++def test_a_turned_view_says_the_turn_once_and_the_reference_piece_only_pins_the_edge() -> None:+ """With --direction the view sentence says the turn. The reference piece said it again as a full profile+ ("facing left (toward the left edge of the image)"), against a three-quarter view's 45 degrees."""+ plain = gen.still_prompt("a rabbit", facing="left", refs=True)+ assert plain.text.endswith(facing_mod.prompt_suffix("left")) and "must be facing left" in plain.text+ for view in sorted(h.LATERAL_VIEWS):+ text = gen.still_prompt("a rabbit", view=view, facing="left", refs=True).text+ assert "must be facing" not in text+ assert text.endswith("Left here means toward the left edge of the image, regardless of the reference image's "+ "orientation. Preserve the subject's design.")+ front = gen.still_prompt("a rabbit", view="front", refs=True)+ assert front.piece("facing") is None+++def test_a_correction_takes_the_place_of_the_sentence_it_corrects() -> None:+ """The regeneration's prompt was the first prompt plus the correction: the facing sentence twice."""+ parts = gen.still_prompt("a rabbit", facing="right", refs=True, key="magenta")+ retry = parts.replaced("facing", facing_mod.prompt_suffix("right", retry=True)).text+ assert retry.count("The subject must be facing right") == 1 and retry.count("Preserve the subject's design.") == 1+ assert retry.endswith(facing_mod.prompt_suffix("right", retry=True))+ assert chroma.KEY_BACKGROUND_TEXT["magenta"] in retry+++def test_a_side_clip_is_held_once_and_a_prompt_turned_the_other_way_is_refused() -> None:+ prompt = batch.build_prompt("side", "walk", None, facing="left")+ assert video_mod.side_view_prompt(prompt, "left").text == prompt+ own = video_mod.side_view_prompt("The fox trots in place.", "left").text+ assert own == "The fox trots in place.\n\nThe subject stays in exact side view, facing left. No turning around."+ with pytest.raises(SystemExit, match="faces left .* facing right"):+ video_mod.side_view_prompt(prompt, "right")+++def test_an_engine_rule_the_motion_paragraph_quotes_is_not_said_again() -> None:+ rule = "Camera completely locked, no zoom, no pan, no reframing."+ text = batch.build_prompt("side", "walk", None, motion=f"The fox trots in place. {rule}")+ assert text.count(rule) == 1+ assert "Keep the design, colors and proportions exactly as in the image." in text+++def test_video_prompt_warns_when_the_callers_words_turn_the_other_way() -> None:+ record = clip_prompt.plan_prompt(direction="side", state="walk", facing="right", motion="It walks to the left.")+ assert any('"walks to the left"' in line for line in record["warnings"])+ assert record["notes"][0]["kind"] == "conflict"+ quiet = clip_prompt.plan_prompt(direction="side", state="walk", facing="right", motion="It strolls.")+ assert quiet["warnings"] == [] and "notes" not in quiet+++def test_gen_reports_what_the_callers_text_says_against_the_options(tmp_path, monkeypatch, capsys) -> None:+ from PIL import Image++ from sprite_gen.gen.base import ProviderRun++ class Backend:+ name = "fake"+ transparency = "native"++ def generate(self, request, workdir):+ Image.new("RGB", (8, 8), (255, 0, 255)).save(request.raw)+ return ProviderRun(self.name, 1, model="test-image", extra={})++ monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: Backend())+ result = gen.generate_image("fake", "a rabbit facing left, a black smartwatch on its right wrist",+ tmp_path / "out.png", view="side", facing="right",+ handed=h.parse_all(["the black smartwatch=left wrist"]))+ assert {note["about"] for note in result.extra["prompt_notes"]} == {"facing", "handed"}+ err = capsys.readouterr().err+ assert '[gen] warning: the text says "facing left" and the engine\'s sentence says right' in err+ quiet = gen.generate_image("fake", "a rabbit", tmp_path / "quiet.png", view="side", facing="right")+ assert "prompt_notes" not in quiet.extra