Skip to content

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__.py
index 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_text
from . import chroma as chroma_mod
from . import facing as facing_mod
from . import handedness as handed_mod
+from . import prompt_parts
from .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_cell
width, 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 // 2
line, 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 cell
def _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 = None
strategy_source: str | None = None
- key_background: dict[str, Any] | None = None
if 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 refusal
raise 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 None
workdir = 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 = None
if 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.raw
raw_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 ""
+ return
handed_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 parts
def _run(args: argparse.Namespace) -> int:
diff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.py
index 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.py
index 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 an
explicit 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, fix
else:
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 the
diff --git a/sprite_gen/gen/prompt_parts.py b/sprite_gen/gen/prompt_parts.py
new file mode 100644
index 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.py
index 18e0871..9aa3f68 100644
--- a/sprite_gen/gen/video.py
+++ b/sprite_gen/gen/video.py
@@ -55,7 +55,7 @@ from pathlib import Path
from typing import Any, Callable
from sprite_gen.spec.runio import atomic_write_text
-from . import refusal
+from . import prompt_parts, refusal
from .base import announce_api_billing
from .facing import FACINGS, validate as validate_facing
from 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 = None
if 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.py
index 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_text
from sprite_gen.gen.chroma import KEY_BACKGROUND_TEXT
from sprite_gen.gen.facing import FACINGS, validate as validate_facing
from sprite_gen.gen import handedness as handed_mod
+from sprite_gen.gen import prompt_parts
from sprite_gen.gen.handedness import Handed
from sprite_gen.video import facing as facing_mod
from 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 the
motion, written as whole sentences about the subject (a request interpreter's output, for
instance). 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 asks
for 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: str
written), 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 None
if state in ACTION_TEXT_STATES:
template = ACTION_COMMON_TEXT
elif (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: str
if 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[Hande
then 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.text
def 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"] = facing
try:
- 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.notes
clip = item_dir / "clip.mp4"
clip_report = item_dir / "clip.report.json"
reuse_clip = clip.exists() and clip_report.exists() and not force
diff --git a/sprite_gen/video/clip_prompt.py b/sprite_gen/video/clip_prompt.py
index 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 = False
warnings.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 right
canvas_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.py
new file mode 100644
index 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