Skip to content

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

14.8 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""`sprite-gen gen-set` — generate every state row of a prepared run, N at a time.

The atlas pipeline's one AI step, as a command instead of prose. `prepare` already
wrote the numeric request, one prompt per state and one layout guide per state; this
runs `gen` for each state with the identity ref the run declares (`base-source.*`, or
the accepted direction anchor for a direction-contract action row — `sprite_gen.curate.anchor`
owns that choice) and writes `raw/<state>.png` where `extract` expects it.

Same contract as `video-set`: items are idempotent (an existing row is reused unless
`--force`), every item gets its own report, `table.md` names failures by stage, and the
exit code is non-zero when any item failed. There is no fallback provider: `--provider`
is honoured verbatim and the unspecified case resolves exactly like `gen` does
(`SPRITE_GEN_DEFAULT_PROVIDER` > codex; a codex that cannot run turns into what the user
chose for that, recorded per item). When that choice is to ask, every row's `gen` asks
instead of generating, and the set stops with the same question and exit code
(`base.CODEX_UNAVAILABLE_EXIT`) once the rows under way have ended, naming `--provider` as
the way to answer it.

Direction-contract runs follow the run's own `references/generation-plan.json`: stage 1
(direction anchors, base-referenced) must be generated, extracted and an anchor frame
accepted before stage 2 rows can attach it, so a stage-2 row whose anchor is not
resolvable fails by name instead of quietly re-attaching the base.
"""

from __future__ import annotations

import argparse
import json
import sys
import time
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path
from typing import Any, Callable

from sprite_gen import gen as gen_mod
from sprite_gen.curate import anchor as anchor_mod
from sprite_gen.gen.base import ask_codex_unavailable, child_asked, codex_unavailable_question, run_logged
from sprite_gen.spec import layout
from sprite_gen.spec.runio import REQUEST_FILENAME, atomic_write_text
from sprite_gen.util.console import utf8_streams

DEFAULT_CONCURRENCY = 6  # lead-verified 2026-08 (no provider throttling at 6-wide); serial one-by-one is the anti-pattern
REPORT_DIR = "reports"  # <run>/reports/gen-set/<state>.json — outside raw/ and frames/, the run contract's derived areas


def _row_states(request: dict[str, Any], wanted: list[str] | None) -> list[str]:
    """States to generate, in generation-plan order (anchors before rows), minus mirrored directions."""
    states = list(request.get("states") or {})
    if not states:
        raise SystemExit("gen-set: the request declares no states")
    directions = request.get("directions")
    mirrored = set((directions or {}).get("mirror") or {})
    ordered: list[str] = []
    if directions:
        anchors = [anchor_mod.anchor_state(request, d) for d in anchor_mod.directions(request)]
        ordered = [s for s in anchors if s in states] + [s for s in states if s not in anchors]
    else:
        ordered = states
    ordered = [s for s in ordered if not any(s.startswith(m + "_") for m in mirrored)]
    if wanted:
        unknown = [s for s in wanted if s not in states]
        if unknown:
            raise SystemExit(f"gen-set: state(s) not in the request: {', '.join(unknown)} (have: {', '.join(states)})")
        ordered = [s for s in ordered if s in wanted]
    return ordered


def _stages(request: dict[str, Any], states: list[str]) -> list[list[str]]:
    """Direction runs: anchors first (parallel), then rows. Flat runs: one stage."""
    directions = request.get("directions")
    if not directions:
        return [states]
    anchors = {anchor_mod.anchor_state(request, d) for d in anchor_mod.directions(request)}
    first = [s for s in states if s in anchors]
    second = [s for s in states if s not in anchors]
    return [stage for stage in (first, second) if stage]


def _row_image_ok(out: Path) -> str | None:
    """None when `out` is a complete, decodable image; otherwise why not."""
    if not out.is_file():
        return "row image missing"
    try:
        from PIL import Image

        with Image.open(out) as im:
            im.verify()
    except Exception as exc:  # noqa: BLE001 — any decode failure is the same verdict
        return f"row image unreadable ({exc.__class__.__name__})"
    return None


def read_report(report: Path) -> tuple[dict[str, Any] | None, str | None]:
    """Parse a row's gen report. Returns (report, None) or (None, why) — a missing,
    unreadable or provider-less report is never treated as a finished row."""
    if not report.is_file():
        return None, "report missing"
    try:
        data = json.loads(report.read_text(encoding="utf-8"))
    except (OSError, ValueError) as exc:
        return None, f"report unreadable ({exc.__class__.__name__})"
    if not isinstance(data, dict) or not data.get("provider"):
        return None, "report has no provider — not a finished gen report"
    return data, None


def _auth_source(report: dict[str, Any]) -> str | None:
    """What a row's gen call ran on, as its report says (`extra.auth_source`)."""
    extra = report.get("extra") if isinstance(report.get("extra"), dict) else {}
    return extra.get("auth_source")


