Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

feat(pixel-draw): Claude Opus draws 8-48 px pixel art directly as a pixel grid — G1 parse with row repair and one redraw, gates G2-G6, a vision pick, Message Batches and --resume; grid.txt is the truth

Soohong Kime083822749aa
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9d66cdd..ae25c8d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased
+- **New: `sprite-gen pixel-draw` — Claude Opus draws pixel art of 8–48 px directly, as a pixel grid.** The model writes a palette and one line of keys per pixel row (a character grid, or JSON with `--format json`); code checks it and renders it. `--subject` (or `--spec`), `--size` 8–48 (32), `--kind sprite|icon|tile`, `--frames` (up to four, drawn in one call; `--walk-cycle` for contact, passing, contact, passing), `--palette free[:N]|pico8|#hex,…|file`, `--candidates` (2), `--effort medium|high|xhigh` (high), `--batch` (Message Batches, half price), `--max-tokens` (32000 for one frame, 64000 for more), `--pick vision|human`. G1 reads every answer strictly; a row one key too long or short, a key outside the palette or rows missing at the end go back to the model on their own with a column ruler and are spliced in (two rounds), and an answer still broken — or broken beyond its rows — is drawn once more; a single frame written without its `FRAME` line is recovered and recorded. G2 palette, G3 alpha and G6 frames (one ground line, heights within a pixel, no two frames the same) fail a candidate; G4 tile seam, G5 stray pixels and a walk whose legs barely change sides warn. Of two or more candidates that pass, one vision call at effort low picks (G7). An answer that spent every token thinking is drawn once more one effort lower; a refusal is reported as it came (`refused by the provider's content policy (stop_reason=refusal category=…)`); nothing falls back to another model. The run folder holds `grid.txt` (the truth: edit it and re-render with `--grid`), `palette.json`, `frame-<name>.png` written by an encoder whose bytes depend on the pixels alone, `preview-x<s>.png`, `tiled-3x3.png` for a tile, `anim.gif` for several frames, every call under `calls/` and `report.json` with each call's model, effort, usage (thinking tokens included), price, seconds and request id, the gate results and the repair history. A batch is recorded the moment it is submitted, and `--resume` collects it — and reads every answered call back — instead of buying it twice. It runs on `ANTHROPIC_API_KEY`, billed per call and said so on stderr; the transport is urllib, so the dependency surface stays Pillow and NumPy — [docs/pixel-draw.md](docs/pixel-draw.md).
- **Fix: a poll xAI answers 429 or 5xx asks the same request again — the clip is bought once.** `video`, `video-extend` and `video-edit` ended the run on any non-2xx poll, after xAI had accepted the request and may bill it, and the line read `(HTTP 429)` — what `video-set`, and any caller that backs off on a refused submission, answers by submitting the clip again: a second clip paid for, the first never published. A poll answered `429`, `500`, `502`, `503` or `504` is now asked again on the same `request_id`, after a wait that doubles from 8 s up to 60 s while the polls are refused and goes back to 4 s on an answer; a stderr note says each, the status in plain digits. The poll timeout (`SPRITE_GEN_VIDEO_TIMEOUT_SECONDS`) still bounds the whole poll, a pending poll's waits included (and, below, the downloads). A refused POST is still never sent again, and a `400` or `404` poll still ends the run with its status (a `401` or `403` poll is unfinished, below).
- **Output change: a generation the poll timeout cut short is unfinished, named by its `request_id`.** Polls still pending or still refused at the timeout end the run with a line that names `request_id=<id>`, says the generation may still finish and be billed, and carries no `(HTTP <n>)`, a refusal line's status — a caller that reads `(HTTP 429)` there sends the request again, unbilled only when it was refused. The pending line keeps its front (`still 'pending' after N polls — poll timeout;`). With `--report` the run leaves a `sprite-gen-video-unfinished` report there (`verb`, `auth_source`, `model`, `request_id`, `out`, `polls`, `polls_refused`, `last_poll`, `elapsed_seconds`) and prints nothing on stdout; Python callers catch `GenerationUnfinished`, a `SystemExit`. The success report gains `polls_refused`, how many of its `polls` xAI answered 429 or 5xx (docs/video.md, An unfinished generation).
- **`tests/gen/test_video.py`** scripts the polls: each of the five statuses refused twice, then pending, then done, is asked on the one request with waits 8, 16, 4 and published with `polls_refused` 2; polls refused until a 300 s timeout wait 8, 16, 32, 60 × 4, ask no poll whose wait would reach the timeout and end unfinished after eight with no `(HTTP n)` and no `HTTP 429` on stderr; a pending timeout names the request; a 400 or 404 poll ends at once; a refused POST is sent once; the CLI leaves the unfinished report and an empty stdout. The 500-poll case of the failure table is a 404 now, the status that still ends a run.
diff --git a/SKILL.md b/SKILL.md
index 44c1e91..7fd384c 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -109,6 +109,7 @@ hold the arms still, and check the loop with `handed-check --state walk`.
| Restore post-processing damage in the current cut from its exact source times, preserving normal cells and playback | `video-source-manifest` → `video-loop-repair` → `video-loop-compare` | [source restoration](docs/loop-comparison.md#restoring-the-active-cut-from-source) |
| Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop` (a walk or run with `--anchor motion-auto`, which holds its size), and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories (a set it stops on a loop that may hold two cycles: look at that loop, count its strides, and pass `--cycles <loop>=<k>`; a loop the report lists under `unnamed_feet` — its view could not tell the feet apart, or only by too small a margin (`low-margin`): look at its first candidate frame, say which own foot lands there, and align again with `--foot <loop>=left|right`). `video-set` is not run on this route, so the set stage it runs by default (`--align-cycles auto`) is yours to run. sprite-gen never calls the MCP. Walk, run and jump only: ZCRE's `grok-imagine-video-1.5` has no end frame, so idle, attack and diagonal walks are refused unless `--unpinned` | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
| Ordinary image or edit | `gen --provider codex` or `gen --provider grok` (subscription routes) | [gen](docs/gen.md) |
+| Pixel art the model draws directly as a grid, 8–48 px (best at 32 or less): an icon, a prop, a monster, a character still, four directions, a walk draft, a tile — on `ANTHROPIC_API_KEY`, **billed per call**; `grid.txt` is the truth, `--grid` re-renders an edited one, `--resume` collects a batch instead of buying it twice | `pixel-draw` | [pixel-draw](docs/pixel-draw.md) |
| Image generation with no login available (server, container, SaaS) | `gen --provider openai` — server/SaaS route on `OPENAI_API_KEY`, **billed per call**, never a default or a fallback | [gen](docs/gen.md#subscription-first--openai-is-named-or-it-does-not-run) |
| Base and direction anchors | `anchor` | [directional-anchor-workflow](docs/directional-anchor-workflow.md) |
| Curation view or existing image candidates | `curation`, `unpack-atlas --pngs-dir` | [curation](docs/curation.md) |
diff --git a/docs/README.md b/docs/README.md
index dda502a..a42988e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -78,6 +78,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
| Doc | Owns |
|---|---|
| [gen.md](gen.md) | `sprite-gen gen` / `gen-set`: providers, default resolution, transparency strategy per provider, row usage |
+| [pixel-draw.md](pixel-draw.md) | `sprite-gen pixel-draw`: Claude Opus draws 8–48 px pixel art as a pixel grid — the inputs, the run folder and its report, gates G1–G7, the row repair and the one redraw, the pick between candidates, Message Batches and `--resume`, re-rendering an edited `grid.txt` |
| [prompt-assembly.md](prompt-assembly.md) | What the engine adds to a still or clip prompt and when: the pieces, the 2.22.0 freeze without `--handed`, what counts as already said, and the notes on the caller's own words |
| [video.md](video.md) | `sprite-gen video` / `video-extend` / `video-edit` / `video-resume`: stills and clips to mp4 through Grok Imagine (image-to-video, last-frame pin, references, extension, editing, asking again for an unfinished generation) with the user's own credential |
| [video-pipeline.md](video-pipeline.md) | Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, the batch, a set's directions on one sheet |
diff --git a/docs/pixel-draw.md b/docs/pixel-draw.md
new file mode 100644
index 0000000..8d7a793
--- /dev/null
+++ b/docs/pixel-draw.md
@@ -0,0 +1,227 @@
+# `sprite-gen pixel-draw` — Claude Opus draws pixel art as a pixel grid
+
+> Owns: `sprite-gen pixel-draw`: the inputs, the run folder and `report.json`, gates G1–G7, the row repair, the one redraw, the pick between candidates, Message Batches and `--resume`, re-rendering an edited `grid.txt` · Index: [docs/README.md](README.md)
+
+The model does not paint an image that is then shrunk to a grid. It writes the grid itself: a
+palette of keys and, per frame, one line of keys per pixel row. Code checks every answer, asks for
+broken rows again one at a time, renders the frames and, among candidates that pass, has one
+vision call pick. `grid.txt` — the palette and the rows — is the truth of a run; every PNG is
+derived from it and can be derived again.
+
+Use it for a single small asset: an item icon, a prop, a monster, a character still, four facing
+directions, a draft walk cycle, a grass or water tile. It was measured on `claude-opus-5-5` on
+2026-10-12 (250 drawings of 12 subjects at 16–48 px, judged by a vision model against the same
+subjects made with GPT images shrunk by sprite-gen's own functions):
+
+- single assets at 32 px and below came out shippable, and beat the shrunk GPT images at 16 px and
+ on characters, where one-pixel details (eyes, a belt, a glint) are placed on the grid from the
+ start instead of being averaged away;
+- 48 px held up (7 of 8 shippable) but is the edge of what was measured; past 48 px, painterly
+ styles, or a character from a picture the user gave, use [`gen`](gen.md) and
+ [pixel-unfake](pixel-unfake.md) instead;
+- a walk cycle keeps the body consistent but the legs barely change sides between the two contact
+ frames: it is a draft for a touch-up, and the run says so (G6 warning). A real loop belongs to the
+ [video → loop pipeline](video-pipeline.md);
+- a fixed palette (`pico8`) was kept every time, at a visible cost in material rendering;
+- dense small-pattern tiles (cobblestones) sometimes spent every token thinking and wrote nothing,
+ at effort xhigh only.
+
+It runs on `ANTHROPIC_API_KEY` and **every call is billed per call** against that key; the run
+says so on stderr before the first request leaves, and `report.json` adds up what it cost.
+
+## Quick start
+
+```bash
+export ANTHROPIC_API_KEY=<your Claude Console key>
+
+# one sprite, 32x32, two candidates, the vision pick
+sprite-gen pixel-draw --out-dir runs/slime \
+ --subject "A green slime monster: a glossy jelly blob with two black eyes and a white highlight, front view."
+
+# an inventory icon at 16 px, PICO-8 colours only
+sprite-gen pixel-draw --out-dir runs/potion --kind icon --size 16 --palette pico8 \
+ --subject "An inventory icon of a red health potion: a round glass flask with a cork stopper."
+
+# four directions in one call (say what each frame is in the subject)
+sprite-gen pixel-draw --out-dir runs/knight-4dir --frames down,up,left,right \
+ --subject "A small RPG knight, standing idle: down = facing the viewer, up = back turned, left and right = profiles."
+
+# a walk cycle draft
+sprite-gen pixel-draw --out-dir runs/knight-walk --frames walk1,walk2,walk3,walk4 --walk-cycle \
+ --subject "A small RPG knight, side view facing right, walking."
+
+# a repeating tile, twenty of them at half price: --batch
+sprite-gen pixel-draw --out-dir runs/grass --kind tile --batch \
+ --subject "A top-down grass ground tile: short green grass with a few lighter blades and small darker tufts."
+```
+
+On success the report is printed on stdout and written to `<out-dir>/report.json`; the picked
+candidate's files are at the top of the run folder.
+
+## Inputs
+
+| Flag | Values (default) | What it does |
+|---|---|---|
+| `--subject TEXT` | words | What to draw. For several frames, say what each one is (the frame names are listed for the model, their meaning comes from your words). |
+| `--spec FILE` | JSON object | `subject`, `size`, `kind`, `frames`, `walk_cycle`, `palette` instead of the flags. A key given both in the file and as a flag is refused. |
+| `--size N` | 8–48 (32) | Canvas side in pixels; every frame is N×N. Measured best at 32 or less. |
+| `--kind` | `sprite`, `icon`, `tile` (`sprite`) | Sprites and icons have a transparent background and a dark outline; a tile fills every pixel and repeats seamlessly. |
+| `--frames a,b,…` | 1–4 names (one frame named after `--kind`) | Frames drawn **in one call**, so they share one palette and one design. Names are letters, digits, `_` and `-`. |
+| `--walk-cycle` | flag | The four frames are contact, passing, contact, passing: the prompt says so and G6 checks the legs change sides. |
+| `--palette` | `free[:N]` (`free:16`), `pico8`, `#RRGGBB,…`, or a file | A free palette allows at most N colours; a fixed one allows only its colours. A file is JSON (a list, or `{"colors": [...]}`) or one colour per line (`RRGGBB` or `#RRGGBB`, `;` comments — Lospec's `.hex`). |
+| `--candidates K` | 1–6 (2) | Answers drawn for the request, each on its own; one is picked (G7). |
+| `--effort` | `medium`, `high`, `xhigh` (`high`) | Thinking effort of each drawing. |
+| `--format` | `chargrid`, `json` (`chargrid`) | How the model writes the grid. `grid.txt` is a character grid either way. |
+| `--batch` | flag | Draw through Message Batches at half price and wait for the batch (below). |
+| `--batch-wait S` | seconds (3600) | How long to wait for one batch before the run ends unfinished; `--resume` collects it later. `0` submits and returns. |
+| `--max-tokens N` | 1024–128000 (32000 for one frame, 64000 for more) | Output cap of each drawing, thinking included. |
+| `--pick` | `vision`, `human` (`vision`) | Who picks among candidates that passed. |
+| `--out-dir DIR` | a new or empty folder | The run folder. |
+| `--resume` | flag | Continue the run in `--out-dir` from its `request.json` (below). |
+| `--grid FILE` | a `grid.txt` | Check and render an edited grid; no model call (below). |
+
+## What a run does
+
+For each candidate, independently (in parallel, or in one batch):
+
+1. **Draw** at `--effort`, with the prompt built from the inputs: the subject, the canvas, the frames
+ (and the walk cycle), the palette rule, the kind's background and style rules, and the exact
+ output format.
+2. **G1 parse.** The answer is read strictly ([below](#gates)). A row one key too long or short, a
+ key that is not in the palette, rows missing at the end — those rows go back to the model on
+ their own, each with the rows above and below and a column ruler, and it answers
+ `ROW <frame> <n>: <row>` lines that code splices in (effort medium, about $0.01 and six seconds
+ each). Two rounds at most.
+3. **Redraw, once.** An answer still broken after its repairs, or broken beyond its rows (no block,
+ a broken palette, a frame missing, too many rows), is drawn again at the same effort. An answer
+ that spent all `--max-tokens` thinking and wrote nothing is drawn again **one effort lower**
+ (xhigh → high → medium → low). A candidate is drawn at most twice in all.
+4. **G2–G6** on the pixels. G2, G3 and G6 fail the candidate; G4, G5 and the walk check warn.
+5. **G7 pick.** Of two or more candidates that passed, one vision call (`claude-opus-5-5`, effort
+ low, structured output) looks at all of them on one sheet, shuffled under letters, scores each and
+ names the best; with `--pick human` nobody picks and the candidates wait for a person. One that
+ passed alone is the pick.
+
+A refusal is reported as it came and that candidate is not drawn again. Nothing falls back to
+another model, provider or effort beyond the one lowered redraw.
+
+## Gates
+
+| Gate | Checks | On failure |
+|---|---|---|
+| G1 parse | One block; palette lines `<key> #RRGGBB` (`.` is transparent and nothing else); the frames asked for, each exactly N rows of N palette keys | Row issues → row repair (two rounds), then one redraw; anything else → one redraw. Recovered by code and recorded: a single frame written without its `FRAME` line or under another name, frames in another order, the fence tagged otherwise, no `END` line |
+| G2 palette | Opaque colours used ≤ the limit; a fixed palette's colours only | fails |
+| G3 alpha | Sprite/icon: something drawn, four transparent corners, border at least half transparent. Tile: every pixel opaque | fails |
+| G4 tile seam | Colour step across the wrap edges ÷ the mean step inside the tile ≤ 1.5 | warns — mortar lines that meet the edge raise it on tiles that repeat cleanly; look at `tiled-3x3.png` |
+| G5 stray pixels | Opaque pixels of a sprite/icon with no opaque 4-neighbour | warns |
+| G6 frames | Same bottom row in every frame, heights within one pixel, no two frames the same. With `--walk-cycle`: the contact frames differ by at least 40% of the mean contact↔passing difference | fails; the walk check warns ("weak leg alternation — touch up the legs") |
+| G7 pick | Two or more passed: the vision pick (or a person) | a pick that fails ends the run `pick_failed`, candidates kept |
+
+## The run folder
+
+```
+<out-dir>/
+ request.json the resolved request (what --resume reads)
+ report.json everything below, and what it cost
+ grid.txt the picked candidate's grid: the truth, editable, diffable
+ palette.json its keys and colours, the rule, the colours used
+ frame-<name>.png each frame at its own size, byte for byte reproducible
+ preview-x<s>.png the frames side by side, nearest-neighbour ×s (about 256 px a frame)
+ tiled-3x3.png a tile repeated 3×3 (×s)
+ anim.gif two or more frames, 150 ms each (×s)
+ candidates/c1/… the same files for every candidate whose grid parsed whole
+ calls/<id>.json every model call: prompt, answer, thinking summary, usage, request id
+ batches/<id>.json every batch submitted, the moment it was
+ pick-sheet.png the sheet the vision pick looked at
+```
+
+The top-level files are the picked candidate's, copied. With `--pick human`, or when nothing
+passed, there are none: the candidates are under `candidates/`.
+
+`frame-<name>.png` is written by sprite-gen's own encoder (stored deflate blocks): its bytes depend
+on the pixels alone, so the same `grid.txt` gives the same file on any machine and any Pillow or
+zlib build. The previews, the tiling and the GIF are views for the eye.
+
+### `report.json`
+
+| Field | |
+|---|---|
+| `status` | `ok`, `failed` (no candidate passed), `refused` (every candidate refused), `pick_failed`, `unfinished` (a batch not collected yet) |
+| `request` | the resolved inputs (`palette` with its rule and colours) |
+| `chosen`, `files`, `warnings` | the picked candidate, its top-level files, its warnings |
+| `pick` | `by` (`vision` / `only` / `human`), `best`, and for the vision pick its `labels`, `sheet` and `verdict` |
+| `candidates[]` | per candidate: `status`, `reason`, `effort` of the answer kept, `generations` (call ids), `redraws` (after which call, why, at which effort), `repairs` (rows asked, answered, still broken), `G1` (issues and what was recovered), `gates` (G2–G6 with their measures), `warnings`, `files` |
+| `calls[]` | per call: `id` (`c1-gen1`, `c1-gen1-fix1`, `pick`), `purpose`, `mode` (`realtime` / `batch`), `model`, `effort`, `max_tokens`, `request_id`, `message_id`, `batch_id`, `stop_reason`, `stop_details`, `usage` (as the API reported it), `thinking_tokens`, `cost_usd`, `seconds`, and for a failed call `error` and `billed` |
+| `batches[]` | per batch: `id`, `custom_ids`, `submitted_at`, `collected`, `ended_at`, `waited_seconds` |
+| `usage`, `cost_usd`, `seconds` | totals over the calls, and the run's wall time |
+
+`cost_usd` is each call's usage at the published price (below), Message Batches at half. It is
+what the calls cost by the API's own usage counts, not a console bill.
+
+## Failures
+
+The run ends non-zero with one line on stderr, and the report says the rest:
+
+- **No candidate passed** — `pixel-draw: no candidate passed the gates (c1: <reason>; c2: …)`.
+- **Every candidate refused** — `pixel-draw: refused by the provider's content policy
+ (stop_reason=refusal category=<category>); every candidate was refused` (the
+ [refusal marker](gen.md#direct-openai-calls-and-authentication) callers already read).
+- **A call failed** — a request the API refused before answering (429, 5xx, 529 overloaded) made
+ nothing and is asked again twice, each wait said on stderr. Anything else — a 400, a rejected key,
+ a stream that broke after it began (what was written may be billed) — ends that candidate with
+ the API's line (the key masked) and is not asked again.
+- **A batch not collected** — `unfinished`, below.
+
+## Message Batches and `--resume`
+
+`--batch` sends the drawings through Message Batches, which bill half and may take up to 24 hours
+(most finish within one). The row repairs and the pick stay realtime: they cost about a cent and
+would add a batch wait each. The batch is recorded in `batches/<id>.json` the moment it is
+submitted.
+
+If it has not ended within `--batch-wait`, the run ends `unfinished`, naming the batch and the
+command that collects it:
+
+```bash
+sprite-gen pixel-draw --out-dir runs/grass --resume
+```
+
+`--resume` reads the request from `request.json` (generation flags are refused with it), reads every
+call already answered back from `calls/` instead of asking it again, collects a batch already
+submitted instead of submitting it again, and carries on. A call that ended in an error, and a
+realtime call that was cut off mid-answer, are asked again. A `calls/` record built from another
+request than the one in `request.json` stops the run rather than being reused.
+
+## Editing `grid.txt` — `--grid`
+
+```bash
+sprite-gen pixel-draw --grid runs/slime/grid.txt --out-dir runs/slime-edit [--kind sprite] [--palette free:16] [--walk-cycle]
+```
+
+Reads a character grid (the frames and size are what it holds), runs G1 (no repair: an issue is
+reported with its frame and row) and G2–G6, and writes the same files and a report with no calls.
+Pass the `--kind`, `--palette` and `--walk-cycle` the grid was drawn under; the run's
+`request.json` has them.
+
+## Model, effort and price
+
+| | Value | Source |
+|---|---|---|
+| Model | `claude-opus-5-5` | Models API `GET /v1/models/claude-opus-5-5`, 2026-10-12: output cap 128,000 tokens |
+| Thinking | `{type: adaptive, display: summarized}` | the only mode the model takes (`disabled` and a token budget are 400s); the summary keeps the stream alive and is kept in `calls/` |
+| Effort | `output_config.effort`, always sent | the model's own default is `medium`, so the run never leaves it implicit |
+| Price | $4 input, $20 output per million tokens; thinking is billed as output; Message Batches half | platform.claude.com pricing, 2026-10-12 |
+
+Measured at 32 px on one candidate (median, realtime): effort high $0.17 and about 80 seconds,
+xhigh $0.59 and 2–5 minutes, medium $0.10 and about 50 seconds; judged quality hardly moved between
+them, which is why high is the default. Medium and high break the grid more often (a quarter or
+more of answers at 32 px, against a sixth at xhigh) — the row repair fixed 21 of 29 broken answers on its
+own. xhigh alone ended five times with nothing written at the token cap.
+
+A run of this verb, 2026-10-12, at 32 px, effort high, two candidates and the vision pick: a
+sprite $0.39 in 104 seconds, an icon $0.31 in 79, a tile $0.21 in 56, a four-frame walk cycle $0.96
+in 274. One drawing of a single frame cost $0.09–0.20, a row repair $0.01–0.02 and the pick about
+$0.01.
+
+The transport is raw HTTPS over urllib, as for the other providers: the runtime dependency surface
+stays Pillow and NumPy ([SECURITY.md](../SECURITY.md)).
diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.py
index 4d1d665..dd05e35 100644
--- a/sprite_gen/_modules.py
+++ b/sprite_gen/_modules.py
@@ -22,6 +22,7 @@ MODULE_DOMAIN = {
'migrate_breathe': 'spec',
'video': 'gen',
'gen_set': 'gen',
+ 'pixel_draw': 'gen',
'canvas': 'video',
'frames': 'video',
'loop': 'video',
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index 5abafa4..0bbebaa 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -14,7 +14,7 @@ from sprite_gen.compose import compose_atlas, compose_cycle, compose_gif, compos
from sprite_gen.qa import correction_loop, inspect, preview, score, motion
from sprite_gen.qa import handed as handed_check
from sprite_gen.frames import cutout, extract, slice_sheet, unpack_atlas
-from sprite_gen.gen import gen_set, prepare, video
+from sprite_gen.gen import gen_set, pixel_draw, prepare, video
from sprite_gen.video import batch as video_batch
from sprite_gen.video import canvas as video_canvas
from sprite_gen.video import frames as video_frames
@@ -320,6 +320,12 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
gen_set.add_arguments,
gen_set.run,
),
+ # Same declaration-once rule: the module owns its argument surface (docs/pixel-draw.md).
+ "pixel-draw": (
+ "Claude Opus draws 8..48 px pixel art as a pixel grid: gates, row repair, a pick of candidates; grid.txt is the truth, PNGs byte-reproducible (ANTHROPIC_API_KEY, billed per call).",
+ pixel_draw.add_arguments,
+ pixel_draw.run,
+ ),
"video": (
"Animate a still (or pin a last frame / guide with references) into a verified mp4 via Grok Imagine (your own grok login or XAI_API_KEY).",
_add_video,
diff --git a/sprite_gen/gen/anthropic_api.py b/sprite_gen/gen/anthropic_api.py
new file mode 100644
index 0000000..853f5b8
--- /dev/null
+++ b/sprite_gen/gen/anthropic_api.py
@@ -0,0 +1,419 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Anthropic Messages API transport for `pixel-draw`: the credential, one streamed message,
+Message Batches, and what a call cost.
+
+Raw HTTP over urllib, like `openai_provider` and `xai`: the runtime dependency surface is Pillow
+and NumPy (SECURITY.md), and one more SDK with its own HTTP stack would be a second transport for
+the same job. Field names and behaviour are the documented Messages API surface
+(platform.claude.com, 2026-10-12 확인):
+
+- `POST /v1/messages` with `stream: true` answers Server-Sent Events: `message_start` (a message
+ with empty content and the input usage), per content block a `content_block_start`, its deltas
+ (`text_delta`, `thinking_delta`, `signature_delta`) and a `content_block_stop`, then
+ `message_delta` (stop reason, cumulative usage) and `message_stop`; `ping` at any time; an
+ `error` event may arrive mid-stream (`overloaded_error`). The response header `request-id`
+ names the request.
+- `claude-opus-5-5` takes `thinking: {type: adaptive}` only (`disabled` and a token budget are
+ 400s) and `output_config.effort` low|medium|high|xhigh|max, default medium — so the effort is
+ always sent. Thinking tokens are billed as output and reported under
+ `usage.output_tokens_details.thinking_tokens`.
+- `POST /v1/messages/batches` takes `{requests: [{custom_id, params}]}` (custom_id
+ `^[a-zA-Z0-9_-]{1,64}$`, no `stream` in params); `GET /v1/messages/batches/{id}` reports
+ `processing_status` in_progress|canceling|ended and, once ended, `results_url`, a JSONL file of
+ `{custom_id, result: {type: succeeded|errored|canceled|expired, ...}}`. Only `succeeded` is
+ billed, at half the price of the same call made directly.
+
+A refusal of the request itself — 429, 500, 502, 503, 504, 529 before any answer began — made
+nothing, so it is asked again, twice at most, each time said on stderr. Anything after the answer
+began (a broken stream, an `error` event) may have been billed and is never asked again here.
+There is no refusal fallback to another model: `pixel-draw` reports a refusal as it came.
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from . import refusal
+
+API_BASE = "https://api.anthropic.com/v1"
+API_VERSION = "2023-06-01"
+AUTH_ENV = "ANTHROPIC_API_KEY"
+MODEL = "claude-opus-5-5"
+EFFORTS = ("low", "medium", "high", "xhigh", "max")
+# Output cap of claude-opus-5-5 (Models API `max_tokens`, measured 2026-10-12).
+MODEL_MAX_TOKENS = 128000
+
+# USD per million tokens, platform.claude.com/docs/en/about-claude/pricing (2026-10-12 확인).
+PRICE_PER_MTOK = {
+ MODEL: {"input": 4.00, "cache_write_5m": 5.00, "cache_write_1h": 8.00, "cache_read": 0.20, "output": 20.00},
+}
+BATCH_DISCOUNT = 0.5
+
+RETRY_STATUSES = (429, 500, 502, 503, 504, 529)
+RETRY_WAITS = (10.0, 30.0) # before the second and the third ask
+RETRY_AFTER_MAX = 120.0
+# One socket read may wait this long. Thinking streams its summary (`display: summarized`) and the
+# API sends `ping`s, so a stream that says nothing for minutes is stalled, not thinking.
+READ_TIMEOUT_SECONDS = float(os.environ.get("SPRITE_GEN_CLAUDE_READ_TIMEOUT_SECONDS", "300"))
+
+# Everything that ends an exchange before its answer is read whole (as in `xai.NO_ANSWER`).
+NO_ANSWER = (OSError, http.client.HTTPException)
+
+Sleep = Callable[[float], None]
+
+
+def resolve_credential(env: dict[str, str] | None = None) -> str:
+ """Return the Anthropic API key, or fail loud naming the variable that is missing."""
+ env = os.environ if env is None else env
+ key = (env.get(AUTH_ENV) or "").strip()
+ if key:
+ return key
+ if AUTH_ENV in env:
+ raise SystemExit(f"pixel-draw: {AUTH_ENV} is set but empty; give it a value")
+ raise SystemExit(
+ f"pixel-draw: no Anthropic credential — {AUTH_ENV} is not set.\n"
+ f" export {AUTH_ENV}=<your Claude Console API key> (platform.claude.com/settings/keys)."
+ )
+
+
+@dataclass
+class Reply:
+ """One answered message: its text, its thinking summary and what it used."""
+
+ text: str
+ thinking: str
+ stop_reason: str | None
+ usage: dict[str, Any]
+ model: str | None = None
+ message_id: str | None = None
+ stop_details: dict[str, Any] | None = None
+ request_id: str | None = None
+ batch_id: str | None = None
+ mode: str = "realtime"
+ seconds: float | None = None
+
+
+class ApiError(Exception):
+ """The request was refused, got no answer, or its answer broke. `line` says which, masked.
+
+ `partial` is what had arrived when a stream broke (its usage may be billed); `billed` is False
+ only when the API says nothing was made (a refused request, a batch item that errored)."""
+
+ def __init__(self, line: str, *, status: int | None = None, request_id: str | None = None,
+ partial: Reply | None = None, billed: bool | None = None) -> None:
+ super().__init__(line)
+ self.line = line
+ self.status = status
+ self.request_id = request_id
+ self.partial = partial
+ self.billed = billed
+
+
+def message_body(*, system: str | None, content: str | list[dict[str, Any]], effort: str, max_tokens: int,
+ schema: dict[str, Any] | None = None) -> dict[str, Any]:
+ """A Messages API request body. Effort is always explicit (the model's default is medium)."""
+ if effort not in EFFORTS:
+ raise ValueError(f"effort must be one of {', '.join(EFFORTS)}, got {effort!r}")
+ output_config: dict[str, Any] = {"effort": effort}
+ if schema is not None:
+ output_config["format"] = {"type": "json_schema", "schema": schema}
+ body: dict[str, Any] = {"model": MODEL, "max_tokens": max_tokens}
+ if system is not None:
+ body["system"] = system
+ body.update(thinking={"type": "adaptive", "display": "summarized"}, output_config=output_config,
+ messages=[{"role": "user", "content": content}])
+ return body
+
+
+def thinking_tokens(usage: dict[str, Any]) -> int | None:
+ details = usage.get("output_tokens_details")
+ value = details.get("thinking_tokens") if isinstance(details, dict) else None
+ return value if isinstance(value, int) else None
+
+
+def cost_usd(usage: dict[str, Any], *, batch: bool, model: str = MODEL) -> float:
+ """What `usage` costs at the published prices; Message Batches bill half."""
+ price = PRICE_PER_MTOK[model]
+ creation = usage.get("cache_creation") if isinstance(usage.get("cache_creation"), dict) else {}
+ write_5m = creation.get("ephemeral_5m_input_tokens")
+ write_1h = creation.get("ephemeral_1h_input_tokens")
+ if write_5m is None and write_1h is None:
+ write_5m, write_1h = usage.get("cache_creation_input_tokens") or 0, 0
+ total = (
+ (usage.get("input_tokens") or 0) * price["input"]
+ + (write_5m or 0) * price["cache_write_5m"]
+ + (write_1h or 0) * price["cache_write_1h"]
+ + (usage.get("cache_read_input_tokens") or 0) * price["cache_read"]
+ + (usage.get("output_tokens") or 0) * price["output"]
+ ) / 1_000_000
+ return round(total * (BATCH_DISCOUNT if batch else 1.0), 6)
+
+
+def _request(method: str, url: str, token: str, data: bytes | None, *, accept: str) -> urllib.request.Request:
+ request = urllib.request.Request(url, data=data, method=method)
+ request.add_header("x-api-key", token)
+ request.add_header("anthropic-version", API_VERSION)
+ request.add_header("Accept", accept)
+ if data is not None:
+ request.add_header("Content-Type", "application/json")
+ return request
+
+
+def _error_body(exc: urllib.error.HTTPError) -> Any:
+ try:
+ raw = exc.read().decode("utf-8", "replace")
+ except NO_ANSWER:
+ return refusal.RawBody("")
+ try:
+ return json.loads(raw)
+ except json.JSONDecodeError:
+ return refusal.RawBody(raw)
+
+
+def _error_type(body: Any) -> str | None:
+ """`error.type` of an Anthropic error body (`{"type": "error", "error": {"type", "message"}}`)."""
+ error = body.get("error") if isinstance(body, dict) else None
+ return refusal.identifier(error.get("type")) if isinstance(error, dict) else None
+
+
+def refused_line(status: int, body: Any, token: str | None) -> str:
+ code = _error_type(body)
+ suffix = f" code={code}" if code else ""
+ if status in (401, 403):
+ return (f"pixel-draw: credential {AUTH_ENV} rejected (HTTP {status}){suffix}; check the key's value and "
+ f"that its workspace may call {MODEL}{refusal.said(body, token)}")
+ return f"pixel-draw: claude request failed (HTTP {status}){suffix}; not asked again{refusal.said(body, token)}"
+
+
+def _no_answer(exc: BaseException) -> str:
+ said = exc.reason if isinstance(exc, urllib.error.URLError) else exc
+ if isinstance(said, http.client.HTTPException) and not isinstance(said, OSError):
+ return repr(said)[:200]
+ return (str(said) or type(said).__name__)[:200]
+
+
+def _retry_after(headers: Any) -> float | None:
+ value = headers.get("retry-after") if headers is not None else None
+ try:
+ seconds = float(value) if value is not None else None
+ except ValueError:
+ return None
+ return min(seconds, RETRY_AFTER_MAX) if seconds is not None and seconds >= 0 else None
+
+
+def _open(request_for: Callable[[], urllib.request.Request], token: str, *, timeout: float, sleep: Sleep,
+ label: str) -> http.client.HTTPResponse:
+ """Send a request; a refusal that made nothing is asked again (RETRY_STATUSES), anything else raises."""
+ for attempt in range(len(RETRY_WAITS) + 1):
+ try:
+ return urllib.request.urlopen(request_for(), timeout=timeout)
+ except urllib.error.HTTPError as exc:
+ body = _error_body(exc)
+ if exc.code in RETRY_STATUSES and attempt < len(RETRY_WAITS):
+ wait = _retry_after(exc.headers)
+ wait = RETRY_WAITS[attempt] if wait is None else wait
+ kind = _error_type(body)
+ print(f"[{label}] claude refused the request ({exc.code}{' ' + kind if kind else ''}); "
+ f"nothing was made — asking again in {wait:g}s ({attempt + 1} of {len(RETRY_WAITS)})",
+ file=sys.stderr)
+ sleep(wait)
+ continue
+ raise ApiError(refused_line(exc.code, body, token), status=exc.code,
+ request_id=exc.headers.get("request-id") if exc.headers else None, billed=False) from exc
+ except NO_ANSWER as exc:
+ raise ApiError(f"pixel-draw: claude request got no answer ({_no_answer(exc)}); not asked again "
+ "(the API may have accepted it)") from exc
+ raise AssertionError("unreachable")
+
+
+class _Stream:
+ """The state of one streamed message, fed one SSE event at a time."""
+
+ def __init__(self) -> None:
+ self.message: dict[str, Any] = {}
+ self.usage: dict[str, Any] = {}
+ self.blocks: dict[int, dict[str, Any]] = {}
+ self.stop_reason: str | None = None
+ self.stop_details: dict[str, Any] | None = None
+ self.done = False
+ self.error: Any = None
+
+ def feed(self, payload: dict[str, Any]) -> None:
+ kind = payload.get("type")
+ if kind == "message_start":
+ self.message = payload.get("message") or {}
+ self.usage.update(self.message.get("usage") or {})
+ elif kind == "content_block_start":
+ block = payload.get("content_block") or {}
+ self.blocks[payload.get("index", len(self.blocks))] = {
+ "type": block.get("type"), "text": block.get("text") or "", "thinking": block.get("thinking") or ""}
+ elif kind == "content_block_delta":
+ block = self.blocks.setdefault(payload.get("index", 0), {"type": None, "text": "", "thinking": ""})
+ delta = payload.get("delta") or {}
+ if delta.get("type") == "text_delta":
+ block["text"] += delta.get("text") or ""
+ elif delta.get("type") == "thinking_delta":
+ block["thinking"] += delta.get("thinking") or ""
+ elif kind == "message_delta":
+ delta = payload.get("delta") or {}
+ self.stop_reason = delta.get("stop_reason", self.stop_reason)
+ if isinstance(delta.get("stop_details"), dict):
+ self.stop_details = delta["stop_details"]
+ self.usage.update(payload.get("usage") or {}) # cumulative counts
+ elif kind == "message_stop":
+ self.done = True
+ elif kind == "error":
+ self.error = payload
+ # ping and event types added later are not ours to read
+
+ def reply(self, *, request_id: str | None, seconds: float) -> Reply:
+ ordered = [self.blocks[i] for i in sorted(self.blocks)]
+ return Reply(
+ text="".join(b["text"] for b in ordered if b["type"] == "text"),
+ thinking="\n".join(b["thinking"] for b in ordered if b["type"] == "thinking" and b["thinking"]),
+ stop_reason=self.stop_reason,
+ stop_details=self.stop_details,
+ usage=dict(self.usage),
+ model=self.message.get("model"),
+ message_id=self.message.get("id"),
+ request_id=request_id,
+ mode="realtime",
+ seconds=round(seconds, 3),
+ )
+
+
+def stream_message(token: str, body: dict[str, Any], *, sleep: Sleep = time.sleep,
+ timeout: float | None = None, label: str = "pixel-draw") -> Reply:
+ """Send one message with `stream: true` and read its events to the end."""
+ data = json.dumps({**body, "stream": True}).encode("utf-8")
+ timeout = READ_TIMEOUT_SECONDS if timeout is None else timeout
+ started = time.monotonic()
+ response = _open(lambda: _request("POST", API_BASE + "/messages", token, data, accept="text/event-stream"),
+ token, timeout=timeout, sleep=sleep, label=label)
+ request_id = response.headers.get("request-id")
+ state = _Stream()
+ event_data: list[str] = []
+ try:
+ with response:
+ for raw in response:
+ line = raw.decode("utf-8").rstrip("\r\n")
+ if line:
+ field_name, _, value = line.partition(":")
+ if field_name == "data":
+ event_data.append(value[1:] if value.startswith(" ") else value)
+ continue
+ if event_data:
+ state.feed(json.loads("\n".join(event_data)))
+ event_data = []
+ if state.error is not None or state.done:
+ break
+ if event_data and state.error is None and not state.done:
+ state.feed(json.loads("\n".join(event_data)))
+ except NO_ANSWER as exc:
+ partial = state.reply(request_id=request_id, seconds=time.monotonic() - started)
+ raise ApiError(f"pixel-draw: the answer stream broke ({_no_answer(exc)}); not asked again "
+ "(what was written may be billed)", request_id=request_id, partial=partial) from exc
+ except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+ partial = state.reply(request_id=request_id, seconds=time.monotonic() - started)
+ raise ApiError("pixel-draw: the answer stream carried an event that is not JSON; not asked again",
+ request_id=request_id, partial=partial) from exc
+ reply = state.reply(request_id=request_id, seconds=time.monotonic() - started)
+ if state.error is not None:
+ error = state.error.get("error") if isinstance(state.error, dict) else None
+ code = refusal.identifier(error.get("type")) if isinstance(error, dict) else None
+ raise ApiError(f"pixel-draw: the answer stream ended in an error{' code=' + code if code else ''}; "
+ f"not asked again (what was written may be billed){refusal.said(state.error, token)}",
+ request_id=request_id, partial=reply)
+ if not state.done:
+ raise ApiError("pixel-draw: the answer stream ended before message_stop; not asked again "
+ "(what was written may be billed)", request_id=request_id, partial=reply)
+ return reply
+
+
+def _json_call(method: str, url: str, token: str, body: dict[str, Any] | None, *, sleep: Sleep,
+ label: str, timeout: float = 120.0) -> Any:
+ data = None if body is None else json.dumps(body).encode("utf-8")
+ response = _open(lambda: _request(method, url, token, data, accept="application/json"),
+ token, timeout=timeout, sleep=sleep, label=label)
+ try:
+ with response:
+ raw = response.read().decode("utf-8")
+ except NO_ANSWER as exc:
+ raise ApiError(f"pixel-draw: claude answer broke ({_no_answer(exc)})") from exc
+ try:
+ return json.loads(raw) if raw else {}
+ except json.JSONDecodeError as exc:
+ raise ApiError("pixel-draw: claude answer was not JSON") from exc
+
+
+def submit_batch(token: str, requests: list[tuple[str, dict[str, Any]]], *, sleep: Sleep = time.sleep,
+ label: str = "pixel-draw") -> dict[str, Any]:
+ """Create one Message Batch of `(custom_id, params)` and return the batch object."""
+ body = {"requests": [{"custom_id": custom_id, "params": params} for custom_id, params in requests]}
+ batch = _json_call("POST", API_BASE + "/messages/batches", token, body, sleep=sleep, label=label)
+ if not isinstance(batch, dict) or not isinstance(batch.get("id"), str):
+ raise ApiError("pixel-draw: the batch answer names no batch id")
+ return batch
+
+
+def get_batch(token: str, batch_id: str, *, sleep: Sleep = time.sleep, label: str = "pixel-draw") -> dict[str, Any]:
+ batch = _json_call("GET", f"{API_BASE}/messages/batches/{batch_id}", token, None, sleep=sleep, label=label)
+ if not isinstance(batch, dict):
+ raise ApiError("pixel-draw: the batch status answer is not an object")
+ return batch
+
+
+def _message_reply(message: dict[str, Any], batch_id: str) -> Reply:
+ content = message.get("content") if isinstance(message.get("content"), list) else []
+ return Reply(
+ text="".join(b.get("text") or "" for b in content if isinstance(b, dict) and b.get("type") == "text"),
+ thinking="\n".join(b.get("thinking") or "" for b in content
+ if isinstance(b, dict) and b.get("type") == "thinking" and b.get("thinking")),
+ stop_reason=message.get("stop_reason"),
+ stop_details=message.get("stop_details") if isinstance(message.get("stop_details"), dict) else None,
+ usage=message.get("usage") if isinstance(message.get("usage"), dict) else {},
+ model=message.get("model"),
+ message_id=message.get("id"),
+ batch_id=batch_id,
+ mode="batch",
+ )
+
+
+def batch_results(token: str, batch: dict[str, Any], *, sleep: Sleep = time.sleep,
+ label: str = "pixel-draw") -> dict[str, Reply | ApiError]:
+ """Every result of an ended batch by custom_id; an item that was not answered is an ApiError."""
+ url = batch.get("results_url")
+ if not isinstance(url, str) or not url:
+ raise ApiError(f"pixel-draw: batch {batch.get('id')} has ended but names no results_url")
+ response = _open(lambda: _request("GET", url, token, None, accept="application/binary"),
+ token, timeout=120.0, sleep=sleep, label=label)
+ try:
+ with response:
+ lines = response.read().decode("utf-8").splitlines()
+ except NO_ANSWER as exc:
+ raise ApiError(f"pixel-draw: batch results broke ({_no_answer(exc)})") from exc
+ results: dict[str, Reply | ApiError] = {}
+ for line in lines:
+ if not line.strip():
+ continue
+ item = json.loads(line)
+ custom_id, result = item.get("custom_id"), item.get("result") or {}
+ kind = result.get("type")
+ if kind == "succeeded" and isinstance(result.get("message"), dict):
+ results[custom_id] = _message_reply(result["message"], batch["id"])
+ elif kind == "errored":
+ error = result.get("error") or {}
+ results[custom_id] = ApiError(
+ f"pixel-draw: batch item {custom_id} errored{' code=' + str(_error_type(error)) if _error_type(error) else ''}"
+ f" (not billed){refusal.said(error, token)}", billed=False)
+ else:
+ results[custom_id] = ApiError(f"pixel-draw: batch item {custom_id} {kind or 'has no result'} (not billed)",
+ billed=False)
+ return results
diff --git a/sprite_gen/gen/pixel_draw.py b/sprite_gen/gen/pixel_draw.py
new file mode 100644
index 0000000..5101b65
--- /dev/null
+++ b/sprite_gen/gen/pixel_draw.py
@@ -0,0 +1,1073 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sprite-gen pixel-draw` — Claude Opus draws pixel art of 8..48 px directly, as a pixel grid.
+
+The model writes a palette and rows of keys (docs/pixel-draw.md); code checks every answer and
+renders it. Measured 2026-10-12 on `claude-opus-5-5` (250 calls, 12 subjects, 16..48 px): single
+assets come out shippable, effort high costs a third of xhigh for the same judged quality, and
+about one answer in eight breaks the grid (a row one key too long or short, a key outside the
+palette, output cut short) — so every answer goes through the gates below, and a broken row is
+asked for again on its own.
+
+One run, `--candidates` K answers to the same request:
+
+1. Each candidate is drawn once at `--effort`. An answer that used all `--max-tokens` thinking
+ and wrote nothing is drawn once more one effort lower; a refusal is reported as it came.
+2. G1 parse. Row issues are repaired one row at a time (`ROW <frame> <n>: …`, two rounds at most);
+ an answer still broken, or broken beyond its rows, is drawn once more. A candidate is drawn at
+ most twice in all.
+3. G2 palette, G3 alpha and G6 frames fail a candidate; G4 tile seam, G5 stray pixels and the walk
+ cycle's leg alternation warn.
+4. G7: of two or more candidates that passed, one vision call (effort low) picks, or a person
+ does (`--pick human`). One that passed alone is the pick.
+
+Every model call is kept under `calls/` and is read back instead of asked again on `--resume`;
+a batch (`--batch`, half price) is recorded under `batches/` the moment it is submitted, so a run
+cut short collects it on `--resume` instead of buying it twice. Nothing falls back to another
+model, provider or effort beyond the one lowered draw above.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import io
+import json
+import random
+import shutil
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Generator
+
+from PIL import Image, ImageDraw
+
+from sprite_gen.spec.runio import atomic_write_text
+from . import anthropic_api as api
+from . import refusal
+from .anthropic_api import ApiError, Reply
+from .base import announce_api_billing
+from .pixel_gates import evaluate
+from .pixel_grid import (
+ FORMATS, Grid, Issue, PaletteRule, check_rows, frame_name_ok, frame_pixels, palette_rule, parse_answer,
+ parse_row_answers, png_bytes, preview_scale, preview_strip, read_grid_text, recovered, row_issues, row_text,
+ save_gif, splice, structural, tiled_3x3, to_text,
+)
+
+VERB = "pixel-draw"
+SIZE_MIN, SIZE_MAX, SIZE_DEFAULT = 8, 48, 32
+FRAMES_MAX = 4
+KINDS = ("sprite", "icon", "tile")
+CANDIDATES_MIN, CANDIDATES_MAX, CANDIDATES_DEFAULT = 1, 6, 2
+EFFORT_CHOICES = ("medium", "high", "xhigh")
+EFFORT_DEFAULT = "high"
+LOWER_EFFORT = {"max": "xhigh", "xhigh": "high", "high": "medium", "medium": "low"}
+MAX_TOKENS_SINGLE, MAX_TOKENS_MULTI = 32000, 64000
+MAX_TOKENS_MIN = 1024
+REPAIR_EFFORT, REPAIR_MAX_TOKENS, REPAIR_ROUNDS = "medium", 16000, 2
+PICK_EFFORT, PICK_MAX_TOKENS = "low", 16000
+PICKS = ("vision", "human")
+BATCH_WAIT_DEFAULT = 3600.0
+BATCH_POLL_SECONDS = 30.0
+GIF_FRAME_MS = 150
+SPEC_KEYS = ("subject", "size", "kind", "frames", "walk_cycle", "palette")
+RUN_FLAGS = ("candidates", "effort", "answer_format", "batch", "max_tokens", "pick")
+REPORT_KIND = "sprite-gen-pixel-draw-report"
+
+SYSTEM = ("You are an expert pixel artist who draws game assets directly as pixel data. "
+ "What you write is converted to a PNG mechanically, pixel for pixel, with no cleanup: "
+ "what you write is exactly what ships.")
+
+PICK_SCHEMA = {
+ "type": "object",
+ "properties": {
+ "candidates": {"type": "array", "items": {
+ "type": "object",
+ "properties": {
+ "label": {"type": "string"},
+ "subject_read": {"type": "integer", "enum": [1, 2, 3, 4, 5]},
+ "craft": {"type": "integer", "enum": [1, 2, 3, 4, 5]},
+ "consistency": {"type": "integer", "enum": [0, 1, 2, 3, 4, 5]},
+ "verdict": {"type": "string", "enum": ["ship", "touch_up", "redraw"]},
+ "note": {"type": "string"},
+ },
+ "required": ["label", "subject_read", "craft", "consistency", "verdict", "note"],
+ "additionalProperties": False}},
+ "best": {"type": "string"},
+ "any_shippable": {"type": "boolean"},
+ },
+ "required": ["candidates", "best", "any_shippable"],
+ "additionalProperties": False,
+}
+
+
+# ----------------------------------------------------------------------------- the request
+
+@dataclass(frozen=True)
+class PixelRequest:
+ subject: str
+ size: int
+ kind: str
+ frames: tuple[str, ...]
+ walk_cycle: bool
+ palette: PaletteRule
+ candidates: int
+ effort: str
+ answer_format: str
+ batch: bool
+ max_tokens: int
+ pick: str
+
+ def to_dict(self) -> dict[str, Any]:
+ data = asdict(self)
+ data["frames"] = list(self.frames)
+ data["palette"] = self.palette.to_dict()
+ return data
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> "PixelRequest":
+ palette = data["palette"]
+ return cls(**{**data, "frames": tuple(data["frames"]),
+ "palette": PaletteRule(palette["name"], palette["limit"], tuple(palette["colors"]))})
+
+
+def _refuse(message: str) -> SystemExit:
+ return SystemExit(f"{VERB}: {message}")
+
+
+def _frames(value: Any) -> tuple[str, ...]:
+ names = [n.strip() for n in value.split(",")] if isinstance(value, str) else value
+ if not isinstance(names, list) or not names or not all(isinstance(n, str) and n for n in names):
+ raise _refuse("--frames takes comma-separated frame names, e.g. down,up,left,right")
+ bad = [n for n in names if not frame_name_ok(n)]
+ if bad:
+ raise _refuse("frame names are letters, digits, '_' or '-' (at most 32): " + ", ".join(map(repr, bad)))
+ if len(set(names)) != len(names):
+ raise _refuse("frame names must differ: " + ", ".join(names))
+ if len(names) > FRAMES_MAX:
+ raise _refuse(f"at most {FRAMES_MAX} frames in one call, got {len(names)}")
+ return tuple(names)
+
+
+def _load_spec(path: Path) -> dict[str, Any]:
+ try:
+ spec = json.loads(Path(path).expanduser().read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError) as exc:
+ raise _refuse(f"--spec {path}: {exc}") from exc
+ if not isinstance(spec, dict):
+ raise _refuse(f"--spec {path}: expected a JSON object with {', '.join(SPEC_KEYS)}")
+ unknown = sorted(set(spec) - set(SPEC_KEYS))
+ if unknown:
+ raise _refuse(f"--spec {path}: unknown key(s) {', '.join(unknown)}; a spec holds {', '.join(SPEC_KEYS)}")
+ if isinstance(spec.get("palette"), list):
+ spec["palette"] = ",".join(spec["palette"])
+ return spec
+
+
+def resolve_request(args: argparse.Namespace) -> PixelRequest:
+ spec = _load_spec(args.spec) if args.spec else {}
+ given = {key: getattr(args, key) for key in SPEC_KEYS if getattr(args, key) is not None}
+ both = sorted(set(spec) & set(given))
+ if both:
+ raise _refuse(f"{', '.join('--' + k.replace('_', '-') for k in both)} given both as a flag and in --spec; "
+ "say each once")
+ merged = {**spec, **given}
+ subject = merged.get("subject")
+ if not isinstance(subject, str) or not subject.strip():
+ raise _refuse("nothing to draw — pass --subject TEXT or --spec FILE with a subject")
+ size = merged.get("size", SIZE_DEFAULT)
+ if not isinstance(size, int) or isinstance(size, bool) or not SIZE_MIN <= size <= SIZE_MAX:
+ raise _refuse(f"--size is {SIZE_MIN}..{SIZE_MAX} pixels, got {size!r}")
+ kind = merged.get("kind", "sprite")
+ if kind not in KINDS:
+ raise _refuse(f"--kind is one of {', '.join(KINDS)}, got {kind!r}")
+ frames = _frames(merged["frames"]) if "frames" in merged else (kind,)
+ walk_cycle = bool(merged.get("walk_cycle", False))
+ if walk_cycle and len(frames) != 4:
+ raise _refuse(f"--walk-cycle is four frames (contact, passing, contact, passing), got {len(frames)}")
+ try:
+ rule = palette_rule(str(merged.get("palette", "free")))
+ except ValueError as exc:
+ raise _refuse(str(exc)) from exc
+ candidates = CANDIDATES_DEFAULT if args.candidates is None else args.candidates
+ if not CANDIDATES_MIN <= candidates <= CANDIDATES_MAX:
+ raise _refuse(f"--candidates is {CANDIDATES_MIN}..{CANDIDATES_MAX}, got {candidates}")
+ max_tokens = args.max_tokens or (MAX_TOKENS_SINGLE if len(frames) == 1 else MAX_TOKENS_MULTI)
+ if not MAX_TOKENS_MIN <= max_tokens <= api.MODEL_MAX_TOKENS:
+ raise _refuse(f"--max-tokens is {MAX_TOKENS_MIN}..{api.MODEL_MAX_TOKENS}, got {max_tokens}")
+ return PixelRequest(
+ subject=subject.strip(), size=size, kind=kind, frames=frames, walk_cycle=walk_cycle, palette=rule,
+ candidates=candidates, effort=args.effort or EFFORT_DEFAULT, answer_format=args.answer_format or "chargrid",
+ batch=bool(args.batch), max_tokens=max_tokens, pick=args.pick or "vision",
+ )
+
+
+# ----------------------------------------------------------------------------- prompts
+
+def _format_spec(request: PixelRequest) -> str:
+ w = h = request.size
+ names = ", ".join(request.frames)
+ if request.answer_format == "chargrid":
+ return (
+ "Output format: exactly one fenced code block tagged `pixels`, and nothing after it:\n"
+ "```pixels\nPALETTE\n. transparent\na #RRGGBB\nb #RRGGBB\n...\n"
+ f"FRAME <frame name>\n<{h} lines, each exactly {w} characters>\n...\nEND\n```\n"
+ "- Each palette line is one key character and one #RRGGBB color. Keys are single "
+ "characters from a-z, A-Z, 0-9; `.` is always transparent and is never redefined.\n"
+ f"- Each frame is exactly {h} lines of exactly {w} characters, every character a "
+ "palette key, with no spaces.\n"
+ f"- Frames in this order: {names}. Write `FRAME <name>` before each frame and `END` "
+ "once after the last frame.")
+ return (
+ "Output format: exactly one fenced code block tagged `json` holding one JSON object, "
+ "and nothing after it:\n"
+ '{"palette": ["transparent", "#RRGGBB", ...], "frames": {"<frame name>": '
+ f"[[...{w} integers...], ...{h} rows...]}}}}\n"
+ '- palette[0] is always "transparent"; every other entry is a #RRGGBB color.\n'
+ f"- Each frame is a list of exactly {h} rows; each row is a list of exactly {w} "
+ "integers indexing into palette.\n"
+ f"- Frames: {names}.")
+
+
+def generation_prompt(request: PixelRequest) -> str:
+ frames = request.frames
+ lines = [f"Draw: {request.subject}", f"Canvas: exactly {request.size}x{request.size} pixels per frame."]
+ if len(frames) > 1:
+ same = (f"Frames: {', '.join(frames)}. All frames share one palette and show the same subject with "
+ "the same proportions, colors and size")
+ lines.append(same + ("; the feet stand on the same bottom row in every frame." if request.kind == "sprite" else "."))
+ if request.walk_cycle:
+ a, b, c, d = frames
+ lines.append(f"The frames are one looping walk cycle: {a} = contact pose with the front leg forward, "
+ f"{b} = passing pose (legs together, body one pixel higher), {c} = contact pose with the "
+ f"other leg forward, {d} = passing pose.")
+ if request.palette.fixed:
+ lines.append(f"Palette: use only these {len(request.palette.colors)} colors and transparent, no others: "
+ + " ".join(request.palette.colors) + ".")
+ else:
+ lines.append(f"Palette: at most {request.palette.limit} colors plus transparent.")
+ if request.kind == "tile":
+ lines.append("This is a tile: fill every pixel (no transparency) and make it repeat seamlessly in a grid, "
+ "so the left edge continues into the right edge and the top edge into the bottom edge. "
+ "No border or outline around the tile.")
+ lines.append("Style: clean, readable pixel art for a 2D RPG: 2-3 shades per material, light from the "
+ "top-left, no noisy single-pixel speckle.")
+ else:
+ lines.append("Background: transparent. The subject should fill most of the canvas, leaving at most a "
+ "1-2 pixel margin.")
+ lines.append("Style: clean, readable pixel art for a 2D RPG: a dark (not pure black) outline around the "
+ "silhouette, 2-3 shades per material, light from the top-left, no anti-aliasing noise and "
+ "no stray single pixels.")
+ lines += ["", _format_spec(request)]
+ return "\n".join(lines)
+
+
+def _ruler(n: int) -> str:
+ return "".join(str(i % 10) for i in range(1, n + 1))
+
+
+def repair_prompt(request: PixelRequest, grid: Grid, issues: list[Issue]) -> tuple[str, list[tuple[str, int]]]:
+ """The broken rows with their neighbours (and a column ruler), and the rows to write."""
+ wanted = sorted({(i.frame, i.row) for i in issues}, key=lambda fr: (request.frames.index(fr[0]), fr[1]))
+ broken = {(i.frame, i.row): [] for i in issues}
+ for issue in issues:
+ broken[(issue.frame, issue.row)].append(issue)
+ chargrid = grid.fmt == "chargrid"
+ parts: list[str] = []
+ for name in request.frames:
+ rows = grid.frames[name]
+ for number, row in enumerate(rows, 1):
+ found = broken.get((name, number))
+ if not found:
+ continue
+ what = "; ".join(f"{len(row)} {'characters' if chargrid else 'values'}" if i.code == "row_width"
+ else i.detail for i in found)
+ head = f" row {number} (BROKEN, {what}): "
+ context = []
+ if number > 1:
+ context.append(f" row {number - 1} ({'also broken' if (name, number - 1) in broken else 'correct'}): "
+ f"{row_text(grid, rows[number - 2])}")
+ context.append(head + row_text(grid, row))
+ if chargrid:
+ context.append(" ruler" + " " * (len(head) - len(" ruler")) + _ruler(max(len(row), grid.width)))
+ if number < len(rows):
+ context.append(f" row {number + 1} ({'also broken' if (name, number + 1) in broken else 'correct'}): "
+ f"{row_text(grid, rows[number])}")
+ parts.append(f"frame {name} row {number}:\n" + "\n".join(context))
+ if len(rows) < grid.height:
+ parts.append(f"frame {name} rows {len(rows) + 1}-{grid.height} are MISSING. The rows so far:\n"
+ + "\n".join(f" row {k}: {row_text(grid, r)}" for k, r in enumerate(rows, 1)))
+ if chargrid:
+ palette = "\n".join(f"{k} {'transparent' if c is None else c}" for k, c in grid.palette.items())
+ unit = f"<exactly {grid.width} characters>"
+ rule = f"Every row must be exactly {grid.width} characters, each a palette key."
+ how = ("Change as few pixels as possible (a row that is one too long usually has one duplicated pixel; "
+ "one too short has one dropped), keep the drawing, use only palette keys.")
+ else:
+ palette = json.dumps(["transparent" if c is None else c for c in grid.palette.values()])
+ unit = f"[<exactly {grid.width} integers>]"
+ rule = f"Every row must be a list of exactly {grid.width} integers, each an index into the palette."
+ how = "Change as few pixels as possible, keep the drawing, use only palette indices."
+ prompt = (
+ f"A {grid.width}x{grid.height} pixel-art grid ({request.subject}) failed a mechanical check. {rule}\n"
+ "Palette:\n" + palette + "\n\n" + "\n\n".join(parts) + "\n\n"
+ f"Answer with one line per row listed below and nothing else, in the form `ROW <frame> <row number>: {unit}`. "
+ f"{how} For missing rows, continue the drawing in the same style.\n"
+ "Rows to write: " + ", ".join(f"{n} {i}" for n, i in wanted))
+ return prompt, wanted
+
+
+def pick_prompt(request: PixelRequest, labels: list[str]) -> str:
+ multi = len(request.frames) > 1
+ lines = [
+ "You are judging pixel-art game assets for a game asset service.",
+ f"The image shows {len(labels)} candidates labelled {', '.join(labels)} for the same request. Each is "
+ "enlarged with nearest-neighbour scaling, so every square block is one pixel; the grey checkerboard stands "
+ "for transparency.",
+ ]
+ if request.kind == "tile":
+ lines.append("Each tile is shown alone and, to its right, repeated 3x3 so seams are visible.")
+ if multi:
+ lines.append(f"Each candidate is a row of {len(request.frames)} frames in this order: {', '.join(request.frames)}.")
+ lines += [
+ f"The request was: {request.subject} Canvas {request.size}x{request.size} pixels per frame.",
+ "Score every candidate:",
+ "- subject_read 1-5: how clearly it reads as the requested subject (5 instantly, 1 unrecognisable).",
+ "- craft 1-5: pixel-art craft: clean silhouette and outline, consistent shading and light, no noise, sensible "
+ "use of the canvas (5 professional, 3 acceptable indie, 1 broken)."
+ + (" For tiles, visible seams in the 3x3 repeat count against craft." if request.kind == "tile" else ""),
+ ("- consistency 1-5: the same subject, proportions and colours across frames, and correct poses/directions "
+ "for the frame names." if multi else "- consistency: 0 (single frame)."),
+ "- verdict: ship (usable in a game as is), touch_up (usable after a few pixel fixes), redraw (not usable).",
+ "- note: one short sentence naming the main flaw or strength.",
+ "Then best: the label of the candidate you would ship; any_shippable: whether at least one is ship or touch_up.",
+ "Judge only what is visible.",
+ ]
+ return "\n".join(lines)
+
+
+# ----------------------------------------------------------------------------- calls
+
+def _sha(body: dict[str, Any]) -> str:
+ return hashlib.sha256(json.dumps(body, sort_keys=True, ensure_ascii=False).encode("utf-8")).hexdigest()
+
+
+def _now() -> str:
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _prompt_text(body: dict[str, Any]) -> str:
+ content = body["messages"][0]["content"]
+ if isinstance(content, str):
+ return content
+ return "\n".join(block.get("text", "") for block in content if block.get("type") == "text")
+
+
+@dataclass
+class Ask:
+ """A generation call a candidate is waiting on."""
+
+ call_id: str
+ candidate: str
+ effort: str
+ body: dict[str, Any]
+
+
+class Unfinished(Exception):
+ """A batch the run cannot finish now: still processing after --batch-wait, or results not read."""
+
+ def __init__(self, batch_id: str, waited: float, why: str) -> None:
+ super().__init__(batch_id)
+ self.batch_id = batch_id
+ self.waited = waited
+ self.why = why
+
+
+class Calls:
+ """Every model call of a run: asked, or read back from `calls/<id>.json` on --resume."""
+
+ def __init__(self, run_dir: Path, token: str, *, sleep: Callable[[float], None], note: Callable[[str], None]) -> None:
+ self.dir = run_dir / "calls"
+ self.batch_dir = run_dir / "batches"
+ self.token = token
+ self.sleep = sleep
+ self.note = note
+ self.lock = threading.Lock()
+ self.summaries: dict[str, dict[str, Any]] = {}
+ self.batches: dict[str, dict[str, Any]] = {}
+ self.dir.mkdir(parents=True, exist_ok=True)
+ for path in sorted(self.batch_dir.glob("*.json")):
+ record = json.loads(path.read_text(encoding="utf-8"))
+ self.batches[record["id"]] = record
+
+ def _path(self, call_id: str) -> Path:
+ return self.dir / f"{call_id}.json"
+
+ def cached(self, call_id: str, body: dict[str, Any]) -> Reply | None:
+ path = self._path(call_id)
+ if not path.is_file():
+ return None
+ record = json.loads(path.read_text(encoding="utf-8"))
+ if record.get("outcome") != "reply":
+ return None
+ if record.get("body_sha256") != _sha(body):
+ raise _refuse(f"--resume: {path} was asked with another request than this run builds now; "
+ "start a new --out-dir")
+ with self.lock:
+ self.summaries[call_id] = self._summary(record)
+ return Reply(**record["reply"])
+
+ @staticmethod
+ def _summary(record: dict[str, Any]) -> dict[str, Any]:
+ return {k: v for k, v in record.items() if k not in ("prompt", "reply", "body_sha256")}
+
+ def save(self, call_id: str, purpose: str, candidate: str | None, body: dict[str, Any],
+ outcome: Reply | ApiError, *, image: str | None = None) -> None:
+ reply = outcome if isinstance(outcome, Reply) else outcome.partial
+ batch = reply is not None and reply.mode == "batch"
+ usage = reply.usage if reply is not None else {}
+ record: dict[str, Any] = {
+ "id": call_id, "purpose": purpose, "candidate": candidate,
+ "outcome": "reply" if isinstance(outcome, Reply) else "error",
+ "mode": "batch" if batch else "realtime", "model": body["model"],
+ "effort": body["output_config"]["effort"], "max_tokens": body["max_tokens"],
+ "request_id": reply.request_id if reply else getattr(outcome, "request_id", None),
+ "message_id": reply.message_id if reply else None,
+ "batch_id": reply.batch_id if reply else None,
+ "stop_reason": reply.stop_reason if reply else None,
+ "stop_details": reply.stop_details if reply else None,
+ "usage": usage or None,
+ "thinking_tokens": api.thinking_tokens(usage) if usage else None,
+ "cost_usd": api.cost_usd(usage, batch=batch) if usage else 0.0,
+ "seconds": reply.seconds if reply else None,
+ "finished_at": _now(),
+ }
+ if isinstance(outcome, ApiError):
+ record["error"] = outcome.line
+ record["billed"] = outcome.billed
+ if image:
+ record["image"] = image
+ record["body_sha256"] = _sha(body)
+ record["prompt"] = _prompt_text(body)
+ record["reply"] = asdict(reply) if reply is not None else None
+ atomic_write_text(self._path(call_id), json.dumps(record, ensure_ascii=False, indent=1) + "\n")
+ with self.lock:
+ self.summaries[call_id] = self._summary(record)
+
+ def realtime(self, call_id: str, purpose: str, candidate: str | None, body: dict[str, Any], *,
+ image: str | None = None) -> Reply | ApiError:
+ cached = self.cached(call_id, body)
+ if cached is not None:
+ self.note(f"{call_id}: read back from calls/{call_id}.json (not asked again)")
+ return cached
+ try:
+ outcome: Reply | ApiError = api.stream_message(self.token, body, sleep=self.sleep, label=f"{VERB} {call_id}")
+ except ApiError as exc:
+ outcome = exc
+ self.save(call_id, purpose, candidate, body, outcome, image=image)
+ self.note(_call_line(call_id, outcome))
+ return outcome
+
+ # -- Message Batches
+
+ def _save_batch(self, record: dict[str, Any]) -> None:
+ self.batch_dir.mkdir(parents=True, exist_ok=True)
+ atomic_write_text(self.batch_dir / f"{record['id']}.json", json.dumps(record, ensure_ascii=False, indent=1) + "\n")
+ with self.lock:
+ self.batches[record["id"]] = record
+
+ def batch_round(self, asks: list[Ask], wait: float) -> dict[str, Reply | ApiError]:
+ """One answer per ask: read back, collected from a batch already recorded, or from a new batch."""
+ out: dict[str, Reply | ApiError] = {}
+ need: dict[str, Ask] = {}
+ for ask in asks:
+ cached = self.cached(ask.call_id, ask.body)
+ if cached is not None:
+ out[ask.call_id] = cached
+ else:
+ need[ask.call_id] = ask
+ for record in list(self.batches.values()):
+ held = [cid for cid in record["custom_ids"] if cid in need]
+ if held and not record.get("collected"):
+ self.note(f"batch {record['id']} was submitted earlier with {', '.join(held)}; collecting it")
+ out.update(self._collect(record, need, wait))
+ need = {cid: ask for cid, ask in need.items() if cid not in out}
+ if need:
+ try:
+ batch = api.submit_batch(self.token, [(cid, ask.body) for cid, ask in need.items()],
+ sleep=self.sleep, label=VERB)
+ except ApiError as exc:
+ for cid, ask in need.items():
+ self.save(cid, "generate", ask.candidate, ask.body, exc)
+ out[cid] = exc
+ self.note(f"batch not submitted: {exc.line}")
+ return out
+ record = {"id": batch["id"], "submitted_at": _now(), "custom_ids": list(need), "collected": False}
+ self._save_batch(record)
+ self.note(f"batch {batch['id']} submitted: {', '.join(need)} (half price; waiting up to {wait:g}s)")
+ out.update(self._collect(record, need, wait))
+ return out
+
+ def _collect(self, record: dict[str, Any], asks: dict[str, Ask], wait: float) -> dict[str, Reply | ApiError]:
+ started = time.monotonic()
+ while True:
+ try:
+ batch = api.get_batch(self.token, record["id"], sleep=self.sleep, label=VERB)
+ except ApiError as exc:
+ self.note(f"batch {record['id']}: status not read ({exc.line}); asking again")
+ batch = {}
+ if batch.get("processing_status") == "ended":
+ break
+ if time.monotonic() - started >= wait:
+ raise Unfinished(record["id"], time.monotonic() - started, "has not ended")
+ self.sleep(BATCH_POLL_SECONDS)
+ try:
+ results = api.batch_results(self.token, batch, sleep=self.sleep, label=VERB)
+ except ApiError as exc:
+ raise Unfinished(record["id"], time.monotonic() - started, f"has ended but its results were not read ({exc.line})") from exc
+ seconds = round(time.monotonic() - started, 3)
+ out: dict[str, Reply | ApiError] = {}
+ for cid in record["custom_ids"]:
+ outcome = results.get(cid) or ApiError(f"{VERB}: batch {record['id']} has no result for {cid} (not billed)",
+ billed=False)
+ if cid in asks:
+ ask = asks[cid]
+ self.save(cid, "generate", ask.candidate, ask.body, outcome)
+ self.note(_call_line(cid, outcome))
+ out[cid] = outcome
+ self._save_batch({**record, "collected": True, "ended_at": batch.get("ended_at"), "waited_seconds": seconds,
+ "request_counts": batch.get("request_counts")})
+ return out
+
+
+def _call_line(call_id: str, outcome: Reply | ApiError) -> str:
+ if isinstance(outcome, ApiError):
+ return f"{call_id}: {outcome.line}"
+ usage = outcome.usage
+ cost = api.cost_usd(usage, batch=outcome.mode == "batch")
+ took = f" {outcome.seconds:.0f}s" if outcome.seconds is not None else ""
+ return (f"{call_id}: {outcome.stop_reason} — {usage.get('output_tokens')} output tokens "
+ f"({api.thinking_tokens(usage)} thinking), ${cost:.4f}{took}")
+
+
+# ----------------------------------------------------------------------------- candidates
+
+@dataclass
+class Candidate:
+ id: str
+ status: str = "pending" # passed | failed | refused | error
+ reason: str | None = None
+ effort: str | None = None
+ generations: list[str] = field(default_factory=list)
+ redraws: list[dict[str, Any]] = field(default_factory=list)
+ repairs: list[dict[str, Any]] = field(default_factory=list)
+ g1: dict[str, Any] | None = None
+ gates: dict[str, Any] | None = None
+ warnings: list[str] = field(default_factory=list)
+ grid: Grid | None = None
+ files: dict[str, Any] = field(default_factory=dict)
+
+ def end(self, status: str, reason: str | None = None) -> "Candidate":
+ self.status, self.reason = status, reason
+ return self
+
+ def to_dict(self) -> dict[str, Any]:
+ return {"id": self.id, "status": self.status, "reason": self.reason, "effort": self.effort,
+ "generations": self.generations, "redraws": self.redraws, "repairs": self.repairs, "G1": self.g1,
+ "gates": self.gates, "warnings": self.warnings, "files": self.files}
+
+
+def _g1(issues: list[Issue]) -> dict[str, Any]:
+ failing = structural(issues) + row_issues(issues)
+ return {"ok": not failing, "issues": [i.to_dict() for i in failing],
+ "recovered": [i.to_dict() for i in recovered(issues)]}
+
+
+def _refusal_reason(reply: Reply) -> str:
+ details = reply.stop_details or {}
+ category = refusal.identifier(details.get("category"))
+ return f"{refusal.CONTENT_POLICY} (stop_reason=refusal{' category=' + category if category else ''})"
+
+
+class Run:
+ """One pixel-draw run: its request, its calls and its candidates."""
+
+ def __init__(self, request: PixelRequest, run_dir: Path, calls: Calls, *, batch_wait: float,
+ note: Callable[[str], None]) -> None:
+ self.request = request
+ self.run_dir = run_dir
+ self.calls = calls
+ self.batch_wait = batch_wait
+ self.note = note
+
+ def generation_body(self, effort: str) -> dict[str, Any]:
+ return api.message_body(system=SYSTEM, content=generation_prompt(self.request), effort=effort,
+ max_tokens=self.request.max_tokens)
+
+ def flow(self, cid: str) -> Generator[Ask, Reply | ApiError, Candidate]:
+ request = self.request
+ candidate = Candidate(cid)
+ effort, number, redrawn = request.effort, 1, False
+ while True:
+ ask = Ask(f"{cid}-gen{number}", cid, effort, self.generation_body(effort))
+ outcome = yield ask
+ candidate.generations.append(ask.call_id)
+ if isinstance(outcome, ApiError):
+ return candidate.end("error", outcome.line)
+ if outcome.stop_reason == "refusal":
+ return candidate.end("refused", _refusal_reason(outcome))
+ grid, issues = parse_answer(outcome.text, request.answer_format, request.size, request.size, request.frames)
+ if outcome.stop_reason == "max_tokens" and grid is None: # nothing readable was written
+ lower = LOWER_EFFORT.get(effort)
+ if not redrawn and lower:
+ self.note(f"{ask.call_id}: all {request.max_tokens} tokens went to thinking and nothing was "
+ f"written; drawing {cid} once more at effort {lower}")
+ candidate.redraws.append({"after": ask.call_id, "why": "max_tokens", "effort": lower})
+ effort, number, redrawn = lower, number + 1, True
+ continue
+ return candidate.end("failed", f"max_tokens: {ask.call_id} used all {request.max_tokens} tokens "
+ f"at effort {effort} and wrote nothing")
+ grid, issues = self.repair(candidate, ask.call_id, grid, issues)
+ candidate.g1 = _g1(issues)
+ if not candidate.g1["ok"]:
+ if not redrawn:
+ self.note(f"{ask.call_id}: G1 still fails ({_issue_list(issues)}); drawing {cid} once more")
+ candidate.redraws.append({"after": ask.call_id, "why": "G1", "effort": effort})
+ number, redrawn = number + 1, True
+ continue
+ return candidate.end("failed", f"G1: {_issue_list(issues)}")
+ candidate.effort, candidate.grid = effort, grid
+ pixels = {name: frame_pixels(grid, name) for name in request.frames}
+ candidate.gates = evaluate(pixels, kind=request.kind, rule=request.palette, walk_cycle=request.walk_cycle)
+ candidate.warnings = candidate.gates["warnings"]
+ if candidate.gates["ok"]:
+ return candidate.end("passed")
+ return candidate.end("failed", "failed " + ", ".join(candidate.gates["failed"]))
+
+ def repair(self, candidate: Candidate, gen_id: str, grid: Grid | None,
+ issues: list[Issue]) -> tuple[Grid | None, list[Issue]]:
+ """Row repair: the broken rows go back with their neighbours, the answers are spliced in."""
+ if grid is None or structural(issues):
+ return grid, issues
+ for round_number in range(1, REPAIR_ROUNDS + 1):
+ broken = row_issues(issues)
+ if not broken:
+ break
+ prompt, wanted = repair_prompt(self.request, grid, broken)
+ call_id = f"{gen_id}-fix{round_number}"
+ body = api.message_body(system=SYSTEM, content=prompt, effort=REPAIR_EFFORT, max_tokens=REPAIR_MAX_TOKENS)
+ outcome = self.calls.realtime(call_id, "repair", candidate.id, body)
+ entry: dict[str, Any] = {"call": call_id, "rows_asked": [f"{n} {i}" for n, i in wanted]}
+ if isinstance(outcome, ApiError) or outcome.stop_reason == "refusal":
+ entry["error"] = outcome.line if isinstance(outcome, ApiError) else _refusal_reason(outcome)
+ candidate.repairs.append(entry)
+ break
+ fixes, ignored = parse_row_answers(outcome.text, grid, set(wanted))
+ grid = splice(grid, fixes)
+ issues = [i for i in issues if i not in broken] + check_rows(grid)
+ entry.update(rows_answered=[f"{n} {i}" for n, i in sorted(fixes)], ignored=ignored,
+ rows_still_broken=sorted({f"{i.frame} {i.row}" for i in row_issues(issues)}))
+ candidate.repairs.append(entry)
+ return grid, issues
+
+ # -- drivers
+
+ def _realtime(self, cid: str) -> Candidate:
+ flow = self.flow(cid)
+ try:
+ ask = next(flow)
+ while True:
+ ask = flow.send(self.calls.realtime(ask.call_id, "generate", cid, ask.body))
+ except StopIteration as stop:
+ return stop.value
+
+ def _batched(self, cids: list[str]) -> dict[str, Candidate]:
+ flows = {cid: self.flow(cid) for cid in cids}
+ done: dict[str, Candidate] = {}
+
+ def step(cid: str, value: Reply | ApiError | None) -> Ask | Candidate:
+ try:
+ return next(flows[cid]) if value is None else flows[cid].send(value)
+ except StopIteration as stop:
+ return stop.value
+
+ with ThreadPoolExecutor(max_workers=len(cids)) as pool:
+ asks: dict[str, Ask] = {}
+ for cid, out in zip(cids, pool.map(lambda c: step(c, None), cids)):
+ (asks.__setitem__ if isinstance(out, Ask) else done.__setitem__)(cid, out)
+ while asks:
+ answers = self.calls.batch_round(list(asks.values()), self.batch_wait)
+ waiting = list(asks)
+ outs = list(pool.map(lambda c: step(c, answers[asks[c].call_id]), waiting))
+ asks = {}
+ for cid, out in zip(waiting, outs):
+ (asks.__setitem__ if isinstance(out, Ask) else done.__setitem__)(cid, out)
+ return done
+
+ def candidates(self) -> list[Candidate]:
+ cids = [f"c{n}" for n in range(1, self.request.candidates + 1)]
+ if self.request.batch:
+ done = self._batched(cids)
+ return [done[cid] for cid in cids]
+ with ThreadPoolExecutor(max_workers=len(cids)) as pool:
+ return list(pool.map(self._realtime, cids))
+
+ # -- G7
+
+ def pick(self, passed: list[Candidate]) -> dict[str, Any]:
+ if len(passed) == 1:
+ return {"by": "only", "best": passed[0].id}
+ if self.request.pick == "human":
+ return {"by": "human", "best": None, "candidates": [c.id for c in passed]}
+ labels = "ABCDEFGH"[:len(passed)]
+ order = list(passed)
+ random.Random(_sha(self.request.to_dict())).shuffle(order)
+ by_label = {label: c for label, c in zip(labels, order)}
+ sheet = pick_sheet(self.run_dir, by_label, tile=self.request.kind == "tile")
+ sheet_path = self.run_dir / "pick-sheet.png"
+ sheet_path.write_bytes(sheet)
+ content = [{"type": "image", "source": {"type": "base64", "media_type": "image/png",
+ "data": base64.standard_b64encode(sheet).decode("ascii")}},
+ {"type": "text", "text": pick_prompt(self.request, list(labels))}]
+ body = api.message_body(system=None, content=content, effort=PICK_EFFORT, max_tokens=PICK_MAX_TOKENS,
+ schema=PICK_SCHEMA)
+ record: dict[str, Any] = {"by": "vision", "call": "pick", "sheet": sheet_path.name,
+ "labels": {label: c.id for label, c in by_label.items()}, "best": None}
+ outcome = self.calls.realtime("pick", "pick", None, body, image=sheet_path.name)
+ if isinstance(outcome, ApiError):
+ return {**record, "error": outcome.line}
+ if outcome.stop_reason == "refusal":
+ return {**record, "error": _refusal_reason(outcome)}
+ try:
+ verdict = json.loads(outcome.text)
+ best = verdict["best"]
+ except (json.JSONDecodeError, TypeError, KeyError):
+ return {**record, "error": f"the pick answer is not the verdict JSON: {outcome.text[:200]!r}"}
+ if best not in by_label:
+ return {**record, "error": f"the pick named {best!r}, not one of {', '.join(labels)}", "verdict": verdict}
+ return {**record, "best": by_label[best].id, "verdict": verdict}
+
+
+def _issue_list(issues: list[Issue]) -> str:
+ failing = structural(issues) + row_issues(issues)
+ shown = [f"{i.code}" + (f" {i.frame}" if i.frame else "") + (f" row {i.row}" if i.row else "") for i in failing[:6]]
+ return ", ".join(shown) + (f" and {len(failing) - 6} more" if len(failing) > 6 else "")
+
+
+def _checker(width: int, height: int, cell: int = 8) -> Image.Image:
+ board = Image.new("RGBA", (width, height), (236, 236, 236, 255))
+ draw = ImageDraw.Draw(board)
+ for y in range(0, height, cell):
+ for x in range(0, width, cell):
+ if (x // cell + y // cell) % 2:
+ draw.rectangle([x, y, x + cell - 1, y + cell - 1], fill=(206, 206, 206, 255))
+ return board
+
+
+def pick_sheet(run_dir: Path, by_label: dict[str, Candidate], *, tile: bool) -> bytes:
+ """One sheet of the candidates' previews (and 3x3 tilings), each row labelled."""
+ rows = []
+ for label, candidate in by_label.items():
+ preview = Image.open(run_dir / candidate.files["preview"]).convert("RGBA")
+ tiled = Image.open(run_dir / candidate.files["tiled"]).convert("RGBA") if tile else None
+ rows.append((label, preview, tiled))
+ pad, label_width = 16, 56
+ width = max(label_width + p.width + (t.width + pad if t else 0) for _, p, t in rows) + pad * 2
+ height = sum(max(p.height, t.height if t else 0) + pad for _, p, t in rows) + pad
+ sheet = Image.new("RGBA", (width, height), (255, 255, 255, 255))
+ draw = ImageDraw.Draw(sheet)
+ y = pad
+ for label, preview, tiled in rows:
+ draw.text((pad, y + 4), label, fill=(0, 0, 0, 255), font_size=36)
+ x = pad + label_width
+ sheet.alpha_composite(Image.alpha_composite(_checker(preview.width, preview.height), preview), (x, y))
+ if tiled is not None:
+ sheet.alpha_composite(tiled, (x + preview.width + pad, y))
+ y += max(preview.height, tiled.height if tiled is not None else 0) + pad
+ buffer = io.BytesIO()
+ sheet.convert("RGB").save(buffer, format="PNG")
+ return buffer.getvalue()
+
+
+# ----------------------------------------------------------------------------- files and report
+
+def write_files(directory: Path, grid: Grid, request_frames: tuple[str, ...], kind: str, rule: PaletteRule,
+ pixels_used: list[str]) -> dict[str, Any]:
+ """grid.txt, palette.json, frame-<name>.png, preview-x<s>.png, tiled-3x3.png (tile), anim.gif (2+ frames)."""
+ directory.mkdir(parents=True, exist_ok=True)
+ frames = {name: frame_pixels(grid, name) for name in request_frames}
+ scale = preview_scale(max(grid.width, grid.height))
+ files: dict[str, Any] = {"grid": "grid.txt", "palette": "palette.json", "frames": {}}
+ (directory / "grid.txt").write_text(to_text(grid), encoding="utf-8")
+ keys = grid.key_map()
+ palette = {"rule": rule.to_dict(), "transparent": ".",
+ "keys": {keys[k]: (None if c is None else c.upper()) for k, c in grid.palette.items()},
+ "colors_used": pixels_used}
+ (directory / "palette.json").write_text(json.dumps(palette, indent=1) + "\n", encoding="utf-8")
+ for name, pixels in frames.items():
+ (directory / f"frame-{name}.png").write_bytes(png_bytes(pixels))
+ files["frames"][name] = f"frame-{name}.png"
+ preview_strip(list(frames.values()), scale).save(directory / f"preview-x{scale}.png")
+ files["preview"] = f"preview-x{scale}.png"
+ if kind == "tile":
+ tiled_3x3(frames[request_frames[0]], scale).save(directory / "tiled-3x3.png")
+ files["tiled"] = "tiled-3x3.png"
+ if len(frames) > 1:
+ save_gif(list(frames.values()), scale, directory / "anim.gif", GIF_FRAME_MS)
+ files["gif"] = "anim.gif"
+ return files
+
+
+def _flat(files: dict[str, Any]) -> list[str]:
+ names = [v for k, v in files.items() if k != "frames"]
+ return names + list(files.get("frames", {}).values())
+
+
+def _prefixed(files: dict[str, Any], prefix: str) -> dict[str, Any]:
+ out = {k: f"{prefix}/{v}" for k, v in files.items() if k != "frames"}
+ out["frames"] = {n: f"{prefix}/{v}" for n, v in files.get("frames", {}).items()}
+ return out
+
+
+def _totals(calls: list[dict[str, Any]]) -> tuple[dict[str, int], float]:
+ usage = {"input_tokens": 0, "output_tokens": 0, "thinking_tokens": 0, "cache_creation_input_tokens": 0,
+ "cache_read_input_tokens": 0}
+ for call in calls:
+ for key in usage:
+ value = call.get("thinking_tokens") if key == "thinking_tokens" else (call.get("usage") or {}).get(key)
+ usage[key] += value if isinstance(value, int) else 0
+ return usage, round(sum(call.get("cost_usd") or 0.0 for call in calls), 6)
+
+
+def _write_report(run_dir: Path, report: dict[str, Any]) -> Path:
+ path = run_dir / "report.json"
+ atomic_write_text(path, json.dumps(report, ensure_ascii=False, indent=1) + "\n")
+ return path
+
+
+def _print_json(payload: dict[str, Any]) -> None:
+ text = json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+ buffer = getattr(sys.stdout, "buffer", None)
+ if buffer is not None:
+ buffer.write(text.encode("utf-8"))
+ buffer.flush()
+ else:
+ sys.stdout.write(text)
+
+
+# ----------------------------------------------------------------------------- the verb
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+ source = parser.add_mutually_exclusive_group()
+ source.add_argument("--subject", help="what to draw, in words (the frames' poses or views included)")
+ source.add_argument("--spec", type=Path, help=f"a JSON object holding {', '.join(SPEC_KEYS)} instead of the flags")
+ source.add_argument("--grid", type=Path, help="check and render an edited grid.txt; no model call")
+ parser.add_argument("--size", type=int, help=f"canvas side in pixels, {SIZE_MIN}..{SIZE_MAX} (default {SIZE_DEFAULT}; "
+ "measured best at 32 or less)")
+ parser.add_argument("--kind", choices=KINDS, help="sprite (default) and icon have a transparent background; a tile is "
+ "opaque and repeats")
+ parser.add_argument("--frames", help=f"comma-separated frame names drawn in one call, at most {FRAMES_MAX} "
+ "(default: one frame named after --kind)")
+ parser.add_argument("--walk-cycle", action="store_true", default=None,
+ help="the four frames are one walk cycle (contact, passing, contact, passing): says so in the "
+ "prompt and checks the legs change sides")
+ parser.add_argument("--palette", help="free[:N] (default free:16), pico8, #RRGGBB,#RRGGBB,..., or a palette file "
+ "(.json list, or one colour per line)")
+ parser.add_argument("--candidates", type=int, help=f"answers drawn for the request, {CANDIDATES_MIN}..{CANDIDATES_MAX} "
+ f"(default {CANDIDATES_DEFAULT})")
+ parser.add_argument("--effort", choices=EFFORT_CHOICES, help=f"thinking effort of each drawing (default {EFFORT_DEFAULT})")
+ parser.add_argument("--format", dest="answer_format", choices=FORMATS,
+ help="how the model writes the grid: chargrid (default) or json; grid.txt is a chargrid either way")
+ parser.add_argument("--batch", action="store_true", default=None,
+ help="draw through Message Batches at half price; waits for the batch (repairs and the pick stay realtime)")
+ parser.add_argument("--batch-wait", type=float, help=f"seconds to wait for one batch before the run ends unfinished "
+ f"(default {BATCH_WAIT_DEFAULT:g}; --resume collects it later)")
+ parser.add_argument("--max-tokens", type=int, help=f"output cap of each drawing, thinking included (default "
+ f"{MAX_TOKENS_SINGLE} for one frame, {MAX_TOKENS_MULTI} for more)")
+ parser.add_argument("--pick", choices=PICKS, help="who picks among candidates that passed: vision (default, one Opus "
+ "call at effort low) or human (none is copied to the top)")
+ parser.add_argument("--out-dir", required=True, type=Path, help="the run folder: new or empty, or the run to --resume")
+ parser.add_argument("--resume", action="store_true",
+ help="continue the run in --out-dir from its request.json: calls already answered are read back, "
+ "a batch already submitted is collected")
+
+
+def _given(args: argparse.Namespace, names: tuple[str, ...]) -> list[str]:
+ return ["--" + n.replace("answer_format", "format").replace("_", "-") for n in names if getattr(args, n) is not None]
+
+
+def _fresh_dir(out_dir: Path) -> None:
+ if out_dir.exists() and (not out_dir.is_dir() or any(out_dir.iterdir())):
+ raise _refuse(f"--out-dir {out_dir} exists and is not an empty folder; choose a new one "
+ "(or --resume the run it holds)")
+ out_dir.mkdir(parents=True, exist_ok=True)
+
+
+def _note_printer() -> Callable[[str], None]:
+ lock = threading.Lock()
+
+ def note(line: str) -> None:
+ with lock:
+ print(f"[{VERB}] {line}", file=sys.stderr, flush=True)
+
+ return note
+
+
+def _run_grid(args: argparse.Namespace) -> int:
+ extra = _given(args, ("size", "frames") + RUN_FLAGS + ("batch_wait",)) + (["--resume"] if args.resume else [])
+ if extra:
+ raise _refuse(f"--grid checks and renders a grid as it is; drop {', '.join(extra)}")
+ try:
+ text = Path(args.grid).expanduser().read_text(encoding="utf-8")
+ except OSError as exc:
+ raise _refuse(f"--grid {args.grid}: {exc}") from exc
+ try:
+ rule = palette_rule(args.palette or "free")
+ except ValueError as exc:
+ raise _refuse(str(exc)) from exc
+ kind = args.kind or "sprite"
+ grid, issues = read_grid_text(text)
+ if grid is not None and not (SIZE_MIN <= grid.width <= SIZE_MAX and SIZE_MIN <= grid.height <= SIZE_MAX):
+ raise _refuse(f"--grid {args.grid}: {grid.width}x{grid.height}; each side is {SIZE_MIN}..{SIZE_MAX} pixels")
+ frames = tuple(grid.frames) if grid is not None else ()
+ if args.walk_cycle and len(frames) != 4:
+ raise _refuse(f"--walk-cycle is four frames, the grid holds {len(frames)}")
+ out_dir = Path(args.out_dir).expanduser().resolve()
+ _fresh_dir(out_dir)
+ report: dict[str, Any] = {"kind": REPORT_KIND, "status": "failed", "out_dir": str(out_dir), "source": "grid",
+ "grid_source": str(Path(args.grid).expanduser().resolve()), "model": None,
+ "request": {"kind": kind, "frames": list(frames), "walk_cycle": bool(args.walk_cycle),
+ "palette": rule.to_dict()},
+ "G1": _g1(issues), "gates": None, "warnings": [], "files": {}, "calls": [],
+ "cost_usd": 0.0}
+ if grid is None or not report["G1"]["ok"]:
+ path = _write_report(out_dir, report)
+ raise _refuse(f"{args.grid} does not parse whole: {_issue_list(issues)}; report {path}")
+ pixels = {name: frame_pixels(grid, name) for name in frames}
+ gates = evaluate(pixels, kind=kind, rule=rule, walk_cycle=bool(args.walk_cycle))
+ files = write_files(out_dir, grid, frames, kind, rule, _colors_used(pixels))
+ report.update(status="ok" if gates["ok"] else "failed", gates=gates, warnings=gates["warnings"], files=files,
+ request={**report["request"], "size": [grid.width, grid.height]})
+ path = _write_report(out_dir, report)
+ if not gates["ok"]:
+ raise _refuse(f"{args.grid} fails {', '.join(gates['failed'])}; files and report in {out_dir} ({path.name})")
+ _print_json(report)
+ return 0
+
+
+def _colors_used(pixels: dict[str, Any]) -> list[str]:
+ return sorted({"#{:02X}{:02X}{:02X}".format(*p[:3]) for f in pixels.values() for row in f for p in row if p[3] >= 128})
+
+
+def _run(args: argparse.Namespace, *, sleep: Callable[[float], None] = time.sleep) -> int:
+ if args.grid is not None:
+ return _run_grid(args)
+ out_dir = Path(args.out_dir).expanduser().resolve()
+ if args.resume:
+ extra = _given(args, SPEC_KEYS + RUN_FLAGS) + (["--spec"] if args.spec else [])
+ if extra:
+ raise _refuse(f"--resume reads the request from {out_dir / 'request.json'}; drop {', '.join(extra)}")
+ try:
+ request = PixelRequest.from_dict(json.loads((out_dir / "request.json").read_text(encoding="utf-8")))
+ except (OSError, json.JSONDecodeError, KeyError, TypeError) as exc:
+ raise _refuse(f"--resume: {out_dir} holds no readable request.json ({exc})") from exc
+ else:
+ request = resolve_request(args)
+ batch_wait = BATCH_WAIT_DEFAULT if args.batch_wait is None else args.batch_wait
+ if batch_wait < 0:
+ raise _refuse(f"--batch-wait is seconds, at least 0, got {batch_wait:g}")
+ token = api.resolve_credential()
+ if not args.resume:
+ _fresh_dir(out_dir)
+ atomic_write_text(out_dir / "request.json", json.dumps(request.to_dict(), ensure_ascii=False, indent=1) + "\n")
+ note = _note_printer()
+ announce_api_billing("claude", api.AUTH_ENV,
+ f" (model={api.MODEL}, effort={request.effort}, candidates={request.candidates}, "
+ f"{'Message Batches at half price' if request.batch else 'realtime'}).")
+ started = time.monotonic()
+ calls = Calls(out_dir, token, sleep=sleep, note=note)
+ run = Run(request, out_dir, calls, batch_wait=batch_wait, note=note)
+ report: dict[str, Any] = {"kind": REPORT_KIND, "status": None, "out_dir": str(out_dir), "source": "model",
+ "model": api.MODEL, "request": request.to_dict(), "chosen": None, "files": {},
+ "pick": None, "candidates": [], "warnings": []}
+ try:
+ candidates = run.candidates()
+ except Unfinished as unfinished:
+ report.update(status="unfinished", unfinished={"batch_id": unfinished.batch_id, "why": unfinished.why,
+ "waited_seconds": round(unfinished.waited, 3)})
+ path = _finish(report, calls, started)
+ raise _refuse(f"batch {unfinished.batch_id} {unfinished.why} after {unfinished.waited:.0f}s; nothing is asked "
+ f"twice — collect it with `sprite-gen pixel-draw --out-dir {out_dir} --resume`; report {path}")
+ for candidate in candidates:
+ if candidate.grid is not None:
+ pixels = {name: frame_pixels(candidate.grid, name) for name in request.frames}
+ files = write_files(out_dir / "candidates" / candidate.id, candidate.grid, request.frames, request.kind,
+ request.palette, _colors_used(pixels))
+ candidate.files = _prefixed(files, f"candidates/{candidate.id}")
+ passed = [c for c in candidates if c.status == "passed"]
+ report["candidates"] = [c.to_dict() for c in candidates]
+ if not passed:
+ refused_all = all(c.status == "refused" for c in candidates)
+ report["status"] = "refused" if refused_all else "failed"
+ path = _finish(report, calls, started)
+ if refused_all:
+ raise _refuse(f"{candidates[0].reason}; every candidate was refused; report {path}")
+ reasons = "; ".join(f"{c.id}: {c.reason}" for c in candidates)
+ raise _refuse(f"no candidate passed the gates ({reasons}); report {path}")
+ pick = run.pick(passed)
+ report["pick"] = pick
+ chosen = next((c for c in passed if c.id == pick.get("best")), None)
+ if chosen is not None:
+ source = out_dir / "candidates" / chosen.id
+ top = {k: v.split("/", 2)[-1] if k != "frames" else {n: p.split("/", 2)[-1] for n, p in v.items()}
+ for k, v in chosen.files.items()}
+ for name in _flat(top):
+ shutil.copyfile(source / name, out_dir / name)
+ report.update(chosen=chosen.id, files=top, warnings=chosen.warnings)
+ if pick.get("error"):
+ report["status"] = "pick_failed"
+ path = _finish(report, calls, started)
+ raise _refuse(f"{len(passed)} candidates passed but the pick failed ({pick['error']}); they are in "
+ f"{out_dir / 'candidates'}; report {path}")
+ report["status"] = "ok"
+ _finish(report, calls, started)
+ _print_json(report)
+ return 0
+
+
+def _finish(report: dict[str, Any], calls: Calls, started: float) -> Path:
+ summaries = [calls.summaries[cid] for cid in sorted(calls.summaries, key=_call_order)]
+ usage, cost = _totals(summaries)
+ report.update(calls=summaries, batches=list(calls.batches.values()), usage=usage, cost_usd=cost,
+ seconds=round(time.monotonic() - started, 3))
+ return _write_report(Path(report["out_dir"]), report)
+
+
+def _call_order(call_id: str) -> tuple:
+ if call_id == "pick":
+ return (10**6,)
+ parts = call_id.replace("-gen", " ").replace("-fix", " ").split()
+ return (int(parts[0][1:]), *[int(p) for p in parts[1:]])
+
+
+def run(**kwargs: Any) -> int:
+ parser = argparse.ArgumentParser()
+ add_arguments(parser)
+ known = {action.dest for action in parser._actions if action.dest != "help"}
+ unexpected = set(kwargs) - known
+ if unexpected:
+ raise TypeError(f"unexpected keyword argument(s): {', '.join(sorted(unexpected))}")
+ return _run(argparse.Namespace(**{dest: kwargs.get(dest, parser.get_default(dest)) for dest in known}))
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ add_arguments(parser)
+ return _run(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/sprite_gen/gen/pixel_gates.py b/sprite_gen/gen/pixel_gates.py
new file mode 100644
index 0000000..2ae1900
--- /dev/null
+++ b/sprite_gen/gen/pixel_gates.py
@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Gates G2..G6 of `pixel-draw`, on the pixels of a grid that passed G1 (it parsed whole).
+
+- G2 palette: the opaque colours used are at most the rule's limit; a fixed palette allows only its
+ own colours.
+- G3 alpha: a sprite or icon frame has opaque pixels, four transparent corners and a border at
+ least half transparent; a tile frame is opaque everywhere.
+- G4 tile seam (warning): the colour step across the wrap edges over the mean step between
+ neighbours inside the tile, at most 1.5. Mortar lines that meet the edge raise it on tiles that
+ repeat cleanly, so it warns and never fails until the measure is refined.
+- G5 stray pixels (warning): opaque pixels of a sprite or icon with no opaque 4-neighbour.
+- G6 frames: every frame stands on the same bottom row, heights differ by at most one pixel and
+ no two frames are the same. A walk cycle (contact, passing, contact, passing) also warns when
+ its two contact frames differ by less than 40% of the mean contact↔passing difference: the legs
+ barely change sides.
+
+A failed gate fails the candidate; a warning is reported and passes.
+"""
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from .pixel_grid import Pixel, PaletteRule
+
+SEAM_RATIO_MAX = 1.5
+BORDER_TRANSPARENT_MIN = 0.5
+HEIGHT_SPREAD_MAX = 1
+WALK_CONTACT_RATIO_MIN = 0.4
+
+Frame = Sequence[Sequence[Pixel]]
+
+
+def _opaque(pixel: Pixel) -> bool:
+ return pixel[3] >= 128
+
+
+def _hex(pixel: Pixel) -> str:
+ return "#{:02X}{:02X}{:02X}".format(*pixel[:3])
+
+
+def g2_palette(frames: dict[str, Frame], rule: PaletteRule) -> dict[str, Any]:
+ used = sorted({_hex(p) for frame in frames.values() for row in frame for p in row if _opaque(p)})
+ off = [c for c in used if rule.fixed and c not in rule.colors]
+ return {"ok": len(used) <= rule.limit and not off, "colors_used": len(used), "limit": rule.limit,
+ "palette": rule.name, "off_palette": off}
+
+
+def _frame_alpha(frame: Frame) -> dict[str, Any]:
+ height, width = len(frame), len(frame[0])
+ opaque = sum(1 for row in frame for p in row if _opaque(p))
+ border = [frame[y][x] for y in range(height) for x in range(width) if x in (0, width - 1) or y in (0, height - 1)]
+ corners = (frame[0][0], frame[0][width - 1], frame[height - 1][0], frame[height - 1][width - 1])
+ return {
+ "opaque_pixels": opaque,
+ "opaque_fraction": round(opaque / (width * height), 4),
+ "corners_transparent": not any(_opaque(p) for p in corners),
+ "border_transparent_fraction": round(sum(1 for p in border if not _opaque(p)) / len(border), 4),
+ }
+
+
+def g3_alpha(frames: dict[str, Frame], kind: str) -> dict[str, Any]:
+ per = {name: _frame_alpha(frame) for name, frame in frames.items()}
+ if kind == "tile":
+ ok = all(m["opaque_fraction"] == 1.0 for m in per.values())
+ else:
+ ok = all(m["opaque_pixels"] > 0 and m["corners_transparent"]
+ and m["border_transparent_fraction"] >= BORDER_TRANSPARENT_MIN for m in per.values())
+ return {"ok": ok, "kind": kind, "frames": per}
+
+
+def _step(a: Pixel, b: Pixel) -> float:
+ return sum(abs(a[i] - b[i]) for i in range(3)) / 3
+
+
+def seam_ratio(frame: Frame) -> float:
+ height, width = len(frame), len(frame[0])
+ inner = [_step(frame[y][x], frame[y][x + 1]) for y in range(height) for x in range(width - 1)]
+ inner += [_step(frame[y][x], frame[y + 1][x]) for y in range(height - 1) for x in range(width)]
+ wrap = [_step(frame[y][width - 1], frame[y][0]) for y in range(height)]
+ wrap += [_step(frame[height - 1][x], frame[0][x]) for x in range(width)]
+ inner_mean = sum(inner) / max(1, len(inner))
+ wrap_mean = sum(wrap) / max(1, len(wrap))
+ if inner_mean == 0:
+ return 0.0 if wrap_mean == 0 else 99.0
+ return round(wrap_mean / inner_mean, 3)
+
+
+def g4_seam(frames: dict[str, Frame]) -> dict[str, Any]:
+ ratios = {name: seam_ratio(frame) for name, frame in frames.items()}
+ worst = max(ratios.values())
+ return {"warn": worst > SEAM_RATIO_MAX, "seam_ratio": worst, "max": SEAM_RATIO_MAX, "frames": ratios}
+
+
+def isolated_pixels(frame: Frame) -> int:
+ height, width = len(frame), len(frame[0])
+ count = 0
+ for y in range(height):
+ for x in range(width):
+ if not _opaque(frame[y][x]):
+ continue
+ neighbours = ((x + 1, y), (x - 1, y), (x, y + 1), (x, y - 1))
+ if not any(0 <= nx < width and 0 <= ny < height and _opaque(frame[ny][nx]) for nx, ny in neighbours):
+ count += 1
+ return count
+
+
+def g5_isolated(frames: dict[str, Frame]) -> dict[str, Any]:
+ per = {name: isolated_pixels(frame) for name, frame in frames.items()}
+ total = sum(per.values())
+ return {"warn": total > 0, "isolated_pixels": total, "frames": per}
+
+
+def _bbox_rows(frame: Frame) -> tuple[int, int] | None:
+ rows = [y for y, row in enumerate(frame) if any(_opaque(p) for p in row)]
+ return (rows[0], rows[-1]) if rows else None
+
+
+def _difference(a: Frame, b: Frame) -> int:
+ return sum(1 for y in range(len(a)) for x in range(len(a[0])) if a[y][x] != b[y][x])
+
+
+def g6_frames(frames: dict[str, Frame], *, walk_cycle: bool) -> dict[str, Any]:
+ names = list(frames)
+ spans = {name: _bbox_rows(frames[name]) for name in names}
+ baselines = {name: (span[1] if span else None) for name, span in spans.items()}
+ heights = {name: (span[1] - span[0] + 1 if span else 0) for name, span in spans.items()}
+ identical = [[names[i], names[j]] for i in range(len(names)) for j in range(i + 1, len(names))
+ if frames[names[i]] == frames[names[j]]]
+ spread = max(heights.values()) - min(heights.values())
+ result: dict[str, Any] = {
+ "ok": len(set(baselines.values())) == 1 and None not in baselines.values()
+ and spread <= HEIGHT_SPREAD_MAX and not identical,
+ "baselines": baselines, "heights": heights, "height_spread": spread, "identical_pairs": identical,
+ }
+ if walk_cycle:
+ a, b, c, d = (frames[n] for n in names)
+ contact = _difference(a, c)
+ crossing = (_difference(a, b) + _difference(b, c) + _difference(c, d) + _difference(d, a)) / 4
+ ratio = round(contact / crossing, 3) if crossing else 0.0
+ result["walk"] = {"warn": ratio < WALK_CONTACT_RATIO_MIN, "contact_difference": contact,
+ "contact_passing_difference": round(crossing, 1), "ratio": ratio,
+ "min": WALK_CONTACT_RATIO_MIN}
+ return result
+
+
+def evaluate(frames: dict[str, Frame], *, kind: str, rule: PaletteRule, walk_cycle: bool) -> dict[str, Any]:
+ """Every gate of one candidate. `ok` is G2, G3 and G6 together; `warnings` say what G4, G5 and
+ the walk check found, one line each."""
+ gates: dict[str, Any] = {"G2": g2_palette(frames, rule), "G3": g3_alpha(frames, kind)}
+ warnings: list[str] = []
+ if kind == "tile":
+ gates["G4"] = g4_seam(frames)
+ if gates["G4"]["warn"]:
+ warnings.append(f"G4 tile seam ratio {gates['G4']['seam_ratio']} > {SEAM_RATIO_MAX} "
+ "(look at tiled-3x3.png: mortar lines on the edge raise it on tiles that repeat cleanly)")
+ else:
+ gates["G5"] = g5_isolated(frames)
+ if gates["G5"]["warn"]:
+ warnings.append(f"G5 {gates['G5']['isolated_pixels']} stray pixel(s) with no opaque neighbour")
+ if len(frames) > 1:
+ gates["G6"] = g6_frames(frames, walk_cycle=walk_cycle)
+ walk = gates["G6"].get("walk")
+ if walk and walk["warn"]:
+ warnings.append(f"G6 weak leg alternation: the contact frames differ by {walk['contact_difference']} "
+ f"pixels, {walk['ratio']:.0%} of the contact-passing difference (under "
+ f"{WALK_CONTACT_RATIO_MIN:.0%}) — touch up the legs")
+ failed = [name for name in ("G2", "G3", "G6") if name in gates and not gates[name]["ok"]]
+ return {"ok": not failed, "failed": failed, "warnings": warnings, **gates}
diff --git a/sprite_gen/gen/pixel_grid.py b/sprite_gen/gen/pixel_grid.py
new file mode 100644
index 0000000..ed58268
--- /dev/null
+++ b/sprite_gen/gen/pixel_grid.py
@@ -0,0 +1,550 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The pixel grid `pixel-draw` asks a model for: its two answer formats, the canonical `grid.txt`,
+the palette rules, row repair splicing and the renders.
+
+A grid is a palette (one key per colour, `.` transparent) and per frame `height` rows of `width`
+keys. The model answers it as a character grid (a ```pixels block: `PALETTE`, `FRAME <name>`,
+rows, `END`) or as JSON (`{"palette": ["transparent", "#RRGGBB", ...], "frames": {name:
+[[index, ...], ...]}}`). Either way the truth written to disk is `grid.txt`, the character grid
+without its fence: a person can edit it, diff it and render it again (`pixel-draw --grid`).
+
+Parsing is strict and says what it found (`Issue`):
+
+- structural issues (no block, a broken palette, a frame missing or extra, more rows than the
+ canvas) leave nothing a row can fix — that answer is drawn again;
+- row issues (a row one key too long or short, a key not in the palette, rows missing at the end)
+ are what the row repair asks for, one row at a time, and `splice` puts the answers in;
+- recovered issues are code-recoverable and recorded, never silent: the fence tagged otherwise or
+ missing, a fence never closed, a single frame written without its `FRAME` line or under another
+ name, frames in another order, no `END` line.
+
+`png_bytes` writes a frame as a PNG whose bytes depend only on its pixels — stored deflate
+blocks, no compressor in the loop — so the same grid gives the same file on any machine and any
+zlib (Pillow's encoder output follows the zlib build it links). Previews, the 3x3 tiling and the
+GIF are views for the eye and go through Pillow.
+"""
+from __future__ import annotations
+
+import json
+import re
+import string
+import struct
+import zlib
+from collections import Counter
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Sequence
+
+from PIL import Image
+
+from sprite_gen.util.gif_utils import save_clean_gif
+
+FORMATS = ("chargrid", "json")
+KEYS = string.ascii_lowercase + string.ascii_uppercase + string.digits
+TRANSPARENT_KEY = "."
+HEX = re.compile(r"^#[0-9A-Fa-f]{6}$")
+PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
+
+# PICO-8's 16 colours (lexaloffle.com/pico-8.php, the fixed palette of the console).
+PICO8 = ("#000000", "#1D2B53", "#7E2553", "#008751", "#AB5236", "#5F574F", "#C2C3C7", "#FFF1E8",
+ "#FF004D", "#FFA300", "#FFEC27", "#00E436", "#29ADFF", "#83769C", "#FF77A8", "#FFCCAA")
+FREE_DEFAULT_LIMIT = 16
+
+STRUCTURAL = frozenset({
+ "no_block", "json_invalid", "json_shape", "bad_palette_line", "palette_key_duplicate", "dot_redefined",
+ "extra_transparent_key", "palette0_not_transparent", "palette_too_large", "frame_missing", "frame_extra",
+ "frame_duplicate", "row_count_over", "stray_line",
+})
+ROW_CODES = frozenset({"row_width", "unknown_symbol", "row_missing"})
+RECOVERED = frozenset({"block_tag", "block_unclosed", "frame_header_missing", "frame_renamed", "frame_order",
+ "no_end"})
+
+_PALETTE_LINE = re.compile(r"^(\S)\s+(transparent|#[0-9A-Fa-f]{6})$")
+_ROW_ANSWER = re.compile(r"^\s*`?\s*ROW\s+(\S+)\s+(\d+)\s*:\s*(.*?)\s*`?\s*$", re.M)
+_FRAME_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$")
+
+Pixel = tuple[int, int, int, int]
+TRANSPARENT: Pixel = (0, 0, 0, 0)
+
+
+def frame_name_ok(name: str) -> bool:
+ return bool(_FRAME_NAME.fullmatch(name))
+
+
+# ----------------------------------------------------------------------------- palette rules
+
+@dataclass(frozen=True)
+class PaletteRule:
+ """What a request allows: at most `limit` colours (free), or only `colors` (fixed)."""
+
+ name: str # "free:<n>" | "pico8" | "fixed"
+ limit: int
+ colors: tuple[str, ...] = () # "#RRGGBB" upper case; empty for a free palette
+
+ @property
+ def fixed(self) -> bool:
+ return bool(self.colors)
+
+ def to_dict(self) -> dict:
+ return {"name": self.name, "limit": self.limit, "colors": list(self.colors)}
+
+
+def _fixed(colors: Sequence[str], name: str, where: str) -> PaletteRule:
+ normalized = []
+ for raw in colors:
+ value = raw.strip()
+ if not value.startswith("#"):
+ value = "#" + value
+ if not HEX.fullmatch(value):
+ raise ValueError(f"{where}: {raw!r} is not a #RRGGBB colour")
+ normalized.append(value.upper())
+ if not normalized:
+ raise ValueError(f"{where}: no colours")
+ duplicates = sorted({c for c in normalized if normalized.count(c) > 1})
+ if duplicates:
+ raise ValueError(f"{where}: colours listed twice: {', '.join(duplicates)}")
+ if len(normalized) > len(KEYS):
+ raise ValueError(f"{where}: at most {len(KEYS)} colours (one key each), got {len(normalized)}")
+ return PaletteRule(name=name, limit=len(normalized), colors=tuple(normalized))
+
+
+def palette_rule(value: str) -> PaletteRule:
+ """`--palette`: `free` / `free:N`, `pico8`, `#hex,#hex,...`, or a file of colours.
+
+ A file is JSON (a list of colours, or `{"colors": [...]}`) or text with one `#RRGGBB` /
+ `RRGGBB` per line (blank lines and lines starting `;` skipped — Lospec's .hex is this)."""
+ text = value.strip()
+ if text == "free" or text.startswith("free:"):
+ number = text.partition(":")[2] or str(FREE_DEFAULT_LIMIT)
+ if not number.isdigit() or not 1 <= int(number) <= len(KEYS):
+ raise ValueError(f"--palette {value!r}: free:N takes 1..{len(KEYS)} colours")
+ return PaletteRule(name=f"free:{int(number)}", limit=int(number))
+ if text == "pico8":
+ return PaletteRule(name="pico8", limit=len(PICO8), colors=PICO8)
+ if text.startswith("#"):
+ return _fixed(text.split(","), "fixed", f"--palette {value!r}")
+ path = Path(text).expanduser()
+ if not path.is_file():
+ raise ValueError(f"--palette {value!r}: not free[:N], pico8, a #RRGGBB list or a palette file that exists")
+ raw = path.read_text(encoding="utf-8")
+ if path.suffix.lower() == ".json":
+ try:
+ data = json.loads(raw)
+ except json.JSONDecodeError as exc:
+ raise ValueError(f"--palette {path}: not JSON ({exc.msg})") from exc
+ colors = data.get("colors") if isinstance(data, dict) else data
+ if not isinstance(colors, list) or not all(isinstance(c, str) for c in colors):
+ raise ValueError(f"--palette {path}: expected a list of colours or {{\"colors\": [...]}}")
+ else:
+ colors = [line for line in (l.strip() for l in raw.splitlines()) if line and not line.startswith(";")]
+ return _fixed(colors, "fixed", f"--palette {path}")
+
+
+# ----------------------------------------------------------------------------- the grid
+
+@dataclass(frozen=True)
+class Issue:
+ code: str
+ frame: str | None = None
+ row: int | None = None # 1-based
+ detail: str = ""
+
+ def to_dict(self) -> dict:
+ return {k: v for k, v in (("code", self.code), ("frame", self.frame), ("row", self.row),
+ ("detail", self.detail)) if v not in (None, "")}
+
+
+@dataclass(frozen=True)
+class Grid:
+ """A palette and frames of rows of keys, as written (keys of a JSON answer are its indices)."""
+
+ fmt: str
+ width: int
+ height: int
+ palette: dict[str, str | None] # key -> "#RRGGBB" as written, None for transparent
+ frames: dict[str, list[list[str]]]
+
+ def key_map(self) -> dict[str, str]:
+ """The character each key is written with in grid.txt."""
+ if self.fmt == "chargrid":
+ return {key: key for key in self.palette}
+ mapping = {}
+ for key, color in self.palette.items():
+ index = int(key)
+ mapping[key] = TRANSPARENT_KEY if color is None else KEYS[index - 1]
+ return mapping
+
+
+def structural(issues: Sequence[Issue]) -> list[Issue]:
+ return [i for i in issues if i.code in STRUCTURAL]
+
+
+def row_issues(issues: Sequence[Issue]) -> list[Issue]:
+ return [i for i in issues if i.code in ROW_CODES]
+
+
+def recovered(issues: Sequence[Issue]) -> list[Issue]:
+ return [i for i in issues if i.code in RECOVERED]
+
+
+def check_rows(grid: Grid) -> list[Issue]:
+ """Every row issue of `grid`: a row of the wrong length, a key not in the palette, rows missing."""
+ issues: list[Issue] = []
+ for name, rows in grid.frames.items():
+ for number, row in enumerate(rows, 1):
+ if len(row) != grid.width:
+ issues.append(Issue("row_width", name, number, f"{len(row)} values, needs {grid.width}"))
+ unknown = sorted({token for token in row if token not in grid.palette})
+ if unknown:
+ issues.append(Issue("unknown_symbol", name, number, "not in the palette: " + " ".join(map(repr, unknown))))
+ for number in range(len(rows) + 1, grid.height + 1):
+ issues.append(Issue("row_missing", name, number))
+ return issues
+
+
+def _fenced(text: str, tag: str) -> tuple[str | None, str | None]:
+ """The body of the ```<tag> block and how it was found: as asked (None), in a fence tagged
+ otherwise or in no fence at all (`block_tag`), or in a fence never closed (`block_unclosed` —
+ an answer cut off keeps the rows it wrote)."""
+ match = re.search(r"```" + re.escape(tag) + r"[ \t]*\r?\n(.*?)```", text, re.S)
+ if match:
+ return match.group(1), None
+ opener = r"PALETTE" if tag == "pixels" else r"\{"
+ match = re.search(r"```[A-Za-z0-9_-]*[ \t]*\r?\n(\s*" + opener + r".*?)```", text, re.S)
+ if match:
+ return match.group(1), "block_tag"
+ match = re.search(r"```" + re.escape(tag) + r"[ \t]*\r?\n(.*)\Z", text, re.S)
+ if match:
+ return match.group(1), "block_unclosed"
+ if tag == "pixels":
+ match = re.search(r"(?m)^PALETTE[ \t]*$.*", text, re.S)
+ if match:
+ return match.group(0), "block_tag"
+ return None, None
+
+
+def _settle_frames(written: dict[str, list[list[str]]], order: list[str], frames: Sequence[str],
+ issues: list[Issue]) -> dict[str, list[list[str]]]:
+ """The requested frames out of what was written; one frame under another name is recovered."""
+ if len(frames) == 1 and frames[0] not in written and len(written) == 1:
+ (other,) = written
+ issues.append(Issue("frame_renamed", frames[0], None, f"written as FRAME {other}"))
+ written = {frames[0]: written[other]}
+ order = [frames[0]]
+ settled = {}
+ for name in frames:
+ if name not in written:
+ issues.append(Issue("frame_missing", name))
+ else:
+ settled[name] = written[name]
+ for name in order:
+ if name not in frames:
+ issues.append(Issue("frame_extra", name))
+ if [n for n in order if n in frames] != [n for n in frames if n in order]:
+ issues.append(Issue("frame_order", None, None, "written as " + ", ".join(order)))
+ return settled
+
+
+def _parse_chargrid_body(body: str, width: int, height: int, frames: Sequence[str],
+ issues: list[Issue]) -> Grid | None:
+ lines = [line.rstrip() for line in body.splitlines()]
+ palette: dict[str, str | None] = {}
+ written: dict[str, list[list[str]]] = {}
+ order: list[str] = []
+ section = None
+ current = None
+ saw_end = False
+ header_may_be_missing = len(frames) == 1 and not any(_frame_header(l.strip()) is not None for l in lines)
+ for line in lines:
+ stripped = line.strip()
+ if not stripped:
+ continue
+ if stripped == "PALETTE" and section is None:
+ section = "palette"
+ continue
+ name = _frame_header(stripped)
+ if name is not None and section in ("palette", "frame"):
+ if name in written:
+ issues.append(Issue("frame_duplicate", name))
+ written[name] = []
+ order.append(name)
+ current, section = name, "frame"
+ continue
+ if stripped == "END" and section in ("palette", "frame"):
+ saw_end, section = True, "after"
+ continue
+ if section == "palette":
+ match = _PALETTE_LINE.fullmatch(stripped)
+ if match:
+ key, value = match.group(1), match.group(2)
+ if key in palette:
+ issues.append(Issue("palette_key_duplicate", None, None, key))
+ elif key == TRANSPARENT_KEY and value != "transparent":
+ issues.append(Issue("dot_redefined", None, None, value))
+ elif value == "transparent" and key != TRANSPARENT_KEY:
+ issues.append(Issue("extra_transparent_key", None, None, key))
+ else:
+ palette[key] = None if value == "transparent" else value
+ continue
+ if header_may_be_missing and not written:
+ issues.append(Issue("frame_header_missing", frames[0], None, "rows follow the palette"))
+ current, section = frames[0], "frame"
+ written[current] = []
+ order.append(current)
+ else:
+ issues.append(Issue("bad_palette_line", None, None, stripped[:80]))
+ continue
+ if section == "frame":
+ written[current].append(list(line))
+ else:
+ issues.append(Issue("stray_line", None, None, stripped[:80]))
+ if section is None and not palette:
+ issues.append(Issue("no_block", None, None, "no PALETTE line"))
+ return None
+ palette.setdefault(TRANSPARENT_KEY, None)
+ palette = {TRANSPARENT_KEY: None, **{k: v for k, v in palette.items() if k != TRANSPARENT_KEY}}
+ if not saw_end:
+ issues.append(Issue("no_end"))
+ settled = _settle_frames(written, order, frames, issues)
+ for name, rows in settled.items():
+ if len(rows) > height:
+ issues.append(Issue("row_count_over", name, None, f"{len(rows)} rows, needs {height}"))
+ return Grid("chargrid", width, height, palette, settled)
+
+
+def _frame_header(stripped: str) -> str | None:
+ if stripped == "FRAME":
+ return ""
+ if stripped.startswith(("FRAME ", "FRAME\t")):
+ return stripped[5:].strip()
+ return None
+
+
+def _parse_json_body(body: str, width: int, height: int, frames: Sequence[str], issues: list[Issue]) -> Grid | None:
+ try:
+ data = json.loads(body)
+ except json.JSONDecodeError as exc:
+ issues.append(Issue("json_invalid", None, None, f"{exc.msg} at line {exc.lineno} column {exc.colno}"))
+ return None
+ raw_palette = data.get("palette") if isinstance(data, dict) else None
+ raw_frames = data.get("frames") if isinstance(data, dict) else None
+ if not isinstance(raw_palette, list) or not isinstance(raw_frames, dict) \
+ or not all(isinstance(rows, list) for rows in raw_frames.values()):
+ issues.append(Issue("json_shape", None, None, 'expected {"palette": [...], "frames": {name: [[...]]}}'))
+ return None
+ palette: dict[str, str | None] = {}
+ for index, value in enumerate(raw_palette):
+ if index == 0:
+ if value != "transparent":
+ issues.append(Issue("palette0_not_transparent", None, None, repr(value)[:40]))
+ palette["0"] = None
+ elif value == "transparent":
+ issues.append(Issue("extra_transparent_key", None, None, str(index)))
+ elif isinstance(value, str) and HEX.fullmatch(value):
+ palette[str(index)] = value
+ else:
+ issues.append(Issue("bad_palette_line", None, None, f"palette[{index}] = {value!r}"[:80]))
+ if len(raw_palette) - 1 > len(KEYS):
+ issues.append(Issue("palette_too_large", None, None, f"{len(raw_palette) - 1} colours, at most {len(KEYS)}"))
+ written = {name: [_json_row(row) for row in rows] for name, rows in raw_frames.items()}
+ settled = _settle_frames(written, list(raw_frames), frames, issues)
+ for name, rows in settled.items():
+ if len(rows) > height:
+ issues.append(Issue("row_count_over", name, None, f"{len(rows)} rows, needs {height}"))
+ return Grid("json", width, height, palette, settled)
+
+
+def _json_token(value: object) -> str:
+ if isinstance(value, int) and not isinstance(value, bool):
+ return str(value)
+ return json.dumps(value) # never a palette key: an unknown symbol
+
+
+def _json_row(row: object) -> list[str]:
+ return [_json_token(v) for v in row] if isinstance(row, list) else []
+
+
+def parse_answer(text: str, fmt: str, width: int, height: int, frames: Sequence[str]) -> tuple[Grid | None, list[Issue]]:
+ """Read a model's answer. Returns the grid (None when nothing could be read) and every issue."""
+ issues: list[Issue] = []
+ if fmt == "chargrid":
+ body, found = _fenced(text, "pixels")
+ elif fmt == "json":
+ body, found = _fenced(text, "json")
+ if body is None:
+ start, end = text.find("{"), text.rfind("}")
+ body, found = (text[start:end + 1], "block_tag") if 0 <= start < end else (None, None)
+ else:
+ raise ValueError(f"unknown format {fmt!r}")
+ if body is None:
+ issues.append(Issue("no_block", None, None, f"no ```{'pixels' if fmt == 'chargrid' else 'json'} block"))
+ return None, issues
+ if found:
+ issues.append(Issue(found))
+ parse = _parse_chargrid_body if fmt == "chargrid" else _parse_json_body
+ grid = parse(body, width, height, frames, issues)
+ if grid is not None and not structural(issues):
+ issues.extend(check_rows(grid))
+ return grid, issues
+
+
+def read_grid_text(text: str) -> tuple[Grid | None, list[Issue]]:
+ """Read a `grid.txt` (the character grid with or without its fence); the frames and the canvas
+ size are what it holds — the commonest row length is the width, the commonest row count the
+ height, so one row broken by an edit is reported as that row."""
+ body, _ = _fenced(text, "pixels")
+ body = text if body is None else body
+ rows: dict[str, list[str]] = {}
+ names: list[str] = []
+ for line in body.splitlines():
+ stripped = line.strip()
+ name = _frame_header(stripped)
+ if name is not None:
+ names.append(name)
+ rows.setdefault(name, [])
+ elif stripped == "END":
+ break
+ elif names and stripped:
+ rows[names[-1]].append(line.rstrip())
+ if not names:
+ return None, [Issue("frame_missing", None, None, "no FRAME line")]
+ bad = [n for n in names if not frame_name_ok(n)]
+ if bad:
+ return None, [Issue("frame_missing", None, None, "frame names are letters, digits, '_' or '-': "
+ + ", ".join(map(repr, bad)))]
+ lengths = Counter(len(row) for frame in rows.values() for row in frame)
+ counts = Counter(len(frame) for frame in rows.values())
+ width = lengths.most_common(1)[0][0] if lengths else 0
+ height = counts.most_common(1)[0][0]
+ issues: list[Issue] = []
+ grid = _parse_chargrid_body(body, width, height, list(dict.fromkeys(names)), issues)
+ if grid is not None and not structural(issues):
+ issues.extend(check_rows(grid))
+ return grid, issues
+
+
+# ----------------------------------------------------------------------------- repair splicing
+
+def row_text(grid: Grid, row: Sequence[str]) -> str:
+ """A row as the model wrote it: keys for a character grid, a JSON list for a JSON answer."""
+ if grid.fmt == "chargrid":
+ return "".join(row)
+ return "[" + ", ".join(row) + "]"
+
+
+def parse_row_answers(text: str, grid: Grid, wanted: set[tuple[str, int]]) -> tuple[dict[tuple[str, int], list[str]], list[str]]:
+ """`ROW <frame> <n>: <row>` lines of a repair answer: the rows asked for, and what was ignored."""
+ fixes: dict[tuple[str, int], list[str]] = {}
+ ignored: list[str] = []
+ for match in _ROW_ANSWER.finditer(text):
+ frame, number, value = match.group(1), int(match.group(2)), match.group(3).strip().strip("`").strip()
+ if (frame, number) not in wanted:
+ ignored.append(f"{frame} {number}")
+ continue
+ if grid.fmt == "chargrid":
+ fixes[(frame, number)] = list(value)
+ else:
+ try:
+ parsed = json.loads(value)
+ except json.JSONDecodeError:
+ parsed = None
+ fixes[(frame, number)] = _json_row(parsed)
+ return fixes, ignored
+
+
+def splice(grid: Grid, fixes: dict[tuple[str, int], list[str]]) -> Grid:
+ """`grid` with each fixed row put in its place; a missing row is added where it belongs."""
+ frames = {name: [list(row) for row in rows] for name, rows in grid.frames.items()}
+ for (name, number), row in sorted(fixes.items(), key=lambda item: (item[0][0], item[0][1])):
+ rows = frames[name]
+ while len(rows) < number:
+ rows.append([])
+ rows[number - 1] = list(row)
+ return replace(grid, frames=frames)
+
+
+# ----------------------------------------------------------------------------- grid.txt and renders
+
+def to_text(grid: Grid) -> str:
+ """The canonical grid.txt of a grid with no row issues: the character grid, unfenced."""
+ keys = grid.key_map()
+ lines = ["PALETTE", f"{TRANSPARENT_KEY} transparent"]
+ lines += [f"{keys[key]} {color}" for key, color in grid.palette.items() if color is not None]
+ for name, rows in grid.frames.items():
+ lines.append(f"FRAME {name}")
+ lines += ["".join(keys[token] for token in row) for row in rows]
+ lines.append("END")
+ return "\n".join(lines) + "\n"
+
+
+def hex_pixel(color: str | None) -> Pixel:
+ if color is None:
+ return TRANSPARENT
+ value = color.lstrip("#")
+ return (int(value[0:2], 16), int(value[2:4], 16), int(value[4:6], 16), 255)
+
+
+def frame_pixels(grid: Grid, name: str) -> list[list[Pixel]]:
+ colors = {key: hex_pixel(color) for key, color in grid.palette.items()}
+ return [[colors[token] for token in row] for row in grid.frames[name]]
+
+
+def _chunk(tag: bytes, data: bytes) -> bytes:
+ return struct.pack(">I", len(data)) + tag + data + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)
+
+
+def _stored_zlib(data: bytes) -> bytes:
+ """A zlib stream of stored (uncompressed) deflate blocks: its bytes are a function of `data` alone."""
+ out = bytearray(b"\x78\x01")
+ blocks = [data[i:i + 0xFFFF] for i in range(0, len(data), 0xFFFF)] or [b""]
+ for index, block in enumerate(blocks):
+ out.append(1 if index == len(blocks) - 1 else 0)
+ out += struct.pack("<HH", len(block), len(block) ^ 0xFFFF)
+ out += block
+ out += struct.pack(">I", zlib.adler32(data) & 0xFFFFFFFF)
+ return bytes(out)
+
+
+def png_bytes(pixels: Sequence[Sequence[Pixel]]) -> bytes:
+ """An 8-bit RGBA PNG of `pixels`, byte for byte the same for the same pixels."""
+ height, width = len(pixels), len(pixels[0])
+ raw = b"".join(b"\x00" + bytes(channel for pixel in row for channel in pixel) for row in pixels)
+ header = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0)
+ return PNG_MAGIC + _chunk(b"IHDR", header) + _chunk(b"IDAT", _stored_zlib(raw)) + _chunk(b"IEND", b"")
+
+
+def image_of(pixels: Sequence[Sequence[Pixel]]) -> Image.Image:
+ image = Image.new("RGBA", (len(pixels[0]), len(pixels)))
+ image.putdata([pixel for row in pixels for pixel in row])
+ return image
+
+
+def preview_scale(size: int) -> int:
+ """The nearest-neighbour enlargement that makes a frame about 256 px."""
+ return max(1, 256 // size)
+
+
+def preview_strip(frames: Sequence[Sequence[Sequence[Pixel]]], scale: int) -> Image.Image:
+ """The frames side by side, each enlarged `scale` times, two enlarged pixels apart."""
+ images = [image_of(f).resize((len(f[0]) * scale, len(f) * scale), Image.NEAREST) for f in frames]
+ gap = 2 * scale
+ strip = Image.new("RGBA", (sum(i.width for i in images) + gap * (len(images) - 1), max(i.height for i in images)))
+ x = 0
+ for image in images:
+ strip.paste(image, (x, 0))
+ x += image.width + gap
+ return strip
+
+
+def tiled_3x3(pixels: Sequence[Sequence[Pixel]], scale: int) -> Image.Image:
+ tile = image_of(pixels)
+ tiled = Image.new("RGBA", (tile.width * 3, tile.height * 3))
+ for ty in range(3):
+ for tx in range(3):
+ tiled.paste(tile, (tx * tile.width, ty * tile.height))
+ return tiled.resize((tiled.width * scale, tiled.height * scale), Image.NEAREST)
+
+
+def save_gif(frames: Sequence[Sequence[Sequence[Pixel]]], scale: int, path: Path, duration_ms: int) -> None:
+ images = [image_of(f).resize((len(f[0]) * scale, len(f) * scale), Image.NEAREST) for f in frames]
+ save_clean_gif(images, path, duration_ms=duration_ms)