def run_gen_cli(prompt_file: Path, out: Path, refs: list[Path], report: Path, *, provider: str | None, model: str | None, log: Path) -> int:
    cmd = [sys.executable, "-m", "sprite_gen.cli", "gen", "--prompt-file", str(prompt_file), "--out", str(out), "--report", str(report)]
    for ref in refs:
        cmd += ["--ref", str(ref)]
    if provider:
        cmd += ["--provider", provider]
    if model:
        cmd += ["--model", model]
    return run_logged(cmd, log)


def run_item(
    *,
    run_dir: Path,
    request: dict[str, Any],
    state: str,
    provider: str | None,
    model: str | None,
    force: bool,
    gen_runner: Callable[..., int] | None = None,
) -> dict[str, Any]:
    gen_runner = gen_runner or run_gen_cli  # late-bound so a test can stand in for the provider call
    out = run_dir / layout.raw_rel(request, state)
    prompt_file = run_dir / layout.prompt_rel(request, state)
    guide = run_dir / layout.guide_rel(request, state)
    report_dir = run_dir / REPORT_DIR / "gen-set"
    report_dir.mkdir(parents=True, exist_ok=True)
    report = report_dir / f"{state.replace('/', '_')}.json"
    log = report_dir / f"{state.replace('/', '_')}.log"
    result: dict[str, Any] = {"state": state, "out": str(out), "report": str(report)}
    started = time.monotonic()
    try:
        if not prompt_file.is_file():
            raise SystemExit(f"prompt missing: {prompt_file} — run `sprite-gen prepare` first")
        if not guide.is_file():
            raise SystemExit(f"layout guide missing: {guide} — run `sprite-gen prepare` first")
        if out.is_file() and not force:
            prior, why = read_report(report)
            bad_image = _row_image_ok(out)
            if prior is not None and bad_image is None:
                result["reused"] = True
                result["provider"] = prior.get("provider")
                result["provider_resolved_from"] = prior.get("provider_resolved_from")
                result["auth_source"] = _auth_source(prior)
                result["ok"] = True
                return result
            result["regenerated_because"] = why or bad_image  # the files exist but do not prove a finished row — generate again, say why
        identity = anchor_mod.identity_ref(run_dir, state, request, quiet=True)
        refs = [identity, guide]
        result["refs"] = [str(r) for r in refs]
        out.parent.mkdir(parents=True, exist_ok=True)
        # The report is the commit marker of a finished row. Drop the previous one BEFORE the
        # provider runs: a provider that half-overwrites the image and exits non-zero must not
        # leave a valid-looking report next to a broken image (validator finding 2026-09-09).
        report.unlink(missing_ok=True)
        rc = gen_runner(prompt_file, out, refs, report, provider=provider, model=model, log=log)
        gen_report, why = read_report(report) if rc == 0 else (None, None)
        bad_image = _row_image_ok(out) if rc == 0 else None
        if rc != 0 or gen_report is None or bad_image is not None:
            for partial in (out, report):  # no half state: an unproven row is removed so the next run regenerates
                if partial.exists():
                    partial.unlink()
            if rc != 0:
                if (question := child_asked(rc, log)) is not None:
                    result["asked"] = question
                    raise SystemExit(f"gen asked what to do instead of generating: codex cannot run here "
                                     f"({question['reason']})")
                tail = log.read_text(encoding="utf-8", errors="replace").strip().splitlines()[-3:] if log.exists() else []
                raise SystemExit(f"gen exited {rc}; " + (" | ".join(tail) if tail else f"see {log}") + " — the row and its report were removed")
            raise SystemExit(f"gen exited 0 but its {why or bad_image}; the row and the report were removed so the next run regenerates")
        result["provider"] = gen_report.get("provider")
        result["provider_resolved_from"] = gen_report.get("provider_resolved_from")
        result["auth_source"] = _auth_source(gen_report)
        if gen_report.get("provider_fallback"):
            result["provider_fallback"] = gen_report["provider_fallback"]
        result["elapsed_seconds"] = round(time.monotonic() - started, 1)
        result["ok"] = True
    except SystemExit as exc:
        result["ok"] = False
        result["error"] = str(exc)
        result["elapsed_seconds"] = round(time.monotonic() - started, 1)
    return result


def write_table(results: list[dict[str, Any]], path: Path) -> str:
    lines = ["| state | provider | resolved from | seconds | status |", "|---|---|---|---|---|"]
    for r in results:
        if r.get("ok") and r.get("reused"):
            lines.append(f"| {r['state']} | - | - | - | reused |")
        elif r.get("asked"):
            lines.append(f"| {r['state']} | - | - | {r.get('elapsed_seconds', '-')} | ASKED: codex cannot run here "
                         f"({r['asked']['reason'][:80]}) |")
        elif r.get("ok"):
            lines.append(f"| {r['state']} | {r.get('provider') or '-'} | {r.get('provider_resolved_from') or '-'} | {r.get('elapsed_seconds', '-')} | OK |")
        else:
            lines.append(f"| {r['state']} | - | - | {r.get('elapsed_seconds', '-')} | FAIL: {r.get('error', '')[:100]} |")
    text = "\n".join(lines) + "\n"
    atomic_write_text(path, text)
    return text


def run_set(
    *,
    run_dir: Path,
    states: list[str] | None,
    provider: str | None,
    model: str | None,
    concurrency: int,
    force: bool,
    gen_runner: Callable[..., int] | None = None,
) -> dict[str, Any]:
    gen_runner = gen_runner or run_gen_cli
    run_dir = run_dir.expanduser().resolve()
    if not (run_dir / REQUEST_FILENAME).is_file():
        raise SystemExit(f"gen-set: {run_dir} is not a prepared run (no sprite-request.json) — run `sprite-gen prepare` first")
    request = anchor_mod.load_request(run_dir)
    ordered = _row_states(request, states)
    results: list[dict[str, Any]] = []
    for stage in _stages(request, ordered):
        with ThreadPoolExecutor(max_workers=max(1, concurrency)) as ex:
            futures = {ex.submit(run_item, run_dir=run_dir, request=request, state=s, provider=provider, model=model, force=force, gen_runner=gen_runner): s for s in stage}
            for fut in as_completed(futures):
                r = fut.result()
                results.append(r)
                print(json.dumps({k: r[k] for k in ("state", "ok") if k in r} | ({"error": r["error"]} if not r.get("ok") else {}), ensure_ascii=False), flush=True)
        if any(r.get("asked") for r in results):
            break  # every row would ask the same: the set asks it once, below
        if any(not r.get("ok") for r in results if r["state"] in stage) and len(_stages(request, ordered)) > 1:
            # a failed anchor stage cannot feed stage 2 — stop here and say so, do not attach the base instead
            break
    results.sort(key=lambda r: ordered.index(r["state"]))
    report_dir = run_dir / REPORT_DIR / "gen-set"
    report_dir.mkdir(parents=True, exist_ok=True)
    table = write_table(results, report_dir / "table.md")
    skipped = [s for s in ordered if s not in {r["state"] for r in results}]
    # the set's own question, its flag to answer it: the same as its rows', which ran `gen` with gen-set's --provider
    asked = next((codex_unavailable_question(r["asked"]["cause"], r["asked"]["reason"]) for r in results
                  if r.get("asked")), None)
    payload = {
        "kind": "sprite-gen-gen-set-report",
        "run_dir": str(run_dir),
        "states": ordered,
        "ok": sum(1 for r in results if r.get("ok")),
        "failed": [r["state"] for r in results if not r.get("ok")],
        "not_started": skipped,
        **({"asked": asked} if asked else {}),
        "items": results,
    }
    atomic_write_text(report_dir / "set.report.json", json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
    print(table)
    if asked:
        raise ask_codex_unavailable(asked)
    return payload


def add_arguments(parser: argparse.ArgumentParser) -> None:
    parser.add_argument("--run-dir", required=True, type=Path, help="a prepared run (sprite-request.json, prompts/, references/layout-guides/)")
    parser.add_argument("--states", help="comma list; default = every non-mirrored state in the request")
    parser.add_argument("--provider", choices=gen_mod.PROVIDERS, help="honoured verbatim (openai bills per call); default "
                        "resolves like `gen`: env > codex, and a codex that cannot run asks or runs what was chosen for that")
    parser.add_argument("--model")
    parser.add_argument("--concurrency", type=int, default=DEFAULT_CONCURRENCY, help=f"rows generated at once (default {DEFAULT_CONCURRENCY})")
    parser.add_argument("--force", action="store_true", help="regenerate rows that already exist")


def run(**kwargs: object) -> int:
    states = [s.strip() for s in str(kwargs.get("states") or "").split(",") if s.strip()] or None
    payload = run_set(
        run_dir=Path(str(kwargs["run_dir"])), states=states,
        provider=kwargs.get("provider"), model=kwargs.get("model"),  # type: ignore[arg-type]
        concurrency=int(kwargs.get("concurrency") or DEFAULT_CONCURRENCY), force=bool(kwargs.get("force")),
    )
    return 0 if not payload["failed"] and not payload["not_started"] else 1


def main(argv: list[str] | None = None) -> int:
    utf8_streams()
    parser = argparse.ArgumentParser(prog="sprite-gen gen-set", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    add_arguments(parser)
    return run(**vars(parser.parse_args(argv)))


if __name__ == "__main__":
    raise SystemExit(main